> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting ready for AdCP 4.0

> The capabilities Apostra requires of your sales agent, which become required on 1 February 2027, and what to change so your agent keeps its certification.

AdCP 4.0 removes features many sales agents still depend on: HMAC and Bearer
webhook authentication, `adcp.major_versions`, the exact `format_ids` creative
fields, and, over time, the `get_products` / `create_media_buy` /
`update_media_buy` facades. AdCP 3.2 already carries what replaces them. We
require capabilities, not protocol releases: an agent can deliver a capability
on AdCP 3.2 or 3.3, and what matters is that it supports it well. We read the
capabilities your agent declares and tell you which ones you are missing, and
by when, so you can fix them before 4.0 rather than after it breaks.

> [!NOTE]
>
> Nothing here is enforced before 1 February 2027. Until a capability's date,
> your readiness does not change your certification, block a buy, or affect how
> buyers reach you. Canonical creative formats, Reliable Reporting, the compact
> lifecycle and webhook signing are all required from 1 February 2027. Canonical
> creative formats were due on 1 December 2026 until Apostra moved them on
> 15 November 2026. From its date, a sales agent that lacks a
> capability with a date in the "Must from" column loses its certification that
> day, including an agent certified earlier.

## Which AdCP release should I build on?

If you are updating your agent now, build on AdCP 3.2. That way you upgrade
once instead of twice.

* **AdCP 3.1** is enough for today's checks and for canonical creative
  formats, which are required from 1 February 2027.
