> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adclear.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started
> Set up authentication, pick an environment, fetch reference data, and handle errors before you write your first request.
Adclear provides an automated compliance evaluation service for promotional content. You upload a file, classify it against your organisation's regulatory rules, and receive an evaluation. Results, including specific findings with cited rules, are delivered via webhooks.
This page covers everything you need before making your first request: the two services, authentication, environments, reference data, error handling, and the questions integrators ask most often.
Your system talks to two services that share a single API key.
| Service | Base URL | Responsibilities |
| ------------------- | ----------------------- | ---------------------------------------------------------- |
| **File API** | `files.adclear.ai` | Resumable chunked file upload; upload status tracking |
| **Integration API** | `public-api.adclear.ai` | Promotions, evaluations, reference data, outbound webhooks |
**Data flow.** You initiate an upload via the File API, PUT the file in one or more chunks, then reference the upload by ID when creating a promotion via the Integration API. Evaluation results are delivered asynchronously to your webhook endpoint.
### Key concepts
| Concept | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Promotion | A piece of promotional content submitted for compliance review |
| Version | An immutable snapshot of uploaded files within a promotion. Version 1 is created with the promotion; subsequent versions represent revisions |
| Evaluation | An asynchronous compliance review of a specific version. Produces a set of issues with cited rules |
| Webhook | An outbound HTTP POST from Adclear to your endpoint when an event occurs (for example, when evaluation completes) |
| Metadata | An arbitrary key-value map you attach at promotion creation. Adclear stores it and echoes it back in every webhook so you can correlate events to your own entities |
### Supported file formats
| Format | MIME type | Max size |
| ---------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
| PDF | `application/pdf` | 30 MB |
| PNG | `image/png` | 30 MB |
| JPEG | `image/jpeg` | 30 MB |
| WebP | `image/webp` | 30 MB |
| MP4 | `video/mp4` | 2 GB |
| MOV | `video/quicktime` | 2 GB |
| MP3 | `audio/mpeg` | 2 GB |
| WAV | `audio/wav` | 2 GB |
| DOCX | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | 10 MB |
| XLSX | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | 10 MB |
| HTML | `text/html` | N/A |
| Inline text/HTML | N/A | N/A (via `content` field; no upload required) |
Files exceeding the size limit are rejected at upload initiation with HTTP 413.
All requests to both services require two headers.
| Header | Required | Description |
| -------------------- | -------- | ------------------------------------------------------------------------------------ |
| `Authorization` | Yes | `Bearer `, provided during onboarding |
| `X-External-User-ID` | Yes | A stable identifier for the acting user in your system (for example, an employee ID) |
The API key is scoped to a single Adclear organisation and workspace. Rate limits apply per key (see the **Errors** tab).
### Interactive API documentation
Swagger UI:
* File API: [https://files.adclear.ai/v1/docs](https://files.adclear.ai/v1/docs)
* Integration API: [https://public-api.adclear.ai/v1/docs](https://public-api.adclear.ai/v1/docs)
Machine-readable OpenAPI 3.1 specs:
* `GET https://files.adclear.ai/v1/openapi.json`
* `GET https://public-api.adclear.ai/v1/openapi.json`
| Environment | File API | Integration API | Purpose |
| ----------- | ---------------------------------- | --------------------------------------- | ------------------------------------- |
| Staging | `https://files-staging.adclear.ai` | `https://public-api-staging.adclear.ai` | Integration testing with sandbox data |
| Production | `https://files.adclear.ai` | `https://public-api.adclear.ai` | Live |
API keys are environment-specific. A staging key won't authenticate against production, and vice versa.
Test your integration against staging before switching to production.
Before creating a promotion, fetch the IDs for your organisation's products, channels, jurisdictions, and target markets.
```
GET https://public-api.adclear.ai/v1/products
GET https://public-api.adclear.ai/v1/channels
GET https://public-api.adclear.ai/v1/jurisdictions
GET https://public-api.adclear.ai/v1/target-markets
```
All endpoints return at least `{ id, name }`. Some include additional fields.
| Endpoint | Response fields |
| -------------------- | --------------------------- |
| `/v1/products` | `id`, `name` |
| `/v1/channels` | `id`, `name` |
| `/v1/jurisdictions` | `id`, `name`, `countryCode` |
| `/v1/target-markets` | `id`, `name`, `description` |
Results are sorted alphabetically by name. These change infrequently. Cache them and refresh daily.
The classification you provide (products, channels, jurisdiction) determines which regulatory rules are applied during evaluation. Incorrect classification produces irrelevant findings.
All error responses follow a consistent envelope.
```json theme={null}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [
{ "type": "field_error", "field": "uploadIds", "message": "Required" }
]
},
"correlationId": "uuid-for-support"
}
```
### Error codes
| Code | HTTP status | Meaning | Action |
| ------------------ | ----------- | ------------------------------------------------------------------------ | ------------------------------------------------- |
| `VALIDATION_ERROR` | 400 | Request body failed schema validation | Fix the request payload per the `details` array |
| `UNAUTHORIZED` | 401 | Missing or invalid API key | Check the `Authorization` header and key validity |
| `FORBIDDEN` | 403 | API key lacks permission for this resource | Contact Adclear to adjust key scoping |
| `NOT_FOUND` | 404 | Resource does not exist | Verify the resource ID. It may have been deleted |
| `CONFLICT` | 409 | Resource not in expected state (uploads not ready, version not editable) | Retry with back-off |
| `RATE_LIMITED` | 429 | Too many requests | Honour the `Retry-After` header |
| `INTERNAL_ERROR` | 500 | Unexpected server error | Retry once. If persistent, contact support |
Always include the `correlationId` in support requests. It lets us trace the full request lifecycle.
### Rate limits
| Service | Scope | Limit |
| --------------- | ------------------------------------ | ------------------------------ |
| Integration API | All `/v1/*` endpoints | 60 requests/minute per API key |
| File API | `POST /v1/uploads` (initiation only) | 30 requests/minute per API key |
Chunk uploads (`PUT /v1/uploads/{id}`) and status checks (`GET /v1/uploads/{id}`) are not rate-limited.
When rate-limited, the response includes a `Retry-After` header indicating how many seconds to wait before retrying.
### Common issues
* Verify the `Authorization` header is `Bearer ` (note the space after `Bearer`).
* Confirm you're using the correct key for the environment. Staging and production keys are not interchangeable.
* Check the key hasn't been revoked.
The API key authenticates but isn't fully configured for your organisation. Contact Adclear support with the `correlationId` from the error response.
Honour the `Retry-After` header. If you're regularly hitting the limit, batch requests or contact support to discuss your usage.
Transient upstream issue. Retry after 2–5 seconds. If the error persists, contact support with the `correlationId`.
### General tips
* Use the `X-Correlation-ID` request header to pass your own trace ID. Adclear echoes it back in every response.
* Test against staging before production.
* Cache reference data (products, channels, jurisdictions, target markets) and refresh daily.
Either works:
* **Polling**: trigger evaluation, then poll `GET .../evaluation` every 5–10 seconds until `status` is `succeeded` or `failed`.
* **Webhooks**: configure a webhook endpoint during onboarding. Adclear POSTs the result to your endpoint when evaluation completes.
You can use both. Poll as a fallback in case a webhook is delayed.
Yes. Upload IDs aren't consumed. The same upload can be referenced by multiple promotions or versions.
No. Completed uploads are stored indefinitely. If you initiate an upload and never send any chunks, the upload session may eventually become unusable. Complete uploads promptly after initiation.
No. The API doesn't support deleting or archiving promotions. They're retained for compliance audit purposes.
| File type | `fileFormat` |
| ------------------------------------------------------------------------- | ------------------------------------------------------- |
| `.pdf` | `pdf` |
| `.jpg`, `.png`, `.gif`, `.webp`, `.svg`, `.bmp`, `.tiff` | `image` |
| `.mp4`, `.mov`, `.avi`, `.webm`, `.mkv`, `.wmv` | `video` |
| `.mp3`, `.wav`, `.aac`, `.ogg`, `.flac`, `.m4a` | `audio` |
| `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, `.txt`, `.csv`, `.rtf` | `document` |
| Inline text or HTML (no file upload) | `text` (use the `content` field instead of `uploadIds`) |
The `fileFormat` must match the file you uploaded. A `.pdf` upload uses `fileFormat: "pdf"`, not `"document"`.
Use [openapi-typescript](https://openapi-ts.dev/):
```bash theme={null}
npx openapi-typescript https://public-api.adclear.ai/v1/openapi.json -o adclear-api.d.ts
npx openapi-typescript https://files.adclear.ai/v1/openapi.json -o adclear-files.d.ts
```
Or explore the schemas interactively via Swagger UI ([Integration API](https://public-api.adclear.ai/v1/docs), [File API](https://files.adclear.ai/v1/docs)).
## Next steps
Initiate an upload, send chunks, and check status.
Combine uploads with classification metadata.
Trigger and poll evaluation results.
Receive results asynchronously and verify signatures.