Skip to main content
Both the File API and the Adclear API authenticate with the same bearer key. Every request needs two headers.

​
Required headers

The API key is scoped to a single Adclear organisation and workspace. Rate limits apply per key (see Errors & rate limits).

​
Key expiry

Keys generated in Settings stop working at the expiry you chose when you generated them: 30 days by default, or 90 days, 1 year, or never. Keys Adclear provided during onboarding don’t expire. Once a key expires, the File API and the Adclear API reject every request made with it with 401 and a message ending in Code: KEY_EXPIRED. You can’t extend an expiry. Generate a replacement before the date, switch your integration to it, then revoke the old key.

​
Keys tied to their creator

A key generated in Settings acts as the person who generated it. On every request, the Adclear API checks that this person is still a member of your organisation in a role that can hold a key. If they have left the organisation, or now hold an external role (external uploader or reviewer), the Adclear API rejects every request made with the key with 403 and the message API key is not configured for public API access. Keys Adclear provided during onboarding are not affected. Generate integration keys from a long-lived account. Before the person who generated a key leaves or changes role, generate a replacement from another account, switch your integration to it, then revoke the old key.

​
Acting on behalf of Adclear users

By default, actions performed through the API are attributed to the key’s service account, with your X-External-User-ID value recorded alongside for audit purposes. The ID is stored as supplied. Adclear does not verify it. Keys can instead be issued with act-on-behalf enabled, for integrations whose users also have Adclear accounts. On these keys, X-External-User-Email is resolved to the Adclear user with that email, and the action is performed and audited as that person, with their own role and permissions. Two rules apply:
  • The email header is mandatory on every write (POST, PUT, PATCH, DELETE). Writes without it are rejected with 400.
  • An email that does not match an active member of your organisation is rejected with 403. The action is never silently attributed to the service account.
On ordinary keys the email header is ignored. The same rule covers author.email when importing or updating comments: only act-on-behalf keys can attribute a comment or action to another member. On ordinary keys, an imported comment from another member’s email is recorded as an external author. Ask your Adclear contact if you are unsure which kind of key you hold.

​
Environments

API keys are environment-specific. A staging key won’t authenticate against production, and vice versa.
Build and test your integration against staging before switching to production.

​
Interactive API reference

Explore and try endpoints in Swagger UI: Machine-readable OpenAPI 3.1 specs:
  • GET https://public-api.adclear.ai/v1/openapi.json
  • GET https://files.adclear.ai/v1/openapi.json

​
Generate types from the spec

Generate TypeScript types directly from the specs with openapi-typescript: