REST API overview
The AD80 REST API gives your scripts and servers the same data as the dashboard: apps, creatives, violations, policies, the Policy Playground, incidents, plan usage and notification subscriptions.
Base URL
Section titled “Base URL”https://api.ad80.devAll paths start with /v1/. Requests and responses are JSON (UTF-8) unless stated otherwise. Times are RFC 3339 in
UTC, for example 2026-10-26T14:03:00Z. Dates in query parameters are YYYY-MM-DD (UTC days). Unknown fields in a
JSON request body are rejected with 400.
Authentication
Section titled “Authentication”Send a client API key as a bearer token:
Authorization: Bearer ad80_ck_YOUR_KEYCreate API keys on Apps and SDK → API keys → Create API key, or with
POST /v1/keys. The secret is shown once. Store it in a secret
manager or an environment variable, and never put it in an app: anyone holding it can read your data.
The examples in this documentation read the key from an environment variable:
export AD80_API_KEY="ad80_ck_YOUR_KEY"curl -s https://api.ad80.dev/v1/me -H "Authorization: Bearer $AD80_API_KEY"Scopes
Section titled “Scopes”Each key carries one or more scopes. A key can only create keys with scopes it has itself.
| Scope | Allows |
|---|---|
read:creatives | List apps; read creatives, the overview, the plan and usage, Playground images and samples. |
read:verdicts | Verdicts (scores and explanations) in creative payloads; the violations list and the rule and minScore filters; read policies, versions and estimates; read incidents. |
write:policies | Save policies; run draft tests; review creatives (confirm or false positive); upload, classify and re-test Playground images; update incidents. |
manage:keys | List, create, rotate and revoke keys; create apps. |
manage:notifications | Everything under /v1/notifications (subscriptions, verification, tests, secrets, deliveries). |
The scopes manage:webhooks and read:spend are accepted when creating a key but do not currently grant access to
any public endpoint.
A typical read-only reporting key has read:creatives and read:verdicts.
What API keys cannot do
Section titled “What API keys cannot do”Members, invitations, the audit log and sign-in belong to people, not keys. GET /v1/members, /v1/invites and
/v1/audit need a dashboard session and answer 403 with code: forbidden to an API key.
Errors
Section titled “Errors”Every error has the same body:
{ "error": "a sentence that explains the problem", "code": "machine_readable_code" }code is present where your code should react to it. Status codes:
| Status | Meaning |
|---|---|
| 400 | The request is invalid (bad JSON, unknown field, value out of range). error says which. |
| 401 | Missing, unknown, revoked or expired key. The response has WWW-Authenticate: Bearer realm="ad80". |
| 403 | The key lacks a scope (missing scope read:verdicts), or the plan does not allow the action (code: entitlement, below). |
| 404 | Not found. An object of another organization also answers 404. |
| 409 | Conflict, for example an app that already exists. |
| 413, 415, 422 | Upload too large, unsupported type, or an image that cannot be used (Playground uploads). |
| 429 | Too many requests. Wait for Retry-After seconds. |
| 502 | A notification destination could not be reached (tests and verifications). |
| 503 | Temporarily unavailable. Retry after Retry-After seconds. |
Plan limits (entitlement)
Section titled “Plan limits (entitlement)”When your plan does not include an action, or a monthly allowance is used up, the answer is 403:
{ "error": "monthly manual classification allowance reached", "code": "entitlement", "entitlement": "manual_classifications_per_month", "limit": 200, "used": 200, "upgradeTo": "enterprise"}| Field | Meaning |
|---|---|
entitlement | What is limited: sdk_ingest, max_active_policies, manual_classifications_per_month, monitored_impressions_per_month, expedited_notifications_per_month, notification_channels, incident_management. |
limit, used | Where you stand. limit: 0 means not included in your plan. |
upgradeTo | The plan that would allow it (starter, enterprise), or null. |
The numbers in the example are illustrative. Your real limits are in GET /v1/plan.
Pagination
Section titled “Pagination”List endpoints return a page and a nextCursor:
{ "creatives": [ ... ], "nextCursor": "eyJ0IjoxNzYx..." }Pass cursor=<nextCursor> to get the next page; nextCursor is null on the last page. Cursors are opaque: do not
build or change them. limit sets the page size (1 to 200, default 50) unless an endpoint says otherwise.
import osimport requests
API = "https://api.ad80.dev"HEADERS = {"Authorization": f"Bearer {os.environ['AD80_API_KEY']}"}
def all_violations(**filters): params = {"limit": 200, **filters} while True: page = requests.get(f"{API}/v1/violations", headers=HEADERS, params=params, timeout=30) page.raise_for_status() body = page.json() yield from body["creatives"] if not body["nextCursor"]: return params["cursor"] = body["nextCursor"]
for creative in all_violations(review="unreviewed"): print(creative["id"], creative["appId"])// Node 18+ (built-in fetch)const API = 'https://api.ad80.dev';const headers = { Authorization: `Bearer ${process.env.AD80_API_KEY}` };
async function* allViolations(filters = {}) { const params = new URLSearchParams({ limit: '200', ...filters }); while (true) { const res = await fetch(`${API}/v1/violations?${params}`, { headers }); if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`); const body = await res.json(); yield* body.creatives; if (!body.nextCursor) return; params.set('cursor', body.nextCursor); }}
for await (const c of allViolations({ review: 'unreviewed' })) console.log(c.id, c.appId);Rate limits and retries
Section titled “Rate limits and retries”AD80 does not publish fixed request rate limits for the REST API. Some actions have their own limits (for example
notification tests and verifications). When you get 429 or 503, wait for the number of seconds in Retry-After
before you retry, and retry 5xx answers with a growing delay.
Caching
Section titled “Caching”API responses carry Cache-Control: no-store. Image links expire; see Signed image links.
Endpoints
Section titled “Endpoints”| Area | Page |
|---|---|
| Who am I, plan and usage, overview | Account and plan |
| Apps and keys | Apps and keys |
| Creatives, violations and reviews | Creatives and violations |
| Images | Signed image links |
| Policies and draft tests | Policies |
| Policy Playground | Playground |
| Incidents (Enterprise) | Incidents |
| Notifications and webhooks | Notifications |