API documentation
The All Ad Specs API gives approved consumers read-only JSON for every published publisher and ad spec. Request a key to use it.
Base URL: https://alladspecs.com/api/v1. The same reference as an OpenAPI 3.1 document:/api/v1/openapi.json. Use of the API is governed by the API terms.
Authentication
Send your key on every call as Authorization: Bearer aas_live_…. A key isaas_live_ followed by 32 letters and digits. Only /openapi.json works without one.
Keep your key on your servers and out of source control. The API sends no CORS headers, so browsers can’t call it directly. If a key leaks, contact us and we’ll issue a new one.
curl "https://alladspecs.com/api/v1/specs?publisher=meta&limit=2" \
-H "Authorization: Bearer $AAS_API_KEY"Limits
Each key has a daily limit set by its plan, and up to 60 calls a minute. We can set either limit per consumer. All keys calling from one IP address share at most 300 calls a minute. Every call that passes the key check counts, including 400 and404 answers and answers from the cache, exceptGET /usage.
| Plan | Calls a day |
|---|---|
| Free | 10 |
| Starter | 100 |
| Pro | 1,000 |
Successful responses carry these headers; a 429 carries Retry-After:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Calls allowed a day. |
X-RateLimit-Remaining | Calls left today. |
X-RateLimit-Reset | When the day starts over (next UTC midnight), in Unix seconds. |
Retry-After | Seconds to wait before trying again. |
Checking your usage
Call GET /usage with your key to see how many calls you’ve made each UTC day, across all your keys, with today’s count, what’s left today and your limits. Checking usage doesn’t count against your daily limit (it still counts towards the per-minute limits).
fromandtoare UTC dates (YYYY-MM-DD). Leave both out for the last 30 days, today included.tocan’t be after today, andfromcan go back up to 400 days. Any other range gets a400.dayshas one entry per day, oldest first. Days with no calls show0.
curl "https://alladspecs.com/api/v1/usage?from=2026-11-01&to=2026-11-03" \
-H "Authorization: Bearer $AAS_API_KEY"{
"data": {
"from": "2026-11-01",
"to": "2026-11-03",
"total": 57,
"limits": {
"daily": 10,
"per_minute": 60
},
"today": {
"date": "2026-11-03",
"used": 4,
"remaining": 6,
"resets_at": "2026-11-04T00:00:00.000Z"
},
"days": [
{
"date": "2026-11-01",
"calls": 31
},
{
"date": "2026-11-02",
"calls": 22
},
{
"date": "2026-11-03",
"calls": 4
}
]
}
}Paging, filters and freshness
Lists return {data, next_cursor, dataset: {updated_at}}, ordered by slug. Pass next_cursor as cursor to get the next page, with the same filters, until it is null. limit sets the page size. Filters combine: a spec must match all of them. Single items return {data}.
Answers are cached for up to 5 minutes, and full listings (/publishers and /specs without a publisher filter) for up to 10, so a change on the site can take that long to show.dataset.updated_at is the latest change across the catalogue.
Endpoints
GET /api/v1/meta
Counts, the latest change, the API version and the docs links.
Returns PublicMetaItem. Errors: missing_key, unknown_key, revoked, unpaid, inactive, daily_limit, burst, unavailable.
GET /api/v1/publishers
Published publishers, by slug.
| Parameter | In | Type | Description |
|---|---|---|---|
market | query | string | A market code as the catalogue stores it: ISO 3166 alpha-2 (UK for the United Kingdom) or a region such as MENA, EU or APAC. Matches formats listed for it directly or through a region, and formats sold globally (GLOBAL); market=GLOBAL gives the global ones only. |
buying_model | query | string, up to 64 characters | A buying model such as CPM or Flat fee (any case). |
cursor | query | string | The previous page's next_cursor. |
limit | query | integer, 1–500, default 100 | Items per page. |
Returns PublicPublisherList. Errors: bad_request, missing_key, unknown_key, revoked, unpaid, inactive, daily_limit, burst, unavailable.
GET /api/v1/publishers/{slug}
One publisher with a summary of each of its specs.
| Parameter | In | Type | Description |
|---|---|---|---|
slug (required) | path | string | The publisher slug. |
Returns PublicPublisherDetailItem. Errors: missing_key, unknown_key, revoked, unpaid, inactive, not_found, daily_limit, burst, unavailable.
GET /api/v1/specs
Published specs, by publisher then spec slug.
| Parameter | In | Type | Description |
|---|---|---|---|
publisher | query | string | A publisher slug. |
channel | query | string | A channel.One of: social, video, retail_media, display, audio, ctv, dooh |
media_kind | query | string | A media kind.One of: image, video, audio, html5, text |
market | query | string | A market code as the catalogue stores it: ISO 3166 alpha-2 (UK for the United Kingdom) or a region such as MENA, EU or APAC. Matches formats listed for it directly or through a region, and formats sold globally (GLOBAL); market=GLOBAL gives the global ones only. |
buying_model | query | string, up to 64 characters | A buying model such as CPM or Flat fee (any case). |
updated_since | query | string | Specs updated at or after this ISO 8601 date or date-time (2026-11-01, 2026-11-01T00:00:00Z). |
cursor | query | string | The previous page's next_cursor. |
limit | query | integer, 1–500, default 100 | Items per page. |
Returns PublicSpecList. Errors: bad_request, missing_key, unknown_key, revoked, unpaid, inactive, daily_limit, burst, unavailable.
GET /api/v1/specs/{publisher}/{format}
One spec with all its fields.
| Parameter | In | Type | Description |
|---|---|---|---|
publisher (required) | path | string | The publisher slug. |
format (required) | path | string | The spec slug. |
Returns PublicSpecItem. Errors: missing_key, unknown_key, revoked, unpaid, inactive, not_found, daily_limit, burst, unavailable.
GET /api/v1/usage
Your calls per UTC day across all your keys, with today’s count and your limits. Doesn’t count against the daily limit..
| Parameter | In | Type | Description |
|---|---|---|---|
from | query | string (date) | First UTC day (YYYY-MM-DD), no more than 400 days back. Default: 29 days before today. |
to | query | string (date) | Last UTC day (YYYY-MM-DD), no later than today. Default: today. |
Returns PublicUsageItem. Errors: bad_request, missing_key, unknown_key, revoked, unpaid, inactive, daily_limit, burst, unavailable.
GET /api/v1/openapi.json
This document (no key needed).
Returns the OpenAPI 3.1 document.
Errors
Errors are application/problem+json (RFC 9457) with type,title, status and sometimes detail. Thetype URL links to its explanation below.
{
"type": "https://alladspecs.com/api/docs#problem-daily_limit",
"title": "The daily request limit is reached",
"status": 429
}missing_key401- Send your API key as Authorization: Bearer aas_live_…. The Authorization header is missing or isn’t a Bearer key in the aas_live_ format. Send Authorization: Bearer followed by your key.
unknown_key401- This API key is not recognised. No key matches. Check that you copied the whole key; if it still fails, ask us for a new one.
revoked401- This API key has been revoked. This key was rotated or revoked. Use the newest key we sent you, or ask us for a new one.
unpaid402- The subscription for this API key is not active. The plan behind this key needs an active subscription. Renew it, or ask us to move you to the free plan.
inactive403- API access for this consumer is not active. Access for your account is suspended or not approved yet. Contact us.
daily_limit429- The daily request limit is reached. You have used today’s calls. The count starts over at midnight UTC (X-RateLimit-Reset); Retry-After gives the seconds until then.
burst429- Too many requests a minute. More calls in a minute than your key allows, or more than 300 a minute from your IP address across all keys. Wait for the seconds in Retry-After, then slow down.
bad_request400- A query parameter is invalid. A query parameter is invalid; detail names it. Fix the value and retry.
not_found404- No published publisher or spec at this path. No published publisher or spec has that slug. Check the slugs with /publishers.
method_not_allowed405- Only GET is allowed on this path. The API is read-only: use GET.
Response fields
Every listed field is always present unless marked optional; a nullable field isnull when the value isn’t known. Fields of a nested object are shown with dots, for example safe_zone.top_pct.
PublicSource
| Field | Type | Notes |
|---|---|---|
url | string | |
checked_at | string (date-time) | nullable |
verified_at | string (date-time) | nullable |
PublicPublisher
| Field | Type | Notes |
|---|---|---|
slug | string | |
name | string | |
category | string | nullable |
intro | string | nullable |
website_url | string | nullable |
official_docs_url | string | nullable |
logo_url | string | nullable |
logo_credit | object | nullable |
logo_credit.text | string | |
logo_credit.url | string | nullable |
markets | array of string | |
buying_models | array of string | |
spec_count | integer | |
last_verified_at | string (date-time) | nullable |
updated_at | string (date-time) |
PublicSpec
| Field | Type | Notes |
|---|---|---|
id | string (uuid) | |
publisher | string | |
slug | string | |
url | string | |
name | string | |
placement | string | nullable |
media_kind | string | One of: image, video, audio, html5, text |
channels | array of string | One of: social, video, retail_media, display, audio, ctv, dooh |
width_px | integer | nullable |
height_px | integer | nullable |
min_width_px | integer | nullable |
min_height_px | integer | nullable |
size_rule | string | nullableOne of: exact, minimum |
aspect_ratios | array of string | nullable |
orientation | string | nullableOne of: portrait, landscape, square |
max_file_mb | number | nullable |
file_types | array of string | nullable |
max_duration_s | number | nullable |
min_duration_s | number | nullable |
video_codec | string | nullable |
fps | number | nullable |
audio_codec | string | nullable |
audio_channels | integer | nullable |
sample_rate_hz | integer | nullable |
copy_limits | object of integer | nullable |
safe_zone | object | nullable |
safe_zone.top_pct | number | |
safe_zone.bottom_pct | number | |
safe_zone.left_pct | number | |
safe_zone.right_pct | number | |
recommended | object | nullable |
recommended.width_px | integer | optional |
recommended.height_px | integer | optional |
recommended.aspect_ratio | string | optional |
recommended.max_duration_s | number | optional |
recommended.file_types | array of string | optional |
markets | array of string | |
buying_models | array of string | |
platform_spec | array of string | |
extra | object of any | |
example_url | string | nullable |
notes | string | nullable |
lead | string | nullable |
freshness | string | One of: unchecked, current, stale, broken, manual |
published_at | string (date-time) | nullable |
updated_at | string (date-time) | |
sources | array of PublicSource |
PublicSpecSummary
| Field | Type | Notes |
|---|---|---|
slug | string | |
url | string | |
name | string | |
placement | string | nullable |
media_kind | string | One of: image, video, audio, html5, text |
channels | array of string | One of: social, video, retail_media, display, audio, ctv, dooh |
width_px | integer | nullable |
height_px | integer | nullable |
aspect_ratios | array of string | nullable |
markets | array of string | |
buying_models | array of string | |
updated_at | string (date-time) |
PublicPublisherDetail
| Field | Type | Notes |
|---|---|---|
slug | string | |
name | string | |
category | string | nullable |
intro | string | nullable |
website_url | string | nullable |
official_docs_url | string | nullable |
logo_url | string | nullable |
logo_credit | object | nullable |
logo_credit.text | string | |
logo_credit.url | string | nullable |
markets | array of string | |
buying_models | array of string | |
spec_count | integer | |
last_verified_at | string (date-time) | nullable |
updated_at | string (date-time) | |
specs | array of PublicSpecSummary |
PublicMeta
| Field | Type | Notes |
|---|---|---|
api_version | string | One of: v1 |
docs_url | string | |
openapi_url | string | |
counts | object | |
counts.publishers | integer | |
counts.specs | integer | |
updated_at | string (date-time) | nullable |
PublicProblem
| Field | Type | Notes |
|---|---|---|
type | string | |
title | string | |
status | integer | |
detail | string | optional |
PublicMetaItem
| Field | Type | Notes |
|---|---|---|
data | PublicMeta |
PublicPublisherList
| Field | Type | Notes |
|---|---|---|
data | array of PublicPublisher | |
next_cursor | string | nullable |
dataset | object | |
dataset.updated_at | string (date-time) | nullable |
PublicPublisherDetailItem
| Field | Type | Notes |
|---|---|---|
data | PublicPublisherDetail |
PublicSpecList
| Field | Type | Notes |
|---|---|---|
data | array of PublicSpec | |
next_cursor | string | nullable |
dataset | object | |
dataset.updated_at | string (date-time) | nullable |
PublicSpecItem
| Field | Type | Notes |
|---|---|---|
data | PublicSpec |
PublicUsage
| Field | Type | Notes |
|---|---|---|
from | string (date) | |
to | string (date) | |
total | integer | |
limits | object | |
limits.daily | integer | |
limits.per_minute | integer | |
today | object | |
today.date | string (date) | |
today.used | integer | |
today.remaining | integer | |
today.resets_at | string (date-time) | |
days | array of object |
PublicUsageItem
| Field | Type | Notes |
|---|---|---|
data | PublicUsage |