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.

PlanCalls a day
Free10
Starter100
Pro1,000

Successful responses carry these headers; a 429 carries Retry-After:

HeaderMeaning
X-RateLimit-LimitCalls allowed a day.
X-RateLimit-RemainingCalls left today.
X-RateLimit-ResetWhen the day starts over (next UTC midnight), in Unix seconds.
Retry-AfterSeconds 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).

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.

ParameterInTypeDescription
marketquerystringA 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_modelquerystring, up to 64 charactersA buying model such as CPM or Flat fee (any case).
cursorquerystringThe previous page's next_cursor.
limitqueryinteger, 1–500, default 100Items 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.

ParameterInTypeDescription
slug (required)pathstringThe 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.

ParameterInTypeDescription
publisherquerystringA publisher slug.
channelquerystringA channel.One of: social, video, retail_media, display, audio, ctv, dooh
media_kindquerystringA media kind.One of: image, video, audio, html5, text
marketquerystringA 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_modelquerystring, up to 64 charactersA buying model such as CPM or Flat fee (any case).
updated_sincequerystringSpecs updated at or after this ISO 8601 date or date-time (2026-11-01, 2026-11-01T00:00:00Z).
cursorquerystringThe previous page's next_cursor.
limitqueryinteger, 1–500, default 100Items 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.

ParameterInTypeDescription
publisher (required)pathstringThe publisher slug.
format (required)pathstringThe 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..

ParameterInTypeDescription
fromquerystring (date)First UTC day (YYYY-MM-DD), no more than 400 days back. Default: 29 days before today.
toquerystring (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_key 401
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_key 401
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.
revoked 401
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.
unpaid 402
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.
inactive 403
API access for this consumer is not active. Access for your account is suspended or not approved yet. Contact us.
daily_limit 429
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.
burst 429
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.
unavailable 503
The API is unavailable, try again shortly. The API couldn’t reach its data. Retry after a short wait; the call may not have been counted.
bad_request 400
A query parameter is invalid. A query parameter is invalid; detail names it. Fix the value and retry.
not_found 404
No published publisher or spec at this path. No published publisher or spec has that slug. Check the slugs with /publishers.
method_not_allowed 405
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

FieldTypeNotes
urlstring
checked_atstring (date-time)nullable
verified_atstring (date-time)nullable

PublicPublisher

FieldTypeNotes
slugstring
namestring
categorystringnullable
introstringnullable
website_urlstringnullable
official_docs_urlstringnullable
logo_urlstringnullable
logo_creditobjectnullable
logo_credit.textstring
logo_credit.urlstringnullable
marketsarray of string
buying_modelsarray of string
spec_countinteger
last_verified_atstring (date-time)nullable
updated_atstring (date-time)

PublicSpec

FieldTypeNotes
idstring (uuid)
publisherstring
slugstring
urlstring
namestring
placementstringnullable
media_kindstringOne of: image, video, audio, html5, text
channelsarray of stringOne of: social, video, retail_media, display, audio, ctv, dooh
width_pxintegernullable
height_pxintegernullable
min_width_pxintegernullable
min_height_pxintegernullable
size_rulestringnullableOne of: exact, minimum
aspect_ratiosarray of stringnullable
orientationstringnullableOne of: portrait, landscape, square
max_file_mbnumbernullable
file_typesarray of stringnullable
max_duration_snumbernullable
min_duration_snumbernullable
video_codecstringnullable
fpsnumbernullable
audio_codecstringnullable
audio_channelsintegernullable
sample_rate_hzintegernullable
copy_limitsobject of integernullable
safe_zoneobjectnullable
safe_zone.top_pctnumber
safe_zone.bottom_pctnumber
safe_zone.left_pctnumber
safe_zone.right_pctnumber
recommendedobjectnullable
recommended.width_pxintegeroptional
recommended.height_pxintegeroptional
recommended.aspect_ratiostringoptional
recommended.max_duration_snumberoptional
recommended.file_typesarray of stringoptional
marketsarray of string
buying_modelsarray of string
platform_specarray of string
extraobject of any
example_urlstringnullable
notesstringnullable
leadstringnullable
freshnessstringOne of: unchecked, current, stale, broken, manual
published_atstring (date-time)nullable
updated_atstring (date-time)
sourcesarray of PublicSource

PublicSpecSummary

FieldTypeNotes
slugstring
urlstring
namestring
placementstringnullable
media_kindstringOne of: image, video, audio, html5, text
channelsarray of stringOne of: social, video, retail_media, display, audio, ctv, dooh
width_pxintegernullable
height_pxintegernullable
aspect_ratiosarray of stringnullable
marketsarray of string
buying_modelsarray of string
updated_atstring (date-time)

PublicPublisherDetail

FieldTypeNotes
slugstring
namestring
categorystringnullable
introstringnullable
website_urlstringnullable
official_docs_urlstringnullable
logo_urlstringnullable
logo_creditobjectnullable
logo_credit.textstring
logo_credit.urlstringnullable
marketsarray of string
buying_modelsarray of string
spec_countinteger
last_verified_atstring (date-time)nullable
updated_atstring (date-time)
specsarray of PublicSpecSummary

PublicMeta

FieldTypeNotes
api_versionstringOne of: v1
docs_urlstring
openapi_urlstring
countsobject
counts.publishersinteger
counts.specsinteger
updated_atstring (date-time)nullable

PublicProblem

FieldTypeNotes
typestring
titlestring
statusinteger
detailstringoptional

PublicMetaItem

FieldTypeNotes
dataPublicMeta

PublicPublisherList

FieldTypeNotes
dataarray of PublicPublisher
next_cursorstringnullable
datasetobject
dataset.updated_atstring (date-time)nullable

PublicPublisherDetailItem

FieldTypeNotes
dataPublicPublisherDetail

PublicSpecList

FieldTypeNotes
dataarray of PublicSpec
next_cursorstringnullable
datasetobject
dataset.updated_atstring (date-time)nullable

PublicSpecItem

FieldTypeNotes
dataPublicSpec

PublicUsage

FieldTypeNotes
fromstring (date)
tostring (date)
totalinteger
limitsobject
limits.dailyinteger
limits.per_minuteinteger
todayobject
today.datestring (date)
today.usedinteger
today.remaininginteger
today.resets_atstring (date-time)
daysarray of object

PublicUsageItem

FieldTypeNotes
dataPublicUsage