REST API

The Okito REST API lets you run cookie scans and generate policies from your own systems. It is included in the Professional plan.

Authentication

1. Create a key in Settings → API Keys. Each key has a list of allowed domains; it only works for those domains.
2. The key is shown once. Store it as a secret.
3. Send it with every request, either as X-API-Key: okito_live_… or Authorization: Bearer okito_live_….

Base URL: https://app.okito.com

Cookie Scanner API

Synchronous scan

POST /api/external/cookie-scanner/scan

Runs a full scan and returns the cookies in the same response. It waits up to about 85 seconds for the scan; see Long scans for what happens after that.

curl -X POST https://app.okito.com/api/external/cookie-scanner/scan \
  -H "X-API-Key: okito_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "websiteUrl": "https://example.com" }'

{
  "success": true,
  "scanId": "ext_1713690000000_abc12345",
  "websiteUrl": "https://example.com",
  "domain": "example.com",
  "durationMs": 4832,
  "summary": { "total": 17 },
  "complete": true,
  "cookies": [
    {
      "name": "_ga",
      "domain": ".example.com",
      "category": "analytics",
      "provider": "Google Analytics",
      "description": "...",
      "purpose": "...",
      "duration": "2 years"
    }
  ]
}

complete is false when the site loaded only partly; incompleteReason then says why. A site that could not be loaded at all answers 502 with code: "SCAN_INCOMPLETE".

Long scans

If the scan has not finished after about 85 seconds, the answer is 202 Accepted. The scan keeps running on our side; read its result from the status endpoint with the scanId:

{
  "success": true,
  "scanId": "ext_1713690000000_abc12345",
  "status": "running",
  "message": "The scan is still running. Check back with this scan ID.",
  "pollUrl": "/api/external/cookie-scanner/scan/async/ext_1713690000000_abc12345?domain=example.com"
}

Call pollUrl as it is (it already names the domain) with the same key every few seconds until status is completed or failed. Treat 202 as "not finished yet", not as an error.

Asynchronous scan

For large sites, start a scan and poll for the result.

POST /api/external/cookie-scanner/scan/async with { "websiteUrl": "https://example.com" } returns a scanId with status: "queued".

GET /api/external/cookie-scanner/scan/async/:scanId?domain=example.com returns the status (queued, running, completed or failed) and, when status is completed, the cookies. Only the key that started the scan can read it. A failed scan has an error such as SCANNER_BUSY or SCAN_TIMEOUT. Scans are kept for 7 days.

Scanner responses

Policy Generator API

Generate a policy

POST /api/public/policies/generate

curl -X POST https://app.okito.com/api/public/policies/generate \
  -H "X-API-Key: okito_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "policyType": "privacy",
    "language": "en",
    "companyName": "Example Inc.",
    "contactEmail": "privacy@example.com",
    "industry": "ecommerce",
    "includeGoogleAnalytics": true,
    "includeFacebookPixel": true,
    "includeMarketing": true
  }'

The response contains the policy in Markdown and your usage. Generations share the dashboard's monthly quota (7 per user).

Read your quota

GET /api/public/policies/usage?domain=example.com returns used, limit, remaining and resetAt for the current month.