* **AdCP 3.2 or later** is needed for the compact lifecycle, which is required
  from 1 February 2027. We certify the compact lifecycle only for an agent that
  lists 3.2 or later in `adcp.supported_versions` (see
  [Use cases](https://docs.apostra.com/v3/certification.md#use-cases)). An agent that stops at 3.1 has to
  upgrade again before that date.

AdCP 3.2 is a released AdCP version, not a draft. List every release your agent
speaks in `adcp.supported_versions`, for example `["3.1", "3.2"]`, so buyers
still on 3.1 can keep calling you (see
[Release versions](https://docs.apostra.com/v3/adcp-4-readiness.md#release-versions-supported_versions)).

## The schedule

Every capability is a **should** today. A should with a date becomes a
**must** on that date. A should without a date is advice with no deadline:
certification and buying are unaffected while your agent lacks it.

| Capability | Today | Must from |
| - | - | - |
| Reliable Reporting | Should | 1 February 2027 |
| Compact lifecycle | Should | 1 February 2027 |
| Canonical creative formats | Should | 1 February 2027 |
| Webhook signing | Should | 1 February 2027 |
| Release versions | Should | No date |
| Request signing | Should | No date |
| Operator identity | Should | No date |

The compact lifecycle's 1 February 2027 date will be confirmed in mid-December
2026; the other dates are firm.

If we require another capability, it will appear in this table, with its date,
before it is enforced.

A **must** means proven, not declared. From its date, a capability with a date
that we have not yet proved counts as missing. We prove each one
differently:

* **Reliable Reporting:** a complete, valid declaration passes.
* **Webhook signing:** a valid declaration passes, unless the callbacks you sign
  with RFC 9421 are being refused (see "Webhook signing" below).
* **Canonical creative formats:** we have read your products, and every one
  carries canonical `format_options`.
* **Compact lifecycle:** you pass our compact-lifecycle certification.
  Declaring the tools is not enough, and that certification is not available
  yet.

**Agents certified before a capability's date lose their certification on that
date** if they lack that capability. They do not keep it until their next
certification run. To keep it, have the capability in place, and declared,
before then. From 00:00 UTC on a capability's date (1 February 2027 for all
four), an agent we have
found lacking it has no passing certification result, whatever its use cases
show, and everything that needs a pass treats it as not certified. See
[What a pass unlocks](https://docs.apostra.com/v3/certification.md#what-a-pass-unlocks) for what that
covers. We re-check every agent at least once an hour, so a capability you add
counts, and one we newly find missing stops counting, within about an hour of
the Agent page showing it. We read the capabilities we last stored, and
**Capabilities last read** on the Agent page shows when. Certification is what
unlocks the Successful transaction go-live step; see
[What a pass unlocks](https://docs.apostra.com/v3/certification.md#what-a-pass-unlocks).

## Where you see it

* **Agent page, Overview tab.** A sales Agent that lacks a capability with a
  must date shows a notice that names each missing capability and its date. An
  Agent that has them all but is not ready for 4.0 shows a shorter notice. Both
  link to this page. A ready Agent shows nothing.
* **Agent page, Test Agent tab.** The full verdict: every check, whether it
  passed, whether it is a should or a must and from when, what we found, and
  what to change for each check that failed.
* **API.** Read your Agent with `get` (`kind: "agent"`); the verdict is in
  `adcpReadiness`. Each check carries `requirement` (`SHOULD` or `MUST`) and
  `mustFrom` (a `YYYY-MM-DD` date, or `null`), and `datedGaps` lists the
  dated checks you are missing: those that failed, and, from their date, those
  we have not yet proved (`status` is `null`).

Only your organization and Apostra staff, including support acting for your
organization, see it. There is no verdict until we
have read your capabilities at least once (`adcpReadiness` is `null`), and
nothing is enforced against an agent we have never read.

## The verdict

| Verdict | When | What it means for you |
| - | - | - |
| `LACKS_DATED_CAPABILITY` | A check with a must date shows `FAILED`, or, from that date, `null`. | You lose your certification on the earliest of those dates unless you fix them. `datedGaps` names each one. |
| `NOT_READY_FOR_4` | No dated check failed, but at least one check has not passed. | Fix each check that shows `FAILED`. A check that shows `null` is declared but not yet tested by us. |
| `READY_FOR_4` | Every check passed. | Nothing to do. |

The verdict follows the schedule, not your AdCP release number. An agent on AdCP
3.3 that lacks Reliable Reporting is flagged, and an agent on 3.2 that has every
dated capability is not.

No agent can reach `READY_FOR_4` yet. The compact-lifecycle check passes only
once you pass our compact-lifecycle certification, which is not available yet.
When the AdCP release that carries the rest of 4.0 ships, we will add its
checks to this page.

Each check in `adcpReadiness.checks` carries the field we read
(`sourceFieldPath`), what we found (`whatWeSaw`), and what to change
(`howToFix`).

## The checks

### Release versions (`supported_versions`)

**What we read:** `adcp.supported_versions`.

**Why it matters:** AdCP 4.0 removes `adcp.major_versions`. Buyers then pin a
release from `supported_versions` alone, so an agent that does not declare it
cannot be called at the right release.

**To pass:** list every release you speak, for example `["3.1", "3.2"]`. List
each one as a release, `MAJOR.MINOR` with an optional prerelease tag such as
`3.3-beta`, as the AdCP schema requires. A patch version such as `"3.2.8"`
fails this check: Apostra reads it as the release 3.2, but a buyer that pins a
release by name may not. Keep sending `adcp.major_versions` as well. AdCP 3.x still requires it, and an agent
that drops it fails the [AdCP 3 requirement](https://docs.apostra.com/v3/agent-requirements.md#adcp-3)
today.

### Reliable Reporting (`reliable_reporting`)

**What we read:** `media_buy.reporting_delivery` and `experimental_features`.

**Required from:** 1 February 2027. This check reads what your agent declares,
whether or not buyers can use Reliable Reporting yet.

**Why it matters:** [Reliable Reporting](https://docs.apostra.com/v3/seller-reliable-reporting-registration.md) is how
a buyer learns, from an authoritative record, whether a report is due,
complete, or late. It is the AdCP 3.2 reporting contract that 4.0 builds on.

**To pass:** declare a complete `media_buy.reporting_delivery` block with
`supported: true` and `reliable_reporting_version: "1.0"`, and list
`"media_buy.reporting_delivery"` in `experimental_features`.

### Request signing (`request_signing`)

**What we read:** `request_signing`.

**Why it matters:** AdCP 4.0 makes signed requests mandatory on every
operation that commits spend. Apostra already signs the requests it sends you;
[Verifying our signed requests](https://docs.apostra.com/v2/authentication.md#verifying-our-signed-requests)
explains how to check them.

**To pass:** declare `request_signing` with `supported: true`,
`covers_content_digest: "required"`, and at least one spend-committing
operation (`create_media_buy`, `update_media_buy`, `buy_products`,
`accept_proposal`, or `control_media_buy`) in `supported_for` or
`required_for`.

### Webhook signing (`webhook_signing`)

**What we read:** `webhook_signing`.

**Required from:** 1 February 2027.

**Why it matters:** AdCP 4.0 removes HMAC and Bearer webhook authentication,
including `webhook_signing.legacy_hmac_fallback`. After that, only webhooks
signed with the AdCP webhook profile can be verified. Reporting webhooks depend
on AdCP 3.3 relaxing their required `authentication` block
([adcontextprotocol/adcp#8176](https://github.com/adcontextprotocol/adcp/issues/8176)).

**To pass:** sign the webhooks you send and declare
`webhook_signing.supported: true`. If you declare `profile`, it must be
`adcp/webhook-signing/v1`. See
[Signing the webhooks you send us](https://docs.apostra.com/v3/seller-webhook-signing.md).

**Declaring is not enough.** We also look at how your signed callbacks fare,
including callbacks sent to your agent's own callback URL. If,
in the last 7 days, we refused at least 3 callbacks signed with RFC 9421 because
their signatures did not verify, the check fails even though you declare
`webhook_signing.supported: true`. It clears when fewer than 3 such refusals
remain in that 7-day window. An accepted callback does not clear it, because we
cannot tell which signing scheme an accepted callback used. We do not
count HMAC refusals, refusals where we could not check the signature
ourselves, or refusals for any other reason, and a repeated refusal counts each
time even though the results list it once with a repeat count. To see each
refusal and its reason, read your
[agent's webhook results](https://docs.apostra.com/v3/agent-webhook-deliveries.md).

### Operator identity (`operator_identity`)

**What we read:** `identity.brand_json_url`.

**Why it matters:** buyers find your signing keys through your `brand.json`.
AdCP 4.0 requires you to declare its URL whenever you sign requests or
webhooks; the well-known fallback no longer applies.

**To pass:** publish a `brand.json` that lists your agent and its `jwks_uri`,
and declare its https URL in `identity.brand_json_url`.

### Compact lifecycle (`compact_lifecycle`)

**What we read:** `media_buy.lifecycle_tools`.

**Required from:** 1 February 2027.

**Why it matters:** the AdCP 3.2 compact lifecycle (`list_products`,
`request_proposals`, `accept_proposal` or `buy_products`, `control_media_buy`)
is the foundation of buying in 4.0. It is not a drop-in replacement for
`get_products`, so we will certify it separately.

**To pass:** implement the compact lifecycle, list the tools you serve in
`media_buy.lifecycle_tools`, and pass Apostra's compact-lifecycle test against
your sandbox; its latest decisive result decides `PASSED` or `FAILED`. Until
Apostra has run that test, a declared lifecycle shows `null`, and from
1 February 2027 that counts as missing. Apostra does not run the test yet.

Passing this test also changes how Apostra buys from you. Apostra calls your
agent through the compact lifecycle once it passes, and keeps using
`get_products` until then, whatever your agent advertises. See
[Certification](https://docs.apostra.com/v3/certification.md).

### Canonical creative formats (`canonical_creatives`)

**What we read:** `media_buy.features.canonical_creatives`, and the AdCP
releases in `adcp.supported_versions`.

**Required from:** 1 February 2027, the same day as the other dated
capabilities. It was 1 December 2026 until 15 November 2026. From that day an agent
without canonical creative formats is not certified, and its Sources stop taking
new buys.

**Why it matters:** AdCP 4.0 removes the deprecated exact `format_ids` fields
([adcontextprotocol/adcp#7629](https://github.com/adcontextprotocol/adcp/issues/7629)).
A canonical creative format is named by a `format_kind` and its `params`, with
no agent URL. Once `format_ids` is gone, an agent that cannot take canonical
formats cannot be told which creative format a buy uses, and its buys and
creative syncs fail.

**To pass:** three steps, in this order.

1. Publish canonical `format_options` on every product. Each option names a
   `format_kind` and its `params`. Only the `format_kind` values AdCP defines
   count: `image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`,
   `video_vast`, `audio_hosted`, `audio_vast`, `audio_daast`,
   `sponsored_placement`, `native_in_feed`, `responsive_creative`,
   `agent_placement` and `custom`. A value of your own, such as `video` or
   `banner`, is not canonical, and that product fails. Keep `format_ids` on your
   products as well, for buyers still on AdCP 3.x.
2. Accept `format_kind` selectors on `create_media_buy` and `sync_creatives`.
3. Declare `media_buy.features.canonical_creatives: true`. Do this last: from
   then on Apostra names creative formats to your agent by `format_kind` rather
   than `format_ids`, so a buy or creative sync your agent cannot read fails.

**Which AdCP release you need:** AdCP 3.1 is enough for this capability. If
you are updating your agent now, build on 3.2 anyway, because the compact
lifecycle needs it from 1 February 2027 (see
[Which AdCP release should I build on?](https://docs.apostra.com/v3/adcp-4-readiness.md#which-adcp-release-should-i-build-on)).

* **AdCP 3.0 only:** you cannot meet this requirement. AdCP 3.0 has no
  `format_kind` or `format_options`, so move to AdCP 3.1 or later.
* **AdCP 3.1, or no release declared:** follow the three steps above, including
  the declaration in step 3.
* **AdCP 3.2 or later:** canonical formats are assumed, so the declaration
  passes unless you declare `canonical_creatives: false`. You still need steps 1
  and 2.

**How we check it today:** two things must hold. Your declaration: an agent
whose highest declared release is 3.2 or later passes unless it declares
`media_buy.features.canonical_creatives: false`, and an agent on an earlier
release, or one that declares no precise release, passes only if it declares
`true`. And your products: every product we
stored must carry canonical `format_options` whose every entry agrees with its
`format_ids`. One product with only legacy `format_ids` fails the whole check,
so a 3.2 agent that publishes only `format_ids` fails, and so does a catalogue
that mixes the two. So does a product we offer without some of its entries (see
"What buyers see meanwhile" below). The finding says how many products need
changing, names up to three of them by product name for each kind of problem,
and says what is wrong, for example that a format option is not a canonical
declaration or that a legacy format in `format_ids` is in no option's
`v1_format_ref`. If your declaration passes but we have not read your products
yet, the check shows `null`, and from 1 February 2027 that counts as missing.

**If your options also carry `v1_format_ref`:** keep it. It tells legacy buyers
which of your `format_ids` an option stands for. List each of the product's
`format_ids` in the `v1_format_ref` of the option it stands for, and list
nothing else there. A ref to a standard AdCP format, one whose `agent_url` is
`https://creative.adcontextprotocol.org`, must describe the same format as its
option: listing the standard `display_300x250_image` under a 728x90 option
fails. A ref to your own agent is your own legacy format, so we do not check it
against the standard formats, even when its id looks like one, such as
`display_300x250` under a `display_tag` option.

**What buyers see meanwhile:** AdCP requires a product's `format_ids` and
`format_options` to describe the same formats, and a buyer on AdCP 3.2 cannot
receive a product where they disagree. We check each entry on its own and
offer the product without the entries that disagree, so the rest of its
formats still reach buyers:

* A format option is left out when it is not a canonical declaration, when it
  sets `canonical_formats_only` and also names a `v1_format_ref`, when it names
  a `v1_format_ref` that `format_ids` does not list, or when that ref describes
  a different format from the option.
* A legacy format in `format_ids` is left out when no remaining option names it
  in `v1_format_ref` or matches it and AdCP cannot read it as a format of its
  own, or when only options that were left out name it. If the product still
  cannot be read, a legacy format no option names or matches is left out even
  when AdCP can read it on its own. For example, an
  `image_carousel` option that sets `canonical_formats_only: true` stays on
  offer, and the `carousel_card` entry in `format_ids` that no option names is
  left out.

A product is left out whole only when none of its options remain, or when what
remains still cannot be read. The `canonical_creatives` finding above names
each product by its name and lists the entries it is offered without, and
Seller Setup's "Interpretable product formats" check does the same. Fix the
declaration so both lists describe the same formats, and the product is
offered in full again.

## How we read your agent

* We read the capabilities we last stored from your `get_adcp_capabilities`
  response, and each block must be valid under the AdCP 3.2 schema to pass. A
  declaration AdCP would reject, such as a Reliable Reporting block missing
  required fields, shows `FAILED`. We never call your agent to compute the verdict.
  `capabilitiesRefreshedAt` says when we last read them. See
  [Keep capabilities current](https://docs.apostra.com/v3/agent-requirements.md#keep-capabilities-current).
* If your Agent backs more than one inventory source, the verdict is for the
  least-ready of them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.