COKIQ API
Manage sites, read consent logs, run scans and receive webhooks from your own systems or from automation tools. Base URL: https://cokiq.com/api/v1. Machine-readable spec: /openapi.json (OpenAPI 3).
Authentication
Create a key at Developers, API keys (you must be signed in) and choose its scopes: sites:read, sites:write, consent:read, scans:write, cookies:write, hooks:manage. Send it as Authorization: Bearer YOUR_KEY or x-api-key: YOUR_KEY. Keys are shown once and stored only as a hash. Revoke a key at any time.
curl https://cokiq.com/api/v1/me \ -H "Authorization: Bearer YOUR_KEY"
Limits
Free plan: 100 calls a day, 30 a minute, 50 webhook deliveries a day, 5 scans a day. Paid plans: 50,000 calls a day. When a limit is reached the API answers 429 with a JSON error, retry_after seconds and, on the free plan, an upgrade_url. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
Errors
{ "error": { "code": "insufficient_scope", "message": "This API key lacks the consent:read scope." } }
Endpoints
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /me | any key | Connection test: workspace name, plan, scopes and limits. |
GET | /sites | sites:read | List sites (newest first, limit + cursor, since). |
POST | /sites | sites:write | Add a site: {"domain":"example.com","region":"global"}. |
GET | /sites/{id} | sites:read | Get one site. |
POST | /sites/{id}/scans | scans:write | Run a cookie scan and return the result. |
GET | /scans | sites:read | List scans (since, site_id, limit, cursor). |
GET | /consent-logs | consent:read | List consent logs (since, until, site_id, limit, cursor). |
POST | /consent-logs/export | consent:read | Export up to 5,000 consent logs as JSON rows or CSV text. |
POST | /cookie-rules | cookies:write | Classify a cookie for a site: {"site_id","name","category"}. |
POST | /hooks | hooks:manage | Subscribe a REST hook: {"event","target_url"}. Returns the signing secret once. |
DELETE | /hooks/{id} | hooks:manage | Unsubscribe a REST hook. |
GET | /hooks/sample?event= | hooks:manage | Sample payload for an event. |
Lists return { "data": [...], "next_cursor": "...", "has_more": true }. Pass next_cursor as cursor for the next page.
Webhooks
Events: consent.logged scan.completed banner.published site.created. Subscribe with POST /hooks; the target must be a public https URL. Each delivery is a JSON POST signed with Cokiq-Signature: t=UNIX,v1=HEX, where HEX is HMAC-SHA256 of ${t}.${body} using your secret. Failed deliveries are retried three times; a 410 Gone answer unsubscribes the hook. New events are picked up within about a minute.
Privacy
Consent data is personal data under GDPR and similar laws. The API and webhooks never return raw IP addresses, user agents or other visitor details. visitor_hash is a salted, truncated hash used only to tell records apart.
Questions? Contact support.