API Reference

API Endpoints

All endpoints are relative to your configured basePath (e.g. /api/c15t).

Info

The backend auto-generates interactive API docs at {basePath}/docs using your OpenAPI spec. Visit this URL in a browser to explore endpoints with a visual UI.

GET /init

Returns the initial consent state for a client. This is the first call made by the frontend SDKs.

Response:

{
  "jurisdiction": "GDPR",
  "location": {
    "countryCode": "DE",
    "regionCode": "BY"
  },
  "translations": {
    "language": "de",
    "translations": { "...": "..." }
  },
  "branding": "c15t",
  "gvl": null
}

Field	Description
`jurisdiction`	Detected regulation (`GDPR`, `UK_GDPR`, `CCPA`, etc.)
`location`	Geo-location from IP address
`translations`	Server-side translations based on `Accept-Language`
`branding`	Branding configuration
`gvl`	Global Vendor List (if IAB TCF is enabled)

GET /status

Health check endpoint. Returns server version and client info.

Response:

{
  "version": "1.8.0",
  "timestamp": "2026-02-11T12:00:00.000Z",
  "client": {
    "ip": "192.168.1.0",
    "acceptLanguage": "en-US",
    "userAgent": "Mozilla/5.0 ...",
    "region": { "countryCode": "US", "regionCode": "CA" }
  }
}

POST /subjects

Records a consent event. This is an append-only operation — every call creates a new consent record.

Request:

{
  "type": "cookie_banner",
  "subjectId": "sub_abc123",
  "domain": "example.com",
  "preferences": {
    "necessary": true,
    "measurement": true,
    "marketing": false
  },
  "givenAt": 1707648000000,
  "metadata": {}
}

Field	Type	Required	Description
`type`	string	Yes	`cookie_banner`, `privacy_policy`, `dpa`, `terms_and_conditions`, `marketing_communications`, `age_verification`, `other`. Legal-document types (`privacy_policy`, `dpa`, `terms_and_conditions`) also accept suffixed variants, e.g. `terms_and_conditions_b2b`, so multiple policies of one family can be active at once
`subjectId`	string	Yes	Client-generated subject identifier
`domain`	string	Yes	Domain where consent was given
`preferences`	object	No	Consent category preferences (for `cookie_banner` type)
`givenAt`	number	Yes	Epoch timestamp
`policyId`	string	No	Associated policy ID
`metadata`	object	No	Arbitrary metadata
`externalSubjectId`	string	No	External user ID for cross-device linking
`identityProvider`	string	No	Identity provider name

Response:

{
  "subject": { "id": "sub_abc123", "...": "..." },
  "consent": { "id": "con_xyz789", "type": "cookie_banner", "...": "..." }
}

GET /subjects/:id

Retrieves consent status for a subject.

Query Parameters:

Parameter	Description
`type`	Comma-separated consent types to filter (e.g. `cookie_banner,privacy_policy`)

Response:

{
  "subject": { "id": "sub_abc123" },
  "consents": [
    {
      "id": "con_xyz789",
      "type": "cookie_banner",
      "givenAt": "2026-02-11T12:00:00.000Z",
      "jurisdiction": "GDPR",
      "preferences": { "necessary": true, "measurement": true }
    }
  ],
  "isValid": true
}

PATCH /subjects/:id

Links a subject to an external user ID for cross-device consent resolution.

Request:

{
  "externalId": "user_12345",
  "identityProvider": "auth0"
}

Response:

{
  "subject": {
    "id": "sub_abc123",
    "externalId": "user_12345",
    "identityProvider": "auth0"
  }
}

GET /consents/check

Check consent status by external ID — useful for cross-device consent resolution.

Query Parameters:

Parameter	Description
`externalId`	The external user ID to look up
`type`	Comma-separated consent types

Response:

{
  "found": true,
  "consents": [
    { "id": "con_xyz789", "type": "cookie_banner", "...": "..." }
  ]
}

GET /subjects (Authenticated)

List subjects by external ID. Requires an API key.

Headers:

Authorization: Bearer sk_live_abc123

Query Parameters:

Parameter	Description
`externalId`	The external user ID to search

Response:

{
  "subjects": [
    { "id": "sub_abc123", "externalId": "user_12345" }
  ]
}

Warning

This endpoint requires API key authentication. Configure API keys in the apiKeys option. The key is passed via the Authorization: Bearer header using timing-safe comparison.

GET /spec.json

Returns the OpenAPI 3.1 specification for the consent API.

GET /docs

Serves the interactive API documentation UI (Scalar).