Developer API

All /api/v1/* endpoints require an API key via the x-api-key header. API keys are managed in the dashboard and use the ck_ prefix.

Sites

List Sites

GET /api/v1/sites

Returns all sites belonging to the authenticated user:

{ "sites": [ { "id": "...", "name": "...", "domain": "...", "status": "active", "publicToken": "ct_...", "config": {} } ] }

Create Site

POST /api/v1/sites

{
  "name": "My Website",
  "domain": "example.com",
  "config": {}
}

Automatically seeds three default categories: Necessary, Analytics, Marketing.

Returns the created site:

{ "site": { "id": "...", "name": "My Website", "domain": "example.com", "status": "active", "publicToken": "ct_...", "config": {} } }

publicToken is the opaque token used by the widget's token-mode snippet (data-token) and the /api/gateway endpoints.

Get Site

GET /api/v1/sites/:siteId

Returns site details and consent categories:

{
  "site": { "id": "...", "name": "...", "domain": "...", "status": "active", "config": {} },
  "categories": [...]
}

Update Site

PATCH /api/v1/sites/:siteId

{
  "name": "Updated Name",
  "domain": "new-domain.com",
  "config": {},
  "status": "active"
}

All fields are optional. At least one must be provided.

Delete Site (Soft)

DELETE /api/v1/sites/:siteId

Sets site status to deleted.

Categories

List Categories

GET /api/v1/sites/:siteId/categories

Returns categories ordered by sortOrder.

Create Category

POST /api/v1/sites/:siteId/categories

{
  "key": "preferences",
  "nameEn": "Preferences",
  "descriptionEn": "Remember your settings and preferences.",
  "isRequired": false,
  "isDefault": true
}

Key must match pattern /^[a-z0-9_]{1,50}$/ and be unique within the site.

Update Category

PATCH /api/v1/sites/:siteId/categories/:categoryId

{
  "nameEn": "Updated Name",
  "descriptionEn": "Updated description.",
  "isDefault": false
}

Delete Category

DELETE /api/v1/sites/:siteId/categories/:categoryId

Fails if the category is marked as required.

Reorder Categories

PUT /api/v1/sites/:siteId/categories/reorder

{
  "order": [
    { "id": "cat-1", "sortOrder": 0 },
    { "id": "cat-2", "sortOrder": 1 },
    { "id": "cat-3", "sortOrder": 2 }
  ]
}

Consent Events

List Consent Events

GET /api/v1/consent/events/:siteId?limit=50&offset=0

Pro plan only - free-plan keys get 403 with code UPGRADE_REQUIRED.

Record Consent Event

POST /api/v1/consent/events

Same body as the widget events endpoint, but requires API key auth and site ownership verification.

Export Consent Events (CSV)

GET /api/v1/consent/events/:siteId/export?period=30d

Returns a CSV attachment of consent events rather than JSON. Pro plan only — free-plan keys get 403.

Columns: consentId, action, source (gpc for signal-derived decisions, empty for banner interactions), categories, policyVersion, visitorHash, ipHash, country, userAgent, consentedAt.

Responds with Content-Type: text/csv; charset=utf-8 and a Content-Disposition: attachment filename of consent-logs-<siteId>-<YYYY-MM-DD>.csv.

Consent Config

Get Site Config

GET /api/v1/consent/config/:siteId

The authenticated equivalent of the widget config endpoint. Same response body, but resolved via API key and site ownership instead of an Origin check, so it works from a server or a script with no browser origin.