Skip to content

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.

https://api.ad80.dev

All 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.

Send a client API key as a bearer token:

Authorization: Bearer ad80_ck_YOUR_KEY

Create 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:

Terminal window
export AD80_API_KEY="ad80_ck_YOUR_KEY"
curl -s https://api.ad80.dev/v1/me -H "Authorization: Bearer $AD80_API_KEY"

Each key carries one or more scopes. A key can only create keys with scopes it has itself.

ScopeAllows
read:creativesList apps; read creatives, the overview, the plan and usage, Playground images and samples.
read:verdictsVerdicts (scores and explanations) in creative payloads; the violations list and the rule and minScore filters; read policies, versions and estimates; read incidents.
write:policiesSave policies; run draft tests; review creatives (confirm or false positive); upload, classify and re-test Playground images; update incidents.
manage:keysList, create, rotate and revoke keys; create apps.
manage:notificationsEverything 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.

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.

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:

StatusMeaning
400The request is invalid (bad JSON, unknown field, value out of range). error says which.
401Missing, unknown, revoked or expired key. The response has WWW-Authenticate: Bearer realm="ad80".
403The key lacks a scope (missing scope read:verdicts), or the plan does not allow the action (code: entitlement, below).
404Not found. An object of another organization also answers 404.
409Conflict, for example an app that already exists.
413, 415, 422Upload too large, unsupported type, or an image that cannot be used (Playground uploads).
429Too many requests. Wait for Retry-After seconds.
502A notification destination could not be reached (tests and verifications).
503Temporarily unavailable. Retry after Retry-After seconds.

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"
}
FieldMeaning
entitlementWhat is limited: sdk_ingest, max_active_policies, manual_classifications_per_month, monitored_impressions_per_month, expedited_notifications_per_month, notification_channels, incident_management.
limit, usedWhere you stand. limit: 0 means not included in your plan.
upgradeToThe plan that would allow it (starter, enterprise), or null.

The numbers in the example are illustrative. Your real limits are in GET /v1/plan.

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 os
import 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"])

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.

API responses carry Cache-Control: no-store. Image links expire; see Signed image links.

AreaPage
Who am I, plan and usage, overviewAccount and plan
Apps and keysApps and keys
Creatives, violations and reviewsCreatives and violations
ImagesSigned image links
Policies and draft testsPolicies
Policy PlaygroundPlayground
Incidents (Enterprise)Incidents
Notifications and webhooksNotifications