".
> ```
> [tab] Python
>
> The Python SDK ships framework wrappers for Flask and Starlette/FastAPI. Both call into the same `verify_request_signature` and raise `SignatureVerificationError` on rejection. Map that to a 401 with `unauthorized_response_headers`.
>
> A JWKS resolver covers one JWKS, so it's bound to one buyer agent. `CachingJwksResolver` takes that agent's `jwks_uri`. A seller with several buyers keeps one resolver per onboarded agent and picks it by `keyid`. The request carries no agent URL, so the `keyid` → agent index is built from onboarding records (see [Seller walkthrough: buyer-declared accounts](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#seller-walkthrough-buyer-declared-accounts)). `VerifyOptions` also needs the per-request `now` and `operation`, so build it for each request and reuse one replay store:
>
> ```python test=false theme={null}
> import json
> import time
>
> from fastapi import FastAPI, HTTPException, Request
> from adcp.signing import (
> AgentResolverError,
> InMemoryReplayStore,
> StaticJwksResolver,
> VerifierCapability,
> VerifyOptions,
> async_resolve_agent,
> check_key_origin_consistency,
> parse_signature_input_header,
> )
> from adcp.signing.errors import SignatureVerificationError
> from adcp.signing.middleware import (
> unauthorized_response_headers,
> verify_starlette_request,
> )
>
> app = FastAPI()
>
> SIGNING_PROFILE = "3.2" # the profile this endpoint advertises; never read it from the request
> SIG_LABEL = "sig1"
> CAPABILITY = VerifierCapability(
> supported=True,
> covers_content_digest="required",
> supported_for=frozenset({"create_media_buy", "update_media_buy"}),
> required_for=frozenset({"create_media_buy", "update_media_buy"}),
> )
> REPLAY_STORE = InMemoryReplayStore() # one per process; use a shared store across replicas
> NO_KEYS = StaticJwksResolver({"keys": []}) # unknown keyid -> request_signature_key_unknown
> AGENT_INDEX: dict[str, tuple[str, StaticJwksResolver]] = {} # kid -> (agent URL, its keys)
>
>
> async def rebuild_agent_index(onboarded_agent_urls: list[str]) -> None:
> """Run at startup and at least once per revocation polling interval.
>
> Agent URLs come from your onboarding records, never from a request.
> """
> global AGENT_INDEX
> owners: dict[str, list[tuple[str, StaticJwksResolver]]] = {}
> for url in onboarded_agent_urls:
> try:
> res = await async_resolve_agent(url, agent_type="buying")
> check_key_origin_consistency(
> jwks_uri=res.jwks_uri, key_origins=res.key_origins, purpose="request_signing"
> )
> except (AgentResolverError, SignatureVerificationError):
> continue # delisted or misconfigured: the agent drops out of the index
> agent = (res.agent_entry["url"], StaticJwksResolver(res.jwks))
> for key in res.jwks.get("keys", []):
> owners.setdefault(key.get("kid"), []).append(agent)
> # A kid published by more than one agent maps to neither: both fail closed.
> AGENT_INDEX = {kid: agents[0] for kid, agents in owners.items() if kid and len(agents) == 1}
>
>
> def _reject_duplicate_keys(pairs):
> obj = {}
> for key, value in pairs:
> if key in obj:
> raise ValueError(f"duplicate key {key!r}")
> obj[key] = value
> return obj
>
>
> def parse_envelope(body: bytes) -> dict | None:
> """Parse once, strictly (checklist step 14). None means malformed."""
> try:
> envelope = json.loads(body, object_pairs_hook=_reject_duplicate_keys)
> except ValueError:
> return None
> return envelope if isinstance(envelope, dict) else None
>
>
> def mcp_operation(envelope: dict | None) -> str:
> if envelope is None or envelope.get("method") != "tools/call":
> return "" # JSON-RPC protocol methods are matched by protocol_methods_*, not here
> params = envelope.get("params")
> name = params.get("name") if isinstance(params, dict) else None
> return name if isinstance(name, str) else ""
>
>
> def signature_keyid(headers) -> str | None:
> try:
> label = parse_signature_input_header(headers.get("signature-input", ""))[SIG_LABEL]
> except (ValueError, KeyError):
> return None # the verifier reports the precise header error
> return str(label.params.get("keyid"))
>
>
> @app.post("/mcp")
> async def mcp(request: Request):
> body = await request.body()
> envelope = parse_envelope(body)
> operation = mcp_operation(envelope)
>
> if "signature" not in request.headers and "signature-input" not in request.headers:
> if envelope is None:
> raise HTTPException(status_code=400, detail="malformed JSON-RPC body")
> principal = authenticate_fallback(request, envelope, operation) # bearer / API key / mTLS
> if principal is None and operation in CAPABILITY.required_for:
> raise HTTPException(
> status_code=401,
> detail="request_signature_required",
> headers={"WWW-Authenticate": 'Signature error="request_signature_required"'},
> )
> if principal is None:
> return auth_error(request) # AUTH_MISSING, or AUTH_INVALID for a rejected credential
> return await handle_mcp(envelope, principal)
>
> agent_url, jwks = AGENT_INDEX.get(signature_keyid(request.headers), (None, NO_KEYS))
> options = VerifyOptions(
> now=time.time(),
> capability=CAPABILITY,
> operation=operation,
> jwks_resolver=jwks,
> agent_url=agent_url, # copied onto signer.agent_url
> replay_store=REPLAY_STORE,
> label=SIG_LABEL,
> signing_profile_version=SIGNING_PROFILE,
> )
> try:
> signer = await verify_starlette_request(request, options=options)
> if envelope is None:
> # Verified first so step 13 burned the nonce; now reject the ambiguous body.
> raise SignatureVerificationError("request_body_malformed", step=14)
> except SignatureVerificationError as exc:
> raise HTTPException(
> status_code=401,
> detail=exc.code,
> headers=unauthorized_response_headers(exc),
> )
> # signer.key_id, signer.agent_url, signer.verified_at are available for audit.
> return await handle_mcp(envelope, signer)
> ```
>
> `authenticate_fallback`, `auth_error`, and `handle_mcp` stand for your own code, which is why the block is marked `test=false`. Some points the example depends on:
>
> * **Unsigned requests.** `authenticate_fallback` returns `None` for a credential you don't accept. It also has to refuse an operation where signing must be unconditional (the strict posture), and a payload that carries a webhook `authentication` block when you support signing. Those cases get `request_signature_required` too ([Composition with fallback authenticators](/dist/docs/3.2.8/building/by-layer/L1/security#composition-with-fallback-authenticators)).
> * **One strict parse.** The SDK verifier doesn't run the step-14 duplicate-key check, so the example parses the body once with duplicate keys rejected and hands `envelope` to `handle_mcp`. Business logic never parses the body again.
> * **Key rotation.** A `kid` published between rebuilds fails with `request_signature_key_unknown` until the next rebuild, so rebuild at least as often as your JWKS cache TTL. Never fall back to trying every agent's keys.
> * **Blocking fetches.** `StaticJwksResolver` never fetches, which keeps the request path off the network. `CachingJwksResolver(jwks_uri=...)` refetches on a `kid` miss, but it fetches synchronously. If you use it in an async handler, prime it at startup or call `verify_request_signature` through `run_in_threadpool`.
>
> The SDK doesn't derive `signer.agent_url` from the request. It copies the `agent_url` you pass in `VerifyOptions`, and it's `None` when you pass none. `await verify_from_agent_url(request, agent_url, agent_type="buying", operation=..., capability=CAPABILITY)` runs the full discovery chain and fills `agent_url` from the matched `agents[]` entry. It fetches on every call, so pass an agent URL from your onboarding record, never one taken from the request. Always pass `capability`: the default is `VerifierCapability(supported=True)`, which accepts signatures without `content-digest`, and the helper can't set `signing_profile_version`, so it verifies under the 3.1 profile. Pass `revocation_checker` (for example, `CachingRevocationChecker`) if you track revoked keys.
>
> For Flask: swap `verify_starlette_request` for `verify_flask_request` (sync). For non-Starlette ASGI frameworks, call `verify_request_signature` directly.
> [tab] Go
>
> Mount `signing.Middleware` in your `http.Handler` chain. The middleware verifies inbound signatures, populates a `VerifiedSigner` in the request context on success, and writes a `401` with `WWW-Authenticate: Signature error=""` on failure:
>
> ```go theme={null}
> import (
> "net/http"
> "github.com/adcontextprotocol/adcp-go/adcp/signing"
> )
>
> resolver := signing.NewCachingJWKSResolver()
> replay := signing.NewMemoryReplayStore(0 /* default cap */)
> revocation := signing.NewStaticRevocationSource(nil)
>
> mw := signing.Middleware(signing.MiddlewareOptions{
> Resolver: resolver,
> Replay: replay,
> Revocation: revocation,
> OperationResolver: signing.DefaultOperationResolver, // /adcp/
> ContentDigestPolicy: signing.DigestRequired,
> RequiredFor: []string{"create_media_buy", "update_media_buy"},
> })
>
> http.Handle("/mcp", mw(handler))
>
> // Inside handler:
> func handler(w http.ResponseWriter, r *http.Request) {
> v := signing.VerifiedSignerFromContext(r.Context())
> if v == nil {
> // Operation not in RequiredFor and request was unsigned — proceed
> // with bearer auth or whatever fallback you've configured.
> }
> // v.KeyID, v.AgentURL, v.VerifiedAt, v.Algorithm — available for audit.
> }
> ```
>
> For MCP servers: replace `signing.DefaultOperationResolver` with a custom resolver that parses the JSON-RPC envelope and returns the MCP tool name (the equivalent of `mcpToolNameResolver` in the TS SDK).
### Composing signature + bearer auth with `requireAuthenticatedOrSigned`
`requireAuthenticatedOrSigned` bundles the full composition: presence-gated routing (signature auth when headers present, fallback otherwise) plus `requiredFor` enforcement — unauthenticated requests for signing-required operations get `401 request_signature_required` even when no credentials at all are supplied.
```typescript theme={null}
import {
serve,
verifyApiKey,
verifySignatureAsAuthenticator,
requireAuthenticatedOrSigned,
mcpToolNameResolver,
MUTATING_TASKS,
} from '@adcp/client/server';
import { BrandJsonJwksResolver, InMemoryReplayStore, InMemoryRevocationStore } from '@adcp/client/signing/server';
serve(createAgent, {
authenticate: requireAuthenticatedOrSigned({
signature: verifySignatureAsAuthenticator({
capability: { supported: true, required_for: ['create_media_buy'], covers_content_digest: 'required' },
jwks: new BrandJsonJwksResolver(),
replayStore: new InMemoryReplayStore(),
revocationStore: new InMemoryRevocationStore(),
resolveOperation: mcpToolNameResolver,
}),
fallback: verifyApiKey({ keys: { 'sk_live_abc': { principal: 'acct_42' } } }),
requiredFor: [...MUTATING_TASKS],
resolveOperation: mcpToolNameResolver,
}),
});
```
`MUTATING_TASKS` is the full list of spend-committing and state-changing operations exported from `@adcp/client/server` — use it rather than maintaining your own list.
### JWKS resolver options
| Resolver | Use case |
| - | - |
| `StaticJwksResolver` | Fixed set of known buyer keys. Good for dev/testing. |
| `HttpsJwksResolver` | Fetches JWKS from a URL with caching and refresh. |
| `BrandJsonJwksResolver` | Full discovery chain: brand.json → jwks_uri → JWKS. Recommended for production. |
## Step 5: Verify inbound webhooks (buyer / orchestrator)
When sellers send webhooks, verify the signature to confirm authenticity. The webhook profile uses the same RFC 9421 mechanics as request signing but with `tag="adcp/webhook-signing/v1"` and `Content-Digest` always covered (no opt-out).
> [tab] JavaScript/TypeScript
>
> ```typescript theme={null}
> import {
> verifyWebhookSignature,
> BrandJsonJwksResolver,
> InMemoryReplayStore,
> } from '@adcp/client/signing/server';
>
> const jwks = new BrandJsonJwksResolver();
> const replayStore = new InMemoryReplayStore();
>
> app.post('/webhook', async (req, res) => {
> try {
> await verifyWebhookSignature(req, { jwks, replayStore });
> } catch {
> return res.status(401).json({ error: 'invalid webhook signature' });
> }
>
> // Process the verified webhook...
> });
> ```
> [tab] Python
>
> ```python theme={null}
> from adcp.signing import (
> WebhookVerifyOptions,
> BrandJsonJwksResolver,
> InMemoryReplayStore,
> verify_webhook_signature,
> )
> from adcp.signing.errors import SignatureVerificationError
>
> webhook_options = WebhookVerifyOptions(
> jwks_resolver=BrandJsonJwksResolver(),
> replay_store=InMemoryReplayStore(),
> )
>
> @app.post("/webhook")
> async def webhook(request: Request):
> body = await request.body()
> try:
> sender = verify_webhook_signature(
> method=request.method,
> url=str(request.url),
> headers=dict(request.headers),
> body=body,
> options=webhook_options,
> )
> except SignatureVerificationError:
> raise HTTPException(status_code=401, detail="invalid webhook signature")
> # sender.key_id, sender.agent_url available for audit; process the webhook.
> ```
> [tab] Go
>
> ```go theme={null}
> import (
> "github.com/adcontextprotocol/adcp-go/adcp/signing"
> )
>
> // Mount the same Middleware on your webhook receiver, but configure it for
> // the webhook profile — adcp_use="request-signing" (deprecated
> // "webhook-signing" also accepted), Content-Digest required, no required_for
> // gating (webhooks always carry signatures).
> webhookMW := signing.Middleware(signing.MiddlewareOptions{
> Resolver: signing.NewBrandJSONJWKSResolver(),
> Replay: signing.NewMemoryReplayStore(0),
> Revocation: signing.NewStaticRevocationSource(nil),
> Profile: signing.ProfileWebhookSigning,
> ContentDigestPolicy: signing.DigestRequired,
> })
>
> http.Handle("/webhook", webhookMW(webhookHandler))
>
> func webhookHandler(w http.ResponseWriter, r *http.Request) {
> sender := signing.VerifiedSignerFromContext(r.Context())
> // sender.KeyID, sender.AgentURL — process the verified webhook.
> }
> ```
## Step 6: Sign outbound webhooks (seller)
> [tab] JavaScript/TypeScript
>
> Pass a `signerKey` to `createAdcpServer` and the framework signs every outbound webhook automatically:
>
> ```typescript theme={null}
> serve(() => createAdcpServer({
> name: 'My Seller',
> version: '1.0.0',
> webhooks: {
> signerKey: {
> keyid: 'my-seller-webhook-2026',
> alg: 'ed25519',
> privateKey: webhookPrivateJwk,
> },
> },
> mediaBuy: { /* ... */ },
> }));
> ```
> [tab] Python
>
> Sign each outbound webhook with `sign_webhook` and attach the returned headers before sending:
>
> ```python theme={null}
> from adcp.signing import sign_webhook, load_private_key_pem
> import httpx, json
>
> private_key = load_private_key_pem(open("webhook-private-key.pem", "rb").read())
>
> async def post_webhook(url: str, payload: dict) -> None:
> body = json.dumps(payload).encode("utf-8")
> headers = {"Content-Type": "application/json"}
> signed = sign_webhook(
> method="POST",
> url=url,
> headers=headers,
> body=body,
> private_key=private_key,
> key_id="my-seller-webhook-2026",
> alg="ed25519",
> )
> headers.update(signed.as_dict()) # adds Signature, Signature-Input, Content-Digest
> async with httpx.AsyncClient() as client:
> await client.post(url, content=body, headers=headers)
> ```
> [tab] Go
>
> Configure a `Signer` with `ProfileWebhookSigning` and use it via `SignRequest` or its `RoundTripper`:
>
> ```go theme={null}
> priv, _, _ := signing.LoadPrivateKey(webhookPemBytes)
> webhookSigner, _ := signing.NewSigner(signing.SignerOptions{
> KeyID: "my-seller-webhook-2026",
> Algorithm: signing.AlgEd25519,
> PrivateKey: priv,
> Profile: signing.ProfileWebhookSigning,
> })
>
> webhookClient := &http.Client{
> Transport: webhookSigner.RoundTripper(http.DefaultTransport, true /* always cover content-digest for webhooks */),
> }
> // Use webhookClient.Post / .Do to deliver webhooks; signatures are added automatically.
> ```
Publish the webhook signing public key as a JWK with `"adcp_use": "request-signing"`. The webhook verifier still accepts deprecated `"webhook-signing"` keys for backward compatibility, but new signers should use `request-signing`. If you want independent webhook rotation or blast-radius isolation, publish a separate `request-signing` JWK with a webhook-specific `kid`.
## Step 7: Declare the capability
If your seller verifies inbound signatures, declare `signed_requests` (alias `request_signing` in the on-wire schema) in your `get_adcp_capabilities` response so buyers know to sign:
For AdCP 3.2, `covers_content_digest: 'required'` is part of the signing profile rather than an operation-level choice. The operation lists still control where signing is supported, shadowed, or required; they never weaken body binding. Keep `either` or `forbidden` only on an explicitly configured 3.0/3.1 compatibility endpoint.
> [tab] JavaScript/TypeScript
>
> ```typescript theme={null}
> createAdcpServer({
> capabilities: {
> overrides: {
> signed_requests: {
> supported: true,
> required_for: ['create_media_buy', 'update_media_buy'],
> supported_for: ['sync_creatives', 'sync_audiences'],
> covers_content_digest: 'required',
> },
> },
> },
> mediaBuy: { /* ... */ },
> });
> ```
> [tab] Python
>
> ```python theme={null}
> from adcp.server.responses import capabilities_response
>
> class MySeller(ADCPHandler):
> async def get_adcp_capabilities(self, params, context=None):
> return capabilities_response(
> ["media_buy"],
> request_signing={
> "supported": True,
> "required_for": ["create_media_buy", "update_media_buy"],
> "supported_for": ["sync_creatives", "sync_audiences"],
> "covers_content_digest": "required",
> },
> )
> ```
> [tab] Go
>
> ```go theme={null}
> // In your get_adcp_capabilities handler, set the request_signing block on
> // the response builder:
> return adcp.CapabilitiesResponse(adcp.CapabilitiesData{
> SupportedProtocols: []string{"media-buy"},
> RequestSigning: &adcp.RequestSigningCapability{
> Supported: true,
> RequiredFor: []string{"create_media_buy", "update_media_buy"},
> SupportedFor: []string{"sync_creatives", "sync_audiences"},
> CoversContentDigest: "required",
> },
> }), nil
> ```
Buyers call `get_adcp_capabilities` and read `request_signing.required_for` and `supported_for` to know which operations you expect them to sign.
## Key rotation
The JWKS endpoint supports multiple keys simultaneously for zero-downtime rotation:
1. Generate a new keypair with a new `kid`
2. Add the new public key to JWKS (both old and new are published)
3. Update signing configuration to use the new private key
4. After 24–48 hours, remove the old public key from JWKS
For emergency rotation (key compromise), add the old `kid` to `revoked_kids` in your revocation list and rotate to a new key immediately. See [Revocation](/dist/docs/3.2.8/building/by-layer/L1/security#revocation) for the revocation list format.
## Testing
### Conformance vectors
The spec ships legacy-profile wire vectors, dedicated 3.2 wire vectors, and the 3.2 post-parse body-integrity reference-evaluator matrix at `/compliance/latest/test-vectors/request-signing/` (source at `static/compliance/source/test-vectors/request-signing/`). Select fixtures by `signing_profile_version`; the root positive and negative directories are 3.1 compatibility fixtures, not 3.2 conformance cases.
* **Legacy 3.1 positive vectors**: valid signed requests using the legacy binary encoding
* **Legacy 3.1 negative vectors**: invalid requests a 3.1 verifier must reject with the stated error code
* **Profile-3.2 wire vectors**: 3.2 versions of the legacy positive vectors and of the checklist step 2–12 negatives. They sign with `content-digest` covered (except the one negative that tests its absence) and assume a verifier advertising `covers_content_digest: "required"`. The set also includes rejections of malformed RFC 8941 `sf-binary` and malformed authorities.
```bash theme={null}
# Debug a single vector with the matching public key fixture.
# Use "latest" for convenience. Pin and record exact released values for both
# versions when you need to reproduce a verifier debugging run.
VECTOR_VERSION=latest
SDK_VERSION=latest
VECTOR_DIR="$(mktemp -d)"
trap 'rm -rf "$VECTOR_DIR"' EXIT
VECTOR_BASE="https://adcontextprotocol.org/compliance/${VECTOR_VERSION}/test-vectors/request-signing"
curl --fail --silent --show-error \
--output "${VECTOR_DIR}/vector.json" \
"${VECTOR_BASE}/positive/001-basic-post.json"
curl --fail --silent --show-error \
--output "${VECTOR_DIR}/keys.json" \
"${VECTOR_BASE}/keys.json"
npx "@adcp/sdk@${SDK_VERSION}" signing verify-vector \
--vector "${VECTOR_DIR}/vector.json" \
--keys "${VECTOR_DIR}/keys.json"
```
### Grade your verifier
```bash theme={null}
adcp grade request-signing https://agent.example.com/mcp --auth-token $TOKEN
```
### Error codes
When verification fails, return `401` with `WWW-Authenticate: Signature error=""`.
The negative vectors grade `` **byte-for-byte** against the vector's `expected_outcome.error_code`, so a rejection that is correct in substance still fails its vector if the code string differs. Take the code from the taxonomy rather than from memory.
For the codes — with retry semantics for each, and the rules for the `WWW-Authenticate` header itself — see [Transport error taxonomy](/dist/docs/3.2.8/building/by-layer/L1/security#transport-error-taxonomy). Signing-key discovery via `brand_json_url` raises its own `request_signature_brand_*` and `request_signature_key_origin_*` codes, listed under [Discovering an agent's signing keys via `brand_json_url`](/dist/docs/3.2.8/building/by-layer/L1/security#discovering-an-agents-signing-keys-via-brand_json_url).
## Related
* [Security: Signed Requests](/dist/docs/3.2.8/building/by-layer/L1/security#signed-requests-transport-layer) — normative spec with verifier checklist, canonicalization rules, and replay dedup sizing
* [Push Notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks) — webhook setup including signature verification
* [Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent) — full compliance validation including signing conformance
* [Build an Agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent) — SDK setup and storyboard validation
* [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421) — HTTP Message Signatures specification
# Security
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L1/security
AdCP security guide: risk classification for financial operations, webhook HMAC verification, replay prevention, access control, and credential management for production deployments.
> [!WARNING]
>
> **Critical for Production Use**
>
> AdCP handles financial commitments and potentially sensitive campaign data. Implementations managing real advertising budgets must implement the security controls outlined in this document.
> [!NOTE]
>
> **Looking for the *why*?** This page is the normative implementation reference — the rules a compliant agent follows. For the threat model, the layered defense narrative, and a checklist for brand IT and CISOs, see the [Security Model](/dist/docs/3.2.8/building/concepts/security-model).
## Overview
AdCP operates in a high-stakes environment where:
* **Financial transactions** involve real advertising spend
* **Multi-party trust** requires coordination between authenticated agents, publishers, and orchestrators
* **Sensitive data** includes first-party signals, pre-launch creatives, and competitive targeting strategies
* **Asynchronous operations** span multiple systems and protocols
## Risk Classification
### High-Risk Operations (Financial)
These operations commit real advertising budgets:
| Operation | Risk | Primary Threat |
| - | - | - |
| `create_media_buy` | Creates financial commitments | Budget fraud, credential theft |
| `update_media_buy` | Modifies budgets and campaign parameters | Unauthorized modifications |
**Requirements:**
* Short-lived credentials — right-sized to the blast radius of a leaked token. ≤1 hour is a reasonable default for tokens that can commit spend; ≤15 minutes is appropriate for tokens that can commit spend above a material threshold or that cross organizational boundaries. Document and justify the chosen window rather than defaulting to the lowest number.
* Request signing for transaction integrity
* Multi-factor authentication or approval workflows for large budgets
* Full audit trail with immutable logging
### Medium-Risk Operations (Data Access)
These operations access sensitive business data:
| Operation | Risk |
| - | - |
| `get_media_buy_delivery` | Exposes performance metrics and spend data |
| `list_creatives` | Access to creative assets |
| `sync_creatives` | Uploads potentially sensitive creative content |
### Low-Risk Operations (Discovery)
These operations are publicly accessible:
| Operation | Risk |
| - | - |
| `get_adcp_capabilities` | Agent capability discovery |
| `get_products` | Public inventory discovery |
## Webhook Security
AdCP 3.0 unifies webhook signing on the [AdCP RFC 9421 profile](#webhook-callbacks) — the seller signs outbound webhooks with a key published through its operator `brand.json` `agents[].jwks_uri`, and the buyer verifies against that JWKS. When the publisher's `adagents.json` pins `signing_keys[]` for that seller, the pin is authoritative. Nothing secret crosses the wire; identity is cryptographically established the same way it is for inbound requests.
**9421 webhook signing is baseline-required in 3.0.** Any seller that emits webhooks MUST sign them per the [Webhook callbacks](#webhook-callbacks) profile unless the buyer explicitly opts into the legacy scheme below by populating `push_notification_config.authentication`, `accounts[].notification_configs[].authentication`, `sync_principal.configuration.notification_configs[].authentication`, or `sync_agent_notification_configs.notification_configs[].authentication`.
### Legacy HMAC-SHA256 fallback (deprecated, removed in 4.0)
Buyers who need to interoperate with receivers that have not yet adopted the 9421 profile MAY opt in by populating `push_notification_config.authentication.credentials`, `accounts[].notification_configs[].authentication.credentials`, `sync_principal.configuration.notification_configs[].authentication.credentials`, or `sync_agent_notification_configs.notification_configs[].authentication.credentials`. When `authentication` is present on the buyer's request, the seller signs with HMAC-SHA256 using the semantics defined in [Push Notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks#legacy-hmac-sha256-fallback). The legacy scheme is a 3.x-only compatibility affordance; sellers MAY decline to support it, and it is removed in AdCP 4.0.
Normative rules for the legacy scheme when a seller elects to support it:
* **Algorithm**: HMAC-SHA256 only
* **Signed message**: `{unix_timestamp}.{raw_http_body_bytes}` — never re-serialize the JSON
* **Byte-equality invariant**: The HMAC is computed over raw bytes, not over a parsed JSON value. Signers and verifiers MUST compare the bytes on the wire directly; re-parsing and re-serializing a payload — even with matching libraries and compact separators — is not guaranteed to reproduce the signed bytes, because key ordering, unicode-escape policy, and number representation all diverge across serializers (see "Non-canonicalized aspects" below for concrete examples). This scheme does not define a canonical JSON form; the "Canonical on-wire form" and "Verifier input" rules below narrow the most common byte-drift failures on the signer and verifier sides respectively, but do not eliminate byte-level divergence.
* **Canonical on-wire form**: The `{raw_http_body_bytes}` MUST be byte-identical to the bytes the signer puts on the wire as the HTTP body. When the signer constructs the body by serializing a JSON value, it MUST use the JSON compact separators `","` (item separator) and `":"` (key separator) — no whitespace between tokens. The language-level serializers JavaScript `JSON.stringify`, Go `encoding/json` `json.Marshal`, Ruby `JSON.generate`, and Java Jackson `writeValueAsString` produce compact output by default; HTTP clients that wrap them (axios, Go `net/http` with a `json.Marshal`-ed body, Ruby `Net::HTTP` with `JSON.generate`, Java OkHttp with Jackson) inherit those defaults. In Python, `httpx` serializes with compact separators, but stdlib `json.dumps` defaults to `", "` / `": "` and HTTP clients that hand their payload to `json.dumps` without a `separators` kwarg (`requests(json=...)`, `aiohttp`) emit spaced bodies — signers on those paths MUST pass `separators=(",", ":")` explicitly. This enumeration is non-exhaustive; signers MUST verify their HTTP client's actual on-wire serialization (e.g., capture the request body via a proxy or hook) rather than rely on this list. The signature covers the bytes the receiver sees, not the object the signer serialized.
* **Non-canonicalized aspects**: Key ordering, unicode-escape policy, and number representation are NOT canonicalized by this scheme. For numbers in particular, language defaults diverge (`JSON.stringify(1.0)` → `1`, Python `json.dumps(1.0)` → `1.0`, Go `json.Marshal(1.0)` → `1`; floats like `0.1` and scientific notation hit similar cliffs), so a signer that serializes with one library and then re-parses / re-serializes with another before sending can produce signer-verifier drift even with compact separators — the byte-equality invariant above is the only thing that holds the scheme together.
* **Duplicate object keys**: Signers MUST NOT emit duplicate object keys AND MUST reject duplicate-key input from upstream callers before serialization. The signer-side MUST is load-bearing because it is the only place this failure mode can be caught: a signer that silently collapses a duplicate-key payload emits a cryptographically-clean signed frame whose semantics differ from the caller's intent, and the verifier cannot detect the upstream divergence from the wire — the signed bytes look normal. Signer-side conformance is unverifiable on the wire and is expected to be enforced by out-of-band audit / interop testing, not runtime detection (this shape is routine in signing specs; COSE and JOSE use the same pattern). Verifiers MUST reject bodies containing duplicate object keys after HMAC verification succeeds, returning a structured malformed-body error (distinct from a signature-mismatch error — the signature IS valid; the body is malformed). Per RFC 8259 §4, the names within a JSON object "SHOULD be unique" and the behavior of software that receives an object with non-unique names is unpredictable — so two verifiers parsing the same HMAC-valid bytes can disagree on the parsed value. This is a parser-differential attack class (cf. CVE-2017-12635 where one CouchDB parser read `roles=[]` and another read `roles=["_admin"]` from the same signed body). Every body carried on the legacy HMAC webhook scheme is a state-change notification (creative status, media-buy status, governance transitions), so the MUST applies unconditionally to this scheme. The detection MUST use a parser that exposes duplicate keys — a last-wins/first-wins default that silently discards them does not satisfy this requirement. Per-language strict-parse escape hatches for both signer input-validation and verifier body-checking: see [step 14 of the webhook verifier checklist](#webhook-callbacks) for the canonical non-exhaustive enumeration, including the libraries that only *appear* strict by default but silently collapse data-key duplicates. The verifier-side conformance fixture is `duplicate-keys-conflicting-values` in `static/test-vectors/webhook-hmac-sha256.json`, with `expected_verifier_action: "reject-malformed"`. Signer-side conformance fixtures live in the same file under `signer_side.rejection_vectors`: `signer-upstream-duplicate-key-rejection` (top-level), `signer-upstream-duplicate-key-deep-nested` (verifies the signer's check recurses into nested objects, not only top-level keys), `signer-upstream-duplicate-key-array-contained` (verifies the signer's check descends into objects inside arrays — a blind spot in hand-rolled validators that recurse into objects but not array members), and `signer-upstream-duplicate-key-three-deep` (verifies the walker does not halt at a shallow fixed depth). A positive-case fixture `signer-upstream-clean-input` lives under `signer_side.positive_vectors` so that a signer rejecting everything does not trivially pass the negative fixtures — interop harnesses MUST assert both rejection of the duplicate-key inputs and acceptance of the clean input. Signers that surface upstream-input rejections via logs or error responses MUST apply the same key-name sanitization rules defined in [step 14b of the webhook verifier checklist](#webhook-callbacks) (truncate at first non-printable to ``, truncate to last UTF-8 codepoint at or below 32 bytes, cap count at 4) — the signer-side channel has the same attacker-controlled-byte shape as the verifier-side channel, just with the direction of trust inverted. **Error identifier is normative; error-object internals are not.** When a signer surfaces the rejection via an error, the error identifier (error-code string in a discriminated union, exception class name in typed-throw idioms, tag in a sum type) MUST be `duplicate_key_input` exactly — case-sensitive, no prefix or suffix — so that multi-SDK integrations can write `if (error.code === 'duplicate_key_input') { ... }` and have the dispatch work regardless of which SDK signed the frame. The internal shape of the error carrier (field names for the sanitized key list, overflow-marker string, typed-exception constructor arguments) is implementation-defined. Verifiers that crash / fail-closed are conformant-but-suboptimal (the request is not silently accepted, but senders receive no actionable error code); verifiers SHOULD return a structured malformed-body error instead. The non-conformant failure mode — silent accept where the signature verifier's parse diverges from the downstream business-logic parse — is now forbidden; a verifier that does not detect duplicate keys before handing the payload to business logic does not conform to this scheme.
* **Verifier input**: Verifiers MUST use the raw HTTP body bytes as received on the wire, captured before any JSON parse or re-serialize. Every modern HTTP framework exposes a pre-parse raw-body hook (Express `express.raw()`, FastAPI `Request.body()`, aiohttp `Request.read()`, Go `io.ReadAll(r.Body)` before `json.Unmarshal`). The raw-capture hook MUST run before any JSON-parse middleware on the same route; a globally-mounted `express.json()` or FastAPI `BaseModel` body binding that consumes the request body before the verifier runs leaves the verifier operating on a re-stringified payload, not the signed bytes — this is a common deployment mistake. Verifiers SHOULD NOT re-serialize a parsed payload to reconstruct the signed bytes: re-serialization silently fails against signers whose output differs in key order, unicode escapes, or number formatting, and masks signer bugs the verifier should surface. A verifier that genuinely cannot capture raw bytes MUST fail closed and surface the infrastructure gap rather than accept a re-serialized approximation.
* **Timestamp source**: The `{unix_timestamp}` in the signed message MUST be the exact ASCII integer sent in the `X-ADCP-Timestamp` header. Signers and verifiers MUST NOT derive it from any body field.
* **Timing-safe comparison**: MUST use constant-time comparison (e.g., `timingSafeEqual`)
* **Replay window**: Reject requests where `|current_time - timestamp| > 300` seconds
* **Minimum secret length**: 32 bytes
* **Header format**: `X-ADCP-Signature: sha256=` and `X-ADCP-Timestamp: `. Receivers MUST ignore any deprecated body-level `signature` field when authenticating the delivery; the headers are authoritative.
**Verification order** (legacy scheme):
1. Reject if `X-ADCP-Signature` or `X-ADCP-Timestamp` header is missing
2. Reject if timestamp is non-numeric
3. Reject if timestamp is outside the 5-minute window
4. Compute and compare HMAC
**Secret rotation** (legacy scheme):
* Receivers MUST accept signatures from both current and previous secret during rotation
* Rotation window SHOULD NOT exceed the replay window (5 minutes)
* Publishers begin signing with the new secret immediately upon rotation
### Webhook URL validation (SSRF)
Any URL that a buyer, seller, or governance agent provides for another party to fetch is an SSRF vector. This includes `push_notification_config.url`, `accounts[].notification_configs[].url`, `sync_principal.configuration.notification_configs[].url`, `sync_agent_notification_configs.notification_configs[].url`, `accounts[].governance_agents[].url` (the seller fetches this when it calls `check_governance`), collection-list `webhook_url`, TMP provider `endpoint`, `adagents.json` `authoritative_location`, and `reporting_bucket.setup_instructions`.
Account-level webhook subscribers registered through `sync_accounts.accounts[].notification_configs[]` and agent-level subscribers registered through `sync_principal.configuration.notification_configs[]` or `sync_agent_notification_configs.notification_configs[]` also require endpoint ownership proof before activation. SSRF validation proves the seller is not calling an internal network address; it does not prove the buyer controls the public HTTPS endpoint. Sellers MUST complete an RFC 9421-signed activation challenge or equivalent proof-of-control before treating a new or changed active subscriber as active. Account-level challenge signatures bind the account, subscriber ID, exact normalized webhook URL through the covered `@target-uri`, expiry through the signature's `expires` parameter, delivery auth metadata, and normalized event type set; the receiver MUST verify every binding before echoing the single-use nonce. Paused subscribers (`active: false`) may skip only the outbound proof challenge while inactive; sellers MUST still enforce URL parsing, HTTPS, hostname normalization, and reserved-range rejection at write time, and paused subscribers MUST NOT receive fires until reactivated. Account-level challenges use [`webhook-challenge.json`](https://adcontextprotocol.org/schemas/3.2.8/core/webhook-challenge.json) and bind `account_id`; agent-level challenges use [`agent-webhook-challenge.json`](https://adcontextprotocol.org/schemas/3.2.8/core/agent-webhook-challenge.json) and bind `scope: "agent"` instead of an account.
Before any outbound fetch to a counterparty-controlled URL, fetchers MUST:
1. **Reject non-HTTPS URLs** in production.
2. **Resolve the hostname** and reject the fetch if the resolved IP falls in any reserved range:
* IPv4: RFC 1918 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), RFC 6598 CGNAT (`100.64.0.0/10`), loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16` — explicitly includes `169.254.169.254` used by AWS/GCP/Azure/Alibaba instance metadata), broadcast (`255.255.255.255`), `0.0.0.0/8`, multicast (`224.0.0.0/4`).
* IPv6: loopback (`::1`), unique-local (`fc00::/7`), link-local (`fe80::/10`), IPv4-mapped (`::ffff:0:0/96` — the most common bypass, mapping reserved IPv4 into IPv6), multicast (`ff00::/8`), and the AWS IMDSv2 fd00:ec2::254 address.
3. **Pin the connection to the validated IP.** DNS-based filtering alone is vulnerable to DNS rebinding: an attacker serves a public IP at validation time and a private IP at connect time. Fetchers MUST pin the connection. **Preferred**: (a) pass the validated IP directly to the TCP connect call and set the `Host:` header from the URL. **Fallback** (only when the HTTP client cannot accept a pre-resolved IP): (b) validate the socket's post-handshake peer address against the reserved-range list before sending any request body. Note: (b) depends on the client library exposing a peer-address hook that fires before the first body byte ships; many common libraries do not, so implementations choosing (b) MUST verify the hook in testing. Re-resolving DNS without pinning is not sufficient.
4. **Refuse to follow redirects** when fetching counterparty-controlled URLs (a 30x response lets the origin redirect to a reserved address that bypassed the initial check), except for two domain-derived well-known fetches. The initial `/.well-known/brand.json` fetch follows only between the original hostname and its exact `www` counterpart, HTTPS on the original port, for at most 3 hops. The initial `/.well-known/adagents.json` fetch follows only within the original registrable domain (eTLD+1), HTTPS-preserving, for at most 3 hops. Both exceptions are anchored on the original request and re-validate steps 1–3 on every hop. Explicit URLs — including either file's `authoritative_location`, `identity.brand_json_url`, JWKS, revocation lists, and webhook callbacks — MUST use zero redirects.
5. **Cap response size and timeouts.** Recommended: 5 MB body cap, 10 s connect, 10 s read. The only exception is the dereferenced authoritative file in the managed-network indirection pattern — second-hop only, after a pointer file's `authoritative_location` redirects to the network origin — which uses a recommended 20 MB cap because it fans out across a publisher network. Pointer files themselves stay at 5 MB. See [managed networks security](/dist/docs/3.2.8/governance/property/managed-networks#security-considerations).
6. **Do not echo fetch errors to the agent that supplied the URL.** Detailed error messages (connection refused vs. timed out vs. TLS failure) are a side-channel for probing internal network topology.
#### Destination port: permissive by default
Publishers SHOULD NOT enforce a destination-port allowlist on counterparty-supplied URLs (`push_notification_config.url`, collection-list `webhook_url`, TMP provider `endpoint`, etc.) by default. The URL contract is `format: "uri"` only; the protocol does not constrain ports. Buyers legitimately host webhook receivers on non-standard TLS ports — Tomcat default `:9443`, Spring Boot default `:4443`, path-routed multi-tenant gateways, and per-tenant subdomains-with-port carve-outs — and a default port allowlist silently rejects them with no recourse short of asking the publisher operator to widen the list.
The SSRF guard the protocol relies on is the **IP-range check + DNS-rebinding-resistant connect pin** in steps 2–3 above, not port filtering. The reserved-range check covers the realistic SSRF threat (smuggling traffic to internal services on `10.0.0.0/8`, `127.0.0.0/8`, `169.254.169.254`, etc.); port filtering on top of a routable public IP is a marginal defense whose cost (rejecting conformant buyers) typically exceeds its benefit.
Operators who want a destination-port allowlist as defense-in-depth — for example, locked-down enterprise environments where the publisher's egress firewall already restricts outbound ports — SHOULD opt in explicitly via SDK or deployment configuration, with `{443, 8443}` as a reasonable hardened-mode starting point. SDKs that ship a `DEFAULT_ALLOWED_PORTS` constant MUST default it to "no restriction" and surface `{443, 8443}` as an opt-in profile, never as a default. Sellers that activate hardened mode MUST document the allowed-port set in their operator-facing documentation so buyers can size their integration before discovering the constraint at first-webhook-delivery time.
The wire-level URL contract is **unconstrained beyond `format: "uri"`**; hardened-mode port filtering is an operator-side policy choice, not a protocol-side requirement.
Feature-specific security sections extend these rules with their own lifecycle and content-handling requirements:
* [Offline reporting buckets](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting#security-considerations-for-offline-delivery) — IAM-layer prefix scoping, credential revocation on account status change.
* [Collection lists](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#security-considerations) — `auth_token` scope and revocation, distribution-ID validation, webhook signature normative rules.
* [Managed networks `authoritative_location`](/dist/docs/3.2.8/governance/property/managed-networks#security-considerations) — validator fetch semantics, change detection, relationship termination.
* [TMP provider registration](/dist/docs/3.2.8/trusted-match/specification#provider-registration-security) — dynamic registration authentication, router-to-provider auth, `/health` info-leakage rules.
## Portable attestations
Portable attestations let one agent reference an independently issued claim without making the presenter or AdCP the trust authority. A seller or governance agent publishes what it will evaluate through `get_adcp_capabilities.adcp.attestations`; a presenter supplies an `AttestationReference`; the evaluator resolves and verifies the credential under its own policy.
The evaluator is always the **verifier-of-record**. A presentation is a locator and claim hint. It is not proof, a routing instruction, or permission to fetch an arbitrary URL. RFC 9421 request signing authenticates the presenting agent and protects the request in transit, but it does not prove the presented claim.
### Data model and separation
Implementations MUST keep three layers distinct:
1. **Presentation** — the portable reference supplied by a buyer or another agent.
2. **Credential** — the issuer-signed claim found through the reference or supplied as an embedded proof.
3. **Evaluation** — the receiving seller's or governance agent's result after applying its trust policy.
The shared schemas are [`attestation-reference.json`](https://adcontextprotocol.org/schemas/3.2.8/core/attestation-reference.json), [`attestation-issuer.json`](https://adcontextprotocol.org/schemas/3.2.8/core/attestation-issuer.json), [`attestation-subject.json`](https://adcontextprotocol.org/schemas/3.2.8/core/attestation-subject.json), and [`attestation-evaluation.json`](https://adcontextprotocol.org/schemas/3.2.8/core/attestation-evaluation.json).
Every presentation identifies an issuer, an open URI-namespaced `claim_type`, a typed subject, and at least one delivery path:
| Path | Presentation fields | Evaluator behavior |
| - | - | - |
| HTTPS credential | `locator.type: credential_uri` + `credential_uri` | Match the URI's canonical origin to the accepted issuer's `credential_origins` before DNS resolution or any request. |
| Issuer credential ID | `locator.type: issuer_credential_id` + `credential_id` + `resolver_id` | Resolve `resolver_id` to a URL from the evaluator's own capability configuration, then send the fixed resolver request defined below. The presentation never carries the resolver URL. |
| Embedded credential | `embedded_credential.format` + `embedded_credential.value` | Enforce the advertised byte limit before parsing, then verify the supported format locally or through an accepted verifier. |
A presentation MAY carry both a locator and an embedded credential. In that case `content_digest` is REQUIRED, the evaluator MUST obtain both representations, and the exact bytes of each MUST independently match that digest before either is trusted. It MUST verify both credentials under the same proof-format and issuer rules. A missing, unverifiable, or mismatched representation is a hard failure; the evaluator MUST NOT select the representation that passes or fall back to an unpinned body. `credential_version` and `validity_hint` are planning hints only; the credential is authoritative for version, validity, scope, and revocation.
For a resource subject, `subject.content_digest` optionally pins the content or immutable snapshot the credential is about. It is part of the complete typed subject comparison. It is distinct from the presentation-level `content_digest`, which pins credential bytes.
Issuer and claim identifiers are open vocabularies. An evaluator listing them expresses only its own policy; it is not an AgenticAdvertising.org endorsement or a global trust registry.
The presenter MAY nominate `verify_agent.agent_url`, but it MUST match `accepted_verifiers[]` after [URL canonicalization](/dist/docs/3.2.8/reference/url-canonicalization). The evaluator MAY use that verifier, another accepted verifier, or local verification. It MUST NOT call an off-list presenter-supplied endpoint.
### Normative evaluation procedure
For every presentation, an evaluator MUST perform these steps in order:
1. **Validate without network access.** Reject malformed issuer, subject, locator, proof format, and digest fields. JSON inputs MUST be strict-parsed with duplicate object keys rejected before JCS, digest computation, schema validation, or field extraction; a last-key-wins or first-key-wins parser is insufficient.
2. **Apply the capability allowlist.** Match the canonical issuer, claim type, delivery method, proof format when known, and nominated verifier. Reject an untrusted issuer, resolver, credential origin, or verifier without an outbound request.
3. **Select delivery.** For `credential_uri`, validate the canonical origin against the issuer capability. For `issuer_credential_id`, map `resolver_id` through that capability. For embedded delivery, enforce `max_embedded_credential_bytes` before parsing.
4. **Resolve safely when needed.** Apply the fetch contract below to the evaluator-selected URL.
5. **Verify the credential deterministically.** Confirm proof/signature integrity, issuer identity, claim type, complete typed subject, claim scope, validity period, and revocation state. Verify `content_digest` before using credential contents. Cryptographic verification, issuer-key authorization, canonicalization, equality checks, and outcome selection MUST run in deterministic code rather than an LLM. Credential bytes and resolver responses MUST NOT be placed in an LLM context before these checks; an LLM MAY assist a later policy workflow but cannot establish a `verified` outcome.
6. **Apply local trust policy.** A cryptographically valid credential may still be unacceptable for this claim, subject, jurisdiction, action, or time.
7. **Emit a stable outcome.** Never convert resolution or policy failure into success merely because the presenter asserted the claim.
8. **Bind the result.** Carry the exact presentation digest and action binding in the domain result or readback that relied on it.
### Attestation resolution fetch contract
For `issuer_credential_id`, the resolver transport is fixed: `POST` to the evaluator-configured resolver URL with `Content-Type: application/json` and a strict JSON body whose only member is `{"credential_id":""}`. The credential ID MUST NOT be interpolated into the URL path or query. Credential-URI fetches carry no Authorization header or cookies. Resolver authentication, when configured as `evaluator_managed`, is loaded by the evaluator and sent only to the exact configured resolver endpoint; credentials from the incoming task, a credential response, or another origin MUST NOT be forwarded.
Before every credential or resolver request, evaluators MUST:
1. Require HTTPS and reject userinfo, fragments, and non-HTTPS schemes.
2. Match the canonical credential origin or configured resolver ID to `accepted_issuers[]` before DNS resolution.
3. Resolve the hostname and reject private, loopback, link-local, unique-local, CGNAT, multicast, special-use, and cloud-metadata destinations, including IPv4-mapped IPv6 forms.
4. Pin the connection to the validated address, or validate the post-TLS peer address before sending request bytes, to prevent DNS rebinding.
5. Disable redirects and treat every 3xx response as `resolution_failed`. The redirect limit is zero. Authentication headers and cookies MUST NOT be forwarded to any other endpoint.
6. Apply a connect timeout of at most 10 seconds, a read timeout of at most 10 seconds, and a streamed response-body cap of 1 MiB.
7. Keep resolver credentials outside AdCP task payloads and LLM-visible arguments. `authentication: evaluator_managed` means the evaluator loads them from its own secret store.
8. Avoid returning connection-detail differences to the presenter. Map network details to stable outcomes without exposing internal topology.
Before parsing a task that can carry portable attestations, implementations MUST enforce an overall task-body cap of 4 MiB, a maximum JSON nesting depth of 64, and at most 100,000 aggregate object members and array elements. These are whole-task caps, not per-attestation allowances, and apply in addition to the advertised per-credential `max_embedded_credential_bytes` (whose protocol ceiling is 1 MiB). Reject an over-limit body before schema evaluation, JCS, credential extraction, logging of body content, or any LLM-visible processing. An evaluator that advertises `embedded` delivery MUST advertise and enforce `max_embedded_credential_bytes`.
These rules extend the general [SSRF profile](#webhook-url-validation-ssrf). A URL is never authorized solely because it appeared in a signed request.
Resolver access can disclose which buyer, signal, campaign, or claim is being evaluated. Evaluators SHOULD prefer privacy-preserving resolution, send no unnecessary campaign identifiers, disclose resolver access to their operators and users, and bound logs and caches accordingly.
### Issuer signing-key authority
A mathematically valid signature does not by itself establish the `AttestationIssuer` named by the presentation or credential. For each accepted proof format, the evaluator MUST authorize the verification key for that canonical issuer through either (a) the proof format's authenticated issuer-key discovery and binding procedure or (b) an evaluator-managed local trust anchor configured for that issuer and proof format. Unauthenticated key URLs, presenter-supplied keys, and a credential's bare `kid` value are not trust anchors. A credential signed correctly by a key that is not authorized for its claimed issuer has outcome `invalid`, even if the key is trusted for another issuer.
Key discovery is itself part of the proof-format verifier and MUST apply that format's transport, chain, algorithm, key-use, revocation, and freshness requirements. The evaluator MUST bind cached keys to canonical issuer identity and proof format; it MUST NOT reuse a same-named `kid` across issuers.
### Outcomes, action binding, and caching
Stable outcomes are `verified`, `not_found`, `expired`, `revoked`, `invalid`, `unsupported`, `unverifiable`, `untrusted_issuer`, `untrusted_resolver`, `subject_mismatch`, `digest_mismatch`, and `resolution_failed`. Only `verified` means all required credential and policy checks passed.
Every `AttestationEvaluation` requires `reference_digest`, computed as SHA-256 over the RFC 8785 JSON Canonicalization Scheme representation of the complete `AttestationReference`, including an embedded credential. Duplicate JSON object keys MUST already have been rejected before canonicalization. Outcomes based on obtained credential bytes also carry `credential_digest` and `proof_format`, so the digest's byte interpretation is explicit. For dual delivery, `credential_digest` records the resolved bytes while `reference_digest` independently binds the embedded bytes; both representations have already matched the required presentation digest. A domain consumer that relies on the result MUST carry `action_binding` with a domain-defined action type and either an action identifier or canonical action digest.
This produces two independent bindings: `reference_digest` identifies exactly what was evaluated; `action_binding` identifies the governance decision, evidence snapshot, rights decision, or other action that relied on it. Portable credentials SHOULD remain reusable across sellers unless the issuer's model requires a specific audience; the transaction binding belongs to the evaluation result rather than automatically inside every credential.
Evaluators MAY cache results, but cache keys MUST include canonical issuer identity, locator, proof format, and credential or reference digest. Cache lifetime MUST be bounded by the earliest of credential expiry, issuer/verifier key refresh, revocation freshness policy, evaluator policy, and `valid_until`. Trust-policy or revocation changes invalidate prior success.
### Rights-grant attestation profile (3.2)
Rights constraints compose the shared portable-attestation primitive; they do not define a rights-only JWS or trust store. The buyer carries `rights_constraint.attestation_refs[]`, the serving seller remains verifier-of-record, and only the seller produces [`RightsAttestationEvaluation`](https://adcontextprotocol.org/schemas/3.2.8/core/rights-attestation-evaluation.json) readback. A buyer-authored evaluation or the mere presence of a reference has no authorization value.
The rights profile uses these identifiers:
* claim type: `https://adcontextprotocol.org/claims/rights/grant`
* resource subject type: `https://adcontextprotocol.org/claims/subjects/rights-grant`
* action type: `https://adcontextprotocol.org/actions/rights-grant-evaluation`
Each reference MUST use a `brand` issuer exactly equal to `rights_holder`. After URL canonicalization, `subject.namespace` MUST equal `rights_constraint.rights_agent.url`; `subject.id` MUST equal `rights_id`; and `subject.content_digest` MUST equal the constraint's `content_digest`. The digest is `sha256:` plus lowercase-hex SHA-256 of `UTF8(JCS(rights_constraint minus { content_digest, attestation_refs, verification_url }))`. Omitting an optional member is distinct from supplying an empty value. The projection deliberately excludes `verification_url`, which is a deprecated legacy display hint with no fetch or authorization semantics, and includes `ext` plus future grant fields so new serving restrictions cannot be added outside the signed projection.
For AdCP 3.2, every acquired `acquire_rights` response and every reissued `update_rights` constraint MUST carry `content_digest` plus at least one `attestation_refs` entry. The schema keeps them optional only so a 3.2 parser can ingest 3.1 constraints; absence means machine-unverified/informational, never authorized. Multiple references are alternative delivery or proof paths—one current `verified` result is sufficient unless evaluator policy requires more.
The resolved or embedded credential MUST cryptographically protect the exact issuer, claim type, complete typed subject, grant version, validity, and credential identifier. A `verified` result additionally requires authenticated issuer-bound status evidence for that exact credential and grant, an approved constraint, current credential and grant validity, exact digest agreement, and evaluator policy accepting the issuer, proof format, delivery method, jurisdiction, and consuming action. The evaluator MUST bind the actual status-proof verification key through the same exact holder rights-agent JWKS and `attestation-signing` purpose as the credential key; signature validity without that authority check is insufficient. Verified evaluations MUST carry `revocation_checked_at` and `valid_until`; the latter is the earliest credential/grant expiry, revocation-freshness bound, key-refresh bound, and local-policy bound. Missing, stale, swapped, superseded, or unverifiable status cannot produce `verified`. A seller still checks the actual use, country, time, and impression-cap ledger; a grant evaluation cannot prove remaining cap. Partial revocation revokes the old credential and issues a new narrowed constraint/reference rather than leaving the old broad credential valid.
For 3.2 evaluation, `rights_holder` is mandatory and issuer-key authorization chains to that exact BrandRef. Before DNS or any fetch, the evaluator MUST exact-match the holder against its accepted issuer policy; an off-policy holder fails with zero network access. Resolve `rights_holder.domain` using the standard SSRF-safe brand.json contract: HTTPS only, reserved/private/link-local IP rejection before and after DNS, DNS pinning, bounded redirects and response size (256 KiB), deadlines, and negative caching. When `brand_id` is present, select exactly one `brands[]` entry whose `id` equals it; use that entry's `agents[]` when present, otherwise the house `agents[]` fallback. When `brand_id` is absent, the document must unambiguously represent the single brand or house. Select exactly one applicable entry with `type: "rights"`, canonical `url == rights_agent.url`, and exact `id == rights_agent.id`. Never aggregate sibling-brand agents or discover a key from a credential-supplied URL. Resolve JWKS only from the selected entry and bind the actual credential verification key by JWK thumbprint, not `kid` alone. AdCP-agent credential keys use the shared portable-credential purpose `adcp_use: "attestation-signing"`; this is not a rights-only purpose. `response-signing` remains reserved for designated brand-response payloads.
Every seller-produced rights evaluation MUST bind both `action_id == rights_id` and `action_digest == content_digest` under the rights action type and MUST satisfy `reference_digest == sha256(JCS(reference))`. It MUST have `outcome: verified`, and the seller MUST retrieve the byte-identical result from its own local evaluation store keyed by `(evaluated_by, reference_digest)` before relying on it. The `evaluated_by` string is descriptive, not provenance: buyer-authored, foreign-seller, absent-store, and locally mismatched readback all fail closed. This is a reusable evaluation of one exact rights grant, not a serving authorization. The same evaluator may reuse its locally persisted result for another creative carrying the identical unchanged grant until `evaluation.valid_until`; another seller never trusts that readback as its own evaluation. Creative identity, media buy, use, country, delivery scope, and cap state are separate eligibility inputs and MUST be checked at the consuming boundary. The seller persists the exact reference/evaluation pair in creative readback and re-evaluates no later than `evaluation.valid_until`.
Sellers advertise this behavior with `media_buy.rights_attestations.requirement`. Presence requires `adcp.attestations` and the exact rights claim URI in `accepted_claim_types`. `required` makes a current verified result a serving-eligibility condition. `optional` permits a separately established legacy contractual path, but the constraint remains machine-unverified and implementations MUST NOT downgrade to `verification_url`.
Versioned fixtures under `/compliance/{version}/test-vectors/attestations/` cover resolved and embedded credentials, off-policy issuers and resolvers, expiry and revocation, subject and digest mismatch, and resolution failure. Implementations must produce the expected outcome and perform no network access for off-policy cases.
## Authentication Best Practices
### Credential Storage
```javascript theme={null}
// Use secure key management systems
// Never commit credentials to version control
// Use environment variables or secret managers
// Example: Secure credential retrieval
async function getCredentials(agentId) {
// Retrieve from secure storage (AWS KMS, Vault, etc.)
const encrypted = await secretManager.get(`agent/${agentId}/apiKey`);
return decrypt(encrypted);
}
```
### Token Expiration
Use short-lived tokens for high-risk operations:
```javascript theme={null}
const TOKEN_LIFETIMES = {
discovery: 3600, // 1 hour for read operations
financial: 900, // 15 minutes for financial operations
refresh: 86400 // 24 hours for refresh tokens
};
function validateToken(token, operationType) {
const decoded = jwt.verify(token, secret);
const maxAge = TOKEN_LIFETIMES[operationType] || TOKEN_LIFETIMES.discovery;
if (Date.now() - decoded.iat > maxAge * 1000) {
throw new Error('Token expired for this operation type');
}
return decoded;
}
```
## Agent and Account Isolation
Every piece of state — media buys, creatives, idempotency cache entries, session IDs, governance tokens — is scoped to the [account](/dist/docs/3.2.8/reference/glossary#a) that owns it. Cross-account reads MUST return a generic "not found" rather than leak existence. The authenticated [agent](/dist/docs/3.2.8/reference/glossary#a) is how the seller knows *who is calling*; the `account` on the request is *what billing relationship the call is acting on*. Isolation requires both checks.
Sales agents MUST:
1. **Bind on create** — permanently associate each object (media buy, creative, session, etc.) with the account used on the request that created it.
2. **Verify on access** — on every subsequent read or modification, verify the authenticated agent has access to the object's bound account.
3. **Fail closed** — when verification fails, return a generic error (status 403 or 404 is acceptable, but the body MUST NOT distinguish "unauthorized" from "not found" or name the account). Never fall through to the resource query.
See [Accounts & Security — Data Isolation](/dist/docs/3.2.8/media-buy/advanced-topics/accounts-and-security#data-isolation) for the billing-relationship model these rules enforce, and the glossary for the formal definitions of [Account](/dist/docs/3.2.8/reference/glossary#a) and [Agent](/dist/docs/3.2.8/reference/glossary#a).
### The two-step pattern
Every account-scoped request whose schema requires `account` carries an explicit `AccountRef` (via `account_id` for account-id namespaces, or the `{brand, operator}` natural key for buyer-declared accounts). A seller MUST NOT silently replace a missing required `account` with a credential-implied default. For tasks where `account` is optional, omission semantics are task-local and must be documented by that task. Correct isolation is two checks, performed in order:
1. **Auth precheck** — the request's `account` MUST be in the authenticated agent's authorized set. Fail closed with a 403 or a generic "not found" (never "you are not authorized for that account" — that's an existence leak).
2. **Resource query** — filter by the request's `account_id` as the primary key constraint. Not by the whole authorized set — only by the specific account this request is acting on.
```javascript theme={null}
// Two-step: precheck request account is authorized, then scope the query to it.
// authorizedAccountIds is a Set populated once at auth-time, not an Array.
// Set.has() is O(1); Array.includes() is O(n) and scans element-by-element, which
// on large authorized-account sets introduces a timing difference between early
// and late matches that a caller can probe across requests.
async function getMediaBuy(mediaBuyId, requestAccountId, authAgent) {
// Step 1: auth precheck
if (!authAgent.authorizedAccountIds.has(requestAccountId)) {
// Generic error - don't reveal whether the account exists
throw new NotFoundError("Media buy not found");
}
// Step 2: resource query scoped to the specific account
const mediaBuy = await db.mediaBuys.findOne({
id: mediaBuyId,
account_id: requestAccountId // Primary filter
});
if (!mediaBuy) {
// Generic error - same shape as the precheck failure
throw new NotFoundError("Media buy not found");
}
return mediaBuy;
}
```
Filtering by the *whole* authorized set on a by-ID lookup is a regression: a `get_media_buy(X)` issued under account A would succeed for a buy owned by account B if both are in the agent's authorized set. The request-supplied `account_id` is what ties a lookup to the caller's *stated* intent.
### Row-Level Security
The most common isolation failure is **IDOR via joined or nested relations**: a query scopes the primary table by `account_id` but joins or returns fields from a related table (line items, creatives, delivery rows) that was never filtered by the same principal. Defend per-principal at the data layer, not just in handler code, so a bug in one handler cannot punch through the wall:
```sql theme={null}
-- PostgreSQL example
-- app.current_account is set by the auth layer AFTER the precheck above succeeds
CREATE POLICY account_isolation ON media_buys
USING (account_id = current_setting('app.current_account')::uuid);
ALTER TABLE media_buys ENABLE ROW LEVEL SECURITY;
```
For **list endpoints** (`get_media_buys` without an explicit account filter), RLS scopes to the agent's authorized set via a session variable populated at auth time:
```sql theme={null}
CREATE POLICY account_isolation_list ON media_buys
FOR SELECT
USING (account_id = ANY(current_setting('app.authorized_accounts')::uuid[]));
```
### Client-side isolation: cross-principal tool-call confusion
The rules above are server-side enforcement. They protect the seller's data even when a legitimate-but-compromised agent is the caller. The **client-side companion** is the buyer agent's obligation not to let text supplied by principal X drive tool calls that use principal Y's authority.
An LLM-driven buyer agent typically holds credentials for multiple principals at once: several sellers (one credential set per seller) and, inside an agency agent, several brand accounts. Any untrusted string the agent processes — product descriptions returned by a seller, campaign names inherited from a brief, rejection reasons in an error envelope, webhook event bodies — is text sourced from *one* of those principals. If the agent's planning loop can call tools across all of them from a single LLM context, a prompt injected in seller X's text can cause the agent to call `create_media_buy` on seller Y's endpoint, or to spend brand A's budget on brand B's inventory. This is the [confused-deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem) problem at tool-call granularity: the attacker doesn't need to escape the sandbox — the agent's own legitimate authority does the damage.
Operators running LLM-powered AdCP agents MUST apply at least the following controls:
1. **Tag text with its principal of origin.** Every string the LLM context ingests from the network (tool results, webhook bodies, registry documents, creative metadata) MUST be annotated internally with the `{principal_domain, tool_name, response_field}` triple that produced it. Dropping the annotation at ingest time is where this defense dies.
2. **Restrict tool-call targets to the calling principal.** A tool call whose target principal is not the same as the principal that supplied the string(s) driving the decision MUST either (a) be refused, (b) go through a human approval step, or (c) be mediated by an explicit per-principal policy the operator has declared up front. The default MUST be refuse, not allow.
3. **Segregate credential scopes by LLM context.** A single LLM planning loop MUST NOT hold live credentials for principals whose interests can conflict (e.g., two brands competing for the same inventory; a buyer credential and a governance agent's signing key in one context). The scope-segregation is enforced at the process / tool-registration layer, not by instructing the LLM — the LLM MUST NOT have the affordance to misuse.
4. **Log every cross-principal *attempt*, not just successes.** Refusals under rule 2 are the signal operators MUST monitor — a rising refusal rate from a given principal is the earliest detectable sign of an injection campaign targeting your agent.
This threat is distinct from ordinary prompt injection: ordinary injection exfiltrates data or triggers unauthorized tool calls within *one* principal's authority. Cross-principal confusion uses principal X's untrusted text to reach principal Y's authority without the attacker ever holding Y's credentials. The server-side Layer 2 controls above detect the attempt only if principal Y's account isn't already in the buyer agent's authorized set — when it is (the whole point of agency and multi-seller agents), the server sees a legitimate-looking call.
The protocol cannot force this discipline on the client agent. The test for it is operational: every LLM-powered AdCP buyer MUST be able to describe, in writing, which principals can appear together in the same planning context and what gates a cross-principal tool call.
## Time Semantics
AdCP operates across jurisdictions, ad servers, and daypart calendars. Implementations MUST be precise about time or buyers and sellers will disagree about what "delivered by 5pm" meant.
### Timestamp format
All timestamp fields in AdCP requests, responses, and webhook payloads MUST be [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) with an explicit timezone offset.
```
✅ 2026-04-19T10:00:00Z // UTC, recommended
✅ 2026-04-19T10:00:00-04:00 // explicit offset
❌ 2026-04-19T10:00:00 // no offset — ambiguous
❌ 2026-04-19 10:00:00 // not ISO 8601
```
Implementations MUST reject ambiguous ("naïve") timestamps with `INVALID_REQUEST`. Implementations SHOULD use UTC (`Z` suffix) on the wire and convert to local time at the presentation layer.
### Intervals
Any time window in AdCP — flight dates, reporting windows, daypart targeting, idempotency replay TTLs — uses a **half-open interval**: `[start, end)`. The start timestamp is inclusive; the end timestamp is exclusive. A campaign with `start_time: 2026-04-01T00:00:00Z` and `end_time: 2026-05-01T00:00:00Z` runs for April and stops at the first tick of May.
### Daypart targeting
Daypart definitions use either `inventory_local` or a concrete IANA timezone identifier. `inventory_local` evaluates the window in the seller-assigned local timezone of each inventory unit that can deliver the impression; it never means the buyer, account, or server timezone. A concrete IANA identifier evaluates one shared civil-time clock across all targeted inventory. Omission defaults to `inventory_local`; there are no user-, account-, or viewer-timezone aliases on the wire. Entries are independent and may use different clocks.
Sellers MUST validate concrete identifiers against their supported IANA timezone database and MUST NOT silently reinterpret a requested clock. They evaluate each candidate instant after conversion to the selected civil clock, so skipped DST hours match nothing and repeated hours match both occurrences. An unknown identifier is `INVALID_REQUEST`; a valid timezone outside the product's declared support is `UNSUPPORTED_FEATURE` at create or update time. The product-scoped capability rules are defined in [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting#daypart-timezone-semantics).
## Request Safety
### Idempotency
`idempotency_key` is **required on every state-mutating AdCP task request**, except the published 3.x `get_products` compatibility facade, whose request shape keeps the field optional. Guaranteed pure-read tasks leave it optional. Their wrappers MUST tolerate the field when a caller supplies one, but sellers MAY ignore it and execute the read normally; buyers MUST NOT rely on a keyed read returning a byte-stable replay. A seller that voluntarily applies replay semantics to a pure read MUST follow the complete contract below and document that behavior, including its freshness implications. Keys participating in replay are scoped per `(authenticated agent, account)` — they have no meaning across agents on the same seller, across accounts under the same agent, or across sellers.
**Product-discovery migration in 3.2.** AdCP 3.2 adds four compact tools alongside the stable `get_products` facade:
* `list_products` is a naturally idempotent synchronous read. Its key is optional, and a seller MAY ignore one when supplied.
* `request_proposals`, `refine_proposals`, and `decline_proposals` require a key because they can allocate tasks or change proposal state.
* `get_products` remains valid throughout 3.x as a deprecated compatibility facade, and its published request schema keeps the key optional on every arm. A seller MAY ignore a supplied key on a guaranteed side-effect-free synchronous read. Buyers SHOULD supply a key whenever the request may allocate a task, finalize a proposal, or otherwise change observable state. When supplied and the seller declares `adcp.idempotency.supported: true`, the seller MUST apply the replay contract before that effect. If the key is omitted or the seller declares `adcp.idempotency.supported: false`, the buyer has no portable at-most-once retry guarantee after an ambiguous result.
The compact tools reuse legacy implementation paths where useful but are distinct logical operations. A retry MUST keep the same tool name and payload. Reusing a key on another tool is a different payload and returns `IDEMPOTENCY_CONFLICT`; callers must not switch names after an ambiguous failure.
`request_proposals` binds each opaque proposal ID to its full BrandKey (`domain`, optional `brand_id`, and optional `countries[]`) and, when supplied, its seller account. A natural account's operator-unit ID, fixed currency, and sandbox flag are part of that account binding, so distinct advertiser objects do not share an idempotency or proposal namespace. Country arrays are canonicalized as unique uppercase codes in lexical order; the operator unit's mutable display name is excluded from identity. `refine_proposals` and `decline_proposals` resolve that binding before idempotency lookup, require every resolvable ID in a batch to share one binding, and scope the key to the resolved account or BrandKey. Callers do not repeat identity data on those mutation requests, and sellers MUST return the same not-found response for an absent proposal and a proposal outside the caller's principal/account scope. When no ID in a batch resolves, sellers use a principal-local negative-lookup scope; this permits safe replay of an all-`unable` result without creating a cross-account oracle.
This section applies only to AdCP task requests. OpenRTB bid streams have their own semantics (`BidRequest.id` is a transaction ID, not an idempotency key) and are out of scope.
#### Normative seller behavior
Rules 1–10 apply to state-mutating requests and to any optional-key request for which the seller elects or is required to provide replay. A pure read whose optional key is ignored does not create an idempotency-cache entry and is not subject to replay, conflict, expiry, or durability behavior.
1. **Schema validation runs first.** Sellers MUST validate the request against its schema (including presence and format of `idempotency_key` when declared) BEFORE consulting the idempotency cache. A malformed request returns `INVALID_REQUEST` without ever touching the cache — otherwise cache misses become a timing side channel that leaks whether schema validation accepted the key format. Validation errors are never cached (per rule 3).
2. **First call is canonical.** On **task success** (`status: completed` or `status: submitted` for async operations), the seller stores the inner response payload (not the protocol envelope) keyed by `(authenticated_agent, account_id, idempotency_key)` along with a hash of the canonical request payload. **The cache entry is immutable** — replays within the TTL MUST return the originally-cached payload (with `replayed: true`), and state-tracking fields in that payload MUST NOT be refreshed to reflect the resource's current state. This rule applies across both success branches:
* **Async tasks** — the cached response is the `submitted` result containing `task_id`. Even if the async task subsequently completes, fails, or is canceled, a replay MUST return the originally-cached `submitted` response, NOT the current terminal state. The buyer uses the returned `task_id` to observe current state via `tasks/get` or webhook, exactly as it would have on the first call.
* **Synchronous-success tasks** — when the initial response carries state-tracking fields (e.g., `status`, `packages`, `affected_packages` on `create_media_buy`; per-record `status` arrays on `sync_creatives` / `sync_accounts`; resource snapshots on `acquire_rights` / `activate_signal`), replay MUST return the originally-cached payload regardless of intervening mutations to the resource. A media buy that was created with `status: pending_creatives`, then mutated to `canceled` via `update_media_buy`, replays as `status: pending_creatives` — the cached bytes are a historical snapshot of the create-time response, not a current-state read. Buyers MUST consult the resource's read endpoint (`get_media_buys`, `list_accounts`, `list_creatives`, etc.) for current state; see "Buyer obligations" below.
This preserves the byte-stable cache property uniformly and keeps the idempotency layer decoupled from resource lifecycle — sellers don't need to update cache entries when task or resource state changes. The alternative ("refresh state fields on replay") would force every seller to thread the resource state machine through the idempotency cache, multiply the number of valid cache contents for a given key (a single key's replay would no longer be deterministic across calls), and break the canonical-replay invariant the rest of these rules build on. Sellers MUST NOT implement a hybrid where some state-tracking fields refresh on replay and others do not — partial refresh is the worst of both options and is non-conformant.
**Resource deletion does not end the replay window.** The idempotency key record, canonical request hash, and cached response MUST remain available independently of every resource the request created for the full `replay_ttl_seconds`, measured from the successful mutation's durable commit time (`committed_at`). Eviction MUST occur no earlier than `committed_at + replay_ttl_seconds`, even when an operator or later task independently deletes or purges that resource. A `UNIQUE` constraint on an `idempotency_key` column of the resource row alone does not satisfy this requirement: deleting the row would free the key and permit a retry to create a second resource. A replay after resource deletion still returns the historical cached response under rule 4; the buyer then uses the appropriate read task to observe that the resource is gone.
3. **Only unsuccessful operations release their keys.** On any error before a mutation commits — validation, governance denial, transport failure, internal error — the key is **not** stored. A retry re-executes. This matches buyer intent: a retry after a 5xx should try again, not replay a failure. It also prevents a buyer's malformed request from being locked into a key for its full TTL.
`COMMITTED_RESOURCE_PURGED` is the narrow exception to the ordinary error-response rule because it reports a successful write followed by an independent deletion, not an unsuccessful operation or a requested delete operation. When a mutation commits but its affected resource is independently deleted or purged before the seller can durably record the canonical success response, the seller MUST retain a committed-outcome tombstone and canonical request hash until at least `committed_at + replay_ttl_seconds`, return `COMMITTED_RESOURCE_PURGED` with `recovery: terminal`, and return the same terminal outcome with `replayed: true` on equivalent replays without re-executing the mutation. If the canonical success response was already durably recorded, rule 4 takes precedence and the seller returns that historical response even though a current-state read shows the resource is gone. The tombstone MUST be stored independently of the deleted resource. Buyers MUST NOT automatically retry that logical operation with either the same or a fresh key; they MUST first reconcile through the resource read task and seller audit or operator records, and may initiate a new operation only when reconciliation confirms that is intended. Sellers MUST NOT use `CONFLICT` for this case: its transient recovery would instruct the buyer to retry a write that already committed.
4. **Replay returns the cached response.** A subsequent request with the same `idempotency_key` AND an equivalent canonical-form payload (see "Payload equivalence" below) MUST return the stored inner response without re-executing side effects. The seller injects `replayed: true` onto the outgoing protocol envelope at response time — including when replaying a committed-outcome tombstone — and `replayed` is NOT part of the stored inner response or tombstone. Injection at replay time keeps the stored payload byte-stable across replays regardless of envelope changes (new `timestamp`, rotated `governance_context`, etc.). Transport-specific note for MCP: MCP tool responses do not have a separate envelope slot; servers MAY expose `replayed` inside the tool result object itself (e.g., at the top of the structured return) or via a response metadata field. REST and A2A responses use the envelope field directly.
5. **Key reuse with a different canonical payload is a conflict.** Same key, different canonical hash within the replay window MUST be rejected with `IDEMPOTENCY_CONFLICT`. Sellers MUST NOT silently apply the second request.
6. **Expired keys are rejected explicitly.** After `committed_at + replay_ttl_seconds` the seller MAY evict a completed cache entry or committed-outcome tombstone. An unresolved in-flight or reconciliation-required claim is not a completed entry and MUST NOT be evicted merely because this interval elapsed. A request arriving after eviction with a key the seller has seen SHOULD be rejected with `IDEMPOTENCY_EXPIRED` rather than silently treated as new — silent re-execution is exactly the double-booking footgun the key was meant to prevent. Sellers SHOULD allow a ±60s clock-skew window at the TTL boundary (the same tolerance applied to JWS `exp` elsewhere in this document) so that a retry arriving seconds after nominal expiry is still replayed from cache rather than treated as fresh.
**Durability is normative.** The declared `replay_ttl_seconds` is a durability contract, not a best-effort cache hint. Sellers MUST back the idempotency cache with storage that survives process restarts, pod replacements, region failovers, and operator-initiated cache flushes for the declared TTL. In-memory-only stores (plain `Map`, single-process LRU without a backing tier) are non-conformant whenever `replay_ttl_seconds` exceeds process lifetime — which is always true at the 3600 s floor. The consequence of silent eviction below declared TTL is a **displaced-replay window**: the sender legitimately retries with the same `idempotency_key` under a fresh signature nonce (which is how a signed retry is supposed to work — nonces are per-send, not per-event), passes the signature replay check, and finds the app-layer cache empty because the receiver's in-memory state was dropped. The side effect runs twice. Sellers MUST NOT declare a `replay_ttl_seconds` higher than their cache tier can durably honor, and MUST fail-closed (`IDEMPOTENCY_EXPIRED`) rather than fail-open (silent re-execution) when they cannot distinguish "never seen" from "evicted under declared TTL." A seller whose operational reality is "memory-only, lost on pod restart" is required to declare `replay_ttl_seconds` no higher than the shortest guaranteed pod lifetime — in practice, this forces a durable tier.
7. **Replay window is declared, not inferred.** Sellers MUST declare `capabilities.idempotency.replay_ttl_seconds` on `get_adcp_capabilities` (minimum 3600s / 1h, recommended 86400s / 24h, maximum 604800s / 7d). Clients MUST NOT fall back to an assumed default — a seller with no declaration is non-compliant and MUST be treated as unsafe for retry-sensitive operations.
8. **Cache-growth defense.** Sellers MUST apply per-`(authenticated_agent, account)` rate limits on idempotency cache inserts separately from request rate limits, and MUST return `RATE_LIMITED` (see [error taxonomy](/dist/docs/3.2.8/building/by-layer/L3/error-handling#rate-limit-handling)) when the per-agent insert rate exceeds the configured ceiling rather than let the cache grow unbounded. A buyer submitting N fresh keys per second on a cheap success-path operation (e.g., `log_event`) would otherwise force unbounded storage, with amplification proportional to `replay_ttl_seconds` at the 3600 s floor. The natural bound is `inserts_per_hour × replay_ttl_hours ≤ max_cache_rows_per_agent`.
**Recommended ceilings (3.1+):** 60 mutation-cache inserts/sec sustained and 300/sec burst over a rolling 10-second window per `(authenticated_agent, account)`. This starting point is sized against a high-volume launch pattern (≤10 media buys/min × 10 packages × 10 creatives with 3–5× headroom). Operators with steady low-volume traffic MAY tighten below it; operators with larger legitimate bursts MUST raise it rather than silently reject valid mutations. The numeric ceiling is a SHOULD; the rate-limit-and-reject-with-`RATE_LIMITED` behavior is a MUST.
Sellers that voluntarily cache keyed reads MUST give them a separate, seller-defined insert budget so read polling cannot exhaust mutation replay capacity. They MUST document the read budget and window shape, but need not advertise exact ceiling numerics in capability responses. Buyers discover effective ceilings through `RATE_LIMITED` plus `retry_after`.
The ceiling is per `(authenticated_agent, account)` — the same scope as the idempotency key itself (bullet 1) — so a multi-account agency does not have its per-account budgets collapsed into a single shared quota. `RATE_LIMITED` rejections MUST populate `retry_after` (seconds) per the [error handling taxonomy](/dist/docs/3.2.8/building/by-layer/L3/error-handling#rate-limit-handling) and MUST NOT be cached as idempotency responses (rule 3: only successful responses are cached). Sellers SHOULD enforce `retry_after` as a cheap rejection floor — a buyer retrying before `retry_after` elapses SHOULD hit a pre-auth token bucket (e.g., at a reverse-proxy layer) rather than re-entering the full schema-validate-and-cache-check pipeline on every retry. Without this discipline, misbehaving buyers can amplify load on the rate-limiter itself.
9. **Concurrent retries — first-insert-wins.** A second request carrying the same `(authenticated_agent, account_id, idempotency_key)` MAY arrive while the first request is still executing — most commonly when the buyer's transport timeout fires before the seller's downstream call returns, and the buyer retries. Sellers MUST resolve the race deterministically; they MUST NOT execute the side effect twice and MUST NOT silently drop the second request. Resolution is a `(unique constraint, INSERT … ON CONFLICT DO NOTHING)` pattern on the scope tuple: the first row to land owns execution and stores the canonical payload hash on the in-flight row (NOT a sentinel); subsequent requests observe an existing row whose response slot is not yet populated but whose payload hash IS populated.
Sellers MUST handle the second request by one of two policies and MUST behave consistently across calls — clients infer the policy from the first response within a session and apply it to subsequent retries:
* **Wait-and-replay** (preferred for fast operations, \<5s typical): the seller blocks the second request until the first completes, then returns the cached response with `replayed: true`. Total wall-time for the second call is bounded by the seller's request-timeout budget.
* **Reject-and-redirect** (preferred for slow operations involving long-running downstream calls): the seller returns `IDEMPOTENCY_IN_FLIGHT` immediately, with top-level `error.retry_after` (seconds) populated based on the first request's elapsed time and expected completion. Buyers MUST retry with the same `idempotency_key` after the hint elapses — a buyer that mints a fresh key on `IDEMPOTENCY_IN_FLIGHT` turns a safe retry into the exact double-execution race this rule prevents.
A second request with the same key AND a *different* canonical payload during the in-flight window MUST return `IDEMPOTENCY_CONFLICT` (rule 5), not `IDEMPOTENCY_IN_FLIGHT` — the canonical-form mismatch is computable at INSERT time against the row's stored hash, so the conflict is detectable without waiting for the first request's response. Sellers whose backing store cannot persist the real canonical hash until the handler completes (e.g., a placeholder-sentinel pattern) MUST upgrade the store to persist the hash at INSERT time before declaring rule 9 conformance — the alternative (returning `IDEMPOTENCY_IN_FLIGHT` on a same-key-different-payload race and only surfacing the conflict after the first request completes) silently delays detection of a real client bug.
Per rule 3, the seller may release the `(in_flight)` claim only after it has definitive evidence that no local or downstream mutation committed. Schema rejection and errors raised before any side-effecting call are definitive pre-commit failures. A downstream timeout, handler timeout, lost response, process crash, or any other unknown outcome is not proof of failure: the seller MUST retain the durable claim, transition it from active execution to a reconciliation-required state, and MUST NOT invoke the mutation again until reconciliation establishes the outcome. Equivalent retries MAY wait, receive `IDEMPOTENCY_IN_FLIGHT`, or drive the rule-10 reconciliation path; a different canonical hash still returns `IDEMPOTENCY_CONFLICT`. When reconciliation proves non-commit, the seller releases the claim; when it proves commit, the seller records the canonical success response or, after an independent purge, the `COMMITTED_RESOURCE_PURGED` tombstone. Whenever the resource write and idempotency ledger share a transactional boundary, the seller MUST atomically commit the mutation and completed ledger state. Implementations that cannot make that transition atomic MUST use the same fail-closed reconciliation discipline.
Sellers MUST bound the active execution lease to the declared per-task handler timeout so a hung worker can be stopped or replaced. Lease expiry changes the claim to reconciliation-required; it never releases or evicts the claim. Sellers using reject-and-redirect MUST set top-level `error.retry_after` to a value no greater than `replay_ttl_seconds` (declared in `capabilities.idempotency`). Sellers SHOULD also declare `capabilities.idempotency.in_flight_max_seconds` — the maximum active execution lease before reconciliation takes over, scoped to the seller's per-task handler timeout. Buyers SHOULD use that declared value as the primary bound for an individual retry wait when present; when absent, fall back to the order-of-magnitude heuristic (a value derived from the seller's typical handler latency, an order of magnitude below the replay TTL, never the TTL ceiling itself). This value is not permission for a buyer to mint a fresh key or for a seller to release an unresolved claim.
Sellers MUST NOT leak the in-flight state across the scope boundary: an attacker probing a candidate key MUST receive the same response shape and timing whether the row exists, is in flight, or has never existed.
10. **Crossing service boundaries — downstream reconciliation.** Sellers commonly invoke downstream systems during request handling — SSP/ad-server calls on `create_media_buy`, payment-provider calls on billing operations, governance-agent calls on `check_governance`. These calls have their own failure modes that can leave the seller in a "downstream unknown" state: the network connection dropped after the downstream accepted the request but before its response arrived; the seller process crashed mid-call; a region failover swapped the worker before the response was persisted. Rule 3 (only proven pre-commit failures release their claims; completed outcomes become cached successes or committed-outcome tombstones) is necessary but not sufficient: a seller that releases an ambiguous claim and re-executes on retry will double-invoke the downstream and create duplicate side effects there.
**Conformance grading.** This rule is reviewer-graded, not programmatically graded by the compliance storyboard suite. Black-box observation cannot distinguish "the seller has a claim row" from "the seller got lucky on the test run." The `parallel_dispatch_runner` test-kit lists rule-10 conformance under `reviewer_checks` — sellers attesting to rule-10 conformance MUST surface their operational runbook describing which pattern applies to which downstream, and reviewers verify the implementation against that runbook. The other normative rules (1–9) are programmatically graded.
Sellers MUST adopt one of two reconciliation patterns for every downstream call whose duplicate-invocation has business consequences (resource creation, payment movement, irreversible state change). Read-only downstream calls (cache lookups, eligibility checks that don't write) are exempt — but borderline cases like fraud-scoring lookups that also write to a downstream audit log count as writes for this rule (the audit log entry is the side effect).
* **Write-claim-before-invoke (preferred default).** Before invoking the downstream, the seller persists a "claim" row in the same transaction as the idempotency cache row — typically `{idempotency_key, downstream_provider, downstream_request_id, status: 'invoked', invoked_at}` — using the seller-generated `downstream_request_id` it will pass to the downstream as the downstream's own correlation/idempotency identifier. On retry, before invoking the downstream again, the seller MUST look up the claim row by `(idempotency_key, downstream_provider)` and reconcile: query the downstream by `downstream_request_id` to determine the true outcome, then resume cache population from there. The seller MUST NOT treat a missing local record as "downstream call did not happen" — a crash between downstream-accepts and local-persist is exactly the case where it did happen and the local record is missing. If the downstream reports no record of `downstream_request_id` (the claim row was persisted but the seller crashed before invoking), the seller MUST treat the call as not-yet-invoked and proceed with the invocation; the claim row already reserves the `downstream_request_id`, so the downstream's own idempotency will dedup any subsequent retry. On an ambiguous response from the downstream lookup (transient 5xx, network error, malformed response), the seller MUST fail closed — return a transient error to the buyer (so the buyer retries against the same `idempotency_key` per rule 9) rather than proceed with invocation on an unauthenticated "no record" signal.
* **Thread-buyer-key (acceptable when the downstream protocol supports it).** The seller passes a per-downstream-provider derivative of the buyer's `idempotency_key` as the downstream's own idempotency key — typically `HMAC(K_provider, idempotency_key)` where `K_provider` is derived from the seller's KMS-managed root keyed by provider identity (one key per downstream, not one shared seller secret across all downstreams). Per-provider derivation prevents cross-provider replay if any single downstream is compromised; a shared seller secret across all downstreams collapses every provider into a single key-exposure blast radius. The downstream's at-most-once guarantee then covers the case the seller's local persistence missed. The seller MUST still write a claim row on the success path so the cached response can be populated correctly, but the downstream itself becomes the source of truth on retry. The seller MUST NOT pass the buyer's raw `idempotency_key` to any downstream operated by a different trust principal — the buyer's key is a capability token within its TTL (see "Keys are security-sensitive" below) and forwarding it across a trust boundary widens the capability surface. "Different trust principal" means any system the seller does not operate under the same security boundary; passing the raw key to a purely intra-tenant microservice the seller owns end-to-end (same KMS, same audit log, same operator) does NOT cross a trust boundary and is permitted, though per-provider derivation is still the better default.
Sellers MUST document which pattern applies to which downstream in their operational runbook. Sellers MUST NOT use a third pattern of "best-effort dedup on downstream response inspection" — comparing the downstream's response payload to a cached fingerprint to decide whether the call already happened — because the downstream's response shape changes across versions and the fingerprint is a synchronization bug waiting to happen. A claim row OR a threaded key. Not pattern-match-on-response.
Sellers MUST NOT include the buyer's `idempotency_key` (or any reversible derivative thereof) in error envelopes returned to the buyer when those errors originated from the downstream. Downstream errors that mention the seller's per-downstream-provider key (or the buyer's key, if the seller incorrectly threaded it raw) MUST be re-keyed or stripped before propagating to the buyer — otherwise a downstream error message becomes a cross-trust-boundary key-disclosure surface.
The buyer-visible consequence of this rule: when a seller invokes a slow downstream and the buyer retries during the window, the seller's response on the second request is determined by the seller's policy under rule 9 (`IDEMPOTENCY_IN_FLIGHT` or wait-and-replay), not by the downstream's behavior. Buyers do not need to know which downstream is in the path — the seller MUST present a uniform retry surface regardless.
#### Payload equivalence
"Equivalent" means **identical canonical JSON form**, not field-by-field semantic comparison. Sellers MUST determine equivalence by hashing the canonical form and comparing hashes. The canonical form is [RFC 8785 JSON Canonicalization Scheme (JCS)](https://www.rfc-editor.org/rfc/rfc8785) — number serialization, key ordering, and escaping all follow JCS §3 normatively.
**Fields excluded from the hash** (closed list — sellers MUST NOT extend it):
* `idempotency_key` — the key itself
* `context` — buyer-opaque echo data (trace IDs, correlation IDs) changes on retry by design
* `governance_context` — on the envelope; may be a refreshed signed token on retry
* `push_notification_config.authentication.credentials` — may be a rotated bearer token. The URL and scheme remain in the hash; only the credential value is excluded.
Everything else in the request body — including `ext` — is included, and "missing optional field" is NOT equivalent to "field explicitly set to null" (JCS preserves the distinction, and so does the hash). **Buyers MUST NOT place rotating tokens or retry-unstable values inside `ext`.** `ext` is part of the canonical payload; a value that changes between retries will trigger `IDEMPOTENCY_CONFLICT` even when the buyer's intent is unchanged. Rotating credentials belong in the exclusion-list fields above; buyer-side trace data belongs in `context`. Sellers MUST NOT extend the exclusion list via capabilities, config, or extension — the list is fixed by this spec, and drift there silently weakens retry-safety guarantees across the ecosystem. **Any future addition to the exclusion list is a breaking change to payload equivalence** (buyers who put a now-excluded value in `ext` would see previously-distinct retries start deduping against each other), so the list will only grow via a major-version bump with migration notes. New PRs proposing an addition MUST demonstrate why the field is semantically outside the retry contract — not just that a particular buyer happened to rotate it.
**Reference implementation**: `SHA-256(JCS(payload - excluded_fields))`.
* TypeScript / JavaScript: [`@truestamp/canonify`](https://www.npmjs.com/package/@truestamp/canonify) or [`canonicalize`](https://www.npmjs.com/package/canonicalize)
* Python: [`pyjcs`](https://pypi.org/project/pyjcs/) or the reference implementation from [RFC 8785 appendix](https://www.rfc-editor.org/rfc/rfc8785)
* Go: [`gowebpki/jcs`](https://github.com/gowebpki/jcs)
* Rust: [`serde_jcs`](https://crates.io/crates/serde_jcs)
AdCP SDK middleware ships JCS canonicalization so sellers don't roll their own. Rolling your own canonical form is a common source of "works on my machine" idempotency bugs — JCS is precisely specified to avoid that.
#### Server-side tool wrapper conformance
Buyer SDKs and generic transport wrappers may send envelope-level fields admitted by the selected request schema, either as declared properties or through `additionalProperties: true`. Reference SDKs auto-generate `idempotency_key` only for requests they classify as mutating. Servers MUST tolerate schema-admitted fields even when the task handler does not consume them. An explicitly closed schema may reject undeclared fields. Concretely:
* **`idempotency_key`** is required on state-mutating task schemas. Guaranteed pure-read schemas and the 3.x `get_products` compatibility facade may leave it optional, but tool wrappers MUST accept it when the selected schema admits it. A pure-read handler MAY ignore it; a request participating in replay routes it through rules 1–10.
* **`context`, `push_notification_config`, and `governance_context`** MUST be accepted when the selected schema admits them. Tools that do not consume an admitted field MUST ignore it.
* **`context_id` on MCP**, where admitted by the selected request schema, MUST be ignored. It MUST NOT select session state, identity, account, authorization, task continuation, or idempotency scope. A2A conversation continuity uses native Message/Task `contextId`, outside the AdCP task body.
Configuring a server-side validator in a way that contradicts the selected schema's declared properties or `additionalProperties` setting is a conformance violation. Common server-implementation traps:
* **FastMCP / Pydantic with strict signatures** — a tool wrapper declared as `def get_products(brief: str)` raises `unexpected_keyword_argument` when the buyer sends `idempotency_key` inside the same params object. Fix: declare admitted envelope fields as accept-and-ignore optional parameters, or use a `**kwargs` catch-all and discard unknown keys where the selected schema permits them. Pydantic-on-input uses `Extra.allow` or `model_config = ConfigDict(extra='allow')`.
* **Zod / valibot with `.strict()`** on the inbound request schema rejects unknown keys for the same reason; remove `.strict()` on input schemas, or compose with a passthrough variant.
* **OpenAPI-generated server stubs** with `additionalProperties: false` injected by the codegen tool — verify the generated input schema mirrors the spec's `additionalProperties: true` default; some generators flip the default during model emission.
The wire-level invariant is: a buyer SDK MUST be able to send every field admitted by the selected request schema, regardless of whether the task handler consumes it. Request-body `context_id` follows the compatibility rule above. This rule is normative for 3.1+; wrappers that reject schema-admitted fields are non-conformant.
Reference: this rule generalizes the per-validator pattern already established for response-side validators in [`runner-output-contract.yaml` > `response_schema_validator_semantics`](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/universal/runner-output-contract.yaml) — both rules express the same principle ("validator configuration MUST NOT contradict the schema's own `additionalProperties` declaration") on the two ends of the wire.
#### Response-level replay indicator
The protocol envelope carries a top-level `replayed` boolean on responses to any request that resolved via the idempotency cache:
```json theme={null}
{
"status": "completed",
"replayed": true,
"timestamp": "2026-04-18T14:35:00Z",
"payload": {
"media_buy_id": "mb_01HW7J8K9P0Q1R2S3T4U5V6W7X"
}
}
```
`replayed` is produced by the seller's idempotency layer at response time, not stored in the cache. On a fresh execution it is `false` (or omitted — buyers MUST treat omission as `false`). On a cached replay it is `true`; the inner `payload` is byte-for-byte what was stored on the original successful execution. Envelope fields (`timestamp`, `context_id`, etc.) may differ — they describe the current response, not the cached one.
Buyers use `replayed` for:
* **Agent side-effect suppression** — an agent that acts on response data before a human sees it (notifications, downstream tool calls, memory writes) MUST check `replayed` to avoid re-emitting on retry. "Campaign created!" notifications, LLM memory inserts, and downstream agent calls are exactly what silent replay breaks.
* **Side-effect invariants** — downstream systems expecting exactly-once event semantics read `replayed` before treating the response as a new event.
* **Billing reconciliation** — "we processed N buys this month" counts `replayed: false` only.
* **Logging** — distinguishing "retry succeeded by returning cache" from "retry triggered a new execution" (the latter usually signals a bug in the replay window or key management).
* **State-machine routing** — state-tracking fields in the cached `payload` (e.g., `status: pending_creatives` on a replayed `create_media_buy`) are a historical snapshot, not a current-state read (see seller rule 2 and "Replay responses are historical snapshots" under buyer obligations). Buyers MUST re-read via the resource's read endpoint before any state-dependent action.
#### IDEMPOTENCY_CONFLICT response shape
Standard AdCP error envelope. The error body:
* MUST include `code: "IDEMPOTENCY_CONFLICT"` and a human-readable `message`
* MUST NOT include the cached response, the original payload, a canonical-form diff, or any fingerprint derived from them. A `field` json-pointer hint seems harmless but reveals schema shape (e.g., `/packages/0/budget` tells an attacker the victim's payload had a budget in the first package). Sellers MUST NOT emit one. A legitimate buyer debugging a retry can diff their own two payloads — they have both.
```json theme={null}
{
"errors": [
{
"code": "IDEMPOTENCY_CONFLICT",
"message": "idempotency_key was used with a different payload within the replay window. Either resend the exact original payload (to return the cached response) or generate a fresh UUID v4 to submit this new payload.",
"recovery": "correctable"
}
],
"context": { "correlation_id": "..." }
}
```
Leaking cached state turns key-reuse into a read oracle. An attacker who guesses or steals a victim's key could otherwise probe it to infer payload structure. The error body exposes only the code.
#### SI send_message idempotency model
`si_send_message` needs a narrower scope than other mutations because conversational turns advance session state. The key is scoped `(authenticated_agent, account_id, session_id, idempotency_key)`.
* **Retry of turn N within the TTL returns the cached response for turn N**, even if turn N+1 has since been accepted. Idempotency returns what you did, not rewinds what the session is. The buyer's retry is asking "did my message get through" — the answer is still "yes, here's what came back."
* **A new `si_send_message` with a fresh `idempotency_key` is a new turn**, processed against the current session state. Buyers MUST generate a fresh key per logical turn, not per HTTP attempt.
* **If the seller has advanced session state past turn N and cannot reproduce the cached response byte-for-byte** (e.g., the session was pruned for storage), the seller MAY return `SESSION_NOT_FOUND` or `IDEMPOTENCY_EXPIRED` rather than reconstruct. Buyers retrying far past a session timeout should expect this.
#### Buyer obligations
Whenever a buyer sends an `idempotency_key`, it MUST generate a unique key per `(seller, request)` pair. Reusing the same key across sellers allows colluding sellers to correlate requests from the same buyer. Use a fresh UUID v4 for each keyed request. For a state-mutating request, or a read that the seller documents as replay-protected, a retry after a network error MUST resend the exact same payload with the same key — changing either side breaks at-most-once semantics. In particular, buyers MUST NOT change `push_notification_config.url` between retries with the same key; URL is part of the canonical hash and rotating it triggers `IDEMPOTENCY_CONFLICT`. Rotate the key when changing webhook configuration. A pure read has no portable replay guarantee even if its wrapper accepted a key; retry it as a fresh read unless the seller explicitly documents stronger behavior.
**Network retry vs. agent re-plan vs. polling / state re-read.** Three cases that look similar but need different handling:
* **Network retry of a replay-protected operation** — socket timeout, 5xx, transient failure. The buyer has the *same intent* and sent the *same bytes* — and MUST resend them with the *same key*. This is what `idempotency_key` exists for. An ordinary pure read is instead retried as a fresh read because the seller may have ignored its key.
* **Agent re-plan** — the buyer is an agent whose planner re-ran (prompt re-executed, tool output changed, policy re-evaluated) and produced a *different payload*. The intent has changed. The agent MUST mint a *new key* and treat the prior request as abandoned. Reusing the prior key with a different canonical payload returns `IDEMPOTENCY_CONFLICT`, which is the seller correctly telling the agent "you're not retrying, you're doing something new."
* **Polling / state re-read** — a dashboard polling `get_products(brief)`, `list_creatives`, or `list_accounts`; a buyer reading `get_media_buys` after a mutation; any "give me current state at time T" call. Pure reads do not provide a portable keyed-replay guarantee, so buyers SHOULD omit `idempotency_key` and treat each invocation as a fresh read. If a generic wrapper supplies one, mint a fresh key for each poll because some sellers may voluntarily cache keyed reads. Never reuse the mutation's key on its readback request.
For replay-protected operations, ask whether the buyer's intent is **"complete the same operation as before"** (network retry — reuse the key) or **"give me the current answer"** (polling / state re-read — omit the key, or mint a new one if a generic wrapper requires it) or **"do this new thing"** (agent re-plan — mint a new key). Agentic clients that loop through an LLM to build a mutation SHOULD freeze and cache the serialized bytes alongside the key on first send, so retries send the identical payload even if the planner would produce something slightly different on re-execution.
**Bootstrap carve-out — `get_adcp_capabilities`.** The discovery call itself is exempt from any schema-level key requirement. `get_adcp_capabilities` is how the buyer learns whether the seller declares `adcp.idempotency.replay_ttl_seconds`, so a fail-closed rule against the discovery call would deadlock the bootstrap. Buyers MAY omit `idempotency_key`, and sellers MUST accept the call without it. A supplied key may be ignored and does not create a portable replay guarantee. The fail-closed obligation below applies to retry-sensitive mutations once the capability fetch has completed.
**When the seller's capability declaration is missing.** A seller whose `get_adcp_capabilities` response omits `adcp.idempotency.replay_ttl_seconds` is non-compliant. After a successful capability fetch, client SDKs MUST fail closed before any state-mutating task — including `request_proposals`, `refine_proposals`, and `decline_proposals` — so the buyer learns about the non-compliance before a silent duplicate. A guaranteed pure-read task whose schema leaves the key optional MAY proceed without replay protection, but the client MUST NOT silently treat a retry as deduplicated.
**Decoding seller-emitted error codes.** Sellers MAY return error codes (`IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_EXPIRED`, `IDEMPOTENCY_IN_FLIGHT`, `INVALID_REQUEST`, or codes added in later minor versions) that buyers' pinned vocabulary may not recognize. Receivers MUST decode these per [Forward-compatible decoding (normative)](/dist/docs/3.2.8/building/by-layer/L3/error-handling#forward-compatible-decoding-normative) — read `error.recovery` for the recovery classification, default to `transient` when `recovery` is absent, and never reject the response because the code value is unfamiliar. The retry semantics for `transient`-classified errors are bounded by [§ Retry Logic](/dist/docs/3.2.8/building/by-layer/L3/error-handling#retry-logic) (`maxRetries` and exponential backoff with jitter) — buyers MUST NOT loop indefinitely on a `transient` default.
**Replay responses are historical snapshots.** A response carrying `replayed: true` is byte-equivalent to the original first-call response (per seller rule 2) — state-tracking fields in it reflect the resource's state at first-call time, NOT the resource's current state. A buyer that reads `status: pending_creatives` from a replayed `create_media_buy` response and then calls `update_media_buy(canceled: true)` on a resource that has actually been in `canceled` for hours will surface a `NOT_CANCELLABLE` error and a state-machine bug. Buyers requiring current state MUST consult the resource's read endpoint — `get_media_buys` for media buys, `list_accounts` for accounts, `list_creatives` for creatives, `get_signals` for signals, equivalents for other resources. `replayed: true` is the explicit signal that a fresh read is required before any state-dependent decision; SDKs SHOULD surface the flag to caller code rather than transparently unwrap it. Agentic buyers MUST treat `replayed: true` as a stop signal for any planning step whose next action depends on resource state, and MUST re-read before continuing.
**A re-read is a new request.** Do not reuse the mutation's `idempotency_key` on its readback request. Pure-read callers SHOULD omit the field; generic wrappers that include it SHOULD mint a new key for each poll because keyed-read caching is optional seller behavior and cannot be assumed either present or absent.
**TTL boundary for persisted keys.** Some buyers persist `idempotency_key` alongside their own object (e.g., `campaign.pending_idempotency_key` in the buyer's DB) so that retries after a process restart or overnight reconcile still dedup. This works **only within the seller's declared `replay_ttl_seconds`**. Beyond the TTL, the seller will either reject the retry with `IDEMPOTENCY_EXPIRED` (good) or, if the cache was evicted, treat it as a new request (silent double-booking — the failure mode this field exists to prevent). Buyers retrying past the TTL MUST fall back to a natural-key check (e.g., query `get_media_buys` by `context.internal_campaign_id`) before resending. The `idempotency_key` guarantees at-most-once execution within the replay window, not forever. Queue-based retry systems and workflow engines with retry horizons longer than the seller's TTL MUST be designed around this — don't put a key into a dead-letter queue that replays days later without a natural-key re-check.
**Keys are security-sensitive.** An `idempotency_key` is a secret capability token within its TTL — anyone who holds one and knows the original payload can replay it and read the cached response. Treat keys the way you treat session tokens: do not log them in full, do not embed them in URLs, do not share them across agents. Log prefix-only (first 8 chars of the UUID) if you need correlation. Buyers persisting `pending_idempotency_key` at rest (e.g., alongside a campaign row in the buyer's DB) MUST encrypt it with the same controls used for bearer tokens, and SHOULD purge the key after success confirmation to minimize the exposure window.
**Sellers MUST encrypt the cache tier at rest.** When sellers cache keyed read-tool responses (`get_products`, `list_accounts`, `list_creatives`, `get_signals`, etc.), those entries join the write receipts already held by the cache. Read responses carry account-scoped data — brand domains, account names, product allocations, signal references — at the same sensitivity as the seller's underlying resource store. Sellers MUST apply at-rest encryption to the idempotency cache with the same controls used for the resource store the cached data was read from, MUST NOT treat the cache as a transient retry-receipt store exempt from data-at-rest controls, and MUST scope cache reads by `(authenticated_agent, account_id)` at the storage layer (not just at the application layer) so a misconfigured query cannot pull a sibling tenant's cached read response.
**Keys MUST be unguessable.** Schema enforces `^[A-Za-z0-9_.:-]{16,255}$` and buyers MUST use UUID v4 (\~122 bits of entropy) or an equivalent CSPRNG-generated value. Low-entropy keys like `retry-001` or monotonic counters turn the cache into an enumerable surface: an attacker can walk the key space and test each one against a target agent. Sellers SHOULD reject keys that fail a basic entropy check (e.g., all-zeros, repeated characters, short ASCII words) with `INVALID_REQUEST` when the authenticated agent is not individually trusted.
**The three-state response (`success` / `IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_EXPIRED`) is an existence oracle for idempotency keys.** An attacker who holds a candidate key can probe it: `success` means never seen, `IDEMPOTENCY_CONFLICT` means live with a different payload, `IDEMPOTENCY_EXPIRED` means previously used. The per-`(agent, account)` scoping above is the primary defense — an attacker authenticated as agent A cannot probe agent B's keys, and a caller scoped to account A cannot probe account B's keys even under a shared agent credential. Unguessable keys are the secondary defense — an attacker who cannot guess a victim's key cannot probe the oracle usefully. Sellers MUST NOT surface `IDEMPOTENCY_EXPIRED` across scope boundaries or to unauthenticated callers. Sellers SHOULD also avoid distinguishable timing between "key exists" and "key does not exist" lookups in the idempotency layer; a constant-time floor on the negative path closes a side channel that persists even without an error-code oracle.
**SI session scope.** For `si_send_message` the key is scoped `(authenticated_agent, account_id, session_id, idempotency_key)`. `session_id` is therefore part of the oracle surface: if session IDs are guessable, an attacker who steals one key can probe it against many sessions. SI sellers MUST generate `session_id` server-side using a CSPRNG with ≥122 bits of entropy (UUID v4 or equivalent) and MUST NOT derive it from anything observable to another agent (request sequence number, user handle, timestamps). The same idempotency_key sent with a different `session_id` is a different scope tuple — always a new request, never a conflict.
**`account_id` entropy for cache-scope safety.** `account_id` is part of every idempotency scope tuple, so it is also part of the oracle surface: an attacker authenticated as agent A with a stolen idempotency key could probe it against candidate account IDs to enumerate accounts in A's authorized set or learn which accounts A has ever operated on. When account IDs are short sequential or semantic values (`acct_123`, `nike-us`), this is a real enumeration channel. Sellers that issue server-assigned account IDs MUST use unguessable values (UUID v4 / ULID, ≥122 bits of entropy) for any account ID that participates in an idempotency cache scope. Sellers operating under the buyer-declared account model (natural-key `{brand, operator}`) MUST hash the natural key with a seller-local salt before using it as a cache-scope component — the natural key is public by design and cannot be used directly as an oracle defense.
```javascript theme={null}
import { canonicalize } from "@truestamp/canonify"; // RFC 8785 JCS
import { createHash } from "node:crypto";
const EXCLUDED_FROM_HASH = new Set([
"idempotency_key",
"context",
"governance_context",
]);
function payloadHash(request) {
const filtered = Object.fromEntries(
Object.entries(request).filter(([k]) => !EXCLUDED_FROM_HASH.has(k)),
);
// If push_notification_config.authentication.credentials rotates, exclude it too
if (filtered.push_notification_config?.authentication) {
const { credentials, ...auth } = filtered.push_notification_config.authentication;
filtered.push_notification_config = {
...filtered.push_notification_config,
authentication: auth,
};
}
return createHash("sha256").update(canonicalize(filtered)).digest("hex");
}
async function createMediaBuy(request, envelope) {
if (!request.idempotency_key) {
throw new InvalidRequestError("idempotency_key is required");
}
const requestHash = payloadHash(request);
const existing = await db.findByIdempotencyKey({
agent_id: currentAgent.id,
account_id: request.account.account_id,
idempotency_key: request.idempotency_key,
});
if (existing) {
if (existing.expires_at < new Date()) {
throw new IdempotencyExpiredError("idempotency_key is past replay window");
}
if (existing.request_hash !== requestHash) {
throw new IdempotencyConflictError("idempotency_key reused with a different payload");
}
// Return the stored INNER payload; replayed: true is injected by the envelope layer
envelope.replayed = true;
return existing.response;
}
return db.transaction(async (tx) => {
const response = await processMediaBuy(tx, request);
// Cache ONLY on success, and cache only the inner response payload
await tx.idempotencyKeys.insert({
agent_id: currentAgent.id,
account_id: request.account.account_id,
key: request.idempotency_key,
request_hash: requestHash,
response,
expires_at: new Date(Date.now() + TTL_SECONDS * 1000),
});
envelope.replayed = false;
return response;
});
}
```
#### Natural-key idempotency is not a substitute
Upsert-style tasks (`sync_accounts`, `sync_audiences`, `sync_catalogs`, `sync_event_sources`, `sync_governance`, `sync_plans`) already dedup at the resource level — two calls with the same `account_id` or `audience_id` produce one row, not two. That's **resource idempotency**.
`idempotency_key` guarantees something stricter: **envelope idempotency**. The entire request — including its side effects — executes at most once. Retrying the same sync envelope without a key can still fire onboarding webhooks twice, emit duplicate audit log entries, or double-provision pixel endpoints, even though the resource rows end up identical. The key is what makes a retry truly safe.
The one exception in the spec is `si_terminate_session`: `session_id` plus the "terminate" verb is fully idempotent — a second call on an already-terminated session returns the same terminal state with no new side effects — so that schema doesn't require `idempotency_key`.
### Signed Governance Context
`governance_context` crosses trust boundaries — from governance agent to buyer to seller and back, and ultimately to auditors and regulators who may need to verify an approval long after the original transaction closed. AdCP 3.0 tightens the value format to a compact JWS signed by the governance agent so any party can verify authenticity, binding, and replay without subpoenaing the issuer.
**Roles:**
* **Governance agents** sign the token. They are the only party that signs.
* **Buyers** attach the token they received from their governance agent to the protocol envelope and forward to the seller. Buyers MUST NOT construct, modify, or re-sign the token. Buyers SHOULD retain the `jti` and `check_id` for their own audit record.
* **Services** persist the token as received and include it verbatim on all subsequent governance calls. A service advertising `adcp.governance_enforcement` for a task MUST verify per the checklist below before acting. Legacy forward-only services may retain and forward tokens for audit continuity, but MUST NOT advertise enforcement for that task.
* **Auditors and regulators** verify independently using the governance agent's published keys — this is the accountability property the signed format exists to deliver.
The same string is also the primary correlation key for the governance lifecycle. The governance agent decodes its own token to look up internal state. Services parse only the standard claims required by the verification checklist, including task, payload-hash, and commitment bindings; they never interpret `sub`, `plan_hash`, or other embedded governance state as business data.
#### Scope and dependencies
* **In scope (3.0)**: buy-side governance. The `governance_context` token authorizes governed commitments made via AdCP tasks whose request schemas carry an `x-governed-commitment` annotation. A service's own compliance or commercial rejection remains separate from the buyer-governance decision.
* **Out of scope (3.0)**: seller-side governance authorities. A future RFC may extend this profile to cover seller-side signed decisions declared via `adagents.json`.
* **Out of scope (ever)**: OpenRTB bid streams. Governance attestation terminates at the AdCP media buy boundary. Threading a signed attestation through per-impression bid requests is operationally infeasible (one token, many recipients, broadcast-fan-out) and unnecessary (spend authorization happens at media buy time, not per-impression).
**Dependency on Transport Signing (#2307)**: the anti-spoof property of this profile depends on sellers being able to establish the buyer domain independently of the token's `iss` claim — see [Buyer identity resolution](#buyer-identity-resolution) below. In 3.0 without #2307, sellers MUST either use mTLS or a pre-provisioned buyer API key to establish buyer identity; treating the request's bearer token alone as identity input to brand.json resolution is circular and does not prevent spoofing. 3.1 normatively requires #2307-style signed requests.
#### AdCP JWS profile
This profile applies to `governance_context` (#2306) and to any future AdCP artifact that is signed as a standalone token. Transport-layer request signing (#2307) uses RFC 9421 HTTP Signatures but shares the JWKS discovery described here. Governance signing keys MUST NOT also be used as #2307 transport-signing keys — the JWKS endpoint is shared, but each key entry MUST declare `"key_ops": ["verify"]` and `"use": "sig"` and occupy a distinct `kid`. Verifiers MUST enforce key-ops separation to prevent cross-purpose key reuse.
**Header**
* `alg`: `EdDSA` (Ed25519) RECOMMENDED on server-side runtimes. `ES256` (ECDSA P-256) RECOMMENDED on edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy) where Ed25519 may require explicit runtime configuration. Verifiers MUST reject `none`, `HS*`, and any `RS*` variant below 2048-bit. Verifiers MUST enforce the allowlist on the token header; they MUST NOT rely solely on library defaults.
* `kid`: REQUIRED. Identifies the signing key in the issuer's JWKS.
* `typ`: REQUIRED. MUST be exactly `adcp-gov+jws` (byte-for-byte match; verifiers MUST NOT normalize or strip the `+jws` structured suffix per RFC 6838 §4.2.8). The typed header prevents a governance signing key from being tricked into validating a generic JWT for another purpose.
* `crit`: REQUIRED for authorization-changing profile extensions. Per RFC 7515 §4.1.11, `crit` lists protected-header parameter names that MUST be understood by the verifier. Claims `authorized_commitment`, `authorized_task`, and `authorized_payload_hash` each require a same-named boolean protected-header marker and `crit` entry. Verifiers MUST recognize and process every listed extension or reject the token. This prevents older verifiers from silently ignoring a ceiling or action constraint.
**Claims**
| Claim | Required | Description |
| - | - | - |
| `iss` | Yes | Governance agent identifier. MUST be an HTTPS URL that byte-for-byte matches the `url` of a governance-typed entry in the buyer's brand.json, including any path component. Path-level matching is required so multi-tenant SaaS governance agents (e.g., `https://gov.vendor.com/tenant/acme`) cannot be spoofed by sibling tenants sharing the same origin. |
| `sub` | Yes | Issuer-generated opaque governance binding for this governed action. It MUST be stable across that action's lifecycle, unique per action and target audience, and MUST NOT contain or be derived reversibly from `plan_id`. The governance agent maps it to the internal plan; services compare it only for lifecycle continuity and never interpret it as a plan or user identifier. |
| `plan_hash` | Yes | Audit-layer binding of the attestation to the evaluated plan state. Not part of the seller verification checklist — sellers treat it as opaque cargo. Semantics, canonicalization, and verification paths are defined in [Plan binding and audit](/dist/docs/3.2.8/governance/campaign/specification#plan-binding-and-audit). |
| `aud` | Yes | Target seller identifier. MUST be the exact URL string from the seller's `adagents.json` entry that authorized this seller for the property being purchased, byte-for-byte including scheme, host, port, and path. Case-sensitive; no path-prefix match. For intent tokens where the buyer is evaluating multiple sellers, the buyer MUST request one token per target seller (see [Intent-phase disclosure](#intent-phase-disclosure) for the privacy trade-off). |
| `iat` | Yes | Issued-at timestamp (seconds since epoch). |
| `nbf` | No | Not-before timestamp. When present, verifiers MUST reject if now \< nbf (with ±60 s skew). |
| `exp` | Yes | Expiration timestamp. Intent tokens SHOULD expire within 15 minutes. Execution-phase tokens (`purchase`, `modification`, `delivery`) MUST expire within 30 days; governance agents refresh longer lifecycles by issuing a new token on each lifecycle check. |
| `jti` | Yes | Unique token identifier. Used by sellers for replay detection and by auditors for correlation. RECOMMENDED format: UUID v7 or ULID for time-orderability. |
| `phase` | Yes | `intent`, `purchase`, `modification`, or `delivery`. It identifies the authorization stage, not merely the task name. A buyer-supplied token entering any governed service request is `intent`. When the service advertises `online_execution_check`, the service then obtains `purchase` before committing a create, `modification` before committing an update, or `delivery` for a delivery check. |
| `caller` | Yes | URL of the party that requested the governance check that produced this token. In intent phase, this is the orchestrator/buyer; in execution phases, this is typically the seller itself (as callbacks arrive with the seller as caller). |
| `check_id` | Yes | Governance agent's `check_id` for this decision; correlates to `report_plan_outcome` and `get_plan_audit_logs`. |
| `media_buy_id` | Conditional | Seller-assigned media buy ID. MUST be present on `modification` and `delivery` tokens, MAY be present on `purchase` when the service provisionally assigns an ID during prepare, and MUST be absent on `intent`. The opaque `sub` binds a purchase action before a durable media-buy ID exists. |
| `authorized_commitment` | Conditional | Signed `{ amount, currency }` ceiling approved by governance. REQUIRED whenever the check authorizes a numeric monetary commitment, including an explicit `{amount: 0, currency}` ceiling for a verified zero-cost action; omitted only for non-monetary actions. Its matching protected-header marker is critical as defined above. The receiving service compares the price it will commit with this claim, so an indirectly priced payload cannot be authorized with an understated buyer declaration. This reveals only the price already relevant to that service, not plan budget or allocation. |
| `authorized_task` | Conditional | Exact AdCP task name authorized by an intent check. REQUIRED with `authorized_payload_hash` on action-authorizing tokens and listed in `crit`. A service rejects a token minted for another task even when audience and monetary ceiling match. |
| `authorized_payload_hash` | Conditional | `base64url_no_pad(SHA-256(JCS(payload_without_governance_metadata)))`, REQUIRED with `authorized_task` and listed in `crit`. The excluded top-level fields are exactly `governance_context` and `context`; `target_agent` lives on the governance check rather than in the downstream payload. Every business field, including `idempotency_key`, remains bound. The service recomputes this value over the received task request before committing. |
| `policy_decisions` | No | Compact array of `{ policy_id, outcome }` entries (may include `confidence`). Visible to the seller. Governance agents SHOULD omit this in privacy-sensitive deployments (see [Privacy considerations](#privacy-considerations)) and use `policy_decision_hash` instead. |
| `policy_decision_hash` | No | SHA-256 hash of the canonicalized decision log, hex-encoded. When present, sellers treat it as an opaque integrity anchor; full log is retrievable by auditors via `audit_log_pointer`. Governance agents MUST include either `policy_decisions` or `policy_decision_hash` (both is permitted). |
| `runtime_attestation_binding_digest` | Conditional | Required when the check evaluated `runtime_attestations[]`. MUST byte-equal the check response field of the same name: `sha256:` plus lowercase-hex SHA-256 of `JCS({ evaluations, findings })`, where `evaluations` is the ordered `runtime_attestation_evaluations[]` array and `findings` is the ordered response subset carrying `attestation_reference_digest`. This binds the exact credential/reference digests, normalized outcomes, confidence-bearing findings, and governance-check action binding without putting credential bodies in the token. Audit-layer claim; sellers persist it as opaque cargo and do not recompute it. |
| `audit_log_pointer` | No | HTTPS URL consumable by `get_plan_audit_logs` for the full decision evidence. When present, auditors can fetch the full log using the pointer; access control is governed by the governance agent. |
| `status` | No | Optional forward-compatibility hook. When present, MUST be a JSON object conforming to a future IETF JWT Status List mechanism (draft-ietf-oauth-status-list). Verifiers that do not understand `status` MUST NOT reject solely on its presence unless it appears in `crit`. |
Cross-language implementations SHOULD validate payload canonicalization and the task, payload, amount, currency, and critical-marker acceptance rules against the published [`governance-authorization.json` vectors](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/governance-authorization.json). The vectors pin `idempotency_key` into the business hash while excluding only top-level `governance_context` and `context`. The same file publishes 27 byte-exact Ed25519 compact-JWS cases covering positive verification, critical-extension failures, binding mismatches, malformed or widened commitments, time bounds, replay identifiers, signature tampering, and explicit zero-cost authorization. Its private key component is deliberately public test material and MUST NOT be installed as a production trust anchor.
**Unknown-extension handling**: verifiers ignore unknown non-critical claims. When a claim changes authorization semantics, the issuer also emits the same-named protected-header marker and lists it in `crit`; verifiers that do not recognize that header extension MUST reject. Verifiers MUST also reject when the critical marker and its corresponding claim do not appear together.
**Size**: a typical token with `policy_decision_hash` fits comfortably under the 4096-character envelope limit. Implementations MUST NOT put large evidence payloads in the token; use `audit_log_pointer` instead.
When `runtime_attestation_binding_digest` is present, governance agents MUST retain the full ordered evaluations and attestation-bound findings in the corresponding `get_plan_audit_logs` check entry. The entry-level digest, response-level digest, and signed claim MUST be identical. Auditors recompute the digest from the retained arrays; any mismatch means the signed decision and audit readback disagree. This claim MUST NOT appear in `crit`: like `plan_hash`, it is audit-layer evidence that ordinary sellers cannot independently recompute from the spend-commit request.
**`plan_hash` is audit-layer, not wire-layer**: the `plan_hash` claim is cryptographic cargo the token carries for off-wire verification by the governance agent, auditors, and buyer-side compliance. It is not part of this profile's seller verification contract and is never listed in `crit`. Canonicalization, excluded fields, retention rules, and test vectors are specified in [Plan binding and audit](/dist/docs/3.2.8/governance/campaign/specification#plan-binding-and-audit) (governance spec). Sellers persist and forward `governance_context` verbatim and perform the 15-step verification checklist below — authenticity, authorization scope, freshness — without inspecting `plan_hash`.
#### Buyer identity resolution
The brand.json cross-check (step 13 of the verification checklist) is the anti-spoofing control. It requires sellers to know *which buyer's brand.json to consult* — the authenticated agent proves who is calling, and the resolution chain maps that agent to the buyer domain whose brand.json the seller should fetch. In 3.0 sellers MUST establish the buyer domain via one of:
1. **mTLS**: buyer presents a client certificate; the certificate Subject/SAN resolves to the buyer's registered domain; the seller fetches `https://{domain}/.well-known/brand.json`.
2. **Pre-provisioned buyer identity**: an API key or OAuth client identifier issued by the seller at onboarding, mapped to the buyer's domain in the seller's records.
3. **Signed requests per #2307** (3.1 normative): RFC 9421 HTTP Signatures with `keyid` resolving to a buyer-declared public key in the buyer's adagents-style agent registry.
Sellers MUST NOT derive the buyer identity from an unauthenticated field in the request (including the token's `iss`, `caller`, or any client-supplied header). Doing so creates a circular trust chain: the attacker proves "I am the buyer" by presenting a token signed by an attacker-controlled governance agent declared in an attacker-controlled brand.json. In particular, **the token's `iss` is untrusted input until step 13 of the verification checklist confirms it appears as a governance-typed entry in the *authenticated* buyer's brand.json** — the authentication mechanism (mTLS, API key, or signed request) establishes the buyer domain first, and only the brand.json fetched from *that* domain is trusted to attest which governance agent (`iss`) may sign for this buyer.
This profile follows at most one brand.json **document-indirection variant** (`authoritative_location` or `house`) and stops; sellers MUST NOT follow document-indirection chains here. This is not permission to follow an HTTP redirect from an explicit URL: an `authoritative_location` dereference uses zero HTTP redirects. A domain-derived initial `/.well-known/brand.json` fetch uses the bounded original-host/`www` HTTP policy defined above.
#### Key discovery (JWKS)
Sellers and auditors resolve the governance agent's public keys via JWKS (RFC 7517):
1. Establish the buyer domain via the rules in [Buyer identity resolution](#buyer-identity-resolution).
2. Fetch the buyer's brand.json. Locate the `agents[]` entry whose `type` is `governance` and whose `url` byte-for-byte equals the token's `iss`. Reject if no matching entry exists.
3. Use the entry's `jwks_uri` if declared. If absent, default to `{origin of iss}/.well-known/jwks.json` where origin = scheme+host+port per RFC 6454. Multi-tenant governance agents serving multiple buyers from a shared origin MUST declare explicit per-tenant `jwks_uri` so tenant key material is not pooled across the origin. Sharding is also a size requirement, not only an isolation one: each `jwks_uri` is fetched under the `MAX_JWKS_BYTES` budget (64 KiB — see the verifier pseudocode below), which is the JWKS-specific cap and is deliberately tighter than the generic 5 MB SSRF body ceiling. A single JWKS that pools hundreds of per-tenant keys exceeds 64 KiB and is rejected, so per-tenant `jwks_uri` (each serving a small key set) — not one aggregated document — is the conformant path at scale.
4. Fetch the JWKS over HTTPS.
5. Locate the key in the JWKS whose `kid` matches the token header. On cache miss for a `kid`, refetch the JWKS once (respecting a minimum 30-second cooldown to prevent unbounded refetches) before rejecting.
**JWKS cache TTL** MUST be bounded above by the revocation-list polling interval (see [Revocation](#revocation)). Longer cache TTLs defeat revocation: if a compromised `kid` is added to `revoked_kids` but the seller's JWKS cache still serves the revoked key for validation, only the revocation check (performed independently per step 14) catches the fraud.
**SSRF protection**: `jwks_uri` and the revocation-list URL are counterparty-supplied. All outbound fetches to these URLs MUST follow the SSRF controls defined in [Webhook URL validation](#webhook-url-validation-ssrf): reject non-HTTPS, reject resolved IPs in reserved ranges (including cloud metadata addresses), pin the connection to the validated IP, refuse redirects, cap response size and timeouts, suppress detailed error messages to the counterparty. A JWS profile without SSRF discipline on key discovery is a metadata-exfiltration vector.
#### Seller verification checklist
Services apply this checklist to two distinct authorization gates. On an inbound governed request they verify the buyer-supplied `intent` token. When the advertised task mode includes `online_execution_check`, that token permits preparation and the execution check but not the side effect; the service applies the checklist again to the execution token returned by its governance call before commit. Checks run in order and short-circuit on the first failure:
1. Parse the compact JWS. Reject if malformed.
2. Reject if header `alg` is `none` or not in the allowed list (EdDSA, ES256). Library defaults MUST NOT be relied upon.
3. Reject if header `typ` is not exactly `adcp-gov+jws` (no normalization).
4. Reject if the header contains a `crit` array and any listed protected-header extension is not recognized by the verifier. For `authorized_commitment`, `authorized_task`, and `authorized_payload_hash`, require each boolean protected-header marker, its `crit` entry, and its payload claim to appear together. Require `authorized_task` and `authorized_payload_hash` as a pair.
5. Resolve `iss` to a JWKS via the discovery rules above. Reject if the JWKS cannot be fetched (after SSRF validation) or the `kid` is not present after one refetch.
6. Verify the JWKS entry's `use` is `"sig"` and `key_ops` includes `"verify"`. Reject keys marked for other uses.
7. Cryptographically verify the signature.
8. Reject if `aud` does not byte-for-byte equal the seller's own canonical URL as declared in the relevant `adagents.json` entry.
9. Reject if `exp` is in the past or `iat` is more than 60 seconds in the future (±60 s clock-skew tolerance, symmetric on both bounds). If `nbf` is present, reject if `now < nbf − 60 s`.
10. Reject if `sub` is absent or empty. On a continuation for an already-bound action, reject if it differs from the opaque `sub` retained from the prior accepted token. The seller never compares it to `plan_id`; the issuing governance agent prevents plan swap by validating and resolving its own signed context.
11. Reject if `phase` does not match the authorization gate. The buyer-supplied token on an inbound governed request MUST be `intent`. For a task advertising `online_execution_check`, the token returned to the service by its own pre-commit governance call MUST be `purchase` for a create, `modification` for an update, or `delivery` for a delivery check. A service MUST NOT substitute the inbound intent token for that required execution token.
12. Validate action binding. For an inbound intent token, reject unless `authorized_task` equals the invoked task and `authorized_payload_hash` equals the JCS/SHA-256 hash recomputed over the received request after removing exactly `governance_context` and `context`. For `modification` and `delivery`, reject if `media_buy_id` is absent or does not equal the request's media buy ID. For `purchase`, compare it when present; absence is valid because prepare may precede durable ID assignment. For `intent`, reject if it is present. When the action has a monetary commitment, reject if `authorized_commitment` is absent, its currency differs, or the service's computed commitment exceeds its amount. A service that cannot bind the task and payload or compute the price before commit MUST NOT advertise governance enforcement for that task.
13. Cross-check: the token's `iss` MUST appear as a governance-typed agent in the buyer's current brand.json (established via [Buyer identity resolution](#buyer-identity-resolution)). Sellers SHOULD cache brand.json with reasonable TTLs (recommend 1 hour) and refresh on verification failure.
14. Check the revocation list (see [Revocation](#revocation)). Reject if `jti` ∈ `revoked_jtis` or if the token header's `kid` ∈ `revoked_kids`. This check runs on every verification, not only on cache miss.
15. Reject if `jti` has been seen before for this `(iss, aud)` tuple. See [Replay dedup](#replay-dedup) for storage guidance.
Only after all 15 checks pass may the service proceed through the gate represented by that token. For `signed_context`, a valid inbound intent token is the task authorization. For `online_execution_check`, it authorizes prepare/check only; commit additionally requires the valid execution token. Services do not verify `plan_hash` — that claim is bound at the governance-agent / auditor layer (see [Plan-state binding](#plan-state-binding)).
#### Replay dedup
Step 15 requires tracking `jti` values to prevent replay. The naive implementation — an unbounded set — is both a memory risk and a DoS vector (attacker floods the seller with unique tokens to exhaust storage).
**Scaling recommendations**:
* Cap execution-token `exp` at 30 days (enforced by governance agents; sellers reject anything longer). This bounds the dedup window.
* Use a bloom filter keyed on `(iss, aud, jti)` with a small false-positive rate (\~1 in 10⁶) as the fast-path check, with authoritative lookup in a bounded store (Redis `SET jti NX EX `, Postgres unique index with TTL cleanup) only on bloom-filter hits.
* Governance agents SHOULD issue `jti` values in a time-orderable format (UUID v7 or ULID) so sellers can partition the dedup store by time window and drop expired partitions cheaply.
#### Revocation
Exp-based expiry alone does not cover execution-phase tokens that live for a media buy's lifecycle. Governance agents MUST publish a revocation list at `{origin of iss}/.well-known/governance-revocations.json` and MUST sign the list itself using a key in the same JWKS:
```json theme={null}
{
"payload": "",
"signatures": [
{ "protected": "",
"signature": "" }
]
}
```
The payload (JWS-flattened JSON serialization; compact form is also acceptable):
```json theme={null}
{
"version": 1,
"issuer": "https://gov.example.com",
"updated": "2026-04-18T14:00:00Z",
"next_update": "2026-04-18T14:15:00Z",
"revoked_jtis": ["01HWZX..."],
"revoked_kids": ["gov-2026-03"]
}
```
* `revoked_jtis` invalidates individual decisions (e.g., a plan was rescinded). Revocation applies to any token with that `jti`, regardless of signing key.
* `revoked_kids` invalidates every token ever signed under that `kid` (before or after the revocation timestamp), not just tokens issued after.
* `issuer` MUST match the `iss` origin of tokens this list governs. Prevents cache substitution across issuers by a shared CDN.
* The list is signed so a compromised CDN or DNS origin cannot serve a stale or tampered list to un-revoke a compromised key.
**Polling cadence**:
* Sellers MUST poll the list on the cadence declared in `next_update`.
* Floor: 1 minute. Ceiling: 30 minutes for any seller accepting execution-phase tokens. Governance agents MUST NOT declare `next_update` more than 30 minutes in the future for issuers covered by execution-phase traffic. The `next_update` value is a JSON timestamp, not an HTTP cache header — standard HTTP caches will not respect it; sellers MUST parse and honor it themselves. Sellers that prioritize fast key-compromise propagation over DoS tolerance SHOULD poll at or near the floor; the ceiling exists for sellers that accept slower `revoked_kids` propagation in exchange for tolerating longer revocation-endpoint outages.
* Polling is optional for intent-phase tokens with ≤15 min `exp` (the intent-token `exp` cap from the JWT claims table above — distinct from the polling ceiling, even though the numbers were previously coincident).
* Use HTTP conditional requests (`If-Modified-Since` / `ETag`) to avoid unnecessary body transfers.
**Fetch failure safe-default**: if a seller has not successfully refreshed the revocation list within `next_update + grace` (recommend grace = 4× the previous polling interval), the seller MUST reject any new `purchase`, `modification`, or `delivery` phase token until the list is refreshed. This prevents an attacker who DoSes the revocation endpoint from extending the fraud window of a compromised key. Sellers operating at the polling ceiling get \~2.5 h of endpoint-outage tolerance; sellers at the floor get \~5 min. Tune the polling cadence — not the grace constant — to your risk appetite.
* Governance agents MUST retain revoked public keys as discoverable for the audit retention period (recommend 7 years) so auditors can verify historical tokens after the current rotation. Revoked keys SHOULD be served at `{origin}/.well-known/jwks-archive.json` (separate from the active JWKS).
#### Key rotation
* Governance agents rotate by adding a new key to JWKS with a new `kid`, signing fresh tokens with the new `kid`, and leaving the old key published until the longest-lived outstanding token expires.
* Seller JWKS caches MUST invalidate and refetch on a missing-`kid` failure before rejecting (with a 30-second cooldown to prevent unbounded refetches).
* Emergency rotation (key compromise) proceeds by adding the old `kid` to the signed `revoked_kids` list and rotating to a new key immediately. Short exp on intent tokens, capped exp on execution tokens, and revocation-list polling together bound the fraud window.
#### Verification error taxonomy
Sellers and client libraries SHOULD surface verification failures with these codes so that retry vs reject semantics are consistent across the ecosystem. AdCP client libraries (`@adcp/sdk` and equivalents) SHOULD expose typed errors that map to this taxonomy.
| Failure | Retry? | Code | Notes |
| - | - | - | - |
| JWKS fetch timeout or 5xx | Yes, with backoff | `governance_jwks_unavailable` | Transient. Retry with exponential backoff; abort after N attempts. |
| JWKS fetch fails SSRF validation | No | `governance_jwks_untrusted` | Permanent. Indicates misconfigured `jwks_uri` or an attack. |
| `kid` not in JWKS after refetch | No | `governance_key_unknown` | Reject. Possibly indicates rotation lag or key revocation. |
| Signature invalid, `typ` mismatch, `alg` not allowed, `crit` unknown | No | `governance_token_invalid` | Reject. Indicates tampering or implementation bug. |
| `exp` in past, `jti` replayed, or `iat` / `nbf` in future beyond allowed skew | No | `governance_token_expired` / `_replayed` / `_not_yet_valid` | Reject. Tokens cannot be healed by retry. |
| `jti` ∈ `revoked_jtis` or `kid` ∈ `revoked_kids` | No | `governance_token_revoked` | Reject. |
| `iss` not in buyer brand.json | No | `governance_issuer_not_authorized` | Reject. Possibly indicates a spoofing attempt. |
| Revocation list not refreshed within grace | No (block new) | `governance_revocation_stale` | Reject new tokens until revocation list refreshes. Existing fully-verified tokens may continue to be trusted within their existing grace. |
| `aud`, authenticated `caller`, opaque action-binding (`sub`), `phase`, `media_buy_id`, `authorized_task`, `authorized_payload_hash`, or `authorized_commitment` currency/ceiling mismatch | No | `governance_token_not_applicable` | Reject. Token valid but not for this operation. Missing or malformed required claims use `governance_token_invalid`; a well-formed token whose bindings do not match the attempted operation uses this code. |
Servers MUST NOT echo internal verification details (e.g., which specific claim mismatched) to the counterparty. Return the stable code above; log the detail server-side.
#### Privacy considerations
**`policy_decisions` visibility**: the token is a JWS (readable by anyone with the public key), not a JWE (encrypted). If `policy_decisions` contains the full list of policy IDs the governance agent evaluated, every seller who receives the token learns which policies the buyer's governance posture considers — competitive intelligence, and in some cases signaling about sensitive audience characteristics (e.g., a `minors_compliance` policy ID implies targeting of under-18 audiences). Governance agents SHOULD use `policy_decision_hash` in place of `policy_decisions` when the buyer's compliance posture is sensitive; the full log remains available to auditors via `audit_log_pointer` with governance-agent-controlled access.
**Intent-phase seller disclosure to GA**: the `aud` binding means a buyer evaluating N sellers in a competitive auction must request N distinct intent tokens, each `aud`-bound to one seller. The governance agent therefore sees the full list of sellers the buyer considered — a privacy regression relative to the opaque-string model where sellers were unknown to the GA at intent time. This is an explicit trade-off: cross-seller replay resistance requires per-seller binding. A future `aud_hash` mechanism (where the token binds a hash of the seller URL with a token-scoped salt, and each seller computes the hash on its own URL to verify) can recover intent-time seller privacy against the GA without sacrificing replay resistance. Not defined in 3.0; tracked as a follow-up.
**`caller` URL**: contains the orchestrator's identifier. Sellers and auditors who retain tokens long-term should be aware of the retention policy implied by this.
#### Reference implementation
**Decoded example token (intent phase)**:
Header:
```json theme={null}
{
"alg": "EdDSA",
"kid": "gov-2026-04",
"typ": "adcp-gov+jws",
"crit": ["authorized_commitment", "authorized_task", "authorized_payload_hash"],
"authorized_commitment": true,
"authorized_task": true,
"authorized_payload_hash": true
}
```
Payload:
```json theme={null}
{
"iss": "https://governance.example.com",
"sub": "gb_01HWZXABCDEFG1234567890",
"plan_hash": "EiCW8FkxgZ2wKqGv3Z9XuT4n2LwcJm1fK7vRaTpQ0sU",
"aud": "https://seller.example.com/adcp",
"iat": 1744934400,
"exp": 1744935300,
"jti": "01HWZXABCDEFG1234567890",
"phase": "intent",
"caller": "https://orchestrator.example.com",
"check_id": "chk_001",
"authorized_commitment": { "amount": 25000, "currency": "USD" },
"authorized_task": "create_media_buy",
"authorized_payload_hash": "grD8ZKqJa7KJuLX_EJ4iZ5tCVGfOnJrL-o9Q_qXl7xU",
"policy_decision_hash": "9b2a...f41c",
"audit_log_pointer": "https://governance.example.com/audit/01HWZXABCDEFG1234567890"
}
```
**Seller verifier (TypeScript, \~30 lines with `jose`)**:
```ts theme={null}
import { createRemoteJWKSet, decodeProtectedHeader, decodeJwt, jwtVerify } from "jose";
class GovTokenError extends Error {
constructor(public code: string) { super(code); }
}
const jwksCache = new Map>();
function jwksFor(jwksUri: string) {
let jwks = jwksCache.get(jwksUri);
if (!jwks) {
// ssrfValidatedFetch enforces the Webhook URL validation rules on the JWKS URL
jwks = createRemoteJWKSet(new URL(jwksUri), { cacheMaxAge: 15 * 60 * 1000, cooldownDuration: 30 * 1000, [Symbol.for("fetch")]: ssrfValidatedFetch });
jwksCache.set(jwksUri, jwks);
}
return jwks;
}
export async function verifyGovernanceContext(token: string, ctx: {
sellerId: string; priorBindingId?: string; mediaBuyId?: string; phase: "intent" | "purchase" | "modification" | "delivery";
task: string; governedPayloadHash: string; commitment?: { amount: number; currency: string };
resolveBrandJsonGovernanceAgent: (iss: string) => Promise<{ jwks_uri: string } | null>;
seenJti: (iss: string, aud: string, jti: string) => Promise;
isRevoked: (iss: string, jti: string, kid: string) => Promise;
revocationFresh: (iss: string) => Promise;
}) {
const header = decodeProtectedHeader(token);
if (header.typ !== "adcp-gov+jws") throw new GovTokenError("governance_token_invalid");
if (!["EdDSA", "ES256"].includes(header.alg ?? "")) throw new GovTokenError("governance_token_invalid");
const { iss } = decodeJwt(token);
const agent = await ctx.resolveBrandJsonGovernanceAgent(iss as string);
if (!agent) throw new GovTokenError("governance_issuer_not_authorized");
const { payload } = await jwtVerify(token, jwksFor(agent.jwks_uri), {
issuer: iss as string, audience: ctx.sellerId, typ: "adcp-gov+jws",
algorithms: ["EdDSA", "ES256"], clockTolerance: 60,
crit: { authorized_commitment: true, authorized_task: true, authorized_payload_hash: true },
}).catch(() => { throw new GovTokenError("governance_token_invalid"); });
if (typeof payload.sub !== "string" || payload.sub.length === 0)
throw new GovTokenError("governance_token_not_applicable");
if (ctx.priorBindingId && payload.sub !== ctx.priorBindingId)
throw new GovTokenError("governance_token_not_applicable");
if (payload.phase !== ctx.phase) throw new GovTokenError("governance_token_not_applicable");
if (payload.authorized_task !== ctx.task || payload.authorized_payload_hash !== ctx.governedPayloadHash)
throw new GovTokenError("governance_token_not_applicable");
if (ctx.commitment) {
const ceiling = payload.authorized_commitment as { amount?: number; currency?: string } | undefined;
if (!ceiling || ceiling.currency !== ctx.commitment.currency || typeof ceiling.amount !== "number" || ctx.commitment.amount > ceiling.amount)
throw new GovTokenError("governance_token_not_applicable");
}
if (ctx.phase !== "intent" && payload.media_buy_id !== ctx.mediaBuyId)
throw new GovTokenError("governance_token_not_applicable");
if (!(await ctx.revocationFresh(iss as string))) throw new GovTokenError("governance_revocation_stale");
if (await ctx.isRevoked(iss as string, payload.jti as string, header.kid as string))
throw new GovTokenError("governance_token_revoked");
if (await ctx.seenJti(iss as string, ctx.sellerId, payload.jti as string))
throw new GovTokenError("governance_token_replayed");
return payload;
}
```
**Migration dual-path (sellers during 3.0)**:
```ts theme={null}
const JWS_COMPACT = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
function handleGovernanceContext(value: string, ctx) {
persistOpaque(value); // always persist and forward for auditor use
if (!JWS_COMPACT.test(value)) return; // pre-3.0 opaque value, nothing to verify
return verifyGovernanceContext(value, ctx); // throws on any failure
}
```
#### Migration (3.0 → 3.1)
* **3.0**: governance agents MUST emit compact JWS per this profile, including the required `plan_hash` audit-layer claim (see [Plan binding and audit](/dist/docs/3.2.8/governance/campaign/specification#plan-binding-and-audit) for semantics). Sellers MAY verify the 15-step checklist; sellers that do not verify MUST persist and forward the token unchanged. Values that are not JWS are deprecated and SHOULD only appear from pre-3.0 governance agents during the transition; governance agents that emit non-JWS values in 3.0 MUST declare this in their capabilities so sellers can detect unverifiable deployments.
* **3.1**: all sellers MUST verify per the 15-step checklist. Governance agents MUST emit JWS. Non-JWS values will be rejected end-to-end. `plan_hash` remains audit-layer (governance-agent / auditor / buyer-compliance verification only — not seller verification).
The field name and schema shape (single string, ≤4096 chars) do not change between versions. Only the string's internal format is tightened. This preserves the correlation-key semantics from earlier protocol versions — sellers that already treat the value as opaque need no changes to continue forwarding; sellers that want the accountability properties opt in by implementing the verification checklist.
### Signed Requests (Transport Layer)
[Signed Governance Context](#signed-governance-context) signs an authorization artifact. Request signing signs the request itself — method, target URI, headers, and (by default) body bytes — proving control of a request-signing key with replay and tampering protection. A valid signature alone proves only that the key signed the request. Agent identity is established after the verified publication chain binds that key to exactly one canonical operator `brand.json` `agents[].url`. Whether that Agent is *authorized* to act for the brand named in the request body is a separate concern, governed by the target house's `authorized_operator[]` in brand.json. This section defines authentication only; authorization lookup is specified by the brand.json schema and happens whether requests are signed or not.
AdCP 3.0 defines this profile as **optional and capability-advertised** via `request_signing` on `get_adcp_capabilities`. AdCP 3.2 keeps signing optional but makes body integrity mandatory whenever signing is used: every accepted signature on a request with a body covers `content-digest`. AdCP 4.0 — the next breaking-changes accumulation window — additionally requires signing for spend-committing operations. See [Transport migration timeline](#transport-migration-timeline).
**Roles:**
* **Agents** sign requests with a key published at their own `jwks_uri` in their operator's brand.json `agents[]` entry. The operator (the domain hosting brand.json) may be a house buying direct or an authorized third party — this profile does not distinguish. The signer is always an agent.
* **Sellers** verify the signature against the signing agent's published key, establishing agent identity. Sellers then perform the separate brand-operator authorization check (outside this profile's scope).
* **Sellers calling agent-side AdCP endpoints** (e.g., buyer-hosted mutation callbacks that are themselves AdCP protocol calls) sign their outgoing requests symmetrically; the receiving agent verifies against the seller's keys published under the seller operator's brand.json `agents[]` entry. Push-notification webhook callbacks (`push_notification_config.url` and similar asynchronous one-way notifications) are covered by the symmetric [Webhook callbacks](#webhook-callbacks) variant of this profile — the seller signs outbound with its `adcp_use: "request-signing"` key (the deprecated `"webhook-signing"` value is still accepted) and the buyer verifies.
**Dependencies:**
* Shares JWKS discovery, SSRF rules, alg allowlist, revocation semantics, and key rotation with the [AdCP JWS profile](#adcp-jws-profile) above. Request verification never accepts another key purpose: a request-signing JWK MUST declare `"adcp_use": "request-signing"`, `"use": "sig"`, `"key_ops": ["verify"]`, and a `kid` that does not appear on any other JWKS entry with a different `adcp_use`. Verifiers enforce all four; see [Agent key publication](#agent-key-publication). The webhook path has its own explicit relaxation because the webhook `tag` provides domain separation.
* Resolves the identity-bootstrapping dependency in [Buyer identity resolution](#buyer-identity-resolution) for governance: a seller that verifies a request signature has a cryptographically established signing agent identity and MAY use the signing agent's operator domain as the brand.json resolution input for the governance verification step.
**Conformance.** Verifier behavior is graded by the universal capability-gated storyboard at [`/compliance/latest/universal/signed-requests`](https://adcontextprotocol.org/compliance/latest/universal/signed-requests), which runs for any agent advertising `request_signing.supported: true`. The storyboard exercises every step in the [verifier checklist](#verifier-checklist-requests) below and every canonicalization-edge rule in this profile, against the test vectors at [`/compliance/latest/test-vectors/request-signing/`](https://adcontextprotocol.org/compliance/latest/test-vectors/request-signing/). To run the CLI grader against your own agent, see [Auth Graders](/dist/docs/3.2.8/building/verification/grading).
**No general-purpose RFC 9421 response-signing profile.** This profile signs the *request*; AdCP 3.x defines no general-purpose paired profile for signing the synchronous response *transport*. Sellers MUST NOT apply RFC 9421 §2.2.9 response signing to synchronous AdCP responses (whether MCP `tools/call` or A2A non-streaming responses including streaming `artifactUpdate` frames), and buyers MUST NOT rely on an RFC 9421 response signature on the synchronous reply. Integrity of the immediate response transport rests on TLS within the authenticated session that carried the request, modulo the standard edge-termination caveats that govern request-side body integrity at body-modifying CDNs. Durable at-rest attestation for artifacts that need to survive past the session — including specialism-scoped payloads (brand-rights, AAO Verified compliance, sales-intelligence relay, governance receipts, bilateral non-repudiation receipts such as `plan_receipt`) — is the job of [signed webhooks](#webhook-callbacks) (signed with the `adcp_use: "request-signing"` key). The split is deliberate — see [Security Model: What gets signed](/dist/docs/3.2.8/building/concepts/security-model#what-gets-signed--and-what-doesnt) for the full rationale and the request-the-webhook pattern for tools whose canonical artifact needs to be attestable.
**Designated-task payload-envelope response signing.** A closed list of tasks designates their response *payload* as cryptographically signed under `adcp_use: "response-signing"`. The primitive is distinct from RFC 9421 §2.2.9 transport response signing on two load-bearing axes:
* **Signature location:** inside the response body, not in HTTP response headers.
* **Verification path:** parse the response body, then verify the JWS against the responding agent's `response-signing` JWK published at the agent's `jwks_uri` — not RFC 9421 base reconstruction over transport headers.
A task is admitted to the designated list only when its response payload is the canonical attestable artifact AND no webhook-emit restructuring is feasible (see the [request-the-webhook pattern](/dist/docs/3.2.8/building/concepts/security-model#the-request-the-webhook-pattern) for the default path). The list in 3.x is closed at:
* **`verify_brand_claim`** and its bulk variant **`verify_brand_claims`** (Brand Protocol). The responding brand-agent signs its response payload as a JWS envelope under the brand's `adcp_use: "response-signing"` key. The signature is load-bearing for the direction-asymmetric trust model — see [`verify_brand_claim` trust model](/dist/docs/3.2.8/brand-protocol/tasks/verify_brand_claim#trust-model) and [Building a brand agent — Signing setup](/dist/docs/3.2.8/brand-protocol/building-a-brand-agent#signing-setup).
Any task not on this list MUST NOT sign its response under any signing primitive. General-purpose response-signing helpers applying RFC 9421 §2.2.9 to arbitrary tools (regardless of which `tag` or `adcp_use` string they coin) are operating outside this profile and are not 3.x-conformant; the only response-signing primitive the spec authorizes in 3.x is payload-envelope JWS on the designated-tasks list.
The `adcp_use: "response-signing"` value is therefore reserved at the JWK layer for the payload-envelope primitive. **Keys published with `adcp_use: "response-signing"` MUST sign only payload-envelope JWS as defined in this section; using such a key to produce RFC 9421 §2.2.9 transport signatures is a profile violation regardless of the task being signed.** If a future major version scopes RFC 9421 transport response signing for any task, it MUST use a distinct `adcp_use` value (e.g., `"response-transport-signing"`) so verifiers can disambiguate the primitive from the JWK alone — the brand-protocol value cannot be retconned to cover both. List growth and additional primitives are normative decisions deferred to future spec versions.
Designated-task success responses MUST carry a `signed_response` member matching [`response-payload-jws-envelope.json`](https://adcontextprotocol.org/schemas/3.2.8/core/response-payload-jws-envelope.json). The envelope payload is the canonical signed task-body object and MUST include `typ: "adcp-response-payload+jws"`, `task`, `brand_domain`, `agent_url`, `request_hash`, `iat`, `exp`, and `response`. The outer task-body fields are convenience fields for ordinary task consumers; verifiers that rely on the signature MUST reject the envelope if any unsigned task-body field disagrees with `signed_response.payload.response`. Protocol/version envelope fields are excluded from this comparison, including `status`, `context_id`, `task_id`, `message`, `timestamp`, `replayed`, `adcp_version`, and `adcp_major_version`.
This profile uses ordinary JWS signing, not RFC 7797 unencoded payloads. The JWS Signing Input is `BASE64URL(UTF8(protected)) || "." || BASE64URL(UTF8(JCS(payload)))`, where `payload` is `signed_response.payload` and `protected` decodes to `{ "alg": "EdDSA" | "ES256", "kid": "...", "typ": "adcp-response-payload+jws" }`. The protected header MUST NOT contain `b64`. Response verifiers MUST enforce the shared JWS discovery and hardening rules from the [AdCP JWS profile](#adcp-jws-profile): allowed algorithms, `use: "sig"`, `key_ops` containing `"verify"`, exact `adcp_use: "response-signing"`, missing-`kid` refetch, revocation checks, SSRF-safe JWKS fetches, and duplicate-key rejection before canonicalization.
`request_hash` is `sha256:` plus unpadded base64url SHA-256 of the JCS canonical request-binding object `{ task, brand_domain, agent_url, caller_identity, request }`. `caller_identity` MUST be a typed canonical string derived from the authenticated transport or credential mapping, such as `signed-agent-url:`, `api-client-id:`, or `mtls-san:`. If no authenticated caller identity exists, `caller_identity` is `null` and the verifier MUST treat the response as weaker evidence that is not bound to a caller.
`brand_domain` is a tenant-binding field, not an echo. A multi-brand agent MUST populate it from its server-side tenant resolution and the brand.json entry whose policy store produced the answer; it MUST NOT copy it from the request body. `agent_url` is the canonical URL of the responding `agents[]` entry whose `response-signing` JWK verifies the envelope. Online verifiers MUST reject envelopes at or after `exp` after applying only small clock-skew tolerance; audit verifiers MAY verify after `exp`, but only as historical evidence that the brand-agent signed that payload during the stated `iat`/`exp` window.
**Brand-authorization cross-check (3.2 advisory).** A valid signature proves only that *some* agent holding a `response-signing` key signed the payload — not that the key is authorized to answer for `brand_domain`. `brand_domain` and `agent_url` are fields *inside* the payload the same key signs, so resolving the envelope's `kid` from an attacker-selected agent origin confirms authorship, not brand authority. Before treating a cryptographically valid `verify_brand_claim` / `verify_brand_claims` envelope as evidence about the asserted `brand_domain`, an online 3.2 verifier SHOULD:
1. Resolve `https://{brand_domain}/.well-known/brand.json` following the SSRF-safe [brand.json resolution](#buyer-identity-resolution) rules: the initial domain-derived HTTP fetch may follow only the original hostname ↔ exact `www` counterpart on HTTPS at the original port for at most 3 hops, while any explicit `authoritative_location` URL uses zero HTTP redirects. This profile follows at most one JSON document-indirection variant, with no document-indirection chain. Apply the trust-root fetch budgets: strict JSON parsing with duplicate keys rejected, a 256 KiB body cap, 5 s connect and 10 s total deadlines, successful-cache lifetime no longer than the JWKS revocation polling interval, and negative caching of at most 60 s.
2. Resolve the agent collection for the asserted domain, then locate exactly one entry whose `type` is `brand` and whose `url` matches the envelope's `agent_url` after applying the shared [URL canonicalization](/dist/docs/3.2.8/reference/url-canonicalization) algorithm. For a Brand Agent or Brand Canonical Document, use the top-level `agents[]`. For a House Portfolio whose `house.domain` equals `brand_domain`, use `house.agents[]`. Otherwise, locate exactly one inline `brands[]` entry whose `url` hostname equals `brand_domain`; use that brand's `agents[]` when present, or `house.agents[]` only when the brand does not override `agents[]`. Never aggregate sibling brands' agents, and do not search `brand_refs[]`, because those entries require resolving the child's canonical document. No domain or agent match is `agent_not_authorized`; multiple inline-domain or canonical agent matches are `agent_authorization_ambiguous`.
3. Resolve the JWKS source **only** from that matched entry's `jwks_uri`, defaulting when absent to `/.well-known/jwks.json` at the origin of the matched entry's `url`. Never accept a JWKS URI supplied by the envelope or discovered independently from the envelope's `agent_url` host. Deduplicate fetches by canonical resolved JWKS URI.
4. Require exactly one JWK whose `kid` matches the protected header, enforce `use: "sig"`, `key_ops` containing `"verify"`, and exact `adcp_use: "response-signing"`, then bind it to the key that verified the envelope. Either re-verify the JWS with this authorized JWK or compare RFC 7638 thumbprints of the authorized and already-verified public keys. Equal `kid` strings are insufficient; zero matches, duplicate matches, or different key material are `untrusted`.
The cross-check produces a verifier-local [`BrandResponseAuthorizationResult`](https://adcontextprotocol.org/schemas/3.2.8/core/brand-response-authorization-result.json); it is never a field asserted by the responding agent. A successful lookup and key-material binding returns `trust: "trusted"`. Any fetch failure, missing or ambiguous agent entry, missing or duplicate `kid`, key-material mismatch, or key-purpose failure returns `trust: "untrusted"` with the corresponding reason. If a verifier skips the cross-check, it MUST treat the envelope as `untrusted` for relationship decisions. “Advisory” means a failed or skipped cross-check does not transport-reject an otherwise cryptographically valid response; it does not make authorization verification optional when extending or revoking relationship trust. A 3.2 verifier MUST NOT let an untrusted result extend or revoke relationship trust on its own, but MAY retain the cryptographically valid envelope as unauthenticated historical evidence or combine it with independent mutual-assertion evidence. It MUST NOT hard-reject solely because this additive advisory check failed. Mandatory cryptographic authorization binding and incompatible hard-fail behavior are deferred to 4.0.
For `verify_brand_claims`, implementations SHOULD deduplicate brand.json fetches by `brand_domain` and JWKS fetches by canonical resolved `jwks_uri` within the batch verification operation to avoid request amplification against brand origins. The advisory applies symmetrically to assertions (`owned`, `licensed_*`, and similar) and rejections (`disputed`, `not_ours`). Conformance vectors and the paired executable reference evaluator live at [`brand-response-signing/brand-authorization-cross-check`](https://adcontextprotocol.org/compliance/latest/test-vectors/brand-response-signing/brand-authorization-cross-check.json).
Response-signing keys are scoped by brand tenant as well as by purpose. A shared multi-brand fleet MUST publish distinct response-signing key material and distinct `kid` values for each `brand_domain` it serves, even when the same software and `agent_url` serve multiple brands. Cross-brand reuse of a response-signing JWK is a profile violation because it defeats tenant-bound replay analysis; this rule is stricter than ordinary cross-purpose separation and applies only to `adcp_use: "response-signing"` keys.
#### Verifier checklist (designated-task response signing)
Verifiers consuming a `signed_response` on `verify_brand_claim` or `verify_brand_claims` MUST apply these checks in order, short-circuiting on the first failure. Steps 1–6 establish cryptographic validity; steps 7–10 enforce the envelope's binding claims. The [brand-authorization cross-check](#designated-task-response-signing) (advisory in 3.2) is a separate, subsequent check — it does not replace the binding checks below.
1. Parse the `signed_response` member. Reject if `protected`, `payload`, or `signature` is absent or structurally malformed.
2. Decode the base64url-encoded JWS protected header. Reject if `alg` is not in the allowlist (`EdDSA`, `ES256`), `kid` is absent, or `typ` is not exactly `adcp-response-payload+jws`.
3. Resolve `kid` to a JWK at the responding agent's `jwks_uri` (defaulting to `/.well-known/jwks.json` at the agent URL's origin when `jwks_uri` is absent). Enforce `use: "sig"`, `key_ops` containing `"verify"`, and exact `adcp_use: "response-signing"`. Reject on any mismatch, including absent `adcp_use`.
4. Canonicalize `signed_response.payload` with RFC 8785/JCS, base64url-encode the result, construct the JWS Signing Input as `BASE64URL(UTF8(protected)) || "." || BASE64URL(UTF8(JCS(payload)))`, and verify the signature against the resolved JWK. Reject if verification fails.
5. Reject if `signed_response.payload.typ` is not exactly `adcp-response-payload+jws`. This prevents cross-profile replay — a governance JWS (`adcp-gov+jws`) or any other typed token MUST NOT validate under this profile.
6. Reject if `signed_response.payload.task` does not match the invoked task (`verify_brand_claim` or `verify_brand_claims`). This prevents cross-task replay — a valid `verify_brand_claim` envelope MUST NOT validate on a `verify_brand_claims` response and vice versa.
7. **Expiry.** Reject if `signed_response.payload.exp ≤ now − skew`, where `skew` is an implementation-defined clock-skew tolerance (SHOULD be ≤ 60 s). Online verifiers MUST reject expired envelopes with `SIGNED_RESPONSE_ENVELOPE_EXPIRED`. Audit verifiers MAY verify after `exp` as historical evidence, but MUST NOT treat the result as current truth. Also reject if `iat > now + skew` (issued in the future).
8. **Request-hash binding.** Recompute the SHA-256 hash of the JCS-canonical request-binding object `{ task, brand_domain, agent_url, caller_identity, request }` using the same derivation rules documented in [the payload field definitions above](#designated-task-response-signing). Reject with `SIGNED_RESPONSE_REQUEST_HASH_MISMATCH` if the recomputed hash does not byte-match `signed_response.payload.request_hash`. This check binds the signed response to the exact request that produced it — without it, a signed response from one request can be replayed as the answer to a different request.
9. **Tenant binding.** Reject with `SIGNED_RESPONSE_TENANT_MISMATCH` if `signed_response.payload.brand_domain` does not match the verifier's resolved or expected brand tenant for this call. The brand agent derives `brand_domain` from server-side tenant resolution, not from caller-supplied request fields; a mismatch indicates cross-tenant replay or a multi-brand agent routing error.
10. **Payload consistency.** Reject if any unsigned task-body field on the outer response disagrees with the corresponding field in `signed_response.payload.response`. Protocol/version envelope fields (`status`, `context_id`, `task_id`, `message`, `timestamp`, `replayed`, `adcp_version`, `adcp_major_version`) and `signed_response` itself are excluded from this comparison.
Only after all 10 checks pass does the verifier treat the signed response as cryptographically valid and bound. The subsequent [brand-authorization cross-check](#designated-task-response-signing) (3.2 advisory) determines whether the signing key is authorized to answer for `brand_domain` — that check is independent of the binding checks above.
#### Transport scope
| Class | 3.0–3.1 | 3.2 | 4.0 |
| - | - | - | - |
| Spend-committing (`create_media_buy`, `update_media_buy`, `acquire_*`, `activate_signal`) | Signing optional; legacy body-binding modes available | Signing optional; every signed body is digest-bound | Signing required and every signed body is digest-bound |
| Reversible state changes (`sync_creatives`, `update_creative_status`) | Signing optional; legacy body-binding modes available | Signing optional; every signed body is digest-bound | Signing recommended; every signed body is digest-bound |
| Read / discovery (`get_products`, `get_media_buy_delivery`, `list_*`) | Not in scope | Not in scope | Not in scope |
| TMP `provider_endpoint_url` requests | Out of scope (TMP has its own envelope) | Out of scope | Out of scope |
Read calls remain bearer-authenticated. Signing read traffic adds verification cost without proportionate benefit; signing's purpose is integrity of state-changing operations.
#### Quickstart: opt into request signing
For implementers adopting request signing in 3.2 ahead of the 4.0 enforcement flip:
**As an agent that signs requests:**
0. Call `get_adcp_capabilities` on the target seller. Read `request_signing.supported_for` and `required_for` to see which AdCP operations the seller expects you to sign, and read `request_signing.protocol_methods_supported_for` / `protocol_methods_required_for` to see which JSON-RPC protocol methods (for example, A2A 0.3 `tasks/cancel` or A2A 1.0 `CancelTask`) the seller's verifier covers. A 3.2 signing peer MUST advertise `covers_content_digest: "required"`; `"either"` and `"forbidden"` identify a legacy 3.0/3.1 signing posture only.
1. Generate an Ed25519 keypair: `openssl genpkey -algorithm ed25519 -out signing-key.pem`.
2. Export the public key as a JWK. Add `"kid"`, `"use": "sig"`, `"key_ops": ["verify"]`, `"adcp_use": "request-signing"`, and `"alg": "EdDSA"`.
3. Publish the JWK at your agent's `jwks_uri` (the URL declared on your `agents[]` entry in brand.json; defaults to `/.well-known/jwks.json` at your agent URL's origin).
4. Configure your AdCP client with the private key and agent URL. Your SDK signs requests automatically for any operation listed in the seller's `supported_for` or `required_for` capability and any JSON-RPC method listed in `protocol_methods_supported_for` or `protocol_methods_required_for`, honoring the seller's `covers_content_digest` policy. SDKs SHOULD support pluggable signers so the private key can live in a managed key store (KMS / HSM / Vault) rather than in process memory — see [Production key storage](#production-key-storage) below.
5. Validate end-to-end with the conformance vectors at [`/compliance/latest/test-vectors/request-signing/`](https://adcontextprotocol.org/compliance/latest/test-vectors/request-signing/) (published per AdCP version; source lives at `static/compliance/source/test-vectors/request-signing/`) — if your client produces signatures that match the positive vectors' `expected_signature_base`, you're done.
**As a verifier (seller):**
1. Advertise `request_signing.supported: true` and `covers_content_digest: "required"` in `get_adcp_capabilities`. Leave `required_for: []` during the pilot; add operations incrementally per counterparty. Signing remains optional in 3.2, but a signature that is presented on a request with a body is never body-optional.
2. Enable signature verification middleware on mutating routes. Implement the [verifier checklist](#verifier-checklist-requests) — all 14 checks (13 numbered steps plus sub-step 9a), short-circuit on first failure.
3. Start in shadow mode for a pilot counterparty before populating `required_for`. Record well-formed verification and body-binding failures, establish no signer identity from them, and continue only under independent authentication. Partial or malformed signature-header pairs still hard-reject. Surface verification failures in monitoring for the first few weeks.
4. Run the conformance negative vectors against your verifier — each rejection MUST produce the vector's stated `error_code`. The vector's `failed_step` is informational; an implementation that rejects with the correct error code is conformant even if its internal step numbering differs.
**Minimum viable 3.2 verifier:** implement the complete checklist, including digest recomputation, before advertising `request_signing.supported: true`. The older 3.0/3.1 shadow-mode allowance that deferred digest enforcement does not satisfy the 3.2 body-integrity contract. Do not skip ahead of step 1 — malformed signatures always reject, never fall back.
#### Production key storage
Where the signer's private key lives is implementation-defined — the spec is concerned only with the bytes on the wire — but operators SHOULD avoid holding private signing keys in process memory in production. A process compromise leaks the signing key, and the only remedy is rotation across every counterparty that's cached the public key (within their cache TTL).
The recommended pattern: an SDK exposes a pluggable signer interface (e.g., `sign(payload: Uint8Array): Promise`), and the operator's adapter delegates the operation to a managed key store — AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault Transit, or an HSM. The key never leaves the managed store; the SDK builds the canonical signature base, the store signs it, the SDK assembles `Signature` and `Signature-Input` headers from the returned bytes. Wire format is identical to in-process signing.
Two implementation notes for adapter authors:
* ECDSA-P256 signatures returned by most KMS APIs are DER-encoded; this profile and RFC 9421 §3.3.1 require IEEE P1363 (`r‖s`, 64 bytes for P-256). Convert at the adapter boundary.
* Treat the KMS key as single-purpose. The `tag` parameter in this profile protects verifiers, not signers — an operator who reuses the same KMS key for AdCP request-signing and any other signing protocol creates a cross-protocol oracle. Bind the KMS access policy (GCP `roles/cloudkms.signer` scoped to the specific cryptoKey, AWS `kms:Sign` conditioned on the key ARN) so only the AdCP signing path can invoke the key.
Reference implementations: `@adcp/sdk` (TypeScript) ships a `SigningProvider` interface with sync/async parity, an in-memory provider for tests, and a GCP KMS reference adapter at [`examples/gcp-kms-signing-provider.ts`](https://github.com/adcontextprotocol/adcp-client/blob/main/examples/gcp-kms-signing-provider.ts). See the [SDK signing guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/SIGNING-GUIDE.md#step-35-production-key-storage--kms--hsm--vault) for the full walkthrough.
**Tripwire pattern — assert public key at init.** Managed key stores can silently rotate (IAM policy swap, version disable, hostile substitution). If rotation happens without updating the published JWKS, verifiers fetching the unchanged `kid` will reject every signature with no clear error signal — the operator sees counterparty failures, not a KMS mismatch. The defense: commit the expected public key (SPKI bytes, base64-encoded) alongside the code, and at signer init byte-compare it against the key the store returns (`getPublicKey()` or equivalent). A mismatch fails loudly at startup rather than silently on every signed call. Rotation then becomes a deliberate two-step: update the pinned constant, set the new key version path, deploy.
**Lifecycle: lazy init, not eager.** Calling `getPublicKey` (or any KMS warm-up call) before the process binds its listener looks clean in review but has a dangerous failure mode: if KMS auth is misconfigured, gRPC / TLS retries inside the KMS client can block indefinitely, the process never opens its port, and the infrastructure health-check times out — surfacing a "service unreachable" alarm rather than the underlying KMS error. The correct lifecycle is lazy init on first sign: call the store the first time a request needs signing, cache the result only on success (never cache errors), and deduplicate concurrent first-call requests with an in-flight promise. Fail-fast misconfig detection belongs in a CI/CD pre-deploy probe that exercises the KMS path with the deployment target's credentials before cutover — not at process startup.
**One JWK per `adcp_use` — publication shape.** The single-purpose rule applies to key material **and** to JWKS publication. Note that webhooks do not need their own purpose: they are signed with a `"request-signing"` key (see [Webhook callbacks](#webhook-callbacks), step 8), so an operator that signs both requests and webhooks with the same key publishes a single `"request-signing"` entry. An operator that wants separate key material for webhooks (blast-radius isolation) publishes a **second `"request-signing"` key with a distinct `kid`** — isolation comes from the `kid`, not a distinct `adcp_use`. The `adcp_use` value is always a **string**, not an array — publishing `"adcp_use": ["request-signing","webhook-signing"]` on a single entry is a schema error that receivers will reject:
```json theme={null}
{
"keys": [
{
"kty": "OKP", "crv": "Ed25519",
"x": "SRYr8eSvjkZF6dAUquI1sKuU4YGZkoGH-2jwkz4dRJg",
"kid": "acme-signing-2026-04",
"alg": "EdDSA", "use": "sig",
"adcp_use": "request-signing",
"key_ops": ["verify"]
},
{
"kty": "OKP", "crv": "Ed25519",
"x": "lHJI-IvBwCE36heDNOyBmCk5UMKRIs4b4BAWJRgao-M",
"kid": "acme-webhook-2026-04",
"alg": "EdDSA", "use": "sig",
"adcp_use": "request-signing",
"key_ops": ["verify"]
}
]
}
```
This second entry is the optional webhook-isolation key from the [Key publication](#webhook-callbacks) section: same `adcp_use: "request-signing"`, distinct `kid`, used to sign webhooks so a webhook-key compromise doesn't extend to request signing. Distinct `kid` values also mean counterparties can cache and rotate the two keys independently.
#### AdCP RFC 9421 profile
This profile constrains RFC 9421 to a single canonical shape so cross-implementation interop is tractable.
**Covered components (REQUIRED on every signed request):**
| Component | Notes |
| - | - |
| `@method` | Uppercase. |
| `@target-uri` | Canonicalized per the algorithm below. Signer MUST apply canonicalization before computing the signature base; verifier MUST apply the same canonicalization to the received request before verifying. |
| `@authority` | Lowercased `host[:port]`, default ports (`443` for https, `80` for http) stripped. |
| `content-type` | Required on requests with bodies. |
| `content-digest` | Governed by the verifier's `request_signing.covers_content_digest` capability — see [Content-digest and proxy compatibility](#content-digest-and-proxy-compatibility). |
**`@target-uri` canonicalization** follows the [AdCP URL canonicalization rules](/dist/docs/3.2.8/reference/url-canonicalization) — eight steps applying RFC 3986 §6.2.2 (syntax-based normalization) and §6.2.3 (scheme-based normalization), plus UTS-46 Nontransitional IDN processing and IPv6 zone-identifier rejection. Signers and verifiers apply the same algorithm; malformed authorities rejected there map to `request_target_uri_malformed` on the signing path. The authoritative algorithm, conformance vectors, and pitfalls list live on that page — keeping this profile's treatment thin prevents divergence between the signing-specific copy and the general-purpose copy.
**`@authority` canonicalization** produces `host[:port]` from the URL's authority after the canonicalization algorithm's host and port steps (lowercase host / IDN → ACE / one trailing DNS root dot removed / IPv6 bracketing preserved; userinfo stripped; default port stripped). IPv6 hosts retain their brackets in `@authority` (`[::1]:8443`). A signer and verifier MUST remove exactly one trailing DNS root-label dot before deriving both `@target-uri` and `@authority`; `https://example.com./p` therefore yields `https://example.com/p` and `example.com`. The same rule applies to equivalent IDN U-label and A-label inputs, so `bücher.example.` and `xn--bcher-kva.example.` both yield authority `xn--bcher-kva.example`. An authority with multiple trailing dots is malformed and MUST be rejected with `request_target_uri_malformed`. Verifiers MUST apply these rules to the HTTP authority source before comparison. Verifiers MUST derive `@authority` from the HTTP/2+ `:authority` pseudo-header when present, otherwise from the as-received HTTP/1.1 `Host` header — not from reverse-proxy routing state, load-balancer metadata, or any `Host` value a forward proxy may have rewritten in transit. **When both `:authority` and `Host` are present on the as-received request** (HTTP/2→HTTP/1.1 translating intermediaries are permitted to leave both by RFC 7540 §8.1.2.3, which requires equivalence but does not require stripping the source), verifiers MUST reject with `request_target_uri_malformed` if they are not byte-equal after canonicalization; pick-one behavior is a silent downgrade surface. Regardless of the source header, the canonicalized value MUST byte-for-byte match the authority component of the canonical `@target-uri` — the byte-match against the signed `@target-uri` is the load-bearing safety gate, because `Host` can itself be rewritten in transit. Mismatch rejects with `request_target_uri_malformed`. This closes a cross-vhost replay vector: an attacker who intercepts a TLS-terminated request and replays it to a second vhost on the same verifier pool (same cert SAN, different `Host`) will fail the authority-match check even though the signature covers `@authority`.
Signers that canonicalize and verifiers that canonicalize MUST produce identical bytes for the same logical request. If your 9421 library applies different rules, either configure it to match this profile or normalize before handing the URL to the library.
The [`canonicalization.json`](https://adcontextprotocol.org/compliance/latest/test-vectors/request-signing/canonicalization.json) conformance set exercises every rule from the algorithm with fixed inputs and expected outputs, plus malformed-authority rejection cases. SDKs SHOULD run this set on every commit — canonicalization divergence between signers is silent until it isn't, and then it's a production interop bug that's painful to diagnose.
Verifiers MUST reject signatures whose covered-component list omits any required component for the request type. Signers MUST NOT cover additional headers without coordination — extra components silently invalidate signatures across implementations that don't include them.
**MCP transport sessions are non-authoritative.** `Mcp-Session-Id` is not a
covered component in this profile and MUST NOT carry AdCP-relevant authority.
A verifier MUST NOT attribute identity, authorization, account selection,
resource access, or task ownership on the basis of `Mcp-Session-Id` or other
unsigned session-continuity or routing metadata. This prohibition does not
include recognized per-request credential channels such as `Authorization`.
For an operation that requires authentication or authorization, the decision
MUST derive from those per-request credentials and, when request signing
applies, the covered components and digest-bound body. Public and bootstrap
operations retain their documented authentication policy. A stateful MCP
implementation MAY use a session for transport continuity or task waiting.
It MAY also use session-local caches only after per-request authentication and
only when every entry is additionally keyed by the authenticated principal and
account. Rebinding an otherwise valid request to another session MUST NOT
change the principal, authorization decision, resource namespace, returned
cached data, or ownership decision applied to that request.
**Signature parameters (`Signature-Input` parameters, all REQUIRED):**
| Parameter | Notes |
| - | - |
| `created` | Unix seconds. Reject if more than 60 s in the future. |
| `expires` | Unix seconds. MUST satisfy `expires > created` and `expires − created ≤ 300` (5-minute max validity). Reject if past, with ±60 s skew tolerance. |
| `nonce` | Base64url-encoded, unpadded (no trailing `=`). Verifiers MUST reject if the decoded byte length is less than 16 bytes, or if the value includes padding. This is how the "≥ 128 bits of entropy" requirement is enforced in practice. |
| `keyid` | Matches a `kid` in the signer's published JWKS. |
| `alg` | MUST be `ed25519` or `ecdsa-p256-sha256`. Verifiers MUST enforce the allowlist independently of library defaults. |
| `tag` | MUST be exactly `adcp/request-signing/v1` — byte-for-byte match, no prefix matching, no case-folding. The `tag` sig-param MUST appear exactly once in `Signature-Input`; verifiers MUST reject duplicates. The tag namespace is how the profile versions; future versions bump the tag rather than mutating parameter semantics, and `adcp/request-signing/v2` verifiers will reject `v1` signatures and vice versa. |
All six parameters are REQUIRED. Verifiers MUST reject (`request_signature_params_incomplete`) if any is absent.
**Algorithm naming — JWK vs RFC 9421.** The two names for each algorithm differ by source spec. Implementations mix these up often enough to warrant a table:
| Algorithm | JWK `alg` (in JWKS) | RFC 9421 `alg` (in `Signature-Input`) |
| - | - | - |
| Ed25519 | `EdDSA` | `ed25519` |
| ECDSA P-256 with SHA-256 | `ES256` | `ecdsa-p256-sha256` |
When the verifier resolves a `keyid` and finds `"alg": "EdDSA"` on the JWK, the matching sig-param value is `ed25519`. Implementations should validate that the two match (JWK alg matches the sig-param alg by mapping table) in addition to verifying the allowlist on each independently. Edge-runtime rationale from the governance profile applies — `ES256` is the edge-friendly alternative where `EdDSA` requires runtime configuration.
**One signature per request.** Verifiers MUST process exactly one `Signature-Input` label (conventionally `sig1`) and MUST ignore any additional labels present in the request. Intermediaries that need to re-sign a relayed request MUST replace the upstream labels rather than append to them. Full relay-chaining semantics (when a relay wants to preserve the originator's signature) are tracked in [#2324](https://github.com/adcontextprotocol/adcp/issues/2324) and out of scope for 3.0.
**Request-profile binary value encoding (`Signature`, `Content-Digest`).** RFC 9421 and RFC 9530 encode these values as RFC 8941 Structured Field `sf-binary` tokens (`::`). AdCP 3.2 request signing (`tag="adcp/request-signing/v1"`) aligns with those RFCs: signers MUST use the standard RFC 4648 §4 Base64 alphabet with `+` and `/` and the padding required by RFC 8941; request verifiers MUST parse the field as `sf-binary` before using its decoded bytes. Base64URL characters (`-` and `_`) are not valid inside 3.2 request `sf-binary` and MUST be rejected as `request_signature_header_malformed`. This differs intentionally from the `nonce` signature parameter, whose quoted string value uses unpadded Base64URL.
AdCP 3.0/3.1 request signing used a legacy profile override that encoded these binary values as unpadded Base64URL. A request signer selects the wire encoding from the trusted negotiated signing profile: use legacy Base64URL only on an explicitly negotiated 3.0/3.1 request-signing endpoint, and use RFC 8941 Base64 for 3.2 and later. A 3.2 request verifier MUST NOT reinterpret a Base64URL token as `sf-binary` or retry it through a legacy decoder. The versioned conformance fixtures preserve both profiles so SDKs can test an intentional migration rather than accepting both alphabets ambiguously. The separately routed `adcp/webhook-signing/v1` profile retains its legacy Base64URL encoding throughout 3.x; webhook parser selection is endpoint/profile configuration and MUST NOT enable a fallback in the 3.2 request parser.
The `expected_signature_base` field in the conformance vectors is independent of binary-value encoding: it contains the canonical signature-base bytes, while the emitted `Signature` token contains the resulting signature bytes encoded as `sf-binary`.
**Operation names in `required_for` / `supported_for` are AdCP protocol operation names** (`create_media_buy`, `update_media_buy`, `acquire_rights`, etc.) — not MCP tool names, A2A skill names, or any transport-specific rename. (The AdCP A2A profile sets the invocation `skill` to the AdCP operation name exactly, so the two coincide there; see [Operation resolution](#operation-resolution-over-a2a).) Verifiers MUST NOT accept operation names that are not defined by the AdCP protocol spec. This is how cross-transport verifiers agree on what "signed for `create_media_buy`" means.
**Protocol-method coverage (`protocol_methods_*`).** AdCP operations are not the only mutating surface a counterparty calls. A2A 0.3 uses slash-path JSON-RPC method names such as `tasks/cancel` and `tasks/pushNotificationConfig/set`; A2A 1.0 uses PascalCase names such as `CancelTask` and `CreateTaskPushNotificationConfig`. MCP transports may also register `tasks/*` JSON-RPC methods when an SDK task store is wired. Sellers declare verifier coverage of these methods in a separate namespace from the AdCP operation list:
| Field | Contents | Match semantics |
| - | - | - |
| `request_signing.protocol_methods_supported_for` | Exact JSON-RPC method strings (for example, `"tasks/cancel"`, `"tasks/pushNotificationConfig/set"`, or `"CancelTask"`) | Verifier accepts and validates a signature when the JSON-RPC `method` field of the inbound request matches. |
| `request_signing.protocol_methods_warn_for` | Same | Shadow-mode mirror of `warn_for`: record well-formed verification failures, establish no signer identity, and continue only under independent authentication. Malformed signature-header pairs still hard-reject. |
| `request_signing.protocol_methods_required_for` | Same | Reject unsigned matches with `request_signature_required`. |
The matched value is the decoded JSON string in the JSON-RPC envelope's `method` field, **not** the MCP `tools/call` `params.name`. Matching MUST use exact, case-sensitive string equality after JSON decoding: `tasks/cancel`, `CancelTask`, and `cancelTask` are distinct strings, while JSON escape spellings that decode to the same string are not distinct method names. Implementations MUST NOT translate, case-fold, apply Unicode normalization, or otherwise normalize names between A2A versions. A dual-stack agent therefore lists every wire name it covers; declaring `tasks/cancel` does not also declare `CancelTask`.
The two A2A versions name the same methods differently, so check the pairs you care about:
| A2A 0.3 | A2A 1.0 |
| - | - |
| `message/send` | `SendMessage` |
| `message/stream` | `SendStreamingMessage` |
| `tasks/get` | `GetTask` |
| `tasks/cancel` | `CancelTask` |
| `tasks/resubscribe` | `SubscribeToTask` |
| `tasks/pushNotificationConfig/set` | `CreateTaskPushNotificationConfig` |
The A2A 0.3 and 1.0 names used by the conformance vectors are in [`protocol-method-names.json`](https://adcontextprotocol.org/compliance/latest/test-vectors/request-signing/protocol-method-names.json). Say a seller serves A2A 0.3 and 1.0 clients and requires signatures on task cancellation and push-notification registration. It declares both spellings of each method:
```json theme={null}
{
"request_signing": {
"supported": true,
"covers_content_digest": "required",
"supported_for": ["create_media_buy"],
"required_for": ["create_media_buy"],
"protocol_methods_supported_for": ["tasks/cancel", "CancelTask", "tasks/pushNotificationConfig/set", "CreateTaskPushNotificationConfig"],
"protocol_methods_required_for": ["tasks/cancel", "CancelTask", "tasks/pushNotificationConfig/set", "CreateTaskPushNotificationConfig"]
}
}
```
An A2A 1.0 client cancels with `{"jsonrpc": "2.0", "method": "CancelTask", ...}`. That matches `CancelTask`. If the seller had listed only `tasks/cancel`, the request wouldn't match, and an unsigned 1.0 cancel wouldn't get `request_signature_required`. `message/send` works the same way: listing it doesn't cover A2A 1.0 `SendMessage` requests, and listing `SendMessage` covers every A2A 1.0 message no matter which AdCP operation it carries. So it's rarely what you want in `protocol_methods_required_for`: it would also cover `get_adcp_capabilities` and `get_products`, and an unsigned capability fetch is how a new buyer bootstraps. To require signatures for one AdCP operation over A2A, list the operation in `required_for` and resolve it as [Operation resolution over A2A](#operation-resolution-over-a2a) describes.
`lower_snake_case` AdCP operation names such as `create_media_buy` MUST NOT appear in any `protocol_methods_*` array. The reserved MCP envelope method `tools/call` also MUST NOT appear there because its AdCP operation identity is the decoded `params.name`, which is matched against `supported_for` / `warn_for` / `required_for`. JSON-RPC protocol method names — slash-path A2A 0.3 names or PascalCase A2A 1.0 names — MUST NOT appear in those AdCP-operation arrays. Verifiers MUST reject capability blocks that violate the namespace split with a configuration-time error rather than silently coercing strings between the two. **Verifiers MUST NOT cross-namespace match: a `protocol_methods_required_for` membership MUST NOT be satisfied by a body whose JSON-RPC `method` is `tools/call` (even if `params.name` happens to equal a listed method string), and a `required_for` membership MUST NOT be satisfied by a JSON-RPC `method` string itself.** A `required_for` membership is satisfied only by the AdCP operation the verifier resolves from the request, which is `params.name` for `tools/call` and the invocation `skill` for A2A messages ([Operation resolution over A2A](#operation-resolution-over-a2a)). The two buckets are matched against disjoint decoded envelope fields: `protocol_methods_*` against the JSON-RPC `method` only, the operation lists against the resolved operation only.
The signature-base construction is identical for both namespaces and both A2A versions: the same RFC 9421 covered components apply (`@target-uri`, `@method`, `content-digest` per the seller's `covers_content_digest` policy, `authorization` when present), with `@target-uri` and `@method` reflecting the actual HTTP request — not the JSON-RPC method string. Buyers signing a `tasks/cancel` or `CancelTask` POST sign exactly as they would for any other mutating call; the protocol-method fields only change the seller's declaration of which JSON-RPC methods are in scope for verification.
**Body substitution on shared transport.** When a single `@target-uri` accepts `tools/call` envelopes and JSON-RPC protocol methods (the canonical MCP layout — both POST to `/mcp`), `@target-uri` and `@method` alone do not bind the body. Without `content-digest` coverage, an on-path attacker can substitute another tool, switch `tools/call` to `tasks/cancel`, or change parameters within the same method during the signature window. Distinct URIs do not solve same-method parameter substitution, so they are not an integrity alternative. In 3.2 every accepted signature on a request with a body MUST cover `content-digest`, regardless of which operation or protocol-method list caused the verifier to process it.
Buyers reading capability blocks in 3.x MUST NOT assume protocol-method coverage from `supported_for` / `required_for`: a seller that lists `create_media_buy` in `required_for` and is silent on `protocol_methods_*` is not declaring `tasks/cancel` or `CancelTask` coverage. Buyer SDKs that sign protocol methods opportunistically when the seller is silent MAY do so without violating the spec, but interoperable enforcement only emerges once the seller populates `protocol_methods_supported_for` or `protocol_methods_required_for` with the exact wire name used by the request.
#### Operation resolution over A2A
`required_for`, `supported_for`, and `warn_for` are matched against the **resolved AdCP operation**, which the verifier computes once from the decoded request. This section is a security erratum. It resolves a contradiction between this document, which said a `required_for` match could not be satisfied by any JSON-RPC `method` other than `tools/call`, and the [A2A profile](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension#security-and-validation), which requires the signing rules used for the equivalent task over MCP. The fail-closed reading wins, and the earlier `tools/call`-only sentence is superseded. Clauses marked *hardening* are additions, not restatements, and are SHOULD in 3.2.x and MUST from 3.3.
| Request | Resolved operation |
| - | - |
| MCP JSON-RPC `tools/call` | The decoded `params.name`. |
| A2A JSON-RPC `SendMessage` or `SendStreamingMessage` (1.0); `message/send` or `message/stream` (0.3) | The decoded `skill` of the Message's sole DataPart (`params.message.parts[].data.skill`; A2A 0.3 Parts also carry `kind: "data"`). |
| A2A HTTP+JSON `POST …/message:send` or `…/message:stream`; A2A gRPC `SendMessage` or `SendStreamingMessage` | The same `skill`, read from the decoded request's `message`. |
| Any other JSON-RPC method (`tasks/cancel`, `CancelTask`, `GetTask`, …) | None. These match only `protocol_methods_*`. |
The A2A profile defines the invocation shape for A2A 1.0 over JSON-RPC; for A2A 0.3 and for the other bindings an agent serves, this section extends the same resolution by analogy. An agent that cannot apply it on a binding MUST NOT dispatch AdCP operations over that binding. Resolution reads only `skill`: the `input` member, or the legacy 3.0/3.1 `parameters` member, is the dispatcher's concern.
A verifier on an interface that dispatches AdCP operations MUST apply these rules to every POST to that interface. They key on the request's method or path, never on the `A2A-Extensions` header, so a request that omits or misstates extension activation resolves the same way.
1. **Fail closed.** A request that does not resolve to exactly one operation MUST be rejected with `request_body_malformed`, whether or not it is signed, before the verifier consults any capability list and before the request reaches a handler. An A2A Message MUST contain exactly one DataPart, and its `data` MUST be a JSON object whose `skill` is a non-empty string; a text-only message on an AdCP interface is rejected. An unresolvable request is never "an operation that is not in `required_for`". The A2A profile already requires this shape; the rule makes the rejection a precondition of the signature gate. An interface that serves generic conversational A2A under a [separate Agent Card](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension#relationship-to-a2a-async-and-conversation) and dispatches no AdCP operation is outside this rule.
2. **Exact match, no fallback.** The `skill` string, and the method name that selects the A2A message-carrying path, are compared by exact, case-sensitive equality after JSON decoding, with no trimming, case-folding, normalization, or alias. A `skill` that is not an AdCP operation name is rejected by the agent's ordinary unsupported-operation handling and MUST NOT reach a default handler, a text- or model-based router, or an Agent Card `skill.name`, `tags`, or alias lookup. A dispatcher MUST reject any method or path the gate would not have recognized as message-carrying, so a variant spelling such as `sendmessage` cannot reach a handler the gate treated as "no operation".
3. **One source, three uses.** The resolved operation is the only input to (a) the operation-list lookup, (b) handler dispatch, and (c) request-schema selection. Nothing else may influence it: not a TextPart, Part, `message.metadata`, or `params.metadata` value, not the URL path, a header such as `A2A-Extensions`, a `tenant` value, an Agent Card `skill.name`, or the shape of `input`. When the signature gate and the dispatcher are separate components, for example HTTP middleware ahead of an A2A executor, the gate passes its resolved operation to the dispatcher through trusted request context, or the dispatcher re-resolves with this same algorithm over the same bytes. In both cases a dispatcher whose operation differs from the gate's MUST reject before handler entry. Resuming a task by `message.taskId` MUST NOT run a handler other than the resolved operation's. These rejections come after the gate, so they are task-level `INVALID_REQUEST` errors, not transport `request_*` codes.
4. **Pre-check ordering.** Resolution runs first in the pre-check of the [verifier checklist](#verifier-checklist-requests), before the signature-header pair checks, the `required_for` test, and step 1. A request that is both unresolvable and carries a malformed `Signature` / `Signature-Input` pair is rejected with `request_body_malformed`. The rejection is a transport-taxonomy `401` carrying the error code, like every `request_*` code, not an A2A task error.
5. **Both namespaces apply.** A request can match both buckets, for example `SendMessage` in `protocol_methods_required_for` and `create_media_buy` in `required_for`. Either match requires the signature.
**Hardening.** These are additions to the contradiction fix. Verifiers SHOULD apply them in 3.2.x and MUST from 3.3; vectors tagged `hardening` grade them.
* **Strict parse before classification, on unsigned bodies too.** The body is exactly one JSON-RPC request object (or, for HTTP+JSON, one request object) with a string `method`. A verifier that accepts JSON-RPC batches MUST resolve every element and require a signature if any element matches; one that does not MUST reject a JSON array. Batch semantics beyond this are tracked in [#7565](https://github.com/adcontextprotocol/adcp/issues/7565). Duplicate object keys in the envelope, `params`, `message`, each Part, and `data` are rejected after JSON string decoding, so `"skill"` and `"sk\u0069ll"` collide; a verifier MAY apply the whole-body check of step 14 instead. Member names are matched case-sensitively, and an object carrying a case variant of a recognized member (`Skill`, `Parts`) is rejected, because some decoders match names case-insensitively.
* **Part shape.** A Part carries exactly one content member (`text`, `data`, `raw`, or `url` in A2A 1.0; `text`, `data`, or `file` in 0.3), and a `kind`, when present, agrees with it. The Message carries no FilePart (`raw`, `url`, `file`).
* **Task continuation binding.** A request with `message.taskId` is rejected before handler entry unless its resolved operation equals the operation the task was created for and the caller is the principal that created it.
What this does not change: `required_for` still yields to a configured fallback authenticator under [Composition with fallback authenticators](#composition-with-fallback-authenticators), and 3.0/3.1 endpoints on the legacy `"either"` or `"forbidden"` digest posture do not bind the body. On the 3.2 profile a signed A2A request covers `content-digest`, so `skill` is bound by the signature and a captured body cannot be replayed as a different operation. `warn_for` resolves the same way, so a seller can watch unsigned A2A traffic for an operation in `warn_for` before it moves the operation to `required_for`; a seller that skips that step will start rejecting buyers that were previously getting through. Until SDK verifiers adopt the resolution rule, a verifier that predates it does not enforce `required_for` over A2A, and listing the A2A message methods in `protocol_methods_required_for` is the stopgap, at the cost of also requiring a credential on the unsigned capability fetch a new buyer uses to bootstrap.
Buyers sign any operation in `required_for`, and SDKs SHOULD choose what to sign from the resolved `skill`, not the method. A signature on an operation the seller does not require costs nothing.
#### Agent key publication
Request-signing keys live at the signing agent's own `jwks_uri` in its operator's brand.json `agents[]` entry, and outbound webhooks are signed with `"request-signing"` keys (optionally with distinct webhook-only key material under a separate `kid`). Every agent that signs — of any `type` — uses the same publication pattern. Publisher `adagents.json` may additionally pin allowed seller keys through `authorized_agents[].signing_keys[]`; when present, that pin is authoritative for the scoped sell-side authorization.
**Publisher pin precedence.** When a publisher's `adagents.json` entry for an authorized agent carries a `signing_keys` pin (see [`adagents.json` §`signing_keys`](/dist/docs/3.2.8/governance/property/adagents#signing_keys)), that pin is authoritative: verifiers MUST reject any signature whose `keyid` is not in the pinned set, regardless of `jwks_uri` contents. The agent-hosted JWKS is advisory whenever a publisher pin exists. This closes the agent-domain-compromise window — an attacker who takes over the agent's domain cannot silently swap both the endpoint and its advertised keys because the publisher's pin still governs acceptance. Publishers are required to pin for any agent whose delegated scopes include mutating operations; see the adagents.json rule for rotation and cache semantics.
Each request-signing JWK entry MUST declare:
| Member | Value | Notes |
| - | - | - |
| `use` | `"sig"` | Standard JWK signing use. |
| `key_ops` | `["verify"]` | Verifier-visible JWKS declares verify-only. The signing operator holds the corresponding private key locally with `["sign"]` per JWK spec. |
| `adcp_use` | `"request-signing"` | AdCP-specific purpose discriminator. Distinguishes from `"governance-signing"` (JWS profile) and any future AdCP signing purpose. Verifiers MUST reject any JWK with absent or different `adcp_use` when verifying a request signature. The same `"request-signing"` key (or a second one under a distinct `kid`) also signs outbound webhooks — see [Webhook callbacks](#webhook-callbacks). (`"webhook-signing"` is a deprecated purpose pending removal — see [#5555](https://github.com/adcontextprotocol/adcp/issues/5555); still accepted on the webhook path for backward compatibility.) |
| `kid` | distinct | Unique within the JWKS. MUST NOT collide with any other entry's `kid` regardless of `adcp_use`. |
| `alg` | `"EdDSA"` or `"ES256"` | Must match the signature's `alg` parameter (JWK `alg` uses JWS names; `alg` in `Signature-Input` uses RFC 9421 names). |
Cross-purpose key reuse is forbidden and **locally enforceable** via `adcp_use`, except for the explicit webhook relaxation above: a `"request-signing"` key may sign either requests or webhooks because the RFC 9421 `tag` separates those profiles. A single JWK entry can only declare one `adcp_use` value, so a publisher cannot accidentally (or deliberately) present a governance-signing key as a valid request-signing key. Verifiers check `adcp_use` on the JWK they fetched, not across other JWKS endpoints — no cross-endpoint lookup is required or permitted.
**Origin separation (MUST for governance, SHOULD for others).** `adcp_use` is an in-band discriminator — it prevents cross-purpose verification, but it does not defend the publishing origin. An origin compromise on a shared JWKS endpoint simultaneously compromises every signing purpose it publishes. Because a governance-signing key is the highest blast-radius key in the system (its compromise is a multi-tenant breach), governance signing keys MUST be served from a separate origin than transport/webhook RFC 9421 keys. The canonical pattern is:
* `governance-keys.{org}.example/.well-known/jwks.json` — governance-signing JWKs only
* `keys.{org}.example/.well-known/jwks.json` — request-signing keys (including webhook-only `kid`s), deprecated webhook-signing keys during the backward-compatibility window, and TMP keys
Operators SHOULD go further and serve each signing surface from a distinct subdomain. Defense-in-depth: governance keys SHOULD be on offline-rotation (HSM/KMS with manual rotation and human approval), while transport and webhook keys MAY use automated rotation. Operators advertise their separation scheme by publishing an `identity.key_origins` map in `get_adcp_capabilities`; the schema defines `governance_signing`, `request_signing`, `webhook_signing`, and `tmp_signing` origin URIs. `webhook_signing` names the webhook delivery surface, not a required live `adcp_use: "webhook-signing"` purpose; it may point at the same origin as `request_signing` when webhooks use request-signing keys. Implementers SHOULD populate the field so counterparties can verify origin separation at onboarding. **When the field is present, verifiers MUST check that the declared governance-signing origin differs from the declared request/webhook signing origins at onboarding and reject onboarding with a user-actionable error on co-tenancy.** The MUST on origin separation is otherwise unverifiable on the wire — the whole point of publishing the advertisement is to let counterparties enforce it programmatically; accepting a declaration that violates the normative rule would defeat the control. Verifiers MAY additionally fetch each declared JWKS and confirm its `jwks_uri` origin matches the advertised value.
**Implementer note:** `adcp_use` is a custom JWK member. Major JOSE libraries (`jose`, `node-jose`, `python-jose`, `go-jose`) preserve unknown members on parse. Strict JWK validators (some modes of `PyJWT`, and Web Crypto API's `SubtleCrypto.importKey`) may reject unknown members. When handing a JWK to `SubtleCrypto.importKey` or equivalent strict consumers, strip `adcp_use` from the JWK object but retain it for the step-8 policy check. The field is for AdCP verifier policy, not for cryptographic libraries.
**JWKS discovery for a signed request** — given a `keyid` on an incoming signature:
1. The verifier resolves the signing agent's URL to its brand.json `agents[]` entry. Discovery MAY come from prior onboarding, MAY come from a registry cache, but the canonical on-wire bootstrap is the `identity.brand_json_url` field on the agent's `get_adcp_capabilities` response — see [Discovering an agent's signing keys via `brand_json_url`](#discovering-an-agents-signing-keys-via-brand_json_url).
2. Fetch the agent's `jwks_uri` (or default to `/.well-known/jwks.json` at the origin of the agent's `url`) with SSRF validation per [Webhook URL validation](#webhook-url-validation-ssrf). JWKS cache TTL bounded above by the revocation-list polling interval.
3. If the `kid` is absent from the cached JWKS, refetch the JWKS **immediately** (step 2's first fetch may have been cached). If a refetch was already performed in the last 30 seconds for the same `jwks_uri`, the cooldown applies: the verifier MUST NOT refetch again and MUST reject with `request_signature_key_unknown`. The cooldown is between refetches, not before the first.
Verifiers MUST NOT accept signatures from a `keyid` they cannot resolve to a specific `agents[]` entry — anonymous signatures provide no accountability.
**Canonical signed-Agent identity.** Once the publication chain and request signature verify, the canonical form of the exactly matched `agents[].url` is the authenticated Agent subject. That canonical URL—not the operator domain, input spelling, `brand_json_url`, `jwks_uri`, `keyid`, thumbprint, or key generation—is the stable input to a seller-local principal mapping. Distinct canonical Agent URLs remain distinct even when they share a domain, operator, type, or JWKS endpoint. Rotation to another authorized key under the same canonical Agent URL preserves identity. A resolver that starts from a key or cached JWKS mapping and cannot select exactly one canonical Agent URL MUST fail closed; it MUST NOT choose the first entry, collapse entries by domain, or key state by the credential.
#### Discovering an agent's signing keys via `brand_json_url`
The `identity.brand_json_url` field on `get_adcp_capabilities` (added in 3.x, see schema `static/schemas/source/protocol/get-adcp-capabilities-response.json`) is the on-wire bootstrap for the agent → operator → keys chain. The field name reflects the artifact it points at (the operator's `brand.json` file), independent of whether the operator structure is a single brand, a house with sub-brands, an agency, or a pure operator record. In this section (apart from the `authorized_operators[]` field), *operator* means the agent's operator: whoever publishes the brand.json that lists the agent and its keys. It isn't the `operator` in an account's natural key. For buyer-declared accounts, that value comes from `accounts[].operator` on `sync_accounts` and `account.operator` on later calls, and one agent can act for many account operators (see [Seller walkthrough: buyer-declared accounts](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#seller-walkthrough-buyer-declared-accounts)). Given only an agent URL `A`, a verifier resolves the agent's signing keys via:
1. Fetch `A`'s `get_adcp_capabilities` response with SSRF validation per [Webhook URL validation](#webhook-url-validation-ssrf) (HTTPS only — the URL `A` is supplied by the caller and MUST go through the same address-family + private-IP filtering used for webhook callbacks). On unreachable/timeout, reject with `request_signature_capabilities_unreachable`.
2. Read `identity.brand_json_url`. If absent and the request is signed, reject with `request_signature_brand_json_url_missing`. Reject with the same code if the value is non-HTTPS (the schema enforces `^https://` but verifiers MUST restate the check; a 3.x parser tolerating a malformed value MUST NOT proceed). The required-when rule is: `identity.brand_json_url` MUST be present when the agent declares `request_signing.supported_for`/`required_for` non-empty, `webhook_signing.supported === true`, or any field under `identity.key_origins`. This is storyboard-enforced in 3.x. In 4.0 the rule becomes schema-required when the response declares `supported_versions` containing any 4.x release; cross-version verifiers (4.0 talking to a 3.x agent that does not advertise 4.x support) MUST continue to accept absent `identity.brand_json_url`.
3. **Origin binding.** The agent URL `A`'s host eTLD+1 MUST equal the `brand_json_url`'s host eTLD+1. eTLD+1 computation MUST use a pinned, dated [Public Suffix List](https://publicsuffix.org/list/public_suffix_list.dat) snapshot (ICANN+PRIVATE sections both in scope so platforms like `vercel.app`, `pages.dev`, `github.io` are treated as suffixes); two verifiers running different PSL versions are non-conformant against each other. If eTLD+1 mismatches, fetch brand.json and check that `authorized_operators[]` lists `A`'s eTLD+1. If neither holds, reject with `request_signature_brand_origin_mismatch`. This closes the shared-tenancy spoofing vector where an attacker stands up an agent on `attacker.example/mcp` and points its `brand_json_url` at an unrelated operator's brand.json that happens to legitimately list `attacker.example/mcp` (e.g., a SaaS multi-tenant deployment).
4. Fetch brand.json at the exact `brand_json_url` with SSRF validation per [Webhook URL validation](#webhook-url-validation-ssrf). Verifiers MUST NOT follow HTTP redirects on this explicit-URL fetch. This is distinct from a domain-derived `/.well-known/brand.json` bootstrap and from JSON document-indirection variants. Recommended budgets: connect 5 s, total deadline 10 s, body cap 256 KiB. Cache TTL on a successful fetch MUST be bounded above by the JWKS revocation polling interval (so a key rotation cannot be masked by a stale brand.json). Negative responses (404, network failure) MUST NOT be cached for more than 60 s — operators fixing a misconfiguration must not be locked out for a full revocation cycle.
5. Canonicalize `A` and every candidate `agents[].url` with the shared [AdCP URL canonicalization algorithm](/dist/docs/3.2.8/reference/url-canonicalization), then find entries whose canonical URL equals canonical `A`. If none matches, reject with `request_signature_agent_not_in_brand_json`. If multiple entries match after canonicalization, reject with `request_signature_brand_json_ambiguous`; never select the first. Retain the matched canonical URL as the verified Agent identity if the remaining key checks succeed. A trailing slash remains significant under the shared algorithm, while scheme/host case, default ports, dot segments, and percent-encoded unreserved characters normalize as specified there.
6. Resolve the JWKS source by **signing surface AND role** (sender-vs-receiver position, not just `adcp_use`):
* **Sell-side webhook delivery only** — i.e., the seller signing an outbound webhook to the buyer about media-buy delivery: the publisher's `adagents.json signing_keys` pin (when present) is authoritative per the publisher-pin precedence rule above and overrides everything below. The pin is scoped to (agent, webhook delivery surface, sell-side role) — it does NOT override operator-side webhook deliveries (e.g., a buyer-hosted webhook receiving operator status callbacks), and it does not imply a separate `adcp_use: "webhook-signing"` key purpose.
* **All other (surface, role) tuples** — request signing (any direction), operator-side webhook delivery, governance signing, TMP signing: use the matched `agents[]` entry's `jwks_uri`, defaulting to `/.well-known/jwks.json` at the origin of that entry's `url` when absent.
7. **`identity.key_origins` consistency check (mandatory when signing).** For every surface/purpose declared under `identity.key_origins` on the capabilities response **whose JWKS source in step 6 was the operator brand.json** (i.e., not a publisher `adagents.json signing_keys` pin), the host of the resolved `jwks_uri` MUST equal the declared origin for that surface/purpose. Mismatch on any surface/purpose → reject with `request_signature_key_origin_mismatch` carrying `{ purpose, expected_origin, actual_origin }`. Skip the check **only** for the specific (agent, surface/role) tuple whose source was a publisher pin — operator-side use of the same surface is still checked. If the agent declares signing without a corresponding `identity.key_origins.{purpose}` entry, reject with `request_signature_key_origin_missing` carrying `{ purpose, posture }`.
8. Fetch JWKS, find the `kid`, verify per the existing RFC 9421 profile (steps 7+ of the [verifier checklist](#verifier-checklist-requests)).
**Trust roots.** brand.json is operator-attested ("this agent is mine, here are its keys"). `adagents.json` is publisher-attested ("this agent may sell my inventory; optionally, here is its pinned `signing_keys`"). For sell-side webhook signatures, the publisher pin is authoritative (publisher > operator). For request signatures and operator-side webhook signatures, the operator brand.json `jwks_uri` is authoritative. The agent never self-attests its own keys — a `jwks_uri` field is deliberately NOT carried on the capabilities response; the operator publishes the keys out-of-band via brand.json.
**`sponsored_intelligence.brand_url` is distinct.** SI agents may carry a `brand_url` field under `sponsored_intelligence` for rendering purposes (colors, fonts, logos, tone) — the field is named `brand_url` because, in the SI context, it really is "the brand being advertised." That field is a rendering pointer, not a trust-root pointer; an SI agent MAY set its `sponsored_intelligence.brand_url` to a different URL than its `identity.brand_json_url` (e.g., a sub-brand brand.json for rendering while still trusting the operator's brand.json for keys). **Verifiers MUST use `identity.brand_json_url` for key discovery; `sponsored_intelligence.brand_url` MUST NOT be used as a trust-root pointer even when `identity.brand_json_url` is absent.** A verifier consuming SI rendering metadata MAY read `sponsored_intelligence.brand_url`; the same verifier MUST switch to `identity.brand_json_url` for any signature-verification flow. The naming distinction is deliberate: `brand_url` for "the brand being advertised" contexts; `brand_json_url` for "the operator master record" contexts.
**Rejection codes for this discovery chain (3.x).** Detail fields sourced from a counterparty document (`brand_json_url`, `matched_entries[]`) MUST be HTML-escaped before rendering in admin UIs that display verifier errors — they are attacker-influenceable strings, even though the structured shape is verifier-controlled.
| Code | When | Detail fields | Remediation |
| - | - | - | - |
| `request_signature_brand_json_url_missing` | Capabilities did not carry `identity.brand_json_url` and a signed request was received, or carried a non-HTTPS value | `agent_url` | Operator: set `identity.brand_json_url` to the HTTPS URL of your operator brand.json (typically `https://{your-domain}/.well-known/brand.json`). Verifier: surface to operations; do not retry. |
| `request_signature_capabilities_unreachable` | Capabilities fetch failed (DNS, TCP, TLS, timeout, non-2xx) | `agent_url`, `http_status`, `dns_error`, `last_attempt_at` | Verifier MAY retry once after a 1–5 s jittered backoff, then give up; do not negative-cache for more than 60 s. Surface as transient. |
| `request_signature_brand_json_unreachable` | brand.json fetch failed (same conditions) | `brand_json_url`, `http_status`, `dns_error`, `last_attempt_at` | Same retry/cache discipline as `_capabilities_unreachable`. |
| `request_signature_brand_json_malformed` | brand.json failed strict-parse (duplicate keys, body cap exceeded, or non-JSON content) | `brand_json_url`, `parse_error` | Operator: serve a strict-JSON brand.json with no duplicate object keys and within the 256 KiB body cap. Verifier: do not retry; surface to operations. |
| `request_signature_brand_origin_mismatch` | Agent eTLD+1 ≠ `brand_json_url` eTLD+1 and `authorized_operators[]` does not delegate | `agent_url`, `agent_etld1`, `brand_json_url_etld1` | Operator: either move agent to brand eTLD+1, or add agent eTLD+1 to brand.json `authorized_operators[]`. Not retryable. |
| `request_signature_agent_not_in_brand_json` | Canonical Agent URL does not match any canonical `agents[].url` in resolved brand.json | `agent_url`, `brand_json_url` | Operator: add the Agent URL to `agents[]` or correct a semantically different path, query, or scheme. Not retryable. |
| `request_signature_brand_json_ambiguous` | Multiple `agents[]` entries canonically match the Agent URL | `agent_url`, `brand_json_url`, `matched_count`, `matched_entries[]` | Operator: dedupe `agents[]` entries by canonical URL. Not retryable. |
| `request_signature_key_origin_mismatch` | Resolved `jwks_uri` host ≠ declared `identity.key_origins.{purpose}` | `purpose`, `expected_origin`, `actual_origin` | Operator: align `identity.key_origins.{purpose}` with the host of the resolved `jwks_uri`. Not retryable. |
| `request_signature_key_origin_missing` | Signing posture declared but `identity.key_origins.{purpose}` absent | `purpose`, `posture` | Operator: add `identity.key_origins.{purpose}` declaration to capabilities. Not retryable. |
> [!NOTE]
>
> **Adopting `brand_json_url` while pinned to AdCP 3.0.** The field lands in 3.x's next minor as a strictly-additive schema change; AdCP doesn't ship new fields in patch releases (3.0.x), so a formal backport isn't on the table. But you don't have to wait for the version bump to start using it. The wire shape is forward-compatible:
>
> * A 3.0-conformant **seller** MAY populate `identity.brand_json_url` on its `get_adcp_capabilities` response today. A 3.0 verifier ignoring the field continues to work; a 3.x verifier picks it up automatically. No coordination, no version bump.
> * A 3.0-conformant **verifier** MAY read the field opportunistically (via `caps.identity?.brand_json_url`) and run the 8-step chain when present, falling back to your existing out-of-band mapping from agent URL to the agent's brand.json when absent. The chain itself is just HTTPS fetches and JSON parsing — nothing in it requires a 3.x SDK.
>
> This is the recommended path for sellers like [Scope3](https://github.com/scope3) building signature verification today: ship the field on your capabilities response, document the chain for your counterparties, and let the 3.x rollout happen passively.
##### Quickstart: implement a `brand_json_url`-based verifier
Mirrors the [request-signing quickstart](#quickstart-opt-into-request-signing-in-30) above. Run-once-per-agent — the resulting `agents[]` entry, `jwks_uri`, and JWKS are cached per the TTL rules in step 4.
1. **Fetch capabilities** for the signing agent's URL `A`. This is a **protocol-level** call — invoke `get_adcp_capabilities` via the agent's declared transport (MCP `tools/call` or A2A skill invocation), not a raw HTTP `GET` against `A`. The agent URL is the protocol endpoint, not a JSON capabilities document. Use SSRF-safe transport per [Webhook URL validation](#webhook-url-validation-ssrf): HTTPS only, address-family + private-IP filtering, no redirects, with budgets `{ connect: 5000, total: 10000, body: MAX_CAPABILITIES_BYTES, maxRedirects: 0 }`.
2. **Read `identity.brand_json_url`.** Reject `request_signature_brand_json_url_missing` if absent (and the request is signed) or non-HTTPS.
3. **eTLD+1 origin binding.** Compute `eTLD+1(A)` and `eTLD+1(brand_json_url)` using a pinned PSL snapshot. Use [`tldts`](https://www.npmjs.com/package/tldts) (TS), [`publicsuffixlist`](https://pypi.org/project/publicsuffixlist/) (Python), or [`golang.org/x/net/publicsuffix`](https://pkg.go.dev/golang.org/x/net/publicsuffix) (Go) with a vendored, dated snapshot. Do NOT fetch the PSL at runtime — a runtime fetch creates a denial-of-service oracle and a non-deterministic eTLD+1 across deployments. If they match, proceed. Otherwise fetch `brand.json` and check `authorized_operators[]` — if `eTLD+1(A)` is delegated, proceed. Else reject `request_signature_brand_origin_mismatch`. Origin comparisons throughout this algorithm MUST canonicalize both sides: ASCII-lowercase the host, then convert to IDNA-2008 A-label form (Punycode) before byte-equality. A non-canonical comparison (e.g., raw `Example.COM` vs `example.com`, or U-label vs A-label) silently rejects legitimate traffic.
4. **Fetch `brand.json`** with the same SSRF rules + no redirects, body cap `MAX_BRAND_JSON_BYTES`, connect 5 s, total 10 s. Parse with a strict JSON parser that rejects duplicate keys (e.g., [`secure-json-parse`](https://www.npmjs.com/package/secure-json-parse) in TS, the stdlib `json.JSONDecoder` in Python with an `object_pairs_hook` that raises on duplicates, [`encoding/json`](https://pkg.go.dev/encoding/json) `Decoder.DisallowUnknownFields` paired with a duplicate-key check in Go) — duplicate keys are the parser-differential vector that step 14 closes on the request surface, and the same trust-root document MUST NOT parse to two different shapes across verifiers. On duplicate-key detection, reject `request_signature_brand_json_malformed`. Cache successful responses up to (but no longer than) the JWKS revocation polling interval; cache failures for at most 60 s.
5. **Find the `agents[]` entry.** Canonicalize `A` and every `agents[].url` with the shared [AdCP URL canonicalization algorithm](/dist/docs/3.2.8/reference/url-canonicalization). Reject `request_signature_agent_not_in_brand_json` on no canonical match and `request_signature_brand_json_ambiguous` on multiple canonical matches. Retain the one matched canonical URL as the Agent identity after signature verification succeeds.
6. **Resolve `jwks_uri`** from the matched entry — for sell-side webhook delivery only, prefer the publisher's `adagents.json signing_keys` pin (when present) over the operator's `jwks_uri`. For all other (surface, role) tuples, use the matched entry's `jwks_uri` (default: `/.well-known/jwks.json` at the origin of the matched entry's `url`).
7. **Consistency check.** For every surface/purpose declared under capabilities `identity.key_origins`, apply `canonicalizeOrigin()` (ASCII-lowercase + IDNA-2008 A-label) to both the resolved `jwks_uri` host and the declared origin, then byte-compare (skip only the specific (agent, surface/role) tuple sourced from a publisher pin). Reject `request_signature_key_origin_mismatch` / `_missing` as appropriate.
8. **Hand off to step 8+ of the [verifier checklist](#verifier-checklist-requests)** — fetch the JWKS (with the same byte budget `MAX_JWKS_BYTES` and 5/10 s connect/total deadlines), find the `kid` (already resolved here in step 7's preamble — the verifier checklist's step 7 is the discovery preamble itself), verify per RFC 9421.
Pseudocode (TypeScript-flavored; SDK helpers below collapse this to a single call):
```ts theme={null}
const MAX_CAPABILITIES_BYTES = 65_536;
const MAX_BRAND_JSON_BYTES = 262_144;
const MAX_JWKS_BYTES = 65_536;
const FETCH_BUDGETS = { connect: 5_000, total: 10_000, maxRedirects: 0 };
function canonicalizeOrigin(hostOrUrl: string): string {
const host = hostOrUrl.includes('://') ? new URL(hostOrUrl).hostname : hostOrUrl;
return toAsciiIdna2008(host.toLowerCase()); // A-label form
}
async function resolveAgent(agentUrl: string): Promise {
const caps = await getAdcpCapabilities(agentUrl, { // step 1: protocol-level call
...FETCH_BUDGETS, body: MAX_CAPABILITIES_BYTES, ssrf: true,
});
const brandJsonUrl = caps.identity?.brand_json_url;
if (!brandJsonUrl?.startsWith('https://')) throw new Err('brand_json_url_missing'); // step 2
const agentEtld1 = etldPlusOne(new URL(agentUrl).hostname, PINNED_PSL_SNAPSHOT); // step 3
const brandEtld1 = etldPlusOne(new URL(brandJsonUrl).hostname, PINNED_PSL_SNAPSHOT);
const brandJson = await safeFetch(brandJsonUrl, { // step 4
...FETCH_BUDGETS, body: MAX_BRAND_JSON_BYTES, ssrf: true, parse: 'strict-json',
});
if (agentEtld1 !== brandEtld1
&& !brandJson.authorized_operators?.some(o => o.domain === agentEtld1)) {
throw new Err('brand_origin_mismatch');
}
const canonicalAgentUrl = canonicalizeAdcpUrl(agentUrl);
const entries = brandJson.agents.filter( // step 5 (canonical match)
e => canonicalizeAdcpUrl(e.url) === canonicalAgentUrl,
);
if (entries.length === 0) throw new Err('agent_not_in_brand_json');
if (entries.length > 1) throw new Err('brand_json_ambiguous');
const entry = entries[0];
const jwksUri = entry.jwks_uri ?? `${origin(entry.url)}/.well-known/jwks.json`; // step 6
for (const [purpose, declared] of Object.entries(caps.identity?.key_origins ?? {})) { // step 7
if (canonicalizeOrigin(jwksUri) !== canonicalizeOrigin(declared)) {
throw new Err('key_origin_mismatch', { purpose });
}
}
const jwks = await safeFetch(jwksUri, { // step 8 setup
...FETCH_BUDGETS, body: MAX_JWKS_BYTES, ssrf: true, parse: 'strict-json',
});
return { agentUrl: canonicalAgentUrl, brandJsonUrl, agentEntry: entry, jwksUri, jwks, /* trace, freshness */ };
}
```
Validate end-to-end against the brand-discovery test vectors at [`/compliance/latest/test-vectors/brand-discovery/`](https://adcontextprotocol.org/compliance/latest/test-vectors/brand-discovery/) once published; until then, the storyboard at `/compliance/latest/universal/capabilities-brand-url-discovery/` exercises the verifier algorithm against fixture brand.json + JWKS and asserts the right `request_signature_*` codes for each error path.
##### Reference implementations
The 8-step algorithm ships in three SDKs — pick the one matching your runtime. All three return the same logical record: the agent URL, the resolved brand.json URL, the matched `agents[]` entry, the JWKS URI, the JWKS itself, the `identity_posture` block from the capabilities response, an `consistency` flag from the step-7 `key_origins` check, a `freshness` timestamp set, and a per-step `trace`. The Python SDK differs: its record carries `fetched_at` and the raw `key_origins` map instead of the `identity_posture`, `consistency`, and `freshness` fields.
* **TypeScript** ([`@adcp/sdk`](https://github.com/adcontextprotocol/adcp-client)): `resolveAgent(url)` returns `{ agentUrl, brandJsonUrl, agentEntry, jwksUri, jwks, identityPosture, consistency, freshness, trace }`. `getAgentJwks(url)` is the JWKS-only fast path. `createAgentJwksSet(url, opts)` returns a `JWTVerifyGetKey` for handing to `jose`'s `jwtVerify`.
* **Python** ([`adcp`](https://github.com/adcontextprotocol/adcp-client-python)): `resolve_agent(url, *, agent_type)` (sync) and `async_resolve_agent(url, *, agent_type)` return an `AgentResolution` with fields `agent_url`, `brand_json_url`, `agent_entry`, `jwks_uri`, `jwks`, `fetched_at`, `key_origins`, `trace`. `await verify_from_agent_url(request, agent_url, *, agent_type, operation, capability=...)` is the one-shot helper that runs the discovery chain and the [verifier checklist](#verifier-checklist-requests) in one call.
* **Go** ([`adcp-go`](https://github.com/adcontextprotocol/adcp-go)): `ResolveAgent(ctx, agentURL) (*AgentResolution, error)` returns a struct with fields `AgentURL`, `BrandJSONURL`, `AgentEntry`, `JWKSUri`, `JWKS`, `IdentityPosture`, `Consistency`, `Freshness`, `Trace`. `VerifyRequestSignature(ctx, req, opts) (*VerifiedIdentity, error)` mirrors the TS/Python one-shot.
Each SDK ships a CLI for dev-loop debugging — `npx @adcp/sdk@latest resolve `, `adcp resolve ` (also `python -m adcp resolve `), `adcp resolve ` (Go binary, same name as the Python one — disambiguate by `$PATH` or vendor) — printing the trace with per-step `fetched_at`/`age_seconds`/`ok` so an operator triaging a `request_signature_brand_*` failure can see exactly which step rejected and why. Both the Python (`[project.scripts]` console_scripts entry) and Go (binary `adcp`, distinct from the Go module path `github.com/adcontextprotocol/adcp-go`) toolchains install a top-level `adcp` command so a single muscle-memory invocation works across runtimes.
#### Agent identity
A valid signature establishes exactly one fact: **the request was issued by the agent whose `jwks_uri` contains the `keyid`.** The verifier learns which specific agent signed, not just which operator. The agent's containing brand.json (discovered via the verifier's existing agent mapping) tells the verifier which operator runs that agent. That's the agent's operator, not the account operator a buyer names in `account.operator`.
**`agent_url` derivation.** The canonical buyer-agent identifier on the verifier's request context is the `url` field of the `agents[]` entry whose `jwks_uri` resolved the `keyid` at step 7 of the [verifier checklist](#verifier-checklist-requests). `agent_url` is **not** a JWK claim, JWS claim, or signed envelope field — it is the publication coordinate the verifier already used to fetch the JWKS. This makes derivation deterministic from inputs the verifier has fully controlled (the agent mapping established at onboarding, plus the JWKS it just fetched) and removes any wire affordance for the signer to assert a different `agent_url` than the one whose key signed the request. SDKs that surface a resolved-signer object to adopters MUST source `agent_url` from this derivation; they MUST NOT accept a buyer-asserted `agent_url` field on the envelope and treat it as cryptographically established. (Buyer-asserted *verifier* references like `creative.verify_agent.agent_url` and `governance.accepted_verifiers[].agent_url` are a separate construct — they name agents the seller will invoke under a published allowlist, not the signer of the inbound request, and remain permitted.)
Authorization — whether the account operator named in the request is permitted to act for the brand named in the request body — is a separate protocol-level check governed by the target house's brand.json `authorized_operator[]` entries. It happens whether the request is signed or not, and is outside the scope of this profile. Verifiers MUST perform both checks; this section specifies only the first.
Verifiers MUST NOT derive signer identity from request body fields. The signature → JWKS → agent entry chain is the only authoritative identity path on the signed transport. On the bearer / API-key / OAuth transport, agent identity comes from the seller's credential-to-agent mapping in its onboarding record — that mapping is the only legitimate identity source. Sellers MUST NOT introduce an envelope-side `buyer_agent_url` (or equivalent self-asserted caller-identity field) as an alternate input to identity resolution: the wire affordance lets a caller assert an identity the credential map would not, with no offsetting check.
brand.json discovery follows at most one `authoritative_location` **document-indirection variant** and stops. The explicit `authoritative_location` URL itself uses zero HTTP redirects.
#### Verifier checklist (requests)
**Before applying the checklist, verifiers MUST determine whether the operation requires a signature:**
* Resolve the AdCP operation per [Operation resolution over A2A](#operation-resolution-over-a2a); reject with `request_body_malformed` if an A2A message does not resolve to exactly one.
* If the resolved operation is in the verifier's `required_for` capability, AND no `Signature-Input` header is present, AND the caller presents no other credential the verifier accepts for this operation (bearer, API key, or mTLS), THEN reject with `request_signature_required`. Unsigned requests that fall into this branch never enter the checklist. See [Composition with fallback authenticators](#composition-with-fallback-authenticators) for the rule governing unsigned-but-otherwise-authenticated callers.
* If either `Signature` or `Signature-Input` is present without the other, reject with `request_signature_header_malformed`. The two headers are a bound pair; one without the other is malformed, not "signed with a missing piece we can guess at." This rule closes a downgrade vector where a proxy strips `Signature-Input` but leaves `Signature`.
* If a `Signature-Input` header is present but malformed, reject with `request_signature_header_malformed`. Verifiers MUST NOT fall back to bearer-only authentication when a malformed signature is present, **even for operations not in `required_for`** — a present-but-broken signature signals signer intent; silent fallback enables downgrade attacks.
Otherwise, verifiers MUST apply these 15 checks (14 numbered steps plus sub-step 9a) in order, short-circuiting on the first failure. Step 14 decomposes into 14a (strict-parse requirement) and 14b (logging discipline) — both apply whenever step 14 runs; they are elaborations of one check, not separate checks in the count. This checklist establishes agent identity only — brand-operator authorization is a separate, subsequent check governed by the target house's brand.json.
1. Parse `Signature-Input` and `Signature` headers per RFC 9421 §4. Reject if malformed.
2. Reject if any of `created`, `expires`, `nonce`, `keyid`, `alg`, or `tag` is absent from the `Signature-Input` parameters (`request_signature_params_incomplete`).
3. Reject if `tag` is not exactly `adcp/request-signing/v1` (`request_signature_tag_invalid`).
4. Reject if `alg` is not in the allowlist (`ed25519`, `ecdsa-p256-sha256`). Library defaults MUST NOT be relied upon (`request_signature_alg_not_allowed`).
5. Reject if `expires ≤ created`, `created > now + 60 s`, `expires < now − 60 s`, or `expires − created > 300 s` (`request_signature_window_invalid`).
6. Reject (`request_signature_components_incomplete`) if covered components do not include all of: `@method`, `@target-uri`, `@authority`. If a body is present, reject if `content-type` is not covered. Under the 3.2 profile, also reject if `content-digest` is not covered. A verifier operating an explicitly configured 3.0/3.1 compatibility endpoint applies its advertised legacy mode instead: `"required"` rejects missing coverage, while `"forbidden"` rejects present coverage with `request_signature_components_unexpected`.
7. Resolve `keyid` to a JWK via [Agent key publication](#agent-key-publication). If the verifier has no cached Agent → JWKS mapping for the signing Agent, run [Discovering an agent's signing keys via `brand_json_url`](#discovering-an-agents-signing-keys-via-brand_json_url) before this step — its 8-step preamble (capabilities → `identity.brand_json_url` → brand.json → canonical `agents[].url` match → `jwks_uri`) is a precondition for `keyid` resolution and short-circuits with the `request_signature_brand_*` and `request_signature_key_origin_*` codes from that section. Unless an authoritative publisher pin applies to this exact sell-side webhook tuple, the JWKS source is the matched entry's `jwks_uri`, defaulting when absent to `/.well-known/jwks.json` at the origin of that entry's `url`. On `kid` miss within an established mapping, refetch once (subject to the 30-second cooldown between refetches) before rejecting with `request_signature_key_unknown`. Reject if `keyid` cannot be resolved under exactly one canonical `agents[].url`; a domain, JWKS URI, or key alone is not an Agent identity.
8. Verify the JWK's `use` is `"sig"`, `key_ops` includes `"verify"`, and `adcp_use` equals `"request-signing"`. Reject (`request_signature_key_purpose_invalid`) on any mismatch — including absent `adcp_use`, which MUST be treated as non-conforming.
9. Check the [Transport revocation](#transport-revocation) list. Reject if `keyid` ∈ `revoked_kids` (`request_signature_key_revoked`). Reject with `request_signature_revocation_stale` if the verifier has not refreshed the revocation list within grace.
**9a. Per-keyid cap check.** Check the [per-keyid replay-cache cap](#transport-replay-dedup). Reject with `request_signature_rate_abuse` if the cap has been reached for this `keyid`. Runs before cryptographic verify (step 10) — same rationale as step 9: a compromised or misconfigured signer exhausting its cap MUST NOT force amplified Ed25519/ECDSA work on the verifier. Runs *after* `keyid` resolution (step 7) so the cap-state oracle only responds for keys the verifier has already committed to recognizing — running 9a earlier would let an attacker probe verifier-internal rate-limit state across the full keyid space, including keyids not published in JWKS.
10. Compute the canonical signature base per RFC 9421 §2.5 using the covered components, after applying `@target-uri` canonicalization AND `@authority` derivation per [the profile above](#adcp-rfc-9421-profile). **The `@authority` rule is load-bearing:** verifiers MUST derive `@authority` from the HTTP/2+ `:authority` pseudo-header when present, otherwise from the as-received HTTP/1.1 `Host` header — NOT from reverse-proxy routing state, load-balancer metadata, or any `Host` value a forward proxy may have rewritten in transit. If both `:authority` and `Host` are present on the as-received request, they MUST be byte-equal after canonicalization (RFC 7540 §8.1.2.3 equivalence); divergence rejects with `request_target_uri_malformed`. The canonicalized `@authority` MUST byte-for-byte match the authority component of the canonical `@target-uri`; mismatch rejects with `request_target_uri_malformed`. That byte-match against the signed `@target-uri` — not the choice of source header — is the only safe gate, because `Host` itself can be rewritten in transit. Implementers building from this checklist alone — without cross-referencing the profile's canonicalization section — MUST apply this rule; skipping it silently accepts a cross-vhost replay vector (an attacker intercepts a TLS-terminated request and replays it to a second vhost on the same verifier pool: same cert SAN, different `Host`). After canonicalization completes, verify the signature against the JWK (`request_signature_invalid` on failure).
11. If `content-digest` is covered, recompute the digest from the received body bytes and compare (`request_signature_digest_mismatch` on mismatch).
12. Check the nonce against the replay cache (see [Transport replay dedup](#transport-replay-dedup)). Reject if `(keyid, nonce)` has been seen within the replay-cache TTL (`request_signature_replayed`).
13. **Only after steps 1–9, 9a, and 10–12 have all passed**, insert `(keyid, nonce)` into the replay cache with TTL = `(expires − now) + 60 s` (the +60 s matches the skew tolerance applied at step 5). This insert MUST happen before the body-well-formedness check at step 14 so that a captured frame carrying a valid signature over a malformed body cannot be replayed to burn crypto-verify CPU on each retry — the nonce is burned on first sighting of a cryptographically-valid frame, regardless of body shape.
14. **Body well-formedness.** Verifiers MUST reject bodies containing duplicate object keys (`request_body_malformed`). Per RFC 8259 §4, duplicate-key parse behavior is unpredictable — the signature is valid over the bytes on the wire, but two parsers can disagree on the parsed value, which is a parser-differential attack class (cf. CVE-2017-12635). This check closes the gap between the signature verifier's view of the payload and the downstream consumer's view. Request bodies carry state-change and spend-committing payloads (`create_media_buy`, `update_media_buy_delivery`, etc.) whose parser-differential blast radius is larger than webhooks' status-flip blast radius, making this check at least as load-bearing here as on the webhook surface. `request_body_malformed` is distinct from `request_signature_digest_mismatch`: the signature IS valid; the body parses to ambiguous state. A verifier that crashes rather than returning a structured `request_body_malformed` error is conformant-but-suboptimal — senders receive no actionable error code. **Idempotency_key coverage follows from this check**: step 14 runs before schema validation and idempotency-cache lookup (see [idempotency](#idempotency)), so a request body whose `idempotency_key` is itself duplicated (different parsers seeing different keys) is rejected here and never reaches the cache. No separate idempotency-layer audit is required.
**14a. Strict-parse requirement.** The check MUST use a parser that exposes duplicate keys — a last-wins/first-wins default that silently discards them does not satisfy this requirement. The per-language strict-parse escape-hatch enumeration in [step 14a of the webhook verifier checklist](#webhook-callbacks) applies identically here.
**14b. Logging discipline.** Verifiers SHOULD NOT log full request body bytes on a `request_body_malformed` rejection; log `keyid`, nonce, byte length, and the specific duplicate key names only. The key-name sanitization rules (truncate at first non-printable to ``, truncate to last UTF-8 codepoint at or below 32 bytes, cap count at 4) from [step 14b of the webhook verifier checklist](#webhook-callbacks) apply identically here — the attacker-controlled-byte channel has the same shape on the request surface.
Only after all 14 checks pass does the verifier treat the request as cryptographically authenticated. Verifiers SHOULD record `verified_signer: { keyid, agent_url, verified_at }` on the request context, where `agent_url` is the canonical URL of the exactly matched `agents[]` entry, so downstream code — including the principal resolver and subsequent brand-operator authorization check — can log, map, and audit by signed Agent identity without treating the credential as the owner.
**Cheap rejections before crypto verify (steps 9 and 9a before step 10) are deliberate.** If a verifier checks crypto first, an attacker replaying a revoked-key signature — or a signer hammering a verifier whose per-keyid cap is full — forces an Ed25519 or ECDSA verification on every rejection, cheap amplification. Moving revocation and the per-keyid cap ahead closes that O(verify) → O(1) gap. Step 9's revocation state is already published externally on the signer's origin; step 9a's cap state is verifier-internal but is observable via traffic-pattern analysis by any sustained attacker. The spec intentionally pairs the distinct `request_signature_rate_abuse` error code with the `SHOULD alert operators` requirement (see [Transport replay dedup](#transport-replay-dedup)) so cap observations surface as incident signal rather than silent oracles — a compromised-key event should be loud for the operator even if it is also legible to the attacker who caused it.
**A load-bearing invariant for the cap.** External traffic without the private key cannot grow the cap: the replay-cache insert happens at step 13, *after* crypto verify (step 10) and *before* body well-formedness (step 14), so any request that fails at step 10 never consumes a cap entry, and any request that fails at step 14 has already burned its nonce — a captured frame carrying a valid signature over a malformed body cannot be replayed to force amplified crypto-verify work. This is why 9a is a *reader* of cap state, not a writer — only the legitimate key holder (or anyone who has compromised the key, the case the cap exists to detect) can grow the set. Future edits to the checklist MUST preserve both orderings: moving the insert earlier (before step 10) would let any external party flood the cap using forged structurally-valid signatures; moving the insert later (after step 14) would reopen the malformed-body replay vector.
Step 12's `(keyid, nonce)` dedup, by contrast, runs *after* crypto verify so the replay cache is not consumed by invalid signatures.
#### Composition with fallback authenticators
`required_for` governs the signature requirement **relative to a caller's credential path**, not absolutely. A verifier typically accepts more than one authenticator (bearer, API key, mTLS, 9421) and `required_for` is one lever within that auth chain, not an override that trumps the others.
**Terminology for the rule below:** *unauthenticated* means the caller presents neither a valid signature nor any other credential the verifier accepts for this operation. An unrecognized bearer token or API key (one the verifier does not accept) is *not* a valid credential — the caller is unauthenticated and falls into the first rule.
The normative rule is:
* An **unauthenticated** request to a `required_for` operation MUST be rejected with `request_signature_required`.
* An **unsigned but otherwise authenticated** request (valid bearer, API key, or mTLS identity; no `Signature-Input`) to a `required_for` operation MUST NOT be rejected for missing signature. The fallback credential is what the verifier advertised as sufficient for that caller, and `required_for` does not retroactively invalidate the verifier's own authenticator configuration.
* A **signed** request enters the [verifier checklist](#verifier-checklist-requests) and is evaluated on its cryptographic merits, whether or not the operation is in `required_for`.
* A **malformed signature** blocks fallback regardless, per the malformed-signature rule in the checklist preamble. Broken signatures signal signer intent and MUST NOT downgrade silently to bearer.
`warn_for` remains non-rejecting only for unsigned requests and well-formed signatures that fail verification or body binding when an independent authenticator succeeds. Those failures establish no signer identity. A partial or malformed `Signature` / `Signature-Input` pair still hard-rejects regardless of `warn_for` or fallback credentials, because it cannot be safely interpreted as either signed or unsigned traffic.
> [!WARNING]
>
> **Seller enforcement — pick the posture that matches your capability declaration.**
>
> Three enforcement postures are valid; sellers MUST pick one and configure their fallback authenticators accordingly. Advertising `required_for` while letting bearer authentication remain open for the listed operation is security theater — the verifier advertised bearer as valid, and callers are entitled to use it.
>
> * **Strict (signing is unconditional for this operation).** Sellers MUST either stop accepting bearer/API-key/mTLS for the operation entirely, *or* gate the fallback authenticator on a per-caller flag that rejects non-signed requests from counterparties who have completed 9421 onboarding. This is the posture where `required_for` rejects everything unsigned.
> * **Prefer signing, accept fallback (recommended during rollout).** Advertise `required_for` for the operation but leave bearer open. The composition rule applies: unsigned-unauthenticated callers are rejected, unsigned-bearer-authed callers pass. Good for quarters-long migrations where buyers onboard to 9421 at their own pace.
> * **Advisory only.** Move the operation to `warn_for` rather than `required_for`. The verifier records missing signatures and well-formed verification or body-binding failures, establishes no signer identity from them, and continues only under independent authentication. Partial or malformed signature-header pairs still hard-reject.
>
> *Example of the per-caller flag (strict posture):* a seller whose `agents[]` entries carry a `signing_onboarded: true` flag on 9421-ready counterparties configures its bearer authenticator to reject bearer credentials whose resolved agent has `signing_onboarded: true` for operations in `required_for`. Other agents continue to authenticate via bearer until their flag flips. Promotion to `required_for` stays operationally safe — existing bearer traffic continues while onboarded counterparties are held to the stricter bar.
Buyers reading `required_for` on a counterparty's capability surface learn **"callers presenting no credential at all will be rejected on this operation; callers presenting a bearer, API key, or mTLS credential the verifier accepts will not be rejected for missing signature."** That is not "all unsigned callers will be rejected." A buyer that wants its own unsigned bearer calls to fail closed on a `required_for` operation MUST negotiate with the seller to revoke bearer credentials for that operation rather than infer the behavior from the capability block.
**Why this composition and not the strict reading.** The strict reading ("`required_for` rejects all unsigned requests regardless of fallback credentials") has two practical problems. First, it collides with the 3.0 rollout pattern: sellers promote operations `supported_for → warn_for → required_for` over quarters, and most have live bearer traffic on the same operations during the transition. A strict reading would force every counterparty to migrate to signing in lockstep with the seller's `required_for` flip, or break. Second, it creates an action-at-a-distance bug: a seller enabling `required_for` for operational monitoring purposes would inadvertently 401 every bearer-authed buyer on that operation with no warning and no remediation path short of removing the capability. The composition rule makes `required_for` safe to enable incrementally — its effect is scoped to the unauthenticated branch the verifier actually owns.
#### Content-digest and proxy compatibility
Covering `content-digest` binds the request body bytes to the signature. For spend-committing operations, this is the whole point: the body specifies the money, and a signature that doesn't commit to the body is not protecting the attack surface that matters. In server-to-server AdCP deployments — which is most of them — body-modifying intermediaries are rare and usually the result of a specific deliberate configuration. Default position: **cover `content-digest` for spend-committing operations; treat transports that prevent body preservation as bugs to fix rather than constraints to accommodate.**
> [!WARNING]
>
> **Known body-modifying transport patterns.** These configurations break body-binding signatures and are the single biggest source of 9421 interop bugs in production:
>
> * CDN configurations that recompress or buffer-modify POST bodies (uncommon, but specific Cloudflare Workers, Fastly VCL, and CloudFront Lambda\@Edge setups can introduce byte changes).
> * WAFs that "sanitize" JSON request bodies (whitespace normalization, key reordering, unknown field stripping). Most WAFs inspect without modifying; some do modify.
> * Reverse proxies or API gateways that re-serialize JSON between client and origin for logging, validation, or transformation.
> * HTTP/2 → HTTP/1.1 bridges where chunked-encoding framing assumptions differ.
> * **Signer-side serialization mismatch.** A signer that computes `content-digest` over one JSON serialization (e.g., `json.dumps(payload)` with default spaced separators) while its HTTP client writes a different serialization on the wire (e.g., compact separators) produces a digest over bytes the receiver never sees. Every verifier then rejects with `webhook_signature_digest_mismatch` or `request_signature_digest_mismatch`. **Serialize the body once, then use those exact bytes for both the digest input and the HTTP body** — do not compute the digest from the pre-serialized object and trust the client to reproduce the same bytes. This is the same trap the [legacy HMAC scheme pins via compact separators](#legacy-hmac-sha256-fallback-deprecated-removed-in-40); 9421 fails loud rather than silent (digest mismatch is a hard reject) but the signer-side fix is identical.
>
> **If you control the transport**, preserve bodies byte-for-byte end-to-end and cover `content-digest`. **If you don't control the transport**, fix it rather than degrade the security guarantee. Validate end-to-end with a `POST` echo test against a test endpoint before sending real traffic.
AdCP 3.2 verifiers that advertise request-signing support MUST advertise `covers_content_digest: "required"`. Every accepted signature on a request with a body MUST include and cover `content-digest`; this applies uniformly before the verifier trusts the body enough to classify an operation. The `"either"` and `"forbidden"` values are deprecated compatibility postures for 3.0/3.1 endpoints only and are removed in 4.0. Infrastructure that rewrites bodies MUST use a separately configured legacy endpoint/origin or disable request signing under 3.2.
The endpoint's trusted configuration and negotiated capability select this policy before body parsing or dispatch. An `adcp_version`, operation name, or JSON-RPC method inside an unbound body MUST NOT downgrade a 3.2 verifier to a legacy mode. A shared endpoint that advertises 3.2 applies the 3.2 rule to signed body-bearing traffic; operators needing a legacy posture use a separately configured endpoint or origin. A 3.2 signer SHOULD cover `content-digest` even when a legacy peer advertises `"either"`; an explicit legacy `"forbidden"` posture is incompatible with 3.2 capability negotiation rather than a reason to retry without binding.
**`"required"` is strict.** A signed request with a body that does not cover `content-digest` is rejected with `request_signature_components_incomplete`. A digest mismatch uses `request_signature_digest_mismatch`; changing both the body and digest invalidates the signature. A client MUST NOT automatically retry unsigned or without digest coverage after either failure. Requests with no body do not require `content-digest`.
#### Transport replay dedup
Step 12 of the [verifier checklist](#verifier-checklist-requests) requires per-`(keyid, nonce)` deduplication. Unbounded sets are a memory and DoS risk.
* TTL on each entry = `(expires − now) + 60 s` to match the symmetric clock-skew tolerance applied at window validation. Typical TTL ≤ 360 s (5 min + 60 s skew).
* In-memory LRU keyed on `(keyid, nonce)` with TTL eviction, sized to expected request rate × max signature validity.
* Above \~10K req/s per signer: Redis `SETNX` with `EX = remaining_validity_seconds + 60`.
* Distributed verifiers (multi-region): per-region replay cache is acceptable. The only attack this enables is a single replay within (expires − now + 60 s) across regions, bounded by \~6 min and only effective if the attacker controls intermediate routing.
Verifiers MUST NOT use the request bearer token, IP, or any non-`(keyid, nonce)` value as the replay key — those produce false positives that reject legitimate agent traffic.
**Per-keyid cap.** To prevent an abusive or compromised signer from exhausting verifier memory with unique nonces, verifiers MUST enforce a per-keyid entry cap on the replay cache. Recommended ceiling: 1,000,000 entries per `keyid`. On cap exceeded, verifiers MUST reject new signatures from that `keyid` with `request_signature_rate_abuse` — NOT silently evict — and SHOULD alert operators, because hitting the cap indicates either a compromised key or a grossly misconfigured signer. Silent eviction is the dangerous mode: it creates replay windows exactly when the verifier is under attack. The per-keyid cap is distinct from the total cache ceiling; a verifier may legitimately hit its total ceiling via many well-behaved signers, but per-keyid exhaustion is unambiguously an attack signal. The cap check is step 9a of the [verifier checklist](#verifier-checklist-requests) — evaluated **before** crypto verify so an abusive signer cannot force amplified Ed25519/ECDSA work on the verifier.
**Single-process vs. distributed enforcement.** In a single-process verifier, step 9a (read) and step 13 (insert) are sequential in one execution and the cap is exact. In a distributed verifier sharing a Redis-backed replay cache, step 9a is a cheap fast-path amplification guard but is not authoritative: two verifiers can both observe `size == cap − 1`, both pass 9a, both pass steps 10–12, and both insert at step 13. To avoid cap drift, the step 13 insert SHOULD be atomic with a cap check (e.g., a Lua script or `SETNX` pattern that returns an over-cap sentinel) — step 9a remains the cheap amplification guard, step 13 is the authoritative enforcement point. A verifier whose atomic insert returns over-cap MUST reject the request with `request_signature_rate_abuse` rather than let it succeed; a cap that is advisory at step 13 is not a cap.
#### Transport revocation
Operators SHOULD serve a single combined revocation list at the brand.json origin covering governance, request-signing, and any other agent signing keys published under their `agents[]` entries. Format and signing semantics match the governance revocation list (see [Revocation](#revocation) above). For request-signing keys:
* `revoked_kids` invalidates every request ever signed under that `kid` (before or after the revocation timestamp).
* `revoked_jtis` is not used (request signatures don't have a `jti`; nonce uniqueness is per-key).
Verifiers accepting request-signed mutations MUST poll the revocation list on the cadence declared in `next_update` (floor 1 min, ceiling 30 min). The fetch-failure safe-default applies with grace = 4× the previous polling interval: verifiers that have not refreshed within `next_update + grace` MUST reject new request-signed mutations with `request_signature_revocation_stale` until the list is refreshed.
#### Transport capability advertisement
Verifiers advertise signing support and per-call requirements via the `request_signing` block on `get_adcp_capabilities`:
```json theme={null}
{
"request_signing": {
"supported": true,
"covers_content_digest": "required",
"required_for": [],
"warn_for": ["create_media_buy"],
"supported_for": [
"create_media_buy",
"update_media_buy",
"sync_creatives",
"activate_signal"
]
}
}
```
* `supported`: when true, the verifier validates signatures when present. When false or absent, signatures are ignored.
* `covers_content_digest`: `"required"` for every 3.2 signing profile. `"either"` and `"forbidden"` remain decodable only for explicit 3.0/3.1 compatibility and MUST NOT be negotiated as a 3.2 signing posture.
* `required_for`: AdCP protocol operation names (not transport-specific) for which **unsigned requests that present no other valid credential** are rejected with `request_signature_required`. Empty in 3.0 by default. Signers MUST sign any listed operation. Composition with bearer, API key, or mTLS fallbacks is governed by [Composition with fallback authenticators](#composition-with-fallback-authenticators) — in particular, unsigned requests that present a valid fallback credential are accepted, and sellers that intend signing to be unconditional MUST configure their fallback authenticators to reject other credential types for the operation.
* `warn_for`: operations for which the verifier verifies signatures when present and records failures in monitoring. Used as a shadow-mode bridge from `supported_for` to `required_for`. Precedence: `required_for > warn_for > supported_for`. A missing signature or a well-formed signature that fails verification or body binding MUST NOT establish verified-signer identity; processing may continue only when an independent bearer, API-key, or mTLS authenticator succeeds. A partial or malformed `Signature` / `Signature-Input` pair always hard-rejects. Verifiers MUST NOT convert a failed signature into an authenticated signer merely because the operation is in shadow mode.
* `supported_for`: operations for which signatures are verified when present but not required. Signers SHOULD sign these. Typically a superset of `required_for` and `warn_for`.
**Rollout pattern:**
1. Announce signing readiness: add the operation to `supported_for`. Counterparties can begin signing but nothing changes if they don't.
2. Promote to shadow mode: move the operation to `warn_for`. The verifier logs verification failures and relies on independent authentication for that traffic. Operators monitor the failure rate and debug.
3. Enforce: when the failure rate drops below the operator's threshold, move to `required_for`. Unsigned or invalid-signature requests to that operation are now rejected.
In 3.0/3.1, verifiers ship with `required_for: []` and populate it selectively. In 3.2, signing remains optional and the operation/protocol-method lists still decide whether signing is supported, shadowed, or required; they no longer alter the cryptographic component set. For `warn_for`, missing or invalid body binding is recorded but MUST NOT establish verified-signer identity, and processing may continue only under independently valid authentication. For `supported_for` and `required_for`, a presented body-bearing signature without digest coverage rejects. In 4.0, `required_for` additionally includes every supported spend-committing operation.
#### Transport error taxonomy
Stable codes returned in `WWW-Authenticate: Signature error=""` on 401, and surfaced by SDK verifiers as typed errors. Naming pattern matches the [governance taxonomy](#verification-error-taxonomy) so SDK error handling is symmetric.
The machine-readable authority is [`request-signing-error-code.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/request-signing-error-code.json). SDKs MUST consume that schema's `enumMetadata` recovery classifications instead of inferring behavior from a code's spelling or parsing this prose table. These lowercase transport-profile codes are deliberately separate from the uppercase task error vocabulary in `error-code.json` because they are carried in `WWW-Authenticate`, not task `errors[]` arrays.
| Failure | Retry? | Code |
| - | - | - |
| Unsigned request where signing is required — either (a) operation is in `required_for`, or (b) request payload carries a field that triggers signing regardless of `required_for` membership (e.g., `push_notification_config.authentication` or `accounts[].notification_configs[].authentication` on a signing-capable seller — see [Webhook callbacks](#webhook-callbacks)) | No | `request_signature_required` |
| Request `@target-uri` is syntactically malformed (e.g., empty authority, bare IPv6, IPv6 zone identifier, raw non-ASCII host), OR canonicalized `@authority` does not byte-match the authority component of the canonical `@target-uri` (cross-vhost replay) | No | `request_target_uri_malformed` |
| `Signature` or `Signature-Input` header present but malformed | No | `request_signature_header_malformed` |
| Required sig-param absent (`created`, `expires`, `nonce`, `keyid`, `alg`, or `tag`) | No | `request_signature_params_incomplete` |
| `tag` not `adcp/request-signing/v1` | No | `request_signature_tag_invalid` |
| `alg` not in allowlist | No | `request_signature_alg_not_allowed` |
| Signature window invalid (`expires ≤ created`, skew, expired, > 5 min validity) | No | `request_signature_window_invalid` |
| Required covered components missing | No | `request_signature_components_incomplete` |
| Covered components include `content-digest` when capability is `"forbidden"` | No | `request_signature_components_unexpected` |
| `keyid` not in signer JWKS after one refetch | No | `request_signature_key_unknown` |
| JWK `key_ops` lacks `verify`, `use` ≠ `sig`, or `adcp_use` ≠ `request-signing` | No | `request_signature_key_purpose_invalid` |
| `keyid` ∈ `revoked_kids` | No | `request_signature_key_revoked` |
| Revocation list not refreshed within grace | No (block new) | `request_signature_revocation_stale` |
| Cryptographic verification failed | No | `request_signature_invalid` |
| `content-digest` mismatch with recomputed digest | No | `request_signature_digest_mismatch` |
| Body contains duplicate object keys, or an A2A message does not resolve to exactly one AdCP operation (parser-differential vectors) | No | `request_body_malformed` |
| Nonce already seen within window | No | `request_signature_replayed` |
| Per-keyid replay cache exceeded its entry cap | No (block new) | `request_signature_rate_abuse` |
| JWKS fetch transient failure | Yes (with backoff) | `request_signature_jwks_unavailable` |
| JWKS fetch fails SSRF validation | No | `request_signature_jwks_untrusted` |
Servers MUST NOT echo internal verification details beyond the stable code; log the detail server-side.
**`WWW-Authenticate` format.** AdCP does NOT define a realm value for request-signing challenges. Verifiers MUST emit `WWW-Authenticate: Signature error=""` with no `realm` parameter and no other parameters. Clients parsing the header MUST tolerate other parameters (RFC 7235 permits implementations to include extras) but SHOULD NOT depend on them.
#### Webhook callbacks
Push-notification webhooks (POSTs to the `push_notification_config.url` a buyer registers), account-level webhooks (POSTs to `accounts[].notification_configs[].url`), agent-level webhooks (POSTs to `sync_principal.configuration.notification_configs[].url` or `sync_agent_notification_configs.notification_configs[].url`), and similar asynchronous seller-initiated callbacks are signed under a symmetric variant of this profile. Role direction is inverted relative to request signing: the **seller signs outbound**, the **buyer verifies**. 9421 webhook signing is baseline-required for any 3.0 seller that emits webhooks, with a deprecated HMAC fallback described in [Webhook Security](#webhook-security).
**Baseline with programmatic advertisement.** 9421 webhook signing is baseline-required for any seller that emits webhooks — the default is signed, not a negotiated option. The `webhook_signing` capability block on `get_adcp_capabilities` exists so buyers can detect a non-signing seller *at onboarding* rather than discovering it by traffic inspection (which is how the asymmetry with `request_signing` manifested before this block was restored). A seller whose capability surface advertises mutating-webhook emission elsewhere (e.g., `media_buy.reporting_delivery_methods` includes `webhook`, `media_buy.content_standards.supports_webhook_delivery: true`, or `wholesale_feed_webhooks.supported: true`) MUST include this block with `supported: true`. A seller that emits no webhooks MAY omit the block entirely; `supported: false` is reserved for the unsafe posture of emitting unsigned webhooks and MUST NOT be used to signal absence-of-webhooks. Buyers that integrate with a seller whose surface advertises mutating-webhook emission while the `webhook_signing` block advertises `supported: false` or is omitted MUST fail onboarding with a user-actionable error — a seller that emits but does not sign webhooks is unsafe to integrate with for any mutating-webhook use case.
```json theme={null}
{
"webhook_signing": {
"supported": true,
"profile": "adcp/webhook-signing/v1",
"algorithms": ["ed25519", "ecdsa-p256-sha256"],
"legacy_hmac_fallback": false,
"delivery_retry_horizon_seconds": 86400
}
}
```
* `supported`: MUST be `true` when the seller advertises mutating-webhook emission elsewhere in its capability surface. Buyers reject onboarding when `supported: false` or the block is missing and the seller's surface advertises webhook emission. Sellers that emit no webhooks SHOULD omit the entire block.
* `profile`: MUST be exactly `adcp/webhook-signing/v1` for this profile version. Future profile versions bump the string.
* `algorithms`: subset of `["ed25519", "ecdsa-p256-sha256"]` — the algorithm set this seller will sign with. Matches the webhook-signing verifier allowlist (see step 4 of the [verifier checklist](#verifier-checklist-requests), reused for webhooks via the substitutions noted above). Buyers MUST reject onboarding with a user-actionable error if the advertised `algorithms` array contains any value outside this set; an out-of-set algorithm indicates a misconfigured or non-conforming seller and silent acceptance would defeat the allowlist.
* `legacy_hmac_fallback`: `true` iff the seller supports the legacy HMAC-SHA256 scheme when the buyer populates `push_notification_config.authentication.credentials`, `accounts[].notification_configs[].authentication.credentials`, `sync_principal.configuration.notification_configs[].authentication.credentials`, or `sync_agent_notification_configs.notification_configs[].authentication.credentials`. `false` is the recommended posture in 3.x.
* `delivery_retry_horizon_seconds`: maximum interval from the first attempt during which the seller can retry one delivery. Required for `supported: true` in 3.2; minimum 24h, maximum 7 days. Receivers retain the immutable delivery-key binding and terminal publication proof for at least this interval.
The buyer opts into the legacy HMAC-SHA256 scheme by populating `push_notification_config.authentication.credentials`, `accounts[].notification_configs[].authentication.credentials`, `sync_principal.configuration.notification_configs[].authentication.credentials`, or `sync_agent_notification_configs.notification_configs[].authentication.credentials`; otherwise the seller signs with the 9421 webhook profile. Sellers MAY decline to support the legacy scheme — see the `legacy_hmac_fallback` flag above.
**Mode selection is a switch, not both.** The presence of `push_notification_config.authentication`, `accounts[].notification_configs[].authentication`, `sync_principal.configuration.notification_configs[].authentication`, or `sync_agent_notification_configs.notification_configs[].authentication` selects exactly one signing mode for every webhook delivered to that URL: `authentication` present → legacy HMAC-SHA256 (or Bearer); `authentication` absent → 9421. Sellers MUST NOT sign the same webhook both ways. Buyers MUST NOT attempt "try 9421 first, fall back to HMAC" verification — that pattern creates downgrade oracle behavior and accepts signatures the buyer did not ask for. Verifiers key the verification path strictly off whether the receiver has a configured HMAC secret for the webhook registration.
**Key publication.** Signing keys are published by the seller in its **own brand.json** `agents[]` entry at the signing agent's operator domain, at the `jwks_uri` member of that entry — the same publication pattern as any other AdCP agent key. Webhooks are signed with the agent's **`adcp_use: "request-signing"`** key; there is no separate webhook key purpose. Domain separation between requests and webhooks is carried by the signature `tag` (`adcp/request-signing/v1` vs `adcp/webhook-signing/v1`), not by the key purpose. Each signing JWK MUST declare:
| Member | Value |
| - | - |
| `use` | `"sig"` |
| `key_ops` | `["verify"]` |
| `adcp_use` | `"request-signing"` |
| `kid` | distinct within the JWKS; MUST NOT collide with any other `kid` regardless of `adcp_use` |
| `alg` | `"EdDSA"` or `"ES256"` |
**Key isolation is optional, via a distinct `kid` — not a distinct purpose.** An operator that wants its webhook traffic signed by separate key material (so a webhook-key compromise does not extend to request signing, or to rotate the two independently) publishes a **second `adcp_use: "request-signing"` key with a distinct `kid`** and signs webhooks with that one. Both keys carry the same `adcp_use`; the verifier resolves the right one by the `kid` in `Signature-Input`. No dedicated webhook key purpose is required to achieve isolation.
> **Deprecated:** `adcp_use: "webhook-signing"` is deprecated and scheduled for removal in a future major version (tracked in [#5555](https://github.com/adcontextprotocol/adcp/issues/5555); the exact window is a WG/RFC decision). Verifiers MUST still accept it for backward compatibility (a webhook signed under a `"webhook-signing"` key verifies cleanly), but new signers SHOULD publish and sign with `"request-signing"` keys only.
A buyer verifying a webhook MUST accept a JWK whose `adcp_use` is `"request-signing"` (or the deprecated `"webhook-signing"`), and MUST reject any other key-purpose failure — any other `adcp_use` value, absent `adcp_use`, or a missing `verify` key_op — with `webhook_signature_key_purpose_invalid`. The reverse is still forbidden: request verification requires `adcp_use == "request-signing"` exactly (a request signature is rejected if the key declares any other purpose), and neither `"response-signing"` nor `"governance-signing"` keys are ever valid for webhook delivery. The webhook path is permissive on key purpose because it already carries domain separation in the `tag` (`adcp/webhook-signing/v1`) and mandatory `content-digest` coverage, so the key-purpose check adds no confusion resistance there.
**Trust anchor and blast radius.** The trust anchor for webhook authenticity is **the signer's brand.json origin** — the HTTPS origin that hosts the brand.json declaring the signing agent's `agents[]` entry. A compromise of that origin (sub-path takeover, DNS hijack, CDN cache poisoning of `/.well-known/brand.json` or the `jwks_uri`) compromises every webhook that buyer accepts from that signer until the operator publishes a `revoked_kids` entry and buyer verifiers refresh the revocation list. Buyers SHOULD pin the agent's `jwks_uri` URL learned at integration onboarding and alarm on changes to the URL itself (not just on `kid` rotation within a stable URL) — changes to the URL force re-anchoring and SHOULD require operator attention, not silent adoption. `kid` collisions within the same JWKS are forbidden so each `kid` resolves to exactly one key. Webhooks are signed with the agent's `request-signing` key, so by default a request-signing-key compromise extends to webhooks. An operator that needs blast-radius separation publishes a second `request-signing` key with a distinct `kid` dedicated to webhook delivery and signs webhooks with it — isolation comes from separate key material under a separate `kid`, not from a separate `adcp_use`.
**Covered components** are identical to request signing: `@method`, `@target-uri`, `@authority`, `content-type`, and `content-digest`. `content-digest` is REQUIRED on webhook callbacks — the body carries the event, and webhook receivers are buyer-controlled endpoints where body preservation is the buyer's own infrastructure problem. There is no `covers_content_digest: "forbidden"` opt-out for webhooks; transports that cannot preserve webhook body bytes MUST be fixed.
**Signature parameters** are identical to request signing with one override:
| Parameter | Notes |
| - | - |
| `created`, `expires`, `nonce`, `keyid`, `alg` | Same semantics as [request signing parameters](#adcp-rfc-9421-profile). |
| `tag` | MUST be exactly `adcp/webhook-signing/v1`. Verifiers MUST reject `adcp/request-signing/v1` on a webhook route with `webhook_signature_tag_invalid`. The distinct tag prevents a request signature from being replayed as a webhook signature and vice versa. |
**JWKS discovery.** The buyer knows the seller's agent URL from the AdCP integration it's already using. Buyer resolves:
1. Seller agent URL `A` → fetch `/.well-known/brand.json` at the operator domain of `A` with SSRF validation per [Webhook URL validation](#webhook-url-validation-ssrf). The initial domain-derived HTTP fetch may follow only the original hostname ↔ exact `www` counterpart on HTTPS at the original port for at most 3 hops. brand.json document resolution follows at most one `authoritative_location` or `house` variant and stops; an explicit `authoritative_location` URL uses zero HTTP redirects.
2. In the fetched brand.json, find the `agents[]` entry whose `url` byte-for-byte matches `A`.
3. Fetch that entry's `jwks_uri` (or default to `/.well-known/jwks.json` at the origin of `A`) with SSRF validation. JWKS cache TTL bounded above by the revocation-list polling interval (floor 1 min, ceiling 30 min). Long-running task flows cross JWKS rotations; verifiers MUST NOT pin a single JWKS snapshot for the lifetime of a task.
4. Resolve `keyid` on the incoming `Signature-Input` to a JWK in the fetched set. On `kid` miss, refetch once (subject to the 30-second cooldown between refetches) before rejecting with `webhook_signature_key_unknown`. The refetch-on-miss path is the load-bearing mechanism for handling mid-task key rotation — clients that skip it will reject legitimate post-rotation deliveries.
Buyers MUST NOT derive signer identity from webhook payload fields (`task_id`, `operation_id`, etc.) or from `adagents.json` entries — those are publisher authorization, not signer identity. Identity is established solely via the signature → JWKS → seller `agents[]` entry chain.
**Downgrade and injection resistance.** The buyer's webhook-signing preference is communicated by the presence or absence of `push_notification_config.authentication`, `accounts[].notification_configs[].authentication`, `sync_principal.configuration.notification_configs[].authentication`, or `sync_agent_notification_configs.notification_configs[].authentication` on the inbound request that registers the webhook. In 3.0 that inbound request is frequently bearer-authenticated rather than 9421-signed, so an on-path mutator (misconfigured proxy, compromised intermediary) could strip or inject the `authentication` block silently. The following rules contain the blast radius:
* **Sellers MUST log** every request that arrives with a non-empty `authentication` block. Ops alarms on unexpected HMAC selection protect the buyer side when the buyer thought it was getting 9421.
* **Sellers that support request signing MUST require** the inbound request to be 9421-signed (per the [request verifier checklist](#verifier-checklist-requests)) when `authentication` is present on `push_notification_config.authentication`, any `accounts[].notification_configs[].authentication`, any `sync_principal.configuration.notification_configs[].authentication`, or any `sync_agent_notification_configs.notification_configs[].authentication`, rejecting with `request_signature_required` (the same code used for `required_for` operations — see [Transport error taxonomy](#transport-error-taxonomy)). When a signed request cryptographically commits to the body, the `authentication` block cannot be injected or stripped without also invalidating the signature. Sellers that do not support request signing at all have no way to enforce this rule and fall back to the log-and-alarm posture in the preceding bullet — 3.0 migration note, not an exemption: the [request-signing migration timeline](#transport-migration-timeline) makes request signing required for spend-committing operations in 4.0, at which point no seller is unsigned-only.
* **Buyers MUST reject with `webhook_mode_mismatch` and alarm**, not silently downgrade, when they receive a 9421-signed webhook after registering with `authentication.credentials`, or when they receive HMAC-signed webhooks after registering without `authentication`. Rejection is the safety property; alarming is the telemetry — a buyer that alarms but accepts the payload has already handed authority to the mismatched signing scheme. The rejection surfaces as HTTP `401` with the stable error code so sender-side retry logic can route it to incident response rather than replaying identically.
* **Buyers SHOULD negotiate HMAC-mode out-of-band** at onboarding when interoperating with sellers that have not yet implemented 9421. Durable per-counterparty mode selection in operator records is not MITM-mutable the way a per-request field is.
**Verifier checklist for webhooks.** Apply these 15 checks (14 numbered steps plus sub-step 9a) in order, short-circuiting on the first failure. Step 14 decomposes into 14a (strict-parse requirement) and 14b (logging discipline) — both apply whenever step 14 runs; they are elaborations of one check, not separate checks in the count. The steps below are the [request verifier checklist](#verifier-checklist-requests) with **three profile substitutions** — the `tag` value (`adcp/webhook-signing/v1` instead of `adcp/request-signing/v1`), the direction-of-trust resolution (seller's brand.json `agents[]` entry instead of the buyer's), and webhook v1's legacy unpadded Base64URL binary-value decoder instead of the 3.2 request profile's RFC 8941 Base64 decoder. Parser mode comes from the trusted webhook route/profile configuration before header parsing; it is not a lenient fallback after request-profile parsing fails. Step 14 (body well-formedness) is identical across the two profiles; only the error-code prefix differs (`webhook_body_malformed` vs `request_body_malformed`). Implementations SHOULD share verifier code between the two profiles, branch on the three profile parameters, and configure the profile-specific error codes — NOT fork the implementation. Error codes are prefixed `webhook_*` — most carry the `webhook_signature_*` infix, plus structural codes without it (currently `webhook_target_uri_malformed`, `webhook_mode_mismatch`, `webhook_body_malformed`) — so caller-side error handling distinguishes the two profiles.
1. Parse `Signature-Input` structure per RFC 9421 §4 and decode the `Signature` binary token with the webhook-v1 unpadded Base64URL profile. Reject if malformed (`webhook_signature_header_malformed`). If `Signature` or `Signature-Input` is present without the other, reject with the same code — a bound pair, not a guessable one.
2. Reject if any of `created`, `expires`, `nonce`, `keyid`, `alg`, or `tag` is absent from the `Signature-Input` parameters (`webhook_signature_params_incomplete`).
3. Reject if `tag` is not exactly `adcp/webhook-signing/v1` (`webhook_signature_tag_invalid`). Byte-for-byte match; no case-folding.
4. Reject if `alg` is not in the allowlist (`ed25519`, `ecdsa-p256-sha256`). Library defaults MUST NOT be relied upon (`webhook_signature_alg_not_allowed`).
5. Reject if `expires ≤ created`, `created > now + 60 s`, `expires < now − 60 s`, or `expires − created > 300 s` (`webhook_signature_window_invalid`).
6. Reject if covered components do not include ALL of: `@method`, `@target-uri`, `@authority`, `content-type`, `content-digest` (`webhook_signature_components_incomplete`). `content-digest` is REQUIRED; there is no policy branch.
7. Resolve `keyid` to a JWK via the JWKS discovery steps above. On `kid` miss, refetch once (30-second cooldown between refetches) before rejecting (`webhook_signature_key_unknown`). Reject if `keyid` cannot be resolved to a specific `agents[]` entry in the signer's brand.json.
8. Verify the JWK's `use` is `"sig"`, `key_ops` includes `"verify"`, and `adcp_use` is `"request-signing"` — webhooks are signed with the agent's request-signing key (see [Key publication](#webhook-callbacks)); the deprecated `"webhook-signing"` value MUST also be accepted for backward compatibility. Reject on any other outcome with `webhook_signature_key_purpose_invalid`: absent `adcp_use`, a missing `verify` key_op, or any other `adcp_use` value (e.g. `"response-signing"`, `"governance-signing"`). Accepting `"request-signing"` here is safe because cross-protocol confusion is prevented by the `tag` (step 3) and mandatory `content-digest` coverage (step 6), not by the key-purpose discriminator: a captured request signature carries `tag=adcp/request-signing/v1` and is rejected at step 3. (`webhook_mode_mismatch` is reserved for the HMAC-vs-9421 auth-mode selector mismatch — see [Downgrade and injection resistance](#webhook-callbacks) — and is NOT used for key-purpose failures.)
9. Check the [Transport revocation](#transport-revocation) list (reused across signing purposes). Reject if `keyid ∈ revoked_kids` (`webhook_signature_key_revoked`). Reject with `webhook_signature_revocation_stale` if the verifier has not refreshed within grace.
**9a. Per-keyid cap check.** Check the [webhook replay-cache cap](#webhook-replay-dedup-sizing). Reject with `webhook_signature_rate_abuse` if exceeded. Runs before cryptographic verify (step 10) for the same cheap-rejection rationale as request signing.
10. Compute the canonical signature base per RFC 9421 §2.5 using the covered components, after applying `@target-uri` canonicalization AND `@authority` derivation per [the request-signing profile](#adcp-rfc-9421-profile). **The `@authority` rule is load-bearing for webhook security:** verifiers MUST derive `@authority` from the HTTP/2+ `:authority` pseudo-header when present, otherwise from the as-received HTTP/1.1 `Host` header — NOT from reverse-proxy routing state, load-balancer metadata, or any `Host` value a forward proxy may have rewritten in transit. If both `:authority` and `Host` are present on the as-received request, they MUST be byte-equal after canonicalization (RFC 7540 §8.1.2.3 equivalence); divergence rejects with `webhook_target_uri_malformed`. The canonicalized `@authority` MUST byte-for-byte match the authority component of the canonical `@target-uri`; mismatch rejects with `webhook_target_uri_malformed`. That byte-match against the signed `@target-uri` — not the choice of source header — is the only safe gate, because `Host` itself can be rewritten in transit. Implementers building from this checklist alone — without cross-referencing the profile — MUST apply this rule; skipping it silently accepts a cross-vhost replay vector (an attacker intercepts a TLS-terminated webhook and replays it to a second vhost on the same verifier pool: same cert SAN, different `Host`). After canonicalization completes, verify the signature against the JWK (`webhook_signature_invalid` on failure).
11. Recompute `content-digest` from the received body bytes and compare (`webhook_signature_digest_mismatch` on mismatch). REQUIRED — no policy branch.
12. Check the nonce against the replay cache. Reject if `(keyid, nonce)` has been seen within the replay-cache TTL (`webhook_signature_replayed`).
13. **Only after steps 1–12 have all passed**, insert `(keyid, nonce)` into the replay cache with TTL = `(expires − now) + 60 s`. This insert MUST happen before the body-well-formedness check at step 14 so that a captured frame carrying a valid signature over a malformed body cannot be replayed to burn crypto-verify CPU on each retry — the nonce is burned on first sighting of a cryptographically-valid frame, regardless of body shape. The load-bearing cap invariant this ordering preserves is documented after step 14b.
14. **Body well-formedness.** Verifiers MUST reject bodies containing duplicate object keys (`webhook_body_malformed`). Per RFC 8259 §4, duplicate-key parse behavior is unpredictable — the signature is valid over the bytes on the wire, but two parsers can disagree on the parsed value, which is a parser-differential attack class (cf. CVE-2017-12635). This check closes the gap between the signature verifier's view of the payload and the downstream consumer's view. A verifier that crashes rather than returning a structured `webhook_body_malformed` error is conformant-but-suboptimal — senders receive no actionable error code. The conformance fixture for this check is the `duplicate-keys-conflicting-values` vector in `static/test-vectors/webhook-hmac-sha256.json` — the 9421 profile MUST apply the same body-well-formedness rule after signature verification succeeds. `webhook_body_malformed` is distinct from `webhook_signature_digest_mismatch`: the signature IS valid; the body parses to ambiguous state.
**14a. Strict-parse requirement.** The check MUST use a parser that exposes duplicate keys — a last-wins/first-wins default that silently discards them does not satisfy this requirement. Query libraries that happily return a value on duplicate-key input without surfacing the collision also do not satisfy this requirement, regardless of marketing as "safe" or "strict" (cf. `tidwall/gjson` in Go — a query library, not a validator). Per-language strict-parse escape hatches, canonical non-exhaustive list:
* **Python**: stdlib `json.loads(..., object_pairs_hook=...)` — detect duplicates inside the hook and raise. Satisfies the check.
* **Node**: no strict mode in `JSON.parse`. Use a streaming parser (`stream-json`, `jsonparse`) with a duplicate-key event handler. `secure-json-parse` is NOT sufficient by default: its protections target prototype-pollution keys (`__proto__`, `constructor`), not data-key duplicates, which it still collapses last-wins. Configure it to reject data-key duplicates explicitly or layer a streaming parser underneath.
* **Go**: `encoding/json` has no strict mode and does not detect duplicates. Use `json.Decoder` token-walk with an explicit `map[string]struct{}` unique-key guard per object scope, OR `goccy/go-json` with `decoder.DisallowDuplicateKey()` explicitly enabled (NOT the default). Do NOT use `tidwall/gjson` for this check — it is a query library that returns the last value on duplicate-key input without signaling the collision.
* **Java**: Jackson `DeserializationFeature.FAIL_ON_READING_DUP_TREE_KEY` (disabled by default, enable explicitly).
* **Ruby**: stdlib `JSON.parse` has no detection hook. Use `Oj.load(..., mode: :strict)` with the `allow_nan: false` / duplicate-rejection options explicitly configured.
**14b. Logging discipline.** Verifiers SHOULD NOT log full request body bytes on a `webhook_body_malformed` rejection; log `keyid`, nonce, byte length, and the specific duplicate key names only. An attacker holding a compromised signer key can otherwise force attacker-chosen bytes into defender logs at scale, burning a replay-cache slot per frame but leaving an attacker-controlled log trail for SIEM poisoning or credential exfiltration follow-on attacks. When logging duplicate key names, verifiers MUST sanitize each name with the following rules applied in order:
* **(a) Truncate at the first non-printable codepoint** and emit `` where N is the byte length of the truncation prefix. This elides position information (the placement of a non-printable within the key name would otherwise itself be an attacker channel, encodable as bit positions) while preserving the "something was wrong here" diagnostic signal. The non-printable set MUST include at minimum: **C0 controls** (U+0000–U+001F), **DEL** (U+007F), **C1 controls** (U+0080–U+009F, terminal control semantics in multi-byte form), **bidi controls and isolates** (U+200E, U+200F, U+202A–U+202E, U+2066–U+2069 — reverse rendering in terminals and SIEM UIs), **line and paragraph separators** (U+2028, U+2029 — render as line breaks in many log viewers, enabling row-injection), **zero-width characters** (U+200B–U+200D — invisible obfuscation), and the **byte-order mark** (U+FEFF — parser corruption). Implementations MAY extend the set to a broader Unicode non-printable classification but MUST NOT narrow it — an ASCII-only check misses bidi-override and line-separator attacks that reopen exactly the log-injection channel this rule exists to close.
* **(b) Truncate to at most 32 bytes** at the last complete UTF-8 codepoint boundary. Realistic AdCP field names top at roughly 24 characters (`signed_authorized_agents`), so 32 is a generous cap while still bounding the attacker-controlled-byte surface. Truncation MUST occur at the last complete UTF-8 codepoint boundary at or below 32 bytes so multi-byte sequences are not split mid-codepoint and invalid-UTF-8 does not land in logs (different verifiers truncating the same input to different invalid-UTF-8 tails would also break log aggregation).
* **(c) Cap the number of duplicate key names logged per rejection at 4**, emitting `<...N more>` if exceeded. Diagnostic value of knowing 4 vs 8 vs 16 colliding keys is near zero.
Without these constraints, the key-name channel remains an attacker-controlled-byte side channel — smaller than full-body logging but non-zero, and well-precedented as a log-injection vector. Signers that log upstream-input rejections (see [the duplicate-object-keys signer-side rule](#legacy-hmac-sha256-fallback-deprecated-removed-in-40)) MUST apply the same (a)/(b)/(c) sanitization rules to any key names surfaced in signer-side error output; the channel shape is identical even though the wire direction is inverted.
**A load-bearing invariant for the webhook cache.** External traffic without the signer's private key cannot grow this cache: every entry admitted at step 13 has already passed step 10's cryptographic verification, so any party driving cache growth is either the legitimate key holder or someone who has compromised the key — the case the per-keyid cap (step 9a) and the new-keyid admission-pressure alarm (see [Webhook replay dedup sizing](#webhook-replay-dedup-sizing)) are designed to detect. The invariant mirrors the [analogous request-signing rule](#verifier-checklist-requests) (see the "load-bearing invariant for the cap" paragraph immediately after step 13 there). Future edits to the webhook checklist MUST preserve this ordering: moving the step 13 insert before step 10's signature verification would let any external party flood the cache using forged structurally-valid signatures.
There is no subsequent brand-operator authorization step on the webhook path — the signature establishes the seller's identity, and that identity is sufficient to accept the webhook. Application-layer dedup on `idempotency_key` runs after signature verification (step 13) to protect against duplicate side effects.
**One signature per webhook.** Verifiers MUST process exactly one `Signature-Input` label and ignore additional labels.
##### Webhook replay dedup sizing
Replay dedup for webhooks reuses the `(keyid, nonce)` key shape and TTL semantics from [Transport replay dedup](#transport-replay-dedup), but the buyer-side cache sees signatures from every seller the buyer integrates with — fundamentally different fan-in from the request-side case.
* **Per-keyid entry cap**: recommended 100,000 entries (10× lower than the request-side 1,000,000 ceiling). A seller emitting 100K unique webhooks in a 6-minute window is 275/sec sustained from a single signer — plenty of headroom for normal operations and still a strong signal of misconfiguration or key compromise.
* **Aggregate cache cap**: recommended `min(aggregate_memory_budget, 10,000,000)` entries across all signers. On aggregate-cap exceeded, verifiers MUST reject new signatures with `webhook_signature_rate_abuse` and SHOULD alert operators — silent eviction creates replay windows precisely when the verifier is under attack.
* **Per-seller budget**: operators SHOULD budget per-seller by integration criticality rather than equal-weighting all sellers at 100K each. A spend-committing seller's webhook fan-in differs from a discovery-only seller's.
* **New-keyid admission pressure** (MUST track, SHOULD alert). Verifiers MUST track the rate of cache entries admitted from previously-unseen `keyid`s per unit time (e.g., a 5-minute rolling count of distinct `keyid`s inserting their first entry). A sudden spike in new-keyid admission rate is the signature of a **distributed-compromise attack**: an attacker holding N compromised signer keys can drive N entries per TTL window each, every key staying well within its per-keyid cap (step 9a), while collectively saturating the aggregate cache. Each key's traffic individually looks like a low-volume legitimate signer; the aggregate shape is the signal.
Verifiers SHOULD alert when new-keyid admission exceeds **any** of four thresholds (whichever triggers first), each closing a distinct attacker pattern:
* **(a)** a **short-window ratio threshold** comparing the current admission rate against a short-horizon moving-average baseline — catches sudden spikes against a stable baseline.
* **(b)** a **medium-window ratio threshold** against a medium-horizon percentile baseline — catches multi-week ramp-up attacks, whose traffic is dominated by the baseline tail at that horizon.
* **(c)** a **long-window ratio threshold** against a long-horizon percentile baseline — catches multi-month ramp-up attacks that drift the medium-horizon anchor with them.
* **(d)** a **proportional ceiling** combining an absolute floor with a fraction of the unique-keyid count over a documented window — catches sparse-traffic verifiers whose ratio baselines are near zero, AND auto-scales to operators of any size (small verifiers get a low proportional floor; enterprise verifiers get a proportionally larger one).
**The four categories are normative; the concrete threshold values are NOT.** Operators MUST treat any published example values as starting points, baseline their own traffic, and tune accordingly — published normative threshold numbers would hand attackers an oracle into the detection posture. Concrete starting values, baselining methodology, and attack-scenario walkthroughs are published in the non-normative [Webhook Verifier Tuning Guide](/dist/docs/3.2.8/building/by-layer/L1/webhook-verifier-tuning). Implementations MAY ship the guide's starting values as first-deployment defaults but MUST expose each threshold as a tunable configuration parameter (e.g., environment variable, config file) — hardcoded starting values become de facto operator-visible defaults and re-introduce the attacker oracle. Implementations SHOULD log or alarm a `threshold_tuning_overdue` event when any threshold remains at its shipped starting value more than 30 days past the verifier's first admission; this gives the operator-tuning obligation a testable, auditable hook rather than relying on operator diligence alone.
The alarm payload MUST name which clause (a, b, c, or d) tripped so operator triage can respond to the right threat shape. Alarming here catches the slow-burn distributed-compromise pattern *before* the aggregate cap triggers — once `webhook_signature_rate_abuse` fires on the aggregate cap, the cache is already full and every legitimate signer is being rejected. Alarms SHOULD route to incident response, not to automatic revocation: the distinguishing signal between "attack" and "onboarding a batch of new sellers" is operator context, not machine-derivable, and automatic revocation on alarm creates a denial-of-service vector (any party driving legitimate new-signer onboarding can trip the alarm and cause mass revocation).
**Cross-endpoint scoping (MUST).** A buyer that exposes more than one webhook endpoint (per-integration, per-environment, per-tenant, or per-pod in a horizontally-scaled fleet) MUST either:
1. **Share a single logical replay cache across every endpoint** a given signer can reach (Redis / shared dedup service — not per-process in-memory), so that a `(keyid, nonce)` inserted by endpoint A is visible to endpoint B before step 12 runs; or
2. **Include the canonical destination URL in the replay key**, scoping dedup to `(keyid, canonical destination URL, nonce)`. The canonical form is the `@target-uri` after normalisation per [the request-signing profile](#adcp-rfc-9421-profile) (scheme lowercased, host IDNA-normalised, default port elided, fragment stripped).
Option 1 is stronger — it rejects cross-endpoint replay outright within the ±360 s window. Option 2 is weaker — the same `(keyid, nonce)` is replayable at each distinct endpoint URL, but because the signed `@target-uri` is covered by the signature, the verifier at endpoint B will reject any payload whose `@target-uri` was signed for endpoint A with `webhook_signature_digest_mismatch` (the canonical signature base fails) or `webhook_signature_invalid`. Option 2 is acceptable only when the signer's canonical `@target-uri` is per-endpoint; a signer that signs the same payload for multiple endpoints defeats option 2 and MUST use option 1.
Per-pod or per-region *in-memory* replay caches without a shared tier are non-conformant for buyers that run more than one endpoint: they leave a cross-endpoint replay window bounded only by ±360 s and the attacker's ability to route to a different pod. Operators MUST either front the webhook fleet with a shared dedup tier or document and enforce the per-endpoint URL scoping above.
All other rules from [Transport replay dedup](#transport-replay-dedup) apply verbatim: in-memory LRU for single-process verifiers, Redis `SETNX` at high volume, atomic insert-with-cap-check at step 13 in distributed deployments.
##### Webhook revocation and rotation
Signers MUST publish revocations via the same combined revocation list used for request signing — see [Transport revocation](#transport-revocation). A single list per operator origin covers governance-signing, request-signing, and webhook-signing keys.
**HMAC→9421 migration.** A buyer transitioning from HMAC to 9421 MUST disable its HMAC verifier once the seller has acknowledged the cutover. Running both verifiers concurrently leaves the HMAC path exploitable for the original 5-minute replay window plus however long the buyer forgets to turn it off; "just in case" operational posture keeps the deprecated path live past the intended deprecation. Sellers SHOULD reject `authentication` blocks from a counterparty that has previously been migrated to 9421, logging the rejection. During the cutover window, buyers MAY run both verifiers but SHOULD maintain a single dedup keyspace so that the same logical event under either scheme maps to the same `(sender identity, idempotency_key)` tuple — see the [Reliability](/dist/docs/3.2.8/building/by-layer/L3/webhooks#reliability) section for dedup scope under mixed-mode delivery.
##### Webhook error taxonomy
Codes parallel the [request-signing error taxonomy](#transport-error-taxonomy), prefixed `webhook_` so SDK error handling distinguishes the two profiles. Buyers MAY return `401` to the seller on any of these; a seller's retry loop will replay with the same signature bytes, so every code in this table is non-retryable to the sender — signature failures, authority-mismatch, and mode-mismatch all produce identical outputs on retry — even though HTTP semantics permit retry.
| Failure | Code |
| - | - |
| `Signature` or `Signature-Input` header malformed or one without the other | `webhook_signature_header_malformed` |
| Required sig-param absent | `webhook_signature_params_incomplete` |
| `tag` not `adcp/webhook-signing/v1` | `webhook_signature_tag_invalid` |
| `alg` not in allowlist | `webhook_signature_alg_not_allowed` |
| Signature window invalid | `webhook_signature_window_invalid` |
| Required covered components missing (including `content-digest`) | `webhook_signature_components_incomplete` |
| `keyid` not in seller JWKS after one refetch | `webhook_signature_key_unknown` |
| JWK `adcp_use` ∉ , absent, or `key_ops` lacks `verify` | `webhook_signature_key_purpose_invalid` |
| `keyid` ∈ `revoked_kids` | `webhook_signature_key_revoked` |
| Revocation list not refreshed within grace | `webhook_signature_revocation_stale` |
| Cryptographic verification failed | `webhook_signature_invalid` |
| `content-digest` mismatch | `webhook_signature_digest_mismatch` |
| Body contains duplicate object keys (parser-differential attack class) | `webhook_body_malformed` |
| `@authority` does not match signed `@target-uri` authority component (cross-vhost replay) | `webhook_target_uri_malformed` |
| Nonce already seen within window | `webhook_signature_replayed` |
| Per-keyid replay cache exceeded cap | `webhook_signature_rate_abuse` |
| Registered auth mode does not match signature mode on received webhook | `webhook_mode_mismatch` |
**Retry semantics for verification failures.** At-least-once delivery tells senders to retry on any non-2xx response, but a verification failure is not a transient error — the signature bytes and request context arrive identically on every retry, so every retry fails identically. Senders MUST treat a `401` response carrying `WWW-Authenticate: Signature error="webhook_*"` (any code defined in the taxonomy above, including `webhook_signature_*`, `webhook_target_uri_malformed`, and `webhook_mode_mismatch`) as a terminal failure for that specific delivery attempt: stop retrying the current event, log the failure with the error code for operator attention, and continue the normal retry queue for subsequent events. Senders SHOULD route sustained `webhook_*` error rates above an operator-defined threshold to incident response rather than continuing to emit them — persistent signature, authority, or mode failures indicate a key-rotation coordination problem, a misconfigured verifier, or a compromise, all of which need human action. Receivers MUST NOT silently discard these failures; surfacing them in operator logs is part of the security posture.
**Editor note on future additions.** The wildcard `webhook_*` terminal-failure classification above is an eager sweep: any new code added to the taxonomy inherits terminal-per-delivery semantics without individual review. Editors adding a new `webhook_*` code that SHOULD be retryable (e.g., a future transient-infrastructure signal) MUST update this paragraph to carve out the exception at the point of addition — do not rely on the pattern match to remain safe for codes not yet defined.
##### Webhook migration timeline
| Phase | Behavior |
| - | - |
| 3.0 GA | 9421 webhook signing is baseline for any seller that emits webhooks. Legacy HMAC-SHA256 fallback available when buyer populates `push_notification_config.authentication.credentials` or `accounts[].notification_configs[].authentication.credentials`; sellers MAY decline to support it. |
| 3.x | HMAC fallback is deprecated. Sellers SHOULD log warnings when selected. SDKs SHOULD surface a deprecation notice to buyers that still configure `authentication`. |
| 4.0 | `authentication` on `push_notification_config` and `accounts[].notification_configs[]` is removed from the schema. 9421 webhook signing is the only supported path. |
#### TMP cross-reference
**TMP keys MUST declare a distinct `adcp_use` value** (or omit it entirely) so verifiers reject them for request signing via step 8. Publishing TMP keys at the same `jwks_uri` as request-signing and webhook-signing keys is permitted and encouraged — one publication pattern, six signing systems in 3.2, each `kid`-scoped:
* governance JWS — `adcp_use: "governance-signing"`
* request signing (RFC 9421) — `adcp_use: "request-signing"` (also signs webhooks; see [Webhook callbacks](#webhook-callbacks))
* webhook signing (RFC 9421) — uses the `request-signing` key; the legacy `adcp_use: "webhook-signing"` value is **deprecated** (still accepted, pending removal — see follow-up issue in the deprecation note)
* designated-task response-payload JWS — `adcp_use: "response-signing"` (see [Designated-task payload-envelope response signing](#designated-task-response-signing) above)
* portable credentials issued by an AdCP agent — `adcp_use: "attestation-signing"` (the credential proof format still defines the signature input and algorithm)
* TMP envelope — TMP's own future `adcp_use` value
Cross-purpose reuse is prevented automatically because every verifier enforces an exact `adcp_use` match on its own profile.
Trusted Match Protocol signs match-time requests with its own Ed25519 envelope. TMP's per-request budget (sample-verify at \~5%) is too tight for full RFC 9421 verification on every call. **TMP signing is out of scope for this section**; this profile only constrains how TMP keys are published alongside request-signing keys on the same JWKS.
#### Transport migration timeline
AdCP 4.0 is the next breaking-changes accumulation window. Mandatory request signing for spend-committing operations is one of its floor requirements — the minimum security bar for AdCP 4.0 spend traffic — not the sole headline feature. Other v4.0 changes will accumulate on the [roadmap](/dist/docs/3.2.8/reference/roadmap#v40-planned).
| Phase | Status | Behavior |
| - | - | - |
| 3.0 GA | Optional, capability-advertised | Verifiers MAY validate; `required_for: []` by default. Signers MAY sign. Reference vectors ship; reference SDK pilots begin. |
| 3.0–3.1 | Reference SDKs ship; pilots surface bugs | `covers_content_digest` defaults to `"either"`; explicit `"forbidden"` remains available for legacy body-rewriting infrastructure. Early adopters turn on `required_for` incrementally. |
| 3.2 | Signing remains optional; body integrity becomes mandatory when used | An agent advertising request signing MUST explicitly emit `covers_content_digest: "required"`. Every accepted signature on a request with a body covers `content-digest`; legacy modes require a separately configured 3.0/3.1 endpoint. |
| 4.0 | Required for spend-committing operations | `required_for` MUST include `create_media_buy`, `acquire_*`, and every spend-committing operation the verifier supports. Signers MUST sign; legacy digest modes are removed. |
Implementations that ship signing in 3.x SHOULD enable verifier-side `required_for` selectively (per-counterparty pilot, then broader rollout) before 4.0 to validate end-to-end paths against real traffic — this is what makes the 4.0 transition feasible without ecosystem-wide breakage.
#### Request verifier reference (TypeScript)
Illustrative only. The `verify9421` and `parseSignatureInput` callbacks encapsulate protocol-specific canonicalization and signature verification; implementations should pin a specific RFC 9421 library that has been validated against the AdCP conformance test vectors at [`/compliance/latest/test-vectors/request-signing/`](https://adcontextprotocol.org/compliance/latest/test-vectors/request-signing/).
```ts theme={null}
import { createRemoteJWKSet } from "jose";
class RequestSignatureError extends Error {
constructor(public code: string) { super(code); }
}
const ALLOWED_ALGS = new Set(["ed25519", "ecdsa-p256-sha256"]);
const REQUIRED_TAG = "adcp/request-signing/v1";
const REQUIRED_COMPONENTS = new Set(["@method", "@target-uri", "@authority"]);
const REQUIRED_PARAMS = ["created", "expires", "nonce", "keyid", "alg", "tag"] as const;
export async function verifyAdcpRequestSignature(req: Request, ctx: {
operationName: string;
requiredFor: Set;
contentDigestPolicy: "required" | "forbidden" | "either";
resolveJwk: (keyid: string) => Promise<{ jwk: unknown; agentUrl: string }>; // throws _key_unknown after refetch
isKeyRevoked: (keyid: string) => Promise;
isRevocationStale: () => Promise;
isKeyidAtCapacity: (keyid: string) => Promise;
isReplayed: (keyid: string, nonce: string) => Promise;
recordNonce: (keyid: string, nonce: string, ttlSeconds: number) => Promise;
verify9421: (req: Request, jwk: unknown, covered: string[]) => Promise; // throws on signature or digest failure
parseSignatureInput: (header: string) => {
keyid?: string; alg?: string; created?: number; expires?: number;
nonce?: string; tag?: string; components: string[];
};
}) {
const sigInput = req.headers.get("signature-input");
// Pre-check: required_for / downgrade protection.
if (!sigInput) {
if (ctx.requiredFor.has(ctx.operationName)) throw new RequestSignatureError("request_signature_required");
return; // operation doesn't require a signature; verify nothing.
}
let parsed;
try { parsed = ctx.parseSignatureInput(sigInput); }
catch { throw new RequestSignatureError("request_signature_header_malformed"); }
// 2: presence
for (const p of REQUIRED_PARAMS) {
if ((parsed as any)[p] == null) throw new RequestSignatureError("request_signature_params_incomplete");
}
// 3: tag
if (parsed.tag !== REQUIRED_TAG) throw new RequestSignatureError("request_signature_tag_invalid");
// 4: alg
if (!ALLOWED_ALGS.has(parsed.alg!)) throw new RequestSignatureError("request_signature_alg_not_allowed");
// 5: window (including expires > created)
const now = Math.floor(Date.now() / 1000);
if (parsed.expires! <= parsed.created! ||
parsed.created! > now + 60 ||
parsed.expires! < now - 60 ||
parsed.expires! - parsed.created! > 300) {
throw new RequestSignatureError("request_signature_window_invalid");
}
// 6: components
for (const c of REQUIRED_COMPONENTS) {
if (!parsed.components.includes(c)) throw new RequestSignatureError("request_signature_components_incomplete");
}
const coversCd = parsed.components.includes("content-digest");
if (ctx.contentDigestPolicy === "required" && !coversCd) {
throw new RequestSignatureError("request_signature_components_incomplete");
}
if (ctx.contentDigestPolicy === "forbidden" && coversCd) {
throw new RequestSignatureError("request_signature_components_unexpected");
}
// 7: JWK resolution
const { jwk } = await ctx.resolveJwk(parsed.keyid!); // throws _key_unknown
// 8: key purpose
const j = jwk as any;
if (j.use !== "sig" || !Array.isArray(j.key_ops) || !j.key_ops.includes("verify") || j.adcp_use !== "request-signing") {
throw new RequestSignatureError("request_signature_key_purpose_invalid");
}
// 9: revocation (BEFORE crypto verify)
if (await ctx.isRevocationStale()) throw new RequestSignatureError("request_signature_revocation_stale");
if (await ctx.isKeyRevoked(parsed.keyid!)) throw new RequestSignatureError("request_signature_key_revoked");
// 9a: per-keyid cap (BEFORE crypto verify) — prevents amplified crypto work by abusive/misconfigured signer.
if (await ctx.isKeyidAtCapacity(parsed.keyid!)) {
throw new RequestSignatureError("request_signature_rate_abuse");
}
// 10 + 11: crypto verify, content-digest recompute — both inside verify9421.
try { await ctx.verify9421(req, jwk, parsed.components); }
catch (e: any) {
if (e?.code === "digest_mismatch") throw new RequestSignatureError("request_signature_digest_mismatch");
throw new RequestSignatureError("request_signature_invalid");
}
// 12: replay check
if (await ctx.isReplayed(parsed.keyid!, parsed.nonce!)) {
throw new RequestSignatureError("request_signature_replayed");
}
// 13: replay insert (only after all checks pass)
await ctx.recordNonce(parsed.keyid!, parsed.nonce!, (parsed.expires! - now) + 60);
}
```
### Budget Validation
Validate budgets before committing:
```javascript theme={null}
async function validateBudget(request, account) {
const { budget } = request;
// Check positive amount
if (budget.amount <= 0) {
throw new ValidationError('Budget must be positive');
}
// Check against account limits
const limits = await getAccountLimits(account.account_id);
if (budget.amount > limits.daily_spend_limit) {
throw new BudgetError('Exceeds daily spend limit');
}
// Check available balance
const balance = await getAvailableBalance(account.account_id);
if (budget.amount > balance) {
throw new BudgetError('Insufficient balance');
}
}
```
## Transport Security
AdCP's application-layer security primitives (9421 signing, JWS governance, idempotency) assume the transport does not help the attacker. A misconfigured TLS stack breaks that assumption — it downgrades a protocol designed to withstand active on-path adversaries into one that trusts every intermediary.
This section is normative for every AdCP endpoint — inbound (seller and buyer API surfaces) and outbound (JWKS fetch, brand.json fetch, revocation list fetch, webhook delivery). It is deliberately prescriptive so operators do not have to reason from first principles about cipher suites at 3 a.m.
### TLS version policy
* **TLS 1.3 is RECOMMENDED** for every AdCP endpoint.
* **TLS 1.2 is the minimum.** Endpoints MUST reject TLS 1.1 and below at the handshake.
* **Client-side verifiers** (e.g., an AdCP server fetching a counterparty's JWKS, brand.json, or revocation list) MUST refuse to negotiate below TLS 1.2. Libraries that still default to TLS 1.0 for "compatibility" MUST be configured explicitly.
* SSL 2.0, SSL 3.0, TLS 1.0, and TLS 1.1 MUST NOT be enabled — not for any endpoint, not for any legacy partner, not even on a separate port.
### Cipher suites and algorithms
* TLS 1.3: use the IETF-defined suites (`TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`). All three are AEAD; no other TLS 1.3 suites exist. Do not disable any of them arbitrarily — operators who disable ChaCha20 on "speed" grounds are one client quirk away from broken mobile clients.
* TLS 1.2: restrict to **AEAD-only** ECDHE suites. The permitted set is `ECDHE-ECDSA-AES128-GCM-SHA256`, `ECDHE-ECDSA-AES256-GCM-SHA384`, `ECDHE-ECDSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`.
* CBC-MAC, RC4, 3DES, DES, NULL, EXPORT, anonymous DH, and static RSA key-exchange suites MUST be disabled on TLS 1.2 — their presence silently downgrades the security properties of everything built above the handshake.
* Server certificates MUST use ECDSA (P-256 or P-384) or RSA ≥ 2048 bits. RSA \< 2048 MUST NOT be used.
* Endpoints MUST prefer server-side cipher ordering (OpenSSL `SSL_OP_CIPHER_SERVER_PREFERENCE`, nginx `ssl_prefer_server_ciphers on`) so a weak client cannot force a weak suite when a strong one is mutually available.
### Certificate validation (outbound fetches)
Every outbound HTTPS request AdCP makes — JWKS, brand.json, revocation list, webhook callback, aggregator proxy — MUST perform full PKIX validation. The specific checks:
* **Trust chain** MUST terminate at a public root the operator has intentionally included. No `--insecure`, no `verify=False`, no `rejectUnauthorized: false` anywhere in production code paths. This is the single most common production compromise — an engineer turns off verification to work around a cert issue in staging, the flag ships.
* **SAN match** is the authoritative identity check. The certificate MUST have a Subject Alternative Name entry matching the URL host. CN-only fallback MUST NOT be accepted; major HTTP clients still support it for legacy reasons, but AdCP verifiers MUST require SAN.
* **Expiry** MUST be checked against the current clock. Fetching a JWKS from a domain whose TLS cert expired last week is a governance red flag, not a compatibility problem.
* **Hostname verification** MUST be enabled in the library config. Several popular HTTP client libraries ship with hostname verification on by default; a surprising number have a flag that disables it. AdCP implementations MUST assert hostname verification is on, not assume it.
* **OCSP stapling** SHOULD be accepted when offered; OCSP must-staple on operator-controlled certificates is RECOMMENDED. Must-staple turns a missing staple into a hard failure, which closes the soft-fail-on-OCSP loophole.
* **Certificate Transparency (CT)** SCTs SHOULD be checked on endpoints serving regulated spend. Browsers already enforce CT; AdCP SDKs fetching governance JWKS on a regulated-category workflow SHOULD too, so a hidden mis-issued cert is detectable.
* **Pinning** is NOT required at the protocol layer and SHOULD be avoided for counterparty-supplied URLs (brand.json, JWKS) because it collides with legitimate operator cert rotation. Pinning to a public-CA chain (intermediate-pin) is acceptable; pinning to a specific leaf cert is discouraged.
### Inbound server-side headers
```javascript theme={null}
app.use((req, res, next) => {
// HSTS: 1 year, include subdomains, preload-eligible. MUST be on every HTTPS response.
res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
// No framing of AdCP API responses — even though they're JSON, frame isolation
// protects any error or debug HTML that could leak through.
res.setHeader('X-Frame-Options', 'DENY');
// MIME sniffing off: responses declare their type, clients MUST respect it.
res.setHeader('X-Content-Type-Options', 'nosniff');
// Prevent referrers leaking to external URLs supplied by counterparties.
res.setHeader('Referrer-Policy', 'no-referrer');
// AdCP endpoints serve no browser-facing HTML — block script-source loading outright.
// If your operator reuses the same origin for a dashboard, adjust this per-path.
res.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'");
next();
});
```
**HSTS max-age MUST be ≥ 31536000 (1 year)** for any domain serving an AdCP endpoint. `includeSubDomains` MUST be set unless the operator has a documented reason not to. Domains serving spend-committing AdCP endpoints SHOULD be submitted to the HSTS preload list.
### Client / outbound TLS hardening
Outbound-fetch code paths (governance JWKS, brand.json, revocation list, webhook delivery, aggregator proxy) MUST:
* Use a connection pool with a fixed per-host cap and a fixed overall cap. Unbounded pools are a resource-exhaustion surface.
* Cap TLS handshake time at 10 s and total request time at 30 s by default — counterparty-supplied URLs are a tarpit DoS vector otherwise.
* Pin the connection to the IP address that passed the [SSRF controls](#webhook-url-validation-ssrf) — DNS re-resolution between the SSRF check and the actual connect is how TOCTOU bypasses land.
* Refuse redirects on security-sensitive fetches except for the two domain-derived well-known bootstrap URLs. The initial `/.well-known/brand.json` fetch permits only the original hostname ↔ exact `www` counterpart, HTTPS on the original port, ≤ 3 hops. The initial `/.well-known/adagents.json` fetch permits only hosts in the original eTLD+1, HTTPS-preserving, ≤ 3 hops. Both are anchored on the original request and re-apply SSRF validation per hop. Explicit URLs — including either file's `authoritative_location`, `identity.brand_json_url`, JWKS, revocation lists, and webhook callbacks — use zero redirects. JSON `authoritative_location` and `house` variants are document-level indirection and do not expand the HTTP redirect budget.
* Disable session resumption across trust boundaries. Resuming a TLS session with an attacker-controlled counterparty onto a later verified counterparty (same IP via DNS rebind) is a well-known class of confusion; library defaults are usually fine, but the operator MUST audit.
### TLS renegotiation and downgrade
* TLS 1.2 **secure renegotiation** (RFC 5746) MUST be enabled if renegotiation is supported at all. Insecure-renegotiation-tolerant stacks are a MUST-disable.
* **TLS compression** (CRIME) MUST be off.
* **Heartbeat extension** MUST be off on TLS 1.2 endpoints (Heartbleed lineage).
* **0-RTT / early-data** on TLS 1.3 MUST NOT be enabled for any endpoint that accepts mutating AdCP operations. 0-RTT is replayable by design; idempotency and signature-nonce dedup are not free rescues once the request has hit application logic. Read-only `get_adcp_capabilities` MAY use 0-RTT; everything else MUST NOT.
### mTLS transport
When [mTLS](/dist/docs/3.2.8/building/by-layer/L2/authentication#mtls) is the authentication mechanism:
* The client certificate SAN / Subject MUST match the buyer's registered domain as declared in `adagents.json` or `brand.json`. Relying on any header field (`X-Forwarded-Client-Cert`, `X-Client-DN`, etc.) is [explicitly forbidden](#buyer-identity-resolution) — header fields can be injected across misconfigured proxies.
* The terminating edge (load balancer, mesh sidecar) MUST forward the verified certificate identity to the AdCP server over an in-cluster channel the server can authenticate. Unauthenticated sidecar headers are a bypass — deploy mTLS end-to-end, or pin the in-cluster channel.
* Client certificates MUST be checked against a CRL or OCSP responder operated by the operator. "Issued by us" is not the same as "still valid."
### Private-network and metadata protection
This section's transport controls do not substitute for the [SSRF controls](#webhook-url-validation-ssrf) on counterparty-supplied URLs. Every outbound fetch to a counterparty URL MUST apply the SSRF rules — reject non-HTTPS, reject IPs in reserved ranges (including cloud-metadata addresses), refuse redirects, cap size and time. TLS is useless if the URL points at `169.254.169.254`.
### What this section does NOT replace
Transport security is the floor, not the ceiling. Even a flawless TLS stack does not replace:
* **Application-layer body integrity** ([request signing](#request-signing) and [webhook callbacks](#webhook-callbacks)) — TLS protects the wire, not the payload after a compromised intermediary.
* **Governance attestation** ([signed governance context](#signed-governance-context)) — TLS does not tell the seller whether the buyer's governance agent authorized this spend.
* **Idempotency** ([request safety](#request-safety)) — TLS does not prevent the sender from retrying after a network timeout.
Operators that confuse "we have a modern TLS configuration" with "our AdCP deployment is secure" are exactly the operators the body-bound signature profile exists to defend against.
## Input Validation
### Request Validation
Validate all user-provided input:
```javascript theme={null}
const INPUT_LIMITS = {
targeting_brief_max_length: 5000,
creative_upload_max_size: 100 * 1024 * 1024, // 100MB
max_formats_per_request: 50,
max_products_per_query: 100
};
function validateRequest(request) {
// Check string lengths
if (request.brief?.length > INPUT_LIMITS.targeting_brief_max_length) {
throw new ValidationError('Brief exceeds maximum length');
}
// Validate IDs are proper UUIDs
if (request.product_id && !isValidUUID(request.product_id)) {
throw new ValidationError('Invalid product_id format');
}
// Reject unexpected fields
const allowedFields = ['brief', 'product_id', 'budget', 'context_id'];
for (const field of Object.keys(request)) {
if (!allowedFields.includes(field)) {
throw new ValidationError(`Unexpected field: ${field}`);
}
}
}
```
### SQL Injection Prevention
Always use parameterized queries:
```javascript theme={null}
// GOOD: Parameterized query (request-supplied account_id after auth precheck)
const result = await db.query(
'SELECT * FROM media_buys WHERE id = $1 AND account_id = $2',
[mediaBuyId, request.account.account_id]
);
// BAD: String concatenation (NEVER do this)
// const result = await db.query(
// `SELECT * FROM media_buys WHERE id = '${mediaBuyId}'`
// );
```
## Audit Logging
### Required Log Events
Log all security-relevant events:
```javascript theme={null}
const LOG_EVENTS = {
AUTH_SUCCESS: 'auth_success',
AUTH_FAILURE: 'auth_failure',
BUDGET_COMMIT: 'budget_commit',
BUDGET_MODIFY: 'budget_modify',
ACCESS_DENIED: 'access_denied',
WEBHOOK_VERIFIED: 'webhook_verified',
WEBHOOK_REJECTED: 'webhook_rejected'
};
function logSecurityEvent(eventType, details) {
console.log(JSON.stringify({
event: eventType,
timestamp: new Date().toISOString(),
agent_id: details.agentId,
account_id: details.accountId,
ip_address: details.ipAddress,
resource: details.resource,
outcome: details.outcome,
// NEVER log: credentials, PII, targeting briefs
}));
}
```
### Log Retention
* Security logs: 90 days minimum (365 days recommended)
* Financial logs: 7 years (compliance requirement)
* Access logs: 30 days minimum
## Security Checklist
### For Publishers (AdCP Servers)
* [ ] Implement strong authentication (OAuth 2.0, API keys, or mTLS)
* [ ] Enforce agent and account isolation in all database queries
* [ ] Implement idempotency for financial operations
* [ ] Validate all input with strict schema validation
* [ ] Use TLS 1.3+ for all communications
* [ ] Verify webhook signatures cryptographically
* [ ] Log all security events immutably
### For Buyer Agents (AdCP Clients)
* [ ] Store credentials in secure key management system
* [ ] Rotate credentials every 90 days
* [ ] Use HTTPS for all AdCP communications
* [ ] Validate responses from publishers
* [ ] Implement alerts for unusual spending patterns
### For Orchestrators (Multi-Agent, Multi-Account)
* [ ] Store each agent's credentials separately (encrypted)
* [ ] Enforce agent and account filtering in ALL queries
* [ ] Use row-level security in databases
* [ ] Log all operations with agent and account identity
* [ ] Implement per-agent rate limiting
## Next Steps
* **Security Model**: See [Security Model](/dist/docs/3.2.8/building/concepts/security-model) for the threat model and the five-layer defense narrative this reference implements
* **Webhooks**: See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for webhook security patterns
* **Error Handling**: See [Error Handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling) for authentication errors
* **Orchestrator Design**: See [Orchestrator Design](/dist/docs/3.2.8/building/operating/orchestrator-design) for multi-tenant security
# Webhook Verifier Tuning Guide
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L1/webhook-verifier-tuning
Non-normative tuning recipes for webhook verifier thresholds — starting values, baselining methodology, and attack-scenario walkthroughs.
> [!NOTE]
>
> This document is non-normative. It provides **starting values** and a tuning methodology for the webhook verifier thresholds whose **structural shape** is specified in [Webhook Security](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-security). The normative spec specifies only the category (short-window ratio, medium-window ratio, long-window ratio, proportional ceiling) and the requirement that thresholds be operator-configurable. This guide tells you where to start and how to tune.
> [!WARNING]
>
> **First-30-days oracle risk.** The starting values below are published, therefore attacker-known. A verifier running the shipped defaults is running against an oracle until operators tune the thresholds to their own traffic. **Operators MUST tune each threshold within 30 days of first deployment**; verifiers running published starting values past 30 days are running against a known attacker tuning target. Implementations SHOULD randomize each starting threshold on first deployment, drawing from a log-uniform distribution over \[0.5×, 2×] the starting value (equivalently: ratio-uniform jitter with a 4× spread between the narrowest and widest defaults across a fleet). Narrower distributions (e.g., ±30%, giving only a 1.86× spread) let a disciplined attacker tune to 0.7× the published value and stay under every jittered deployment in the fleet; log-uniform over \[0.5×, 2×] forces the attacker to cover a 4× range, which starts to cost meaningfully in attack volume. **Implementations SHOULD log or alarm a `threshold_tuning_overdue` event** when any threshold remains at its shipped starting value more than 30 days past the verifier's first admission — this gives the 30-day tuning rule a testable, auditable hook (without it, the rule is operator-diligence-only and silently fails when diligence lapses).
**Why this guide is separate from the spec.** Publishing concrete threshold values as normative defaults hands attackers an oracle — a disciplined attacker reads the spec and tunes their attack to stay just under the published values. The normative spec deliberately says *what shape the rule has*; this guide says *what numbers to start with*. Operators MUST treat these as starting values, observe their own traffic, and adjust.
## The rule you're tuning
Verifiers MUST track new-keyid admission pressure and SHOULD alert when the rate exceeds **any** of four thresholds (whichever triggers first). The normative spec names these four thresholds by category; this guide gives starting values for each category.
## Starting values
| # | Category | Starting formula | What it catches |
| - | - | - | - |
| **a** | Short-window ratio | `3× the 24-hour moving average` of new-keyid admission rate | Sudden spikes against a stable baseline — the classic "abnormal traffic volume" signal. |
| **b** | Medium-window ratio | `2× the 30-day P95` | Multi-week ramp-up attacks. The 30-day P95 is dominated by the baseline-traffic tail, so a 2–3 week ramp cannot drift the reference into the attack. |
| **c** | Long-window ratio | `1.5× the 90-day P99` | Multi-month ramp-up attacks. A 60–90 day staged compromise that drifts the 30-day P95 still trips the 90-day P99 because the P99 tail moves much more slowly. |
| **d** | Proportional ceiling | `max(20 distinct new keyids, 10% × 30-day unique-keyid count) per 5-minute window` | Sparse-traffic verifiers whose moving averages and P95/P99 values are near zero (small operators), AND auto-scaling for operators of any size. |
**These are starting values, not normative defaults.** A fresh deployment can use them day one. As traffic baselines stabilize, tighten or loosen based on the observed false-positive and false-negative rates.
## Baselining methodology
Before tuning the thresholds, establish the baseline shape of your verifier's traffic:
1. **Collect 30 days of new-keyid admissions** without alarming. Instrument the rate but do not page operators.
2. **Compute your deployment's P50, P95, P99** of new-keyid admissions per 5-minute window.
3. **Track the unique-keyid count per 30-day sliding window.** This is the denominator for clause (d).
4. **Document your median and peak legitimate onboarding batches.** If you routinely onboard 50 new signers per day (batched into a 10-minute window twice a week), clause (d)'s fixed floor of 20/5-min is too tight; raise it to match your largest legitimate batch.
Once the baseline is known, each clause (a)/(b)/(c)/(d) becomes a concrete threshold in your deployment. The spec's OR-of-four shape means any one clause tripping is enough for an alert — so the thresholds do not need to agree on shape, they need to each close a different attacker pattern.
## Attack-scenario walkthroughs
### Scenario 1: Sudden mass-compromise
An attacker compromises 100 signer keys over a weekend and begins sending webhooks from all 100 simultaneously starting Monday morning.
* **What trips**: clause (a). The 24-hour moving average of new-keyid admissions is \~0 (on a stable verifier); 100 new keyids in one 5-min window is orders of magnitude above `3×` that.
* **Alarm detail the operator needs**: which clause (a), so the triage team knows to look for a mass-compromise pattern rather than a single-key spike.
### Scenario 2: Patient multi-week ramp
An attacker compromises 5 keys in week 1, 10 in week 2, 20 in week 3, 40 in week 4 — doubling weekly, staying under any "3× yesterday" rule because today's rate is never more than 2× yesterday.
* **What trips**: clause (b). The 30-day P95 is dominated by the first three weeks of baseline traffic, so `2×` that is roughly the normal peak; by week 4, 40 keyids/day is 8× the weekly baseline, well over the P95 anchor.
* **Miss if you only had clause (a)**: yes. 2× daily ramping stays under 3× short-window MA permanently.
### Scenario 3: Multi-quarter staged compromise
An attacker compromises 1 key per day for 90 days — never triggering any daily-or-weekly ratio because today's rate is roughly equal to yesterday's.
* **What trips**: clause (c). The 90-day P99 is anchored by baseline traffic much older than the attack; even the last 2 weeks of the ramp (days 76–90) register as above `1.5× baseline` P99.
* **Miss if you only had clauses (a) and (b)**: yes. Monotonic slow ramps drift both the 24-hour MA and the 30-day P95 with them.
### Scenario 4: Sparse-traffic verifier, burst attack
A verifier with 20 total active signers and near-zero new-keyid traffic suddenly sees 15 new keyids in a 5-minute window.
* **What trips**: nothing. The ratio rules (a)/(b)/(c) compare against near-zero baselines (`3× 0.01 = 0.03`) and would trip on any positive admission including legitimate single-seller onboarding — so they produce too much noise to alarm on at sparse-traffic verifiers. Clause (d)'s `max(20, 10%×20) = max(20, 2) = 20` fixed floor requires more than 20 new keyids per 5-min window before firing. 15 is under the floor.
* **What the operator sees**: nothing. 15 new keyids at a sparse-traffic verifier is within normal bounds; operators running sparse-traffic verifiers SHOULD raise the fixed floor if routine onboarding regularly exceeds it, OR leave the floor at 20 if routine onboarding stays under (the attacker's ceiling becomes ≤20/window, which sharply limits aggregate pressure over reasonable windows).
### Scenario 5: Large-verifier ceiling scaling
A verifier with 10,000 active signers sees 500 new keyids in a 5-minute window.
* **What trips**: nothing from clause (d). 10% × 10,000 = 1,000; 500 does not exceed the proportional floor. Depending on the verifier's baseline, clauses (a) or (b) might trip if 500/5-min is materially above the 24-hour moving average or the 30-day P95.
* **What changes with scale**: at a small verifier (100 signers), 500 new keyids is 5× the entire signer base — obviously attack. Clause (d)'s `max(20, 10%×100) = 20` floor means 500 is 25× over, firing immediately. The proportional shape auto-scales.
### Scenario 6: Onboarding-burst false positive
A verifier onboarding 200 new sellers in a planned Tuesday batch trips clause (a) or (d) during the batch.
* **What the operator does**: raises the fixed floor in clause (d) temporarily (documented in change-control), OR silences the alert for the known onboarding window. After the batch, floor returns to baseline. Document the raise so it can be audited and floored-back. Raised-floor windows SHOULD be kept as short and internally-scoped as possible — publicly-announced onboarding windows are an attacker planning signal (see Scenario 10).
* **Why automatic revocation is wrong here**: the spec's `Alarms SHOULD route to incident response, not automatic revocation` rule exists specifically for this case. Machine-derivable "attack vs onboarding" is unreliable; operator context is the distinguishing signal.
### Scenario 7: Legitimate key-rotation storm
A peer seller's root CA is revoked and all 500 of their signing agents rotate to fresh `keyid`s within a 10-minute window. Your verifier sees 500 new keyids in one 5-min window and 0 in the next.
* **What trips**: clauses (a) and likely (d). Shape is indistinguishable from Scenario 1 (sudden mass-compromise) at the rate-only level.
* **What the operator does**: triage the alarm, recognize the event shape from the peer seller's notification (CA-compromise incidents are typically pre-announced to peers), mark as legitimate in the incident record, do NOT auto-revoke. If the peer did NOT pre-announce, treat exactly as Scenario 1 until peer contact confirms. **Do not silence the alarm preemptively based on peer announcements alone** — a compromised peer pre-announcement channel is itself an attacker tactic; the alarm firing and being triaged is the detection-in-depth layer.
### Scenario 8: Thin-history window attack (days 1–90 post-deployment)
A verifier deployed yesterday has no 30-day P95 data and no 90-day P99 data. Clauses (b) and (c) degrade gracefully to the clause (d) floor until the percentile windows mature. An attacker who knows the verifier is new stages a ramp that stays under clause (d)'s `max(20, 10%×count)` floor for the first 90 days, during which only clause (a) provides meaningful coverage.
* **What trips**: clause (a) only — and only on sufficiently large short-window spikes. Clauses (b), (c), (d) all degrade to the floor-dominated case.
* **What the operator does**: for new verifiers, SHOULD tighten clause (d)'s absolute floor below the published starting value (e.g., 10 instead of 20) for the first 90 days while P95/P99 mature. Treat this as a documented first-deployment posture, not permanent tuning — relax back to the mature-verifier floor once the percentile windows have real data.
* **Why clauses (b)/(c)/(d) are not independent during warmup**: clause (c) explicitly degrades to `1.5× max(observed_P99, clause_d_floor)`, so during days 1–90 clauses (c) and (d) are redundant. This is a known limitation of the rule shape; the tightened-floor posture is the mitigation.
### Scenario 9: Intermittent low-volume attack (rule-shape limitation)
An attacker compromises 500 keys and emits 1 new keyid every 30 minutes across the fleet — roughly 48/day. Against a clause (d) floor of `max(20, 10% × 200-signer-count) = 20`/5-min, each 5-min window sees 0 or at most 1–2 new keyids. Over 30 days the attack admits 1,440 new keyids — which BECOMES part of the 30-day unique-keyid count clause (b) compares against. The attack is pre-baked into the baseline.
* **What trips**: nothing.
* **What the operator sees**: elevated unique-keyid count over 30 days, but no single-window alarm fires.
* **Why this is a known limitation**: the admission-pressure rule closes volume-spike attacks, not low-rate long-duration attacks smoothed across long windows. **The per-keyid cap (step 9a) and the aggregate cache cap do NOT close this gap** — they bound cache size, not key-population growth, and 1,440 new keyids/month is \~0.014% of a 10M aggregate cap. At the rate-window level, every clause (a/b/c/d) trips at zero and the aggregate-cap alarm never fires. Operators with slow-drip key-population growth in their threat model **MUST layer application-level detection** (signer-reputation scoring, per-seller traffic-anomaly detection over business-meaningful windows like "signals delivered per billing period", new-keyid admission tracked against a declared-fleet-size expectation). Relying only on the admission-pressure rule plus the caps ships a verifier that has the attack class acknowledged in its spec but no actual detection for it.
### Scenario 10: Onboarding-window-timed attack
An attacker monitors the verifier operator's public announcements (product launches, fiscal-year boundaries, platform partnerships). The operator raises clause (d)'s floor to `200` for a scheduled Tuesday onboarding window per Scenario 6. The attacker times their mass-compromise to that Tuesday, riding the temporarily-raised floor.
* **What trips**: nothing during the raised-floor window.
* **What the operator does**: during raised-floor windows, alarms on clauses (a)/(b)/(c) SHOULD escalate to **mandatory human review, not auto-suppress**, even though clause (d) is intentionally loose. Keep raised-floor windows as short as possible and internally-scoped — avoid publicly announcing that "new-seller onboarding will happen on date X" in a form that attackers can schedule against. Where public announcements are unavoidable (regulatory disclosures, customer-facing launches), SHOULD increase out-of-band detection during the window (traffic-pattern analysis, seller-claim cross-validation, request-body sampling).
### Scenario 11: Baseline reset at a mature verifier (failover, cache rebuild, config change)
A mature verifier with 90 days of stable P95/P99 data fails over to a standby pool whose baseline-computation cache is empty. Clauses (b)/(c) degrade to the clause (d) floor-dominated case for the duration of the rebuild — mirroring Scenario 8 (thin-history window) but at a verifier that was supposed to be mature. An attacker who knows failover events happen (public status-page incidents, scheduled maintenance windows, observable response-time changes) can time an attack to land during the rebuild window.
* **What trips**: clause (a) only (same as Scenario 8). Clauses (b)/(c) have no baseline data.
* **What the operator does**: treat as a *temporary* thin-history posture. Persist baseline-statistic state across failover (Redis / shared dedup service) rather than rebuilding from the empty cache — the same infrastructure choice the spec already requires for the replay cache under cross-endpoint scoping also fixes this. If persistence is not possible, tighten clause (d)'s absolute floor during the rebuild window and escalate (a)/(b)/(c) alarms to human review per Scenario 10.
* **Why this is spec-distinct from Scenario 8**: Scenario 8 is a first-deployment posture expected to stabilize in 90 days. Scenario 11 is a mature-verifier operational-event posture that can recur indefinitely if operators don't persist baselines across failover. Spec cannot mandate the persistence choice (deployment-internal); the tuning guide can call it out as a known attack-timing opportunity that operators are responsible for mitigating.
## Tuning adjustments to consider
| Observation | Adjustment |
| - | - |
| Too many false positives from clause (a) during legitimate bursts | Raise the clause (a) ratio from `3×` to `4×` or `5×`. Do NOT lower the threshold on clauses (b)/(c)/(d) to compensate — they catch different attacker shapes. |
| Clause (d) fires on routine onboarding | Raise the fixed floor component of clause (d) to match the largest legitimate batch size. Keep the `10%×30d-unique-count` proportional part unchanged. |
| Clause (c) never fires during red-team exercises that run for \< 60 days | Expected — clause (c) is the multi-month anchor. Red-team exercises SHOULD include a 60-day slow-ramp scenario to validate clause (c) is correctly wired to the 90-day P99. |
| Alarm shows clauses (a) and (d) both fired for the same event | Report the first clause that tripped in the alarm payload (per spec). Both clauses surfacing is informational, not a bug. |
| Verifier is too small to have meaningful P99 data | Clause (c) degrades gracefully to `1.5× max(observed_P99, clause_d_floor)` — never lower than the proportional ceiling. Track for 90 days, then the P99 becomes meaningful. |
## What NOT to do
* **Do NOT publish your tuned threshold values externally.** Thresholds are deployment-internal operational parameters. This rule distinguishes three audiences:
* **Public disclosure** (blog posts, marketing copy, public config repositories, open-source defaults, conference talks): **prohibited**. This is the attacker oracle this guide exists to close.
* **Attested disclosure under NDA** to qualified security auditors, regulators, or contracted red teams: **permitted**. Detection-posture assessment is itself a defense-in-depth practice and SOC 2 / ISO 27001 audits may require it. The NDA scope SHOULD limit redistribution and mandate deletion at engagement close.
* **Internal operator runbooks, incident-response runbooks, version-controlled operator config**: **required**. The detecting team needs the values to triage effectively, and post-incident forensics require knowing what the thresholds were at the time of the event.
* **Do NOT tune all four thresholds to the same value.** Each clause catches a different attacker pattern. Collapsing them loses detection coverage.
* **Do NOT auto-revoke on alarm.** The alarm is a signal for incident response, not a remediation action. Automatic revocation of signer keys on admission-pressure alarm creates a denial-of-service vector: any party driving legitimate new-signer onboarding can trip the alarm and cause mass revocation.
* **Do NOT hardcode the starting values in your deployment config.** Make each threshold a tunable parameter (e.g., environment variable, config file) so operators can adjust without code changes. Hardcoded starting values become de facto operator-visible defaults, which re-introduces the attacker oracle.
## Related
* [Webhook Security → Webhook replay dedup sizing](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-replay-dedup-sizing) — normative spec for the rule this guide tunes. Scroll to the §Webhook replay dedup sizing heading directly beneath the 15-check verifier flow; the "New-keyid admission pressure" bullet is the rule whose four categories the tuning guide populates with starting values.
* [Webhook verifier checklist](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-callbacks) — the full 15-check flow. Step 14b (logging discipline) is a sub-step under step 14 (body well-formedness); its sanitization rules (non-printable classification, 32-byte UTF-8 codepoint-safe truncation, count cap at 4) apply to the diagnostic information this guide assumes alarms carry.
# Account state
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L2/account-state
AdCP account state model: how accounts hold catalogs, creatives, audiences, event sources, and campaigns. Sync tasks, upsert semantics, and async approval workflows.
# Account state
AdCP accounts are stateful containers. Before a buyer can run a campaign on a seller's platform, they build up state on the account: product catalogs, creative assets, audience lists, conversion tracking. Each piece of state has its own sync task, its own approval workflow, and its own lifecycle.
This is different from earlier versions of AdCP where accounts were billing references and most operations were stateless. In AdCP 3.0, the account is the central object that ties everything together.
## State domains
An account holds six categories of state, each managed by a dedicated task:
| Domain | Sync task | What it manages | Lifecycle |
| - | - | - | - |
| **Identity** | `sync_accounts` | Who the buyer is, which brand, billing terms | Setup once, update rarely |
| **Catalogs** | `sync_catalogs` | Product feeds, inventory, stores, promotions, offerings | Continuous — feeds update hourly/daily |
| **Creatives** | `sync_creatives` | Creative assets with format-specific manifests | Per-campaign, updated as needed |
| **Audiences** | `sync_audiences` | First-party CRM audience lists | Incremental — add/remove members over time |
| **Event sources** | `sync_event_sources` | Conversion tracking configuration (pixels, S2S, app events) | Setup once per source, rarely changes |
| **Governance** | `sync_governance` | Governance agent configuration for this account | Setup once per account, update when governance agents change |
| **Campaigns** | `create_media_buy` | Active campaigns with packages and targeting | Created when ready, updated throughout flight |
Each sync task follows the same pattern:
* **Upsert semantics** — items are matched by ID, created if new, updated if existing
* **Discovery mode** — omit the items array to see what's already on the account
* **Async approval** — platforms may review items before activating them
* **Per-item status** — individual items can succeed or fail independently
## Setup sequence
A typical buying workflow builds account state in dependency order. Each step requires the previous steps to be complete:
```mermaid theme={null}
flowchart LR
A[sync_accounts] --> B[sync_catalogs]
A --> C[sync_event_sources]
B --> D[sync_creatives]
C --> D
A --> E[sync_audiences]
A --> G[sync_governance]
D --> F[create_media_buy]
E --> F
G --> F
```
### 1. Establish the account
`sync_accounts` declares who the buyer is and how they pay. The seller acknowledges the relationship and returns status and billing terms.
```json theme={null}
{
"accounts": [{
"brand": { "domain": "acme-corp.com" },
"operator": "pinnacle-media.com",
"billing": "operator"
}]
}
```
### 2. Sync catalogs
`sync_catalogs` makes product data available on the account. Formats declare what catalog types they need via `catalog` asset types in their `assets` array, so the buyer syncs the right feeds before submitting creatives.
```json theme={null}
{
"account": { "account_id": "acct_001" },
"catalogs": [
{
"catalog_id": "product-feed",
"type": "product",
"url": "https://feeds.acme.com/products.xml",
"feed_format": "google_merchant_center",
"update_frequency": "daily"
},
{
"catalog_id": "store-locations",
"type": "store",
"url": "https://feeds.acme.com/stores.json",
"feed_format": "custom",
"update_frequency": "weekly"
}
]
}
```
The platform fetches and validates each feed. Items may be approved, rejected, or flagged — similar to Google Merchant Center reviewing product listings.
### 3. Configure event sources
`sync_event_sources` sets up conversion tracking so the platform can attribute outcomes to ad exposure.
```json theme={null}
{
"account": { "account_id": "acct_001" },
"event_sources": [{
"event_source_id": "web-pixel",
"name": "Website Conversions",
"type": "pixel",
"events": ["purchase", "add_to_cart", "lead"]
}]
}
```
### 4. Configure governance
[`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance) registers governance agents on the account. Once configured, sellers with governance support will call [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) before confirming media buys.
```json theme={null}
{
"account": { "account_id": "acct_001" },
"governance_agents": [{
"agent_url": "https://governance.acme-corp.com/adcp",
"domains": ["campaign", "creative", "content_standards"]
}]
}
```
> [!NOTE]
>
> Changing governance agents on a live account affects all active campaigns. If a governance agent is removed, sellers will stop calling `check_governance` for that domain. If a new agent is added, existing campaigns are not retroactively validated — only new transactions go through the updated governance configuration.
### 5. Sync creatives
`sync_creatives` submits creative assets that reference the catalogs synced in step 2. For catalog-driven formats, the creative's `catalogs` field references synced catalogs by `catalog_id` instead of embedding items inline.
```json theme={null}
{
"account": { "account_id": "acct_001" },
"creatives": [{
"creative_id": "product-carousel",
"format_kind": "image_carousel",
"format_option_ref": { "scope": "product", "format_option_id": "product_carousel_with_inventory" },
"catalogs": [{
"catalog_id": "product-feed",
"type": "product",
"tags": ["summer"]
}],
"assets": {
"banner_image": {
"url": "https://cdn.acmecorp.com/carousel-hero.jpg",
"width": 1200,
"height": 628
}
}
}]
}
```
### 6. Upload audiences
`sync_audiences` uploads first-party audience lists for targeting. Members are hashed before sending.
```json theme={null}
{
"account": { "account_id": "acct_001" },
"audiences": [{
"audience_id": "high-value-customers",
"name": "High Value Customers",
"add": [
{ "hashed_email": "a1b2c3..." },
{ "hashed_email": "d4e5f6..." }
]
}]
}
```
### 7. Create the campaign
With all state in place, `create_media_buy` activates a campaign that references the synced state:
```json theme={null}
{
"account": { "account_id": "acct_001" },
"name": "Summer Product Launch",
"packages": [{
"product_id": "sponsored-products",
"creative_ids": ["product-carousel"],
"targeting_overlay": {
"audiences": { "include": ["high-value-customers"] }
}
}]
}
```
## Discovery
Every sync task supports **discovery mode**: call the task without an items array to see what state already exists on the account. This is how a buying agent learns what a seller already knows about the brand.
```json theme={null}
// What catalogs does this account have?
{ "account": { "account_id": "acct_001" } }
// Response: catalogs already on the account
{
"catalogs": [
{ "catalog_id": "product-feed", "action": "unchanged", "item_count": 1250 },
{ "catalog_id": "store-locations", "action": "unchanged", "item_count": 45 }
]
}
```
This matters because sellers may already have brand data from other sources — a retailer might have the brand's product catalog from their commerce platform, or a publisher might have creatives from a previous campaign. Discovery lets the buyer build on existing state rather than re-uploading everything.
## Approval workflows
Sync tasks are often asynchronous. The platform may need to review items before they're active:
* **Catalogs**: Product listings go through content policy checks. Items can be approved, rejected, or flagged with warnings.
* **Creatives**: Generative creatives require human approval. Traditional creatives may need policy review.
* **Audiences**: Platforms need time to match hashed identifiers against their user base.
* **Event sources**: Conversion tracking may require pixel verification.
All sync tasks support `push_notification_config` for webhook callbacks when processing completes. For long-running operations, the platform returns async status updates (working, input-required, submitted) that the buyer polls or receives via webhook.
## State dependencies
Some state depends on other state. The platform enforces these dependencies:
* **Creatives reference catalogs** — a creative that uses `catalog_id: "product-feed"` requires that catalog to be synced first
* **Campaigns reference creatives and audiences** — `create_media_buy` requires the referenced `creative_ids` and audience IDs to exist on the account
* **Event sources enable optimization** — optimization goals on packages reference event sources for attribution
If a dependency is missing, the platform returns an error explaining what needs to be synced first.
## Stateless vs stateful operations
Not everything requires account state. Some tasks are stateless queries:
| Stateless (no account needed) | Stateful (account required) |
| - | - |
| `get_products` — discover inventory | `create_media_buy` — buy inventory |
| `get_adcp_capabilities` — discover creative operations | `sync_creatives` — upload creatives |
| `get_signals` — discover signals | `activate_signal` — activate signals |
| `get_adcp_capabilities` — discover features | `sync_catalogs` — upload catalogs |
The pattern: **discovery is stateless, execution is stateful**. You can browse a seller's inventory without an account. You need an account to buy.
## Related documentation
* **[Accounts and agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents)** — Account identity, billing models, and `sync_accounts` details
* **[Async operations](/dist/docs/3.2.8/building/by-layer/L3/async-operations)** — How async approval workflows work
* **[Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks)** — Receiving notifications when async operations complete
* **[Catalogs](/dist/docs/3.2.8/creative/catalogs)** — Typed data feeds that provide the items publishers render in ads
# Accounts and agents
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents
AdCP accounts and agents: the four entities in every transaction (brand, account, operator, agent), account-id namespaces, buyer-declared accounts, and billing configuration.
AdCP distinguishes four entities in every billable operation:
| Entity | Question | How identified |
| - | - | - |
| **Brand** | Whose products are advertised? | Brand reference: `domain` + optional `brand_id` and commercial-identity `countries[]` ([brand.json](/dist/docs/3.2.8/brand-protocol/brand-json)) |
| **Account** | Who gets billed? What rates apply? | [Account reference](#account-references) |
| **Operator** | Who operates on the brand's behalf? | Domain (e.g., `pinnacle-media.com`) |
| **Agent** | What software is placing the buy? | Authenticated session |
**Brand** — The advertiser whose products or services are promoted. Identified by a `brand` reference (`domain` + optional `brand_id` and ISO country `countries[]`), resolved via `/.well-known/brand.json`. Countries distinguish commercial advertiser identities without becoming delivery targeting.
**Account** — A billing relationship between a buyer and seller. Determines rate card, payment terms, credit limit, operational timezone, and who receives invoices. Every billable operation requires an account reference — a seller/storefront-assigned `account_id` when the seller or upstream platform owns the canonical account namespace, or an advertiser natural key (`brand`, `operator`, optional `operator_unit`, fixed `currency`, buyer-selected `timezone`, `sandbox`) for buyer-declared accounts.
**Operator** — The entity driving buys — an agency trading desk, the brand's internal team, or another entity acting on behalf of the advertiser. Identified by domain and verifiable via [authorized operators](#authorized-operators) in `brand.json`.
**Agent** — The software placing buys and managing campaigns. Authenticates with the seller and may operate on behalf of multiple operators and brands.
See [Accounts Protocol overview](/dist/docs/3.2.8/accounts/overview) for the full commercial model and [sync_accounts](/dist/docs/3.2.8/accounts/tasks/sync_accounts) for the task reference.
## What sellers declare
Sellers configure the `account` section of [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities#account):
**1. Which billing models do you support?** (`supported_billing`)
The buyer must pass one of these values as `billing` in every `sync_accounts` entry. The seller either accepts or rejects.
| Billing | Who is invoiced | Use case |
| - | - | - |
| `operator` | Operator (agency or brand buying direct) | Operator buying on their own terms |
| `agent` | Agent | Agent consolidates billing across brands |
| `advertiser` | Advertiser directly | Operator places orders but advertiser pays (common on social platforms and in DACH B2B workflows) |
This is an account-level invoiced-party choice. It does not select a payment rail, clearing intermediary, or settlement route for an individual media buy; AdCP payment and settlement remain out of protocol.
**2. Which account currency models do you support?** (`supported_account_currency_modes`)
Sellers implementing AdCP 3.2 advertiser-account provisioning advertise one or both values. The field remains optional in the shared 3.x wire schema so existing 3.0 and 3.1 responses continue to validate; absence means the older seller's currency model is not discoverable and does not imply support for either mode.
| Mode | Provisioning behavior |
| - | - |
| `fixed` | Include one immutable ISO 4217 `currency`; it participates in the advertiser account natural key. |
| `per_media_buy` | Omit account `currency`; select currency on each proposal or media buy. |
When both are present, the buyer selects the model by including or omitting `currency`.
**3. Do you require operator-level auth?** (`require_operator_auth`)
This field determines the authentication model and the account reference shape:
When `false` (default) — **buyer-declared accounts**: the seller trusts the agent. The agent authenticates once and declares accounts via `sync_accounts`. On subsequent requests, the buyer passes the natural key (`brand` + `operator`) and the seller resolves internally. See [Seller walkthrough: buyer-declared accounts](#seller-walkthrough-buyer-declared-accounts) for how the seller identifies the agent and where each field comes from.
When `true` — **account-id namespaces**: each operator must authenticate with the seller directly. The agent obtains a credential per operator — via OAuth using the seller's `authorization_endpoint`, or via API key out-of-band. Subsequent requests pass a seller-assigned `account_id`. If a credential may access more than one account, the seller MUST expose `list_accounts` and the buyer MUST resolve an explicit account before the first account-scoped request. If a credential is bound to exactly one account, the seller SHOULD expose `list_accounts` returning that singleton; a seller MAY omit `list_accounts` only when it supplies the same explicit account ID through another declared path or out-of-band onboarding.
For sandbox, the path follows the account namespace: account-id namespaces use pre-existing test accounts from `list_accounts` or out-of-band setup; buyer-declared accounts use `sync_accounts` with `sandbox: true` and reference by natural key.
Sellers can also declare `account_financials: true` to expose account-level financial data (spend, credit, invoices) via [`get_account_financials`](/dist/docs/3.2.8/accounts/tasks/get_account_financials). This only applies to operator-billed accounts.
**Example capabilities:**
```json theme={null}
{
"account": {
"require_operator_auth": false,
"supported_billing": ["operator", "agent"],
"supported_account_currency_modes": ["fixed", "per_media_buy"]
}
}
```
Sellers that support `advertiser` billing declare it explicitly:
```json theme={null}
{
"account": {
"require_operator_auth": false,
"supported_billing": ["operator", "agent", "advertiser"],
"supported_account_currency_modes": ["fixed", "per_media_buy"]
}
}
```
These fields combine into common patterns.
## Seller patterns
Which kind of platform are you buying from? That determines the account setup pattern.
| Platform type | Account pattern | `require_operator_auth` | `supported_billing` |
| - | - | - | - |
| [Social / walled garden](#social-platform) | Upstream-managed account-id namespace | `true` | `["operator"]` |
| [Direct publisher](#direct-publisher) | Buyer-declared accounts | `false` | `["operator"]` or `["operator", "agent"]` |
| [DSP / programmatic](#dsp--programmatic) | Buyer-declared accounts | `false` | `["agent"]` |
### Social platform
The operator already has an account on the platform — an ad account, a business manager, a self-serve dashboard. The upstream platform owns the canonical account namespace accessible to that credential. The agent obtains the operator's credentials (via OAuth or API key), opens a per-operator session, resolves an explicit account through `list_accounts`, and uses the returned `account_id` values. The platform bills the operator directly.
**Capabilities:**
```json theme={null}
{
"account": {
"require_operator_auth": true,
"supported_billing": ["operator"],
"supported_account_currency_modes": ["fixed"],
"authorization_endpoint": "https://seller.example.com/oauth/authorize"
}
}
```
**Buyer workflow:**
1. Call `get_adcp_capabilities` — see `require_operator_auth: true` and `authorization_endpoint`
2. For each operator:
a. Obtain operator's credential (OAuth via `authorization_endpoint`, or API key out-of-band)
b. Open a new session with the operator's credential
c. Call `list_accounts` to discover accounts visible to that credential
3. Human or policy selects the correct account from the list
4. Call `get_products` / `create_media_buy` with the operator's session and `{ "account_id": "..." }`
**list_accounts response:**
```json theme={null}
{
"accounts": [{
"account_id": "acc_spark_social_001",
"name": "Spark paid social",
"brand": { "domain": "nova-brands.com", "brand_id": "spark" },
"operator": "pinnacle-media.com",
"status": "active",
"billing": "operator",
"account_scope": "operator_brand"
}]
}
```
Subsequent calls use the discovered ID:
```json theme={null}
{
"account": { "account_id": "acc_spark_social_001" }
}
```
**Key point:** The operator's credential — not the agent's — authorizes all calls in that session. The buyer does not declare or create accounts through AdCP in the 3.0.x account-id model; `list_accounts` mirrors the upstream namespace. If the seller exposes `sync_accounts`, it is only for settings updates against an existing `account_id`, not natural-key provisioning, unless a future explicit capability declares account-id provisioning.
### Direct publisher
The publisher trusts the agent but bills the operator directly. The agent sets up accounts via `sync_accounts` — no per-operator login needed. Accounts may require human approval (credit checks, legal agreements) before becoming active.
Many publishers also accept agent billing (`supported_billing: ["operator", "agent"]`). The buyer chooses per account — operators with a direct relationship use `billing: "operator"`, everything else uses `billing: "agent"`. If the seller doesn't support the requested billing for a particular account, it rejects the request and the agent re-submits with a different model.
**Capabilities:**
```json theme={null}
{
"account": {
"supported_billing": ["operator", "agent"],
"supported_account_currency_modes": ["fixed", "per_media_buy"]
}
}
```
**Buyer workflow:**
1. Call `get_adcp_capabilities` — see `require_operator_auth` absent (defaults to `false`)
2. Call `sync_accounts` for each brand/operator pair
3. Wait for account status `active` — may require human to complete credit/legal at `setup.url`
4. Call `get_products` with `account` reference
5. Call `create_media_buy` with `account` reference
**sync_accounts request — brand buying direct:**
```json theme={null}
{
"accounts": [{
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"billing": "operator"
}]
}
```
Seller acknowledges the request but requires setup before provisioning:
```json theme={null}
{
"accounts": [{
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"action": "created",
"status": "pending_approval",
"billing": "operator",
"account_scope": "brand",
"setup": {
"url": "https://seller.example.com/advertiser-onboard",
"message": "Complete advertiser registration and credit application"
}
}]
}
```
The seller has acknowledged the relationship `(brand: "acme-corp.com", operator: "acme-corp.com", billing: "operator")`, but the account is pending review before it becomes active. A human at Acme Corp completes the setup at the URL. To check progress, the agent either:
* Re-calls `sync_accounts` with the same natural key — the seller returns the updated status
* Receives a webhook notification if `push_notification_config` was provided in the request
**Key point:** `pending_approval` is the normal path. Every buyer needs a direct relationship with the seller.
**Billing rejection — operator billing not available:**
The seller supports operator billing in general, but may not support it for every operator. Here, the agent requests operator billing for an operator without a direct relationship:
```json theme={null}
{
"accounts": [{
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"billing": "operator"
}]
}
```
Seller rejects the request because this operator has no direct billing relationship:
```json theme={null}
{
"accounts": [{
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"action": "failed",
"status": "rejected",
"errors": [{
"code": "BILLING_NOT_SUPPORTED",
"message": "Operator billing is not available for this account. Re-submit with billing: \"agent\"."
}]
}]
}
```
The agent re-submits with `billing: "agent"` or informs the buyer that operator billing is not available with this seller. Billing is never silently remapped.
### DSP / programmatic
All billing flows through the agent. The agent has a standing relationship with the platform and consolidates billing across all brands and operators. Accounts are created instantly — no human approval needed.
**Capabilities:**
```json theme={null}
{
"account": {
"supported_billing": ["agent"],
"supported_account_currency_modes": ["per_media_buy"]
}
}
```
**Buyer workflow:**
1. Call `get_adcp_capabilities` — see `supported_billing: ["agent"]`
2. Call `sync_accounts` for each brand/operator pair with `billing: "agent"`
3. Accounts are active immediately — no human approval needed
4. Call `get_products` / `create_media_buy` with `account` reference
**sync_accounts request:**
```json theme={null}
{
"accounts": [{
"brand": { "domain": "nova-brands.com", "brand_id": "spark" },
"operator": "pinnacle-media.com",
"billing": "agent"
}]
}
```
Account active immediately:
```json theme={null}
{
"accounts": [{
"brand": { "domain": "nova-brands.com", "brand_id": "spark" },
"operator": "pinnacle-media.com",
"action": "created",
"status": "active",
"billing": "agent",
"account_scope": "operator_brand"
}]
}
```
**Key point:** The agent receives a single consolidated invoice. Per-brand accounts give reporting granularity but billing is centralized.
## Authorized operators
Brands declare who can represent them in `/.well-known/brand.json` via the `authorized_operators` field. Sellers SHOULD verify operators against this when processing `sync_accounts`.
```json theme={null}
{
"house": {
"domain": "nova-brands.com",
"name": "Nova Brands"
},
"brands": [
{ "id": "spark", "names": [{"en": "Spark"}] },
{ "id": "glow", "names": [{"en": "Glow"}] }
],
"authorized_operators": [
{
"domain": "pinnacle-media.com",
"brands": ["spark", "glow"],
"countries": ["US", "GB", "DE"]
},
{
"domain": "summit-agency.jp",
"brands": ["spark"],
"countries": ["JP"]
},
{
"domain": "nova-brands.com",
"brands": ["*"]
}
]
}
```
| Field | Required | Description |
| - | - | - |
| `domain` | Yes | Operator's domain |
| `brands` | Yes | Brand IDs this operator can represent. `["*"]` means all brands. |
| `countries` | No | ISO 3166-1 alpha-2 country codes. Omit for global authorization. |
### Verification flow
1. Resolve `{brand.domain}/.well-known/brand.json`
2. Check `authorized_operators` for matching `domain` with the brand in `brands`
3. If found → proceed (account may still need credit/legal approval)
4. If not found → reject the account (`action: "failed"`) or return `pending_approval` for manual review
A `brand.json` listing is sufficient, not necessary. Finding the operator lets the seller provision without further review. If the operator isn't listed, the request alone does not authorize it: the seller either rejects the account or holds it in `pending_approval` until its own review confirms the operator out of band. Either way, the brand-operator check below passes only through the listing or that review.
**Self-authorization is implicit.** When the `operator` domain matches the brand's domain, the brand is operating directly — no listing in `authorized_operators` is needed.
`authorized_operators` models the interface between the brand and whoever operates on its behalf. It does not model internal agency hierarchies.
## Buyer-agent identity
`authorized_operators` tells the seller whether an operator is allowed to represent a brand. It doesn't tell the seller who the *agent* placing the call is, or what commercial relationship is on file with that agent. Those are different questions, and the seller checks both before provisioning.
Two layers run on every `sync_accounts` request:
| Layer | Question | Where it lives |
| - | - | - |
| **Agent identity** | Which buyer agent issued this request? | The seller's onboarding record, looked up by signed-request `agent_url` (when [request signing](/dist/docs/3.2.8/building/by-layer/L1/security#signed-requests-transport-layer) is in use) or by the bearer / API-key / OAuth credential the agent presented. Signature or credential establishes identity; authorization is a separate check. |
| **Brand-operator authorization** | Is the operator named in the request authorized to act for the brand? | `brand.json` `authorized_operators` (above). Verified whether the request is signed or not. |
Both layers MUST pass before the account becomes active. A signed request from an onboarded agent for an unlisted operator gets rejected or held for review on the brand-operator check; a request from an unrecognized agent for an authorized operator gets rejected on the identity check. Sellers that advertise [`request_signing.required_for`](/dist/docs/3.2.8/building/by-layer/L1/security#transport-scope) on `sync_accounts` reject unsigned traffic at the identity layer; sellers that don't advertise it MAY still require an established credential mapping before agent-billable values are accepted.
The brand-operator check runs against the seller's cached `brand.json` per [Operator revocation and caching](#operator-revocation-and-caching) — revocation is eventual. Sellers performing high-value or first-time-on-this-brand provisioning SHOULD bypass the cache to close the TOCTOU window.
**SDK naming for the brand-operator authorization Protocol.** SDKs that surface a typed Protocol for the brand-operator check (for adopters to plug their own resolver into) SHOULD name it after the file consulted: `BrandAuthorizationResolver` (or equivalent in idiomatic casing). The file is `brand.json/authorized_operators` — the brand-side declaration of who may represent the brand. SDKs SHOULD NOT name this Protocol after `adagents.json`, which is publisher-side / data-provider-side and models a different relationship (which sales agents may sell that publisher's inventory). Naming the buyer-side resolver `AdagentsResolver` confuses the two surfaces and locks adopters into the wrong mental model. This is a spec-side recommendation; SDK conventions track upstream.
**The agent's commercial state is offline.** Whether a buyer agent is *passthrough-only* (no payments relationship — only the operator can be invoiced) or *agent-billable* (the agent can be invoiced directly) is recorded in the seller's onboarding system, the same way operator account creation is. Provisioning that record — contract, KYC, payment terms, billing entity capture — is out of scope for AdCP. What's in scope is two on-wire consequences:
1. **Runtime billing gate.** A passthrough-only agent that submits `billing: "agent"` or `billing: "advertiser"` is rejected with `BILLING_NOT_PERMITTED_FOR_AGENT` and an `error.details.suggested_billing` of `operator`. See [Billing and Account Setup](/dist/docs/3.2.8/building/by-layer/L3/error-handling#billing-and-account-setup) for the recovery contract.
2. **Per-agent defaults.** Sellers MAY pre-fill `payment_terms`, `billing_entity`, rate-card linkage, and credit limit from the buyer agent's onboarding record when provisioning new accounts under that agent. Per-account values on the `sync_accounts` request always take precedence over per-agent defaults — the buyer can override per row. The per-agent layer is a recommended implementation pattern (it mirrors how SSPs maintain `buyer_id` / `seat_id` rows for OpenRTB DSPs); smaller publishers MAY collapse to seller-wide defaults until they have receivables ops that distinguish per-agent terms.
## Account references
Every account-scoped operation accepts an `account` object instead of a flat `account_id` string. The seller's `require_operator_auth` capability determines the auth model and reference shape; tool exposure distinguishes upstream-managed `account_id` namespaces from seller-defined IDs supplied out-of-band.
> [!NOTE]
>
> Sellers that support caller-scope introspection attach an optional `authorization` object to each per-account entry in [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) responses — listing the tasks and request fields this caller is allowed to use on the account, plus any standard named scope (e.g., `attestation_verifier`). See [Caller authorization](/dist/docs/3.2.8/accounts/overview#caller-authorization) for the full shape and semantics.
### Account-id namespaces (`require_operator_auth: true`)
Accounts are managed outside of AdCP. The advertiser creates an account on the seller's platform, grants the operator permission to manage it, and the buyer passes a seller-assigned `account_id`. The agent is not involved in account creation or billing setup — those are handled between the advertiser, operator, and seller directly.
**Typical sellers:** Social platforms, self-serve ad platforms — anywhere the advertiser already has an account.
**Upstream-managed workflow:**
1. Advertiser creates an account on the seller's platform (out-of-band)
2. Advertiser grants the operator permission to manage the account (out-of-band)
3. Agent calls `list_accounts` to discover available accounts
4. Human selects the correct account from the list
5. Agent passes `{ "account_id": "acc_acme_001" }` on every request (`get_products`, `create_media_buy`, etc.)
`list_accounts` is mandatory when the authenticated credential may access more than one account because the upstream owns the namespace. When the credential is bound to exactly one account, sellers SHOULD still expose `list_accounts` returning that singleton so SDKs can auto-select it and send explicit `{ "account_id": "..." }` on required-account calls. `sync_accounts` provisioning is out of scope for account-id namespaces in 3.0.x unless a future explicit capability declares it; if `sync_accounts` is exposed today, it is settings-update mode for an existing `account_id`.
**Seller-defined workflow:**
Some sellers use `account_id` without exposing an account discovery surface. In that pattern, the seller gives the buyer an account ID during onboarding or configuration, and the buyer passes that ID on account-scoped calls. Absence of `list_accounts` means there is no protocol namespace to discover; it does not mean the buyer should try to provision by natural key.
### Buyer-declared accounts (`require_operator_auth: false`)
The agent manages the buying relationship. It calls `sync_accounts` to tell the seller who's advertising, who's operating on the brand's behalf, and who's paying. The seller provisions accounts and responds with status — the account IDs are a byproduct of the declaration, not something the buyer needs to know upfront.
Buyer-declared-account sellers SHOULD also expose `list_accounts` as the recovery read for stateless buyers. Replaying `sync_accounts` is not a cold-start recovery mechanism when the buyer has lost the advertiser natural keys required to compose that replay. `list_accounts` returns those acknowledged natural-key fields so they round-trip into later calls; it does not make the seller-issued `account_id` mandatory.
**Typical sellers:** Traditional publishers, retail media networks, DSPs — anywhere the buying relationship is established programmatically.
`sync_accounts` is the declaration tool. Each entry is a set of flags that tells the seller what the buyer needs:
| Flag | What it tells the seller |
| - | - |
| `brand` (`domain` + optional `brand_id`/`countries[]`) | Which commercial advertiser entity is advertising; countries do not target delivery |
| `operator` | Who operates on the brand's behalf (agency, trading desk, or the brand itself) |
| `operator_unit` | Optional operator-owned business unit, seat, or platform account; stable `id` plus mutable display `name` |
| `currency` | Optional immutable account currency when the seller's advertiser object is currency-bound |
| `billing` | Who gets the invoice — `operator`, `agent`, or `advertiser` |
| `billing_entity` | Structured business entity details for the party responsible for payment — legal name, VAT ID, tax ID, address, contacts, and bank details. Used for formal B2B invoicing. Bank details are write-only (never echoed in responses). |
| `payment_terms` | Payment terms for this account (`net_15`, `net_30`, `net_45`, `net_60`, `net_90`, `prepay`). The seller must accept these terms or reject the account — terms are never silently remapped. |
| `sandbox` | Whether this is a sandbox (test) account — no real spend. Only used with buyer-declared accounts; account-id namespace sandboxes are pre-existing and discovered through `list_accounts` or supplied out-of-band. |
Every combination of flags that might require the seller to do something different — bill a different entity, set up a different rate card, create a sandbox — is a distinct declaration.
### Billing entity and invoice recipient
For markets that require structured invoicing data (e.g., EU B2B transactions requiring VAT IDs), the `billing_entity` on an account provides the default business entity details for whoever `billing` points to. This includes legal name, tax identifiers, postal address, billing contact, and bank details.
On individual media buys, an `invoice_recipient` can override the account default — useful when a specific campaign should be billed to a different party. When `invoice_recipient` differs from the account default and the account has `governance_agents`, the seller MUST include it in the `check_governance` request so the governance agent can approve or reject the billing redirect.
**Workflow:**
1. Agent calls `sync_accounts` with one or more declarations
2. Seller provisions or links accounts for each, responds with status:
* `active` — ready to use
* `pending_approval` — seller reviewing (human may need to visit `setup.url`)
* `rejected` — seller declined the request
3. For subsequent requests, pass the account reference:
* **Buyer-declared accounts** (`require_operator_auth: false`): pass the natural key `{ "brand": { "domain": "acme-corp.com" }, "operator": "pinnacle-media.com" }`
* **Account-id namespaces** (`require_operator_auth: true`): pass `{ "account_id": "acc_acme_001" }` (discover via `list_accounts` for upstream-managed namespaces, or receive out-of-band for seller-defined namespaces)
* **Sandbox (buyer-declared)**: pass the natural key with `sandbox: true` (declared via `sync_accounts`)
* **Sandbox (account-id namespace)**: pass `{ "account_id": "test_acc_001" }` (pre-existing test account, discovered via `list_accounts` or supplied out-of-band)
4. When anything changes (billing model, new brand, new operator), call `sync_accounts` again
5. After a cold start, call `list_accounts` to recover previously acknowledged relationships when the seller exposes the recommended read surface
The agent may be directly responsible for billing when `billing` is `"agent"`. When `billing` is `"operator"` or `"advertiser"`, the agent facilitates but is not the invoiced party. The seller may require human approval before activating accounts.
### Natural key semantics
The tuple `(brand, operator, operator_unit.id, currency, timezone, sandbox)` identifies the advertiser object in the seller system. The nested `brand` carries `domain`, optional `brand_id`, and optional ISO country `countries[]`; these countries qualify commercial identity and never target delivery. `operator_unit` identifies the operator's own business unit, agency seat, or buying-platform account. Its stable `id` participates in identity, while its optional `name` is display metadata and may change without creating a new account. `currency` participates only when the seller's advertiser object is locked to one currency. `timezone` participates only when the seller requires the buyer to select an immutable account timezone during provisioning. Omit either qualifier when its capability mode does not apply.
This separates two account namespaces that must not be conflated: `operator_unit.id` is assigned by the buyer-side operator, while `account_id` is assigned by the AdCP seller/storefront. Both may be opaque values, but they identify different objects and are not interchangeable.
See [sync_accounts task reference](/dist/docs/3.2.8/accounts/tasks/sync_accounts) for the full request/response schema.
### Account status
| Status | Meaning | Next step |
| - | - | - |
| `active` | Ready to use | Place buys on this account |
| `pending_approval` | Seller reviewing | Human may need to visit `setup.url`. Poll `list_accounts` for updates. |
| `rejected` | Seller declined the request | Review rejection reason, adjust and re-sync, or contact seller |
| `payment_required` | Credit limit reached | Add funds or route spend to other accounts |
| `suspended` | Was active, now paused | Contact seller |
| `closed` | Was active, now terminated | — |
### Account scope
The agent requests accounts by natural key — `(brand, operator)`. The seller decides what granularity to assign. The `account_scope` field in the response tells the agent how the seller resolved the request:
| Scope | Meaning | Example |
| - | - | - |
| `operator` | One account for all brands under this operator | Agent sends (Pinnacle Media, Acme) and (Pinnacle Media, Nova) — seller maps both to the Pinnacle Media account |
| `brand` | One account for this brand regardless of operator | Agent sends (Acme, Pinnacle Media) and (Acme, Summit Agency) — seller maps both to the Acme account |
| `operator_brand` | Dedicated account for this operator+brand pair | Agent sends (Pinnacle Media, Acme) — seller creates a specific Acme-via-Pinnacle account |
| `agent` | Agent-scoped account with no brand- or operator-specific split | Agent sends any brand — seller maps the request to the standing agent-scoped account |
The agent does not choose the scope — the seller assigns it based on its own account policy. An agent requesting `(brand: {domain: "acme-corp.com"}, operator: "pinnacle-media.com")` might receive an operator-scoped account, a brand-scoped account, or a dedicated operator_brand account depending on the seller.
When multiple natural keys resolve to the same scope, the `account_scope` explains why.
For buyer-declared accounts (`require_operator_auth: false`), use the complete natural key (`brand` + `operator` + optional `operator_unit`, fixed `currency`, buyer-selected `timezone`, and `sandbox`) on subsequent requests. A seller may also return an `account_id` from `sync_accounts` as its internal handle, but the seller MUST continue accepting the natural-key `AccountRef` for every account provisioned this way and MUST return its natural-key fields from `list_accounts`. For account-id namespaces (`require_operator_auth: true`), discover seller/storefront account IDs via `list_accounts` for upstream-managed namespaces, or receive them out-of-band for seller-defined namespaces — including sandbox test accounts.
## Seller walkthrough: buyer-declared accounts
This walkthrough is for a seller that declares `require_operator_auth: false` (or omits it). It covers how the seller identifies the calling agent, where the account's operator comes from, and which error applies when.
Three identities show up on every request. Keep them apart:
| Identity | Where the seller gets it | Example |
| - | - | - |
| **Calling agent** | The transport: a verified request signature, or a credential the seller issued at onboarding | `https://agent.orbit-buying.example/mcp` |
| **Agent's operator** | The brand.json that lists the agent in `agents[]`, meaning whoever runs the agent | `orbit-buying.example` |
| **Account operator** | The request payload: `accounts[].operator` on `sync_accounts`, `account.operator` on later calls | `pinnacle-media.com` |
### 1. Onboard the agent
Before the agent's first account-scoped call, the seller records the agent in its onboarding system: the agent's canonical URL, how it authenticates, and its commercial state (see [Buyer-agent identity](#buyer-agent-identity)).
* **Signed requests.** The buyer gives the seller its agent URL during onboarding. From that URL, the seller runs [`brand_json_url` discovery](/dist/docs/3.2.8/building/by-layer/L1/security#discovering-an-agents-signing-keys-via-brand_json_url): capabilities, then `identity.brand_json_url`, then the brand.json `agents[]` entry, then `jwks_uri`. It indexes each `kid` in that JWKS against the agent's canonical URL. Rebuild the index whenever you refresh an agent's JWKS or brand.json, so a rotated `kid` still resolves and a delisted agent drops out. That cache is bounded by the revocation polling interval.
* **Seller-issued credential.** The seller issues an API key or OAuth client and maps it to the agent in the onboarding record. Before mapping a credential to an agent URL, confirm the counterparty controls that agent, for example with a signed onboarding request from it.
> [!NOTE]
>
> For now, the agent URL has to come from outside the request: onboarding, or a registry cache the seller trusts. A signed request carries only a `keyid`. Each signer picks its own `keyid` values, and nothing namespaces them, so a seller can't map a `keyid` it has never seen to an agent URL. AdCP 3.2 doesn't put the signer's agent URL on the wire. A discoverable signer agent URL is under discussion in [#7817](https://github.com/adcontextprotocol/adcp/issues/7817).
### 2. Identify the caller on each request
* **Signed request:** the verifier resolves the `keyid` against the agents it has onboarded. The `keyid` has to resolve under exactly one canonical `agents[].url` ([verifier checklist](/dist/docs/3.2.8/building/by-layer/L1/security#verifier-checklist-requests), step 7). A `keyid` that isn't in any onboarded agent's JWKS, even after the one refetch step 7 allows, fails with `request_signature_key_unknown`. A `keyid` that more than one onboarded agent publishes also fails. The verifier never picks one, and never tries each agent's keys in turn. Agents that share a JWKS can't be told apart by signature alone, so use a seller-issued credential for them. On success, the authenticated caller is the canonical agent URL. It isn't the `keyid`, the domain, or the JWKS URI ([Agent identity](/dist/docs/3.2.8/building/by-layer/L1/security#agent-identity)).
* **Unsigned request with a seller-issued credential:** the seller looks up the credential in its onboarding record, and the mapped agent is the caller.
Nothing in the request body identifies the caller.
### 3. Read the account operator from the request
The authenticated caller is the agent. The operator belongs to the account the agent names in the payload. One agent often acts for many operators. Here one buying agent, with one signing identity, declares accounts for two agencies:
```json theme={null}
{
"idempotency_key": "sync-7f3c2a90-4d1e-4b8a-9c55-2e61f0a7b3d4",
"accounts": [
{ "brand": { "domain": "nova-brands.com", "brand_id": "spark" }, "operator": "pinnacle-media.com", "billing": "agent" },
{ "brand": { "domain": "acme-corp.com" }, "operator": "summit-agency.jp", "billing": "agent" }
]
}
```
The seller takes `operator` from each entry, and later from `account.operator`. It doesn't substitute a value from the transport, such as the agent URL, the agent's brand.json domain, or an `operator` field an SDK attaches to the authenticated principal. If it did, both accounts would be attributed to `orbit-buying.example` instead of their agencies, and invoices would go to the wrong party. Two agencies buying the same brand through this agent would also share one account and see each other's buys and reporting.
Authentication still limits what the payload can reach. On calls after provisioning, each account the agent references has to be in that agent's authorized set ([Agent and account isolation](/dist/docs/3.2.8/building/by-layer/L1/security#agent-and-account-isolation)). This matches [Tenant resolution](/dist/docs/3.2.8/building/by-layer/L2/authentication#tenant-resolution): the authenticated principal decides which accounts are reachable, and the account reference only selects one. For each `sync_accounts` entry the seller also runs the [brand-operator check](#authorized-operators) and checks the agent's commercial state against the requested `billing`.
`sync_accounts` is how an account enters the calling agent's authorized set. The brand-operator check shows that the operator may represent the brand. It doesn't show that this agent acts for that operator. If the seller maps a declaration onto an account another agent already uses, the caller gets every object bound to that account. Decide that deliberately before joining an existing account, for example by keeping accounts per agent or confirming out of band.
### 4. Discover products with the natural key
Once `sync_accounts` returns `status: "active"`, the agent sends the same natural key on `get_products`:
```json theme={null}
{
"buying_mode": "brief",
"brief": "Q3 awareness for Spark in the US",
"account": {
"brand": { "domain": "nova-brands.com", "brand_id": "spark" },
"operator": "pinnacle-media.com"
}
}
```
When `account.required_for_products` is `true`, `get_products` needs this account. Otherwise the account is optional and selects account-specific pricing. Before `sync_accounts` succeeds, leave `account` off and send top-level `brand`: a natural key the seller hasn't provisioned returns `ACCOUNT_NOT_FOUND` unless the seller provisions lazily, even on `get_products` ([Account references before provisioning](/dist/docs/3.2.8/accounts/overview#account-references-before-provisioning)). A seller can instead provision lazily on the first account-scoped request, but only when billing and other required settings are clear from its capabilities or onboarding defaults. Such a seller still has to accept the natural key and expose `list_accounts`. If it needs buyer input before the account is usable, it has to expose `sync_accounts` (see [`require_operator_auth`](/dist/docs/3.2.8/protocol/get_adcp_capabilities#account)).
### 5. Which error applies when
Authentication resolves first. Signature failures are transport errors, returned as `401` with `WWW-Authenticate: Signature error=""` ([transport error taxonomy](/dist/docs/3.2.8/building/by-layer/L1/security#transport-error-taxonomy)). Everything after that is an AdCP error: task-level `errors[]`, or on `sync_accounts` the per-entry `accounts[].errors` with `action: "failed"`.
| Request | Result |
| - | - |
| `Signature` or `Signature-Input` present without the other, or malformed | `request_signature_header_malformed`. The seller doesn't fall back to other credentials. |
| Signed, and fails the verifier checklist (unknown `keyid`, bad window, bad digest, and so on) | The checklist's code, such as `request_signature_key_unknown` (also `request_target_uri_malformed` or `request_body_malformed`). The seller doesn't fall back to other credentials. Exception: for an operation in `warn_for` (or a method in `protocol_methods_warn_for`), a well-formed signature that fails is logged, establishes no signer identity, and the request continues only if another credential authenticates it. |
| Unsigned. No credential the seller accepts for this operation. The resolved operation (the MCP tool name, or the A2A invocation `skill`; see [Operation resolution over A2A](/dist/docs/3.2.8/building/by-layer/L1/security#operation-resolution-over-a2a)) is in `required_for`, or its JSON-RPC method is in `protocol_methods_required_for` | `request_signature_required`. This applies even if an unrecognized bearer token was sent. |
| Unsigned, the seller supports request signing, and the payload carries a webhook `authentication` block (`accounts[].notification_configs[].authentication`, `push_notification_config.authentication`) | `request_signature_required`, even with a valid credential ([webhook callbacks](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-callbacks)) |
| Unsigned, with a credential the seller accepts for this operation | Authenticated through that credential. This holds for `required_for` operations too, unless the payload carries a webhook `authentication` block (previous row), or the seller configured that authenticator to reject the operation ([composition with fallback authenticators](/dist/docs/3.2.8/building/by-layer/L1/security#composition-with-fallback-authenticators)). |
| Unsigned, the operation needs authentication and doesn't require a signature, and no credentials | `AUTH_MISSING` |
| Unsigned, the operation doesn't require a signature, and the credential was presented but rejected | `AUTH_INVALID` |
| Authenticated agent is suspended or blocked | `AGENT_SUSPENDED` or `AGENT_BLOCKED` |
| Requested `billing` not available | `BILLING_NOT_SUPPORTED`, or `BILLING_NOT_PERMITTED_FOR_AGENT` for a passthrough-only agent |
| Natural key doesn't resolve (not yet provisioned, and the seller doesn't provision lazily), or resolves to an account outside the agent's authorized set | `ACCOUNT_NOT_FOUND`, including when `account` is optional on the task. The response is the same in both cases, so it doesn't reveal whether the account exists. |
| Former natural key retired by an account rekey, and the caller is authorized for the current account | `ACCOUNT_MOVED`, with `details.current_account` |
| Natural key matches more than one account in the agent's authorized set | `ACCOUNT_AMBIGUOUS` |
| An account in the authorized set is found, but its state blocks the call | `ACCOUNT_SETUP_REQUIRED`, `ACCOUNT_SUSPENDED`, or `ACCOUNT_PAYMENT_REQUIRED` ([Error codes](#error-codes)) |
Resolve and disambiguate only within the agent's authorized set. To the caller, an account outside that set doesn't exist.
## Error codes
| Code | When returned | Resolution |
| - | - | - |
| `ACCOUNT_REQUIRED` | Multiple accounts; seller can't determine which | Pass `account_id` in the account reference |
| `ACCOUNT_NOT_FOUND` | Account reference doesn't resolve: an `account_id` that doesn't exist, a natural key not yet provisioned, or an account the agent can't access | Natural key: provision through `sync_accounts`, or omit `account` for public discovery. `account_id`: verify through `list_accounts` |
| `ACCOUNT_SETUP_REQUIRED` | Natural key resolved but account needs setup | Check `details.setup` for URL/message |
| `ACCOUNT_AMBIGUOUS` | Natural key resolves to multiple accounts | Pass `account_id` or more specific natural key |
| `ACCOUNT_PAYMENT_REQUIRED` | Credit limit reached or funds depleted | Add funds, route to another account |
| `ACCOUNT_SUSPENDED` | Account not in good standing | Contact seller |
| `BRAND_REQUIRED` | Billable operation without brand reference | Include `brand` in request |
When the seller returns `ACCOUNT_REQUIRED`, it includes the available accounts:
```json theme={null}
{
"errors": [{
"code": "ACCOUNT_REQUIRED",
"message": "Multiple accounts available. Please specify account_id in the account reference.",
"details": {
"available_accounts": [
{ "account_id": "acc_acme_001", "name": "Acme Corp" },
{ "account_id": "acc_pinnacle", "name": "Pinnacle Media" }
]
}
}]
}
```
## Design notes
### sync_accounts and seller record systems
When an agent declares `(brand: {domain: "acme-corp.com"}, operator: "pinnacle-media.com")`, the seller looks up or creates records in its own system — CRM, OMS, ad server, or billing platform.
`sync_accounts` is the buyer-side interface to the seller's record system. The seller may:
* Map the natural key to an existing account and return `status: "active"`
* Create a new record and return it immediately (`status: "active"`)
* Create a placeholder pending human review (`status: "pending_approval"`)
* Decline the request entirely (`status: "rejected"`)
`list_accounts` returns all records the seller has mapped for this agent — including pending and rejected entries. The agent uses `list_accounts` to see the full state of its portfolio with this seller, not just active accounts.
### Accounts and insertion orders
An account represents a standing relationship — who gets billed, what rates apply, what credit is available. It is not a campaign or an insertion order.
Insertion orders and campaign flights are modeled as media buys via `create_media_buy`. The account determines *billing terms*; the media buy determines *what runs and when*. A single account can have many media buys over its lifetime.
### Operator revocation and caching
If a brand removes an operator from `authorized_operators`, existing active accounts are not automatically deactivated. Revocation is eventual, not immediate — similar to how `ads.txt` changes propagate on the supply side.
Sellers SHOULD respect standard HTTP caching headers on `brand.json` and re-validate periodically. A reasonable cache TTL is 24 hours.
### Brand identity for SMBs
Domain-based identity via `/.well-known/brand.json` works for organizations of any size — it's a static JSON file that can be hosted on any web server.
For organizations that cannot host files on their domain, the `authoritative_location` field in `brand.json` allows the house domain to redirect to a hosted location:
```json theme={null}
{
"house": {
"domain": "local-bakery.com"
},
"authoritative_location": "https://registry.agenticadvertising.org/brands/local-bakery.com"
}
```
# Authentication
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L2/authentication
AdCP authentication guide: public vs authenticated operations, static credential implementation, and credential management for buyer and seller agents.
AdCP uses a tiered authentication model where capability discovery is public, catalog discovery may be public, and protected reads and mutations require authentication.
## When Authentication is Required
### Public Operations (No Authentication Required)
This operation works without credentials to bootstrap discovery:
* **`get_adcp_capabilities`** - Discover agent capabilities, portfolio, and supported features
**Rationale**: Publishers want potential buyers to discover their capabilities before establishing a business relationship.
Product and signal discovery are seller-variable. Read `media_buy.anonymous_discovery` before calling `list_products` or `get_products` in discovery mode, and read `signals.anonymous_discovery` before calling `get_signals`. `true` means the call may succeed anonymously; `false` means credentials are required; absence means unspecified legacy behavior and the caller handles `AUTH_MISSING` if an anonymous probe is rejected.
An anonymous discovery response is authoritative only for that anonymous request. It may contain:
* Partial catalog (standard products only)
* No pricing information or CPM details
* No custom product offerings
* Generic format support only
### Authenticated Operations (Credentials Required)
Every mutation and every read of private or account-scoped state requires valid credentials. Examples include:
* **`create_media_buy`** - Create advertising campaigns
* **`update_media_buy`** - Modify existing campaigns
* **`sync_creatives`** - Upload creative assets
* **`list_creatives`** - View your creative library
* **`get_media_buy_delivery`** - Monitor campaign performance and metrics
* **`provide_performance_feedback`** - Submit optimization signals
**Rationale**: These operations involve financial commitments, access to proprietary data, or modifications to active campaigns.
## Authentication Method
AdCP supports three authentication mechanisms for authenticated operations. Which one an endpoint accepts for an operation is set by its advertised security contract, including `request_signing.required_for` on `get_adcp_capabilities`. The canonical rules and the [transport migration timeline](/dist/docs/3.2.8/building/by-layer/L1/security#transport-migration-timeline) live in the implementation security reference:
| Mechanism | 3.0 and 3.1 | 3.2 | 4.0 | Notes |
| - | - | - | - | - |
| **RFC 9421 request signing** | Optional and capability-advertised. | Still optional. When signing is used, every accepted signature on a request with a body covers `content-digest`. | Required for spend-committing operations. | Asymmetric, body-bound, replay-resistant. See [RFC 9421 request signing](/dist/docs/3.2.8/building/by-layer/L1/security#request-signing). |
| **Mutual TLS (mTLS)** | Permitted for any operation | Permitted for any operation | Permitted; 4.0 still requires signatures on spend-committing operations | Transport-layer identity; recommended when the deployment already terminates mTLS at the edge. |
| **Static Authorization credentials (Bearer or Basic)** | Permitted unless the endpoint lists the operation in `request_signing.required_for` | Same as 3.0/3.1 | Not sufficient on its own for spend-committing operations | Shared-secret transport. Bearer is the canonical example; HTTP Basic is also acceptable when sent over TLS and validated on every protected request. See the [known limitation](/dist/docs/3.2.8/reference/known-limitations#authentication-and-identity). |
> [!WARNING]
>
> **Mutating-operation floor in 3.x.** Throughout 3.x, static Authorization-header credentials over TLS remain acceptable for mutating operations unless the endpoint's capability declaration lists the operation in `request_signing.required_for`. Buyers follow the live declaration rather than assuming the protocol version alone determines the mechanism. Operators handling spend commitments should ship RFC 9421 request signing before 4.0, when signing becomes required for spend-committing operations.
### Why signed requests matter for financial operations
A bearer token authenticates whoever presents it. Any party that obtains the token (a leaked log line, a compromised proxy, a captured request, a misconfigured relay) can originate spend commitments indistinguishable from the legitimate agent's, and the seller cannot tell the difference after the fact. For read and discovery operations that risk is bounded; for operations that move money it is not.
Signed requests replace possession of a string with proof of possession of a private key:
* **Proof of possession.** The signature proves the caller holds the signing key. The key never travels on the wire, so the theft surface shrinks from every system a token passes through to the signer's key storage.
* **Payload integrity.** The signature binds `@method`, `@target-uri`, `@authority`, `content-type`, and `content-digest`, so tampering with a budget figure, account reference, or target endpoint invalidates the request. TLS protects bytes in transit but not through intermediaries, relays, or logs; the signature protects the transaction end to end.
* **Replay resistance.** The ±60 s timestamp window and nonce prevent a captured request from being resubmitted as a new transaction.
* **Accountability.** Both parties can prove after the fact who originated a transaction and exactly what was requested. That audit anchor is what lowers fraud and dispute cost in financial workflows; with a shared secret, origination is unprovable once the token may have leaked.
This is why AdCP 4.0 requires signing for spend-committing operations, and why 3.x endpoints can opt in early by listing operations in `request_signing.required_for`. Key discovery, covered components, and the full verifier checklist are defined in the [implementation security reference](/dist/docs/3.2.8/building/by-layer/L1/security#request-signing); build on those (or a reference SDK) rather than hand-rolling the cryptography.
### Static Authorization credentials
```
Authorization: Bearer
Authorization: Basic
```
Bearer tokens may be:
* **Opaque tokens**: Server-validated strings mapped to agents
* **JWT tokens**: Self-contained tokens with embedded claims
HTTP Basic credentials are also a static shared-secret mechanism. They MUST be sent in the `Authorization` header over TLS, and servers MUST validate the credential on every protected request. Basic credentials are not stronger than Bearer tokens; they are accepted as the same conformance class because both carry a pre-provisioned shared secret on the transport.
Implementations MUST enforce TLS 1.2+ on all static-credential-authenticated endpoints. See the [implementation security reference](/dist/docs/3.2.8/building/by-layer/L1/security) for transport requirements.
The credential MUST be carried in the `Authorization` request header. Sellers MUST NOT require non-canonical aliases (e.g. `x-adcp-auth`, which appeared in some early MCP-only deployments) and MUST NOT advertise them as the supported header in agent cards, capability responses, or documentation. A seller MAY accept such an alias as a transitional input while it phases out an existing adopter's integration, but `Authorization: Bearer` or `Authorization: Basic` MUST also be accepted on the same endpoint. Buyer agents and SDKs SHOULD emit `Authorization: Bearer` unless a seller explicitly provisions Basic credentials; SDK examples and docstrings MUST NOT show alias headers as the canonical form.
### RFC 9421 request signing (optional in 3.x; required for spend-committing ops in 4.0)
Signed requests bind `@method`, `@target-uri`, `@authority`, `content-type`, and `content-digest` under an `Ed25519`, `ecdsa-p256-sha256`, or `rsa-pss-sha512` signature with a ±60 s timestamp window and ≥128-bit nonce. The full verifier checklist, key-discovery rules (`brand.json` → `agents[]` → `jwks_uri`), and rotation semantics are defined in the [implementation security reference](/dist/docs/3.2.8/building/by-layer/L1/security#request-signing). Capability discovery via `get_adcp_capabilities.request_signing` (`supported`, `required_for`, `covers_content_digest`) lets clients detect whether a seller verifies or requires signing before sending a mutating call. On an endpoint that advertises a 3.2 release, signatures use the 3.2 profile (RFC 8941 padded Base64 with mandatory `content-digest` coverage) regardless of the request's `adcp_version`; see [mixed-version request signing](/dist/docs/3.2.8/reference/migration/3-1-to-3-2#mixed-version-request-signing).
### mTLS
Operators terminating mTLS at the edge MAY use the peer certificate as the primary identity mechanism for AdCP operations. When mTLS is used, operators MUST pin identity to the certificate subject / SAN rather than any header field.
### JWT Token Claims
When using JWT tokens, include these standard claims:
```json theme={null}
{
"sub": "agent_123",
"exp": 1706745600,
"iat": 1706742000
}
```
Sales agents may require additional claims for authorization.
## Agents and Accounts
AdCP distinguishes between the **agent** (who is making requests) and the **account** (who gets billed):
* **Agent**: The authenticated entity making API calls (identified by the token)
* **Account**: The billing relationship determining rates and invoicing
An agent may have access to multiple accounts (e.g., an agency managing several clients). See [Accounts and Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) for details on account selection and billing attribution.
For schema definitions, see [`account.json`](https://adcontextprotocol.org/schemas/3.2.8/core/account.json).
## Tenant resolution
AdCP resolves tenant from the authenticated principal, not from request payloads. Seller agents map the authenticated identity (bearer token, Basic credential, mTLS client cert, or RFC 9421 key) to the originating buyer's account via their own authorization context. Task payloads never carry tenant identity as a substitute for authentication — when a schema requires a globally-unique resource ID (`plan_id`, `rights_id`, `standards_id`, `event_source_id`, `list_id`) rather than an `account` envelope, the seller resolves ID → tenant via the same authorization context. The authenticated principal must hold access to the referenced resource, and the resource itself carries the brand it was provisioned for; envelope identity on those calls would be redundant and, if it disagreed with the authenticated principal, a spoofing vector.
Compliance storyboards in the training agent inject envelope identity on these calls as a sandbox routing convention, because the training agent has no authenticated-principal layer of its own — see [Storyboard authoring](/dist/docs/3.2.8/contributing/storyboard-authoring). Production sellers do not require it.
## Credential placement
Credentials authenticating the **buyer principal** MUST arrive on the transport's authentication channel and MUST NOT be placed in the task payload — top-level, inside `context`, inside `ext`, or in any other nested location. The transport channel is:
* **Static credentials over HTTP** — `Authorization: Bearer ` per [RFC 6750 §2](https://www.rfc-editor.org/rfc/rfc6750#section-2), or `Authorization: Basic ` when the seller provisions HTTP Basic credentials.
* **RFC 9421 signed requests** — the `Signature` and `Signature-Input` headers per [RFC 9421 §2](https://www.rfc-editor.org/rfc/rfc9421#section-2). The signature itself is the credential; nothing in the payload authenticates the signer.
* **MCP and A2A authentication framing** — the transport's authentication descriptor (e.g., MCP's `authInfo`, A2A's `authentication.schemes`). Discovery of the authentication requirement follows [RFC 9728 §3](https://www.rfc-editor.org/rfc/rfc9728#section-3) protected-resource metadata where applicable.
* **Mutual TLS** — the peer certificate, per the mTLS row in the table above.
The rule is transport-agnostic: it applies regardless of which mechanism the seller accepts. There is no AdCP version, capability, or seller policy under which a buyer principal authenticates via a payload field. The same placement rule applies to credentials or caller-supplied trust material a request tries to pass for a downstream evaluator call: those belong on the agent-to-evaluator transport or in account provisioning, not task payloads. A seller that detects a credential- or trust-material key in the payload (e.g., `_access_token`, `api_key`, `client_secret`, `bearer`, `authorization`, `jwk`, `jwks`, or `jwks_uri` at any nesting depth) SHOULD reject the request with [`CREDENTIAL_IN_ARGS`](/dist/docs/3.2.8/building/by-layer/L3/error-handling#authentication-and-access) under AdCP 3.1; the requirement upgrades to MUST 90 days after the 3.1 publication date. The code's recovery classification is `terminal` — agents MUST NOT auto-retry, since auto-retry re-logs the credential on each attempt and is itself the prompt-injection exfiltration surface this rule closes (see [Threats specific to agentic advertising](/dist/docs/3.2.8/building/concepts/security-model#threats-specific-to-agentic-advertising)).
### Carve-outs
The following credential surfaces are **not** buyer-principal credentials and the rule above does not apply to them:
* **`push_notification_config.authentication.credentials`** ([schema](https://adcontextprotocol.org/schemas/3.2.8/core/push-notification-config.json)). This is the legacy Bearer / HMAC-SHA256 credential that the **seller** uses when calling **back** to the buyer's webhook endpoint. It authenticates the seller-as-caller against the buyer-as-receiver — orthogonal to the buyer-principal credential that authenticates the inbound AdCP request. The default 9421 webhook profile uses keys discovered via `brand.json` and crosses no shared secrets; the legacy block is a deprecated compatibility scheme removed in AdCP 4.0.
* **Onboarding-time secrets exchanged out-of-band** — initial token issuance, OAuth dynamic registration responses, dashboard-issued API keys. These travel through the AAO authorization server or the seller's onboarding flow, not as AdCP task payloads.
### Relay agents
The agency / A2A relay topology (brand → relay → seller) authenticates **under the relay's own principal**. The relay either preserves the brand agent's RFC 9421 signature verbatim (pass-through model) or re-signs under its own key (re-signing model) — both options are described in [#2324](https://github.com/adcontextprotocol/adcp/issues/2324). Neither model permits forwarding the brand's transport credential as a relay-side payload field. Brand-agent identity, when the relay is the principal of record, MUST be carried in the request body as identity context (e.g., a buyer-side identity assertion verifiable by the seller against `adagents.json` / `authorized_operator[]`) — never as a forwarded transport credential. Relays MUST NOT echo or reattach buyer credentials in any args field on outbound seller-bound requests.
## Protocol Configuration
Most MCP and A2A integrations use `Authorization: Bearer ` ([RFC 6750 §2](https://www.rfc-editor.org/rfc/rfc6750#section-2)) as the authentication header. Configure your client with:
```json theme={null}
{
"auth": {
"type": "bearer",
"token": ""
}
}
```
The client library handles adding the `Authorization: Bearer ` header to requests.
If a seller explicitly provisions HTTP Basic credentials, the same transport rule applies: send `Authorization: Basic ` on every authenticated request over HTTPS.
**Header alias policy by leg.** The two protocol legs differ in what aliases they accept beyond the standard `Authorization` header:
* **A2A** — `Authorization` only. For Bearer credentials, send `Authorization: Bearer ` and declare a `bearerAuth` `HTTPAuthSecurityScheme` in the seller's agent card (see the [A2A guide — Agent Cards](/dist/docs/3.2.8/building/by-layer/L0/a2a-guide#agent-cards)). For Basic credentials, send `Authorization: Basic ` and declare HTTP Basic. The `x-adcp-auth` custom header is not recognized on the A2A surface.
* **MCP** — `Authorization` is primary for Bearer and Basic credentials. `x-adcp-auth` is accepted as a back-compat Bearer alias for integrations predating adcp 4.5.0. New implementations should use the standard header on both legs.
> [!WARNING]
>
> **Sellers migrating to adcp 4.5.0.** If you previously configured `x-adcp-auth` as the A2A leg header via the `a2a_header_name` knob, verify that knob is set to the RFC 6750 default before updating your agent card to declare `bearerAuth` — buyers that have not yet migrated off the legacy header will otherwise receive HTTP 401.
## MCP Client Configuration
When using the MCP protocol, authentication is handled by the transport layer, not by adding HTTP headers manually.
### Using MCP Client Libraries
The recommended approach is to use an MCP client library:
```typescript TypeScript theme={null}
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const transport = new StreamableHTTPClientTransport(
new URL('https://test-agent.adcontextprotocol.org/sales/mcp'),
{
requestInit: {
headers: {
'Authorization': 'Bearer YOUR_TOKEN_HERE'
}
}
}
);
const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(transport);
```
```python Python theme={null}
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client(
"https://test-agent.adcontextprotocol.org/sales/mcp",
headers={"Authorization": "Bearer YOUR_TOKEN_HERE"}
) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
```
### Common Mistake: Raw HTTP Headers
A common mistake is trying to add authentication headers to raw HTTP requests:
```http theme={null}
# This won't work for MCP endpoints
GET /mcp HTTP/1.1
Authorization: Bearer YOUR_TOKEN
```
MCP uses a streaming protocol over HTTP. The authentication must be configured in the MCP client transport layer, which handles the protocol negotiation and message framing.
### Troubleshooting Authentication
If you're getting "authentication required" errors:
1. **Verify you're using an MCP client library** - not making raw HTTP calls
2. **Check the token format** - should be passed to the transport configuration
3. **Test with the public test agent** - verify your setup works before testing custom agents
4. **Check protocol version** - ensure client and server protocol versions are compatible
> [!TIP]
>
> For OAuth handshake failures and RFC 9421 signing issues, use the [CLI auth graders](/dist/docs/3.2.8/building/verification/grading) — `diagnose-auth` probes RFC 9728 + RFC 8414 discovery and ranks hypotheses; `grade request-signing` runs every signing vector with per-vector diagnostics.
## Obtaining Credentials
### Account Setup Process
To access authenticated operations, you must establish an account with each sales agent:
1. **Identify Sales Agents**: Discover sales agents via publisher `adagents.json` files
2. **Contact Sales Team**: Reach out to the agent's sales or partnerships team
3. **Complete Onboarding**: Provide business information, sign agreements, configure billing
4. **Receive Credentials**: Get API keys or OAuth client credentials
**Note**: Each sales agent manages their own accounts independently. You need separate credentials for each agent you work with.
### Dynamic Registration (Optional)
Some sales agents support OAuth 2.0 dynamic client registration:
```http theme={null}
POST /oauth/register
Content-Type: application/json
{
"client_name": "Your Company Name",
"redirect_uris": ["https://yourapp.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"scope": "adcp:products adcp:media_buys adcp:creatives"
}
```
Check the sales agent's documentation or `adagents.json` for dynamic registration support.
### Aggregation Platforms
Consider using aggregation platforms (like Scope3) that manage credentials and relationships with multiple sales agents on your behalf. This simplifies:
* Credential management
* Financial relationships
* Legal agreements
* Compliance monitoring
## Authenticating to AAO Platform Services
The mechanisms above govern **agent-to-agent** auth (buyer ↔ sales agent). Authenticating to **AAO-hosted services** — the registry write API, the AAO MCP endpoint, the member dashboard — is a separate surface.
AAO runs an OAuth 2.1 + OIDC authorization server. Clients discover it via standard well-knowns:
* **Authorization server metadata (RFC 8414):** `https://agenticadvertising.org/.well-known/oauth-authorization-server`
* **Protected-resource metadata (RFC 9728):** `/.well-known/oauth-protected-resource/api` (REST API) and `/.well-known/oauth-protected-resource/mcp` (MCP). Both list `https://agenticadvertising.org` as the authorization server.
* **Flow:** authorization code with PKCE (S256). User identity is via WorkOS AuthKit; tokens are signed JWTs.
* **Dynamic client registration (RFC 7591):** `POST /register`.
* **Server-to-server:** there is no `client_credentials` grant. Backend services should use a WorkOS organization API key from the [AAO dashboard](https://agenticadvertising.org/dashboard/api-keys), not the OAuth `/token` endpoint.
All AAO endpoints are HTTPS-only; reject any discovery document served over plain HTTP.
A user JWT obtained from AAO is **not** an AdCP credential. Calls to a sales agent still use that agent's bearer / 9421 / mTLS credentials per the table above. Full reference: [AAO registry — Authentication](/dist/docs/3.2.8/registry#authentication).
> [!WARNING]
>
> **If you discover an `authorization_endpoint` on a sales agent's RFC 9728 protected-resource metadata** (e.g., for an operator-account OAuth flow), pin the discovered `authorization_servers` issuer against what `adagents.json` — or out-of-band onboarding — authorized for that seller. Do not blindly trust an AS URL the resource itself returned, otherwise a malicious or compromised seller can route operator credentials to an attacker-controlled endpoint.
## Error Responses
### Unauthenticated Request to Protected Operation
```json theme={null}
{
"error": {
"code": "AUTH_REQUIRED",
"message": "Authentication required for this operation"
}
}
```
### Invalid or Expired Credentials
```json theme={null}
{
"error": {
"code": "AUTH_INVALID",
"message": "Invalid or expired credentials"
}
}
```
### Insufficient Permissions
```json theme={null}
{
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "Agent does not have required permissions for this operation"
}
}
```
## Best Practices
1. **Secure Storage**: Store credentials securely (environment variables, secret managers)
2. **Rotation**: Implement credential rotation policies
3. **Scope Limitation**: Request minimum required permissions
4. **Token Refresh**: Implement automatic token refresh for JWT tokens
5. **Error Handling**: Handle authentication errors gracefully with retry logic
## Testing Authentication
The public test agent accepts a shared token — no signup required:
```bash theme={null}
export ADCP_AUTH_TOKEN="1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
export AGENT_URL="https://test-agent.adcontextprotocol.org/sales/mcp"
```
Configure your client with this token:
```json theme={null}
{
"agent_uri": "https://test-agent.adcontextprotocol.org/sales/mcp",
"protocol": "mcp",
"auth": {
"type": "bearer",
"token": "1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
}
}
```
For org-scoped usage tracking, replace the public token with your own API key from the [AAO dashboard](https://agenticadvertising.org/dashboard/api-keys).
See [Sandbox Mode](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox) for testing capabilities including sandbox mode for risk-free development.
# Context & Sessions
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L2/context-sessions
AdCP context_id vs task_id explained. How A2A and MCP handle conversation state, task continuity, and application context.
AdCP uses identifiers and data fields to maintain state across requests. Understanding these is essential for building effective integrations.
## Key Identifiers
AdCP uses two distinct identifiers for different purposes:
### context_id vs task_id
| Identifier | Purpose | Lifespan | Scope |
| - | - | - | - |
| **context_id** | A2A conversation correlation | Transport-defined | Across A2A messages in one conversation |
| **task_id** | Tracking specific operations | Until completion (hours to days) | Single operation |
**context_id**:
* Maps to A2A's native Message/Task `contextId`
* Is managed in the A2A transport envelope, not inside the AdCP task body
* Is not an MCP request-body session mechanism
* Is correlation and routing metadata, not authorization
**task_id**:
* Specific to individual requests that could be asynchronous
* Lives beyond the conversation
* Used for tracking operation progress over time
* Persists until the task completes (may be days for complex media buys)
* Can be referenced across different conversations or sessions
### A2A usage example
```javascript theme={null}
// First call - establishes context and creates task
const first = await a2a.send({ message: { parts: [/* AdCP request */] } });
// Later in the same A2A conversation, use the native envelope fields.
const followUp = await a2a.send({
message: {
contextId: first.contextId,
taskId: first.taskId,
parts: [/* follow-up AdCP request */]
}
});
```
## Protocol Differences
* **A2A**: Conversation continuity uses native `contextId` in the A2A envelope.
* **MCP**: Continuity, when offered, belongs to the transport session. Do not send an AdCP `context_id` tool argument to create or resume it.
### A2A Context
A2A carries conversation correlation in the native message envelope:
```javascript theme={null}
const task = await a2a.send({ message: {...} });
// Follow-ups explicitly carry the transport-native contextId.
const followUp = await a2a.send({
message: {
contextId: task.contextId,
taskId: task.taskId,
...
}
});
```
### MCP context
MCP callers send task arguments without an AdCP session identifier:
```javascript theme={null}
// First call - no context
await mcp.call('get_products', {
idempotency_key: "550e8400-e29b-41d4-a716-446655442076",
buying_mode: "brief",
brief: "Video ads"
});
// Follow-up in the same MCP transport session, if the host provides one.
await mcp.call('get_products', {
idempotency_key: "550e8400-e29b-41d4-a716-446655442077",
buying_mode: "brief",
brief: "Focus on premium inventory"
});
```
Where the selected request schema admits `context_id`, MCP servers MUST ignore it. It cannot select session state, identity, account, authorization, task continuation, or idempotency scope. Use the MCP transport session, if provided, for ephemeral continuity and schema-declared task or resource identifiers for durable state.
## What Context Maintains
An A2A `contextId` can associate conversational state such as:
* Current media buy and products being discussed
* Search results and applied filters
* Conversation history and user intent
* User preferences expressed in the session
* Workflow state and temporary decisions
Note: Long-term task state (like media buy status, creative assets, performance data) is tracked via `task_id`, not `context_id`.
## Extension Fields (`ext`)
Extension fields enable platform-specific functionality while maintaining protocol compatibility.
### Schema Pattern
Extensions appear consistently across requests, responses, and domain objects:
```json theme={null}
{
"product_id": "ctv_premium",
"name": "Connected TV Premium Inventory",
"ext": {
"gam": {
"order_id": "1234567890",
"dashboard_url": "https://..."
},
"roku": {
"content_genres": ["comedy", "drama"]
}
}
}
```
The `ext` object:
* Is always **optional** (never required)
* Accepts any valid JSON structure
* Must be preserved by implementations (even unknown fields)
* Is not validated by AdCP schemas (implementation-specific validation allowed)
### Namespacing (Critical)
Extensions MUST use vendor/platform namespacing:
```json theme={null}
// ✅ Correct - Namespaced
{
"ext": {
"gam": { "test_mode": true },
"roku": { "app_ids": ["123"] }
}
}
// ❌ Incorrect - Not namespaced
{
"ext": {
"test_mode": true, // Missing namespace!
"app_ids": ["123"] // Which platform?
}
}
```
## Application Context (`context`)
Context provides opaque correlation data that is echoed unchanged in responses and webhooks.
### Key Properties
* Agents NEVER parse or use context to affect behavior
* Exists solely for the initiator's internal tracking needs
* Echoed unchanged in responses and webhook payloads
### Normative echo contract
Agents MUST obey the following rules. The compliance runner asserts on these literally, and buyers rely on them for correlation.
1. **Echo on success.** When the caller includes a top-level `context` object on a request, the agent MUST include the same JSON value in the response. This applies whether the response status is `completed`, `submitted`, `working`, `input-required`, or any other terminal or intermediate state.
2. **Echo on error.** Failure responses MUST also echo the same `context` JSON value. Dropping context on the error path breaks correlation exactly when the buyer needs it most. Agents that return `adcp_error`, `errors[]`, or any other error envelope MUST still carry through the caller's `context`.
3. **Echo on async updates.** Push notifications, webhook payloads, and any subsequent messages the agent emits for the same operation MUST carry the original `context`. The agent MUST NOT drop context between the initial response and a later status update — a buyer that correlated by `context.trace_id` expects every message for that operation to surface the same trace.
4. **No synthesis.** When the caller does NOT provide a `context` object, the agent MUST NOT fabricate one. Responses to context-less requests MUST omit the `context` field (or emit it as null / absent per the transport's normal serialization). Synthetic context from the agent side is a conformance failure — the whole point of context is that it is owned by the caller.
5. **No mutation.** Agents MUST NOT add, remove, rename, or change the JSON type or value of fields in the echoed context. JSON value equivalence applies: object member order and number lexical form are not types or values. For example, `{"a":1,"b":2}` and `{"b":2.0,"a":1.0}` are equivalent for the echo rule. An integer-valued number remains an integer for JSON Schema validation when serialized with a zero fractional part, so A2A's `3` → `3.0` serialization does not count as retyping. Changing the mathematical value does. Across A2A, the comparison value is the post-decoding `google.protobuf.Value`; senders and receivers MUST enforce the [A2A numeric domain](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension#json-number-interoperability). Verifiers MUST compare parsed JSON values; a verifier that hashes context SHOULD canonicalize the parsed value instead of hashing transport bytes.
6. **No action.** Agents MUST NOT parse, validate, log fields from, or branch on any value inside `context`. Context is opaque to the agent — a value that looks like a structured identifier is not an invitation to interpret it.
> [!WARNING]
>
> A2A 1.0 carries structured data in `google.protobuf.Value`, whose numeric representation is an IEEE 754 double. Callers using A2A MUST encode exact integer identifiers outside the interoperable range `[-9007199254740991, 9007199254740991]` as strings inside `context`; exact decimals that need more precision than binary64 provides MUST also be strings. The transport cannot preserve those numeric values reliably. This is distinct from the harmless lexical change between `3` and `3.0`.
### Schema Pattern
```json theme={null}
{
"tool": "create_media_buy",
"arguments": {
"packages": [...],
"context": {
"ui_session_id": "sess_abc123",
"trace_id": "trace_xyz789",
"internal_campaign_id": "camp_456"
}
}
}
```
Response echoes the context:
```json theme={null}
{
"status": "input-required",
"message": "Media buy requires manual approval before activation.",
"context_id": "ctx_ghi789",
"context": {
"ui_session_id": "sess_abc123",
"trace_id": "trace_xyz789",
"internal_campaign_id": "camp_456"
}
}
```
### Common Context Uses
1. **UI/Session tracking** - Maintaining state across async operations
2. **Request correlation** - Tracing requests through distributed systems
3. **Internal identifiers** - Mapping to your internal data structures
4. **Organization context** - Multi-tenant tracking
## When to Use What
| Field | Purpose | Agent Reads? | Agent Modifies? |
| - | - | - | - |
| `context_id` | A2A conversation correlation; MCP compatibility no-op | A2A transport only | A2A transport only |
| `task_id` | Operation tracking | Yes | Yes (creates) |
| `ext` | Platform-specific config | MAY | MAY add response data |
| `context` | Opaque correlation | NEVER | NEVER |
### Use `ext` when:
* Platform needs to parse the data
* Data MAY affect operational behavior
* Data represents platform-specific configuration
* Data should persist across operations
### Use `context` when:
* Data is only for caller's internal use
* Data should never affect agent behavior
* Data is for correlation/tracking only
* Data needs to be echoed unchanged
## Best Practices
### For A2A
* Let the protocol handle context
* Use contextId for explicit conversation threading
* Trust the session management
### For MCP
* Do not copy response `context_id` values into later tool arguments
* Use the MCP transport session, if provided, for ephemeral continuity
* Use `task_id` or the task's resource identifiers for durable work
* Ignore a request-body `context_id` where the selected schema admits it
### For Extensions
* Always namespace under vendor keys
* Document your extensions extensively
* Consider proposing standardization for common patterns
### For Application Context
* Keep it opaque - don't structure for agents to parse
* Avoid large payloads - context is echoed in every response
* Use for correlation only - never for operational data
# L2 — Auth & registry
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L2/index
Auth-and-registry layer of the AdCP stack. Turns a verified identity into a scoped principal — which buyer, which brand, which advertiser account, which sandbox-vs-live tier.
L2 turns a verified identity into a scoped principal. On the agent side: multi-tenant principal resolution, sandbox/live boundary, brand resolution, permission scoping. On the caller side: publish own identity, look up the agent it's calling — much smaller surface.
## What an SDK at L2 must provide
If you're picking an SDK or porting one to a new language, this is the L2 build target:
* **An account-store abstraction** that resolves an authenticated principal to a scoped account, with hooks for multi-tenant routing.
* **Authentication primitives** for at least API-key and bearer-token shapes, plus a way to compose them.
* **Brand-resolution / agent-registry lookup** — or a documented extension point if the SDK doesn't ship it natively.
* **The sandbox-vs-live account flag**, enforced at the SDK boundary so the conformance-test surface refuses to dispatch on production accounts.
For the cumulative cross-layer story (what L0+L1+L2 buys you), see the [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#l2--auth--registry).
## Pages in this layer
* **[Authentication](/dist/docs/3.2.8/building/by-layer/L2/authentication)** — credentials and permissions.
* **[Account state](/dist/docs/3.2.8/building/by-layer/L2/account-state)** — multi-tenant account resolution.
* **[Accounts and agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents)** — relationship between account scoping and agent identity.
* **[Context & sessions](/dist/docs/3.2.8/building/by-layer/L2/context-sessions)** — managing principal state across requests.
# Async identity and convergence
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L3/async-identity-and-convergence
Normative AdCP rules for correlating asynchronous work across direct responses, polling, continuations, A2A tasks, and webhooks.
AdCP operations can be observed through more than one channel. A direct task
response, an AdCP task-status read, an A2A transport Task, a continuation, and
a webhook can all describe related work, but their identifiers are not
interchangeable.
This page defines the normative identity, convergence, resumability, and
publication rules shared by every AdCP task. Task-specific documentation can
narrow these rules, but MUST NOT weaken them.
## Identity model
Implementations MUST retain each identity in its own namespace and MUST NOT
substitute one identity for another.
| Identity | Authority and purpose | MUST NOT be used as |
| - | - | - |
| Client operation ID (`operation_id`, when present) | Client-generated correlation for one logical operation across local attempts and webhook routing | A seller work handle, replay fence, or authorization grant |
| Request `idempotency_key` | Client-generated replay identity for one canonical mutating request | An operation ID, AdCP task ID, A2A Task ID, or webhook delivery key |
| AdCP `task_id` | Seller-generated handle for durable AdCP work, read through `get_task_status` or legacy `tasks/get` | An A2A Task ID, continuation token, or idempotency key |
| A2A `Task.id` | A2A transport identity for one invocation or native A2A continuation | The AdCP `task_id` returned inside an AdCP Submitted result |
| A2A `contextId` | A2A conversation correlation | A work handle, replay fence, or continuation capability by itself |
| Webhook `idempotency_key` | Sender-generated delivery identity, stable across retries of the same payload | The request idempotency key or stable identity of a re-emitted logical observation |
| Webhook `notification_id`, when defined for the event | Stable identity of one logical notification across re-emissions | A delivery-attempt key or authorization grant |
| Continuation token or descriptor | Current, generation-scoped authority to resume a paused transport interaction | A polling handle or general operation credential |
An SDK MAY present a composite operation object containing several of these
values. That convenience object does not merge their semantics.
### Stable seller-work identity
Once an operation is bound to an AdCP `task_id`, every later AdCP observation
of that operation—`submitted`, subsequent status reads, paused states,
terminal results, task webhooks, and reconciliation—MUST repeat that value or
inherit it from an envelope whose binding is unambiguous. A different explicit
AdCP `task_id` for the same operation is a protocol conflict. A client MUST NOT
silently rebind the operation or treat the new value as a successor.
An A2A transport Task can complete with an AdCP Submitted result. In that case,
the A2A `Task.id` identifies the completed transport invocation and the AdCP
`task_id` identifies the continuing seller work. Polling uses only the AdCP
handle. Native A2A continuation uses only the A2A Task and context identifiers.
## One operation, competing observations
Direct responses, AdCP polling results, continuation responses, and
authenticated webhooks are competing observations of one logical operation.
They are not independent state machines.
An observation is authoritative only after the receiver has:
1. authenticated its source;
2. validated its envelope and task-specific payload;
3. matched the operation, account, task type, and all bound identities; and
4. verified that the observation is permitted from the operation's current
state.
The first authoritative terminal observation wins. The receiver MUST durably
record its terminal identity and canonical payload before publishing terminal
business side effects. Later behavior is:
* an exact terminal duplicate is acknowledged and does not republish effects;
* a non-terminal observation after terminal settlement is acknowledged as
stale and does not reopen the operation; and
* a different terminal payload or terminal status is a protocol conflict and
MUST NOT replace, merge with, or republish over the winner.
`completed`, `failed`, `canceled`, and `rejected` are terminal. `working`,
`submitted`, `input-required`, and `auth-required` are non-terminal. None can
displace an accepted terminal result. `unknown` is indeterminate and is not an
authoritative terminal observation: the receiver MUST reconcile it, and it
cannot settle or reopen an operation. A terminal webhook MAY arrive before the
originating request returns `working` or `submitted`; this is an allowed race,
not an unknown-task error. The implementation preserves the validated terminal
observation and converges the later response onto it.
### Terminal identity and equivalence
For asynchronous work already bound to a seller task, one terminal settlement
is identified by `(authenticated seller identity, AdCP task_id)`. `task_type`,
operation, account, and principal bindings are validated constraints on that
identity. A mismatch is a correlation conflict, not a second settlement.
Synchronous inline terminal responses have no AdCP task identity and cannot
race a task webhook: 3.x sellers MUST NOT synthesize a task webhook for an
inline terminal response.
Channels wrap the task result differently. Before duplicate comparison, a
receiver extracts the task-specific terminal value:
| Channel | Terminal value used for comparison |
| - | - |
| Direct response or A2A artifact | The task-specific response body selected by the invoked task schema, before transport-envelope fields are injected |
| `get_task_status` / `tasks/get` | `result` when the terminal artifact is present. A legacy failed poll carrying only singular `error` proves terminal status but not full payload equivalence; a canceled poll with no artifact has canonical value `null` |
| Task webhook | `result`, validated against the originating task's terminal response schema; a fatal error is normalized to the same core Error shape used by polling |
The canonical comparison record is RFC 8785 JCS of `{task_type, status,
value}`. Transport-only observation fields—including A2A Task and context
identifiers, webhook `idempotency_key`, `notification_id`, `operation_id`,
AdCP `task_id`, delivery timestamp, envelope `message`, and `replayed`—are not
part of `value`. A field declared by the task-specific response schema remains
part of `value`, including task-body `context` or `errors` when declared.
When both a terminal `result` and the polling convenience `error` are present,
the error MUST agree with the canonical fatal error in `result`. A legacy 3.x
poll that exposes only singular `error` can establish that the task failed, but
cannot prove that a later full terminal artifact is an exact duplicate. The
receiver preserves the failure fence and reconciles the complete artifact; it
does not publish from the incomplete observation or call a different payload
equivalent. More generally, when a channel cannot be validated or normalized
to the selected task schema, it is not authoritative for publication.
## Normative race table
“Acknowledge” below means return the success form appropriate to the channel.
For an authenticated HTTP webhook, that is a `2xx` response.
| Race or recovery point | Required winner and state transition | Retry or acknowledgement behavior |
| - | - | - |
| Direct terminal response vs. terminal webhook | The first authoritative terminal observation wins | Exact duplicate: acknowledge. Different terminal result: reject as a protocol conflict and preserve the winner |
| Poll terminal result vs. terminal webhook | The first authoritative terminal observation wins regardless of channel | Exact duplicate: acknowledge. Conflict: reject; polling or webhook order gives neither channel priority |
| Terminal webhook arrives before the request returns `submitted` or `working` | Preserve the terminal result; the later non-terminal response inherits the bound seller-work identity and is stale | Do not reject the webhook merely because local request completion has not yet been observed |
| Terminal callback vs. input or authorization resume | Terminal settlement wins once authoritative | A resume that has not dispatched becomes stale and MUST NOT dispatch. If dispatch already crossed its commitment boundary, reconcile and surface ambiguity rather than inventing an outcome |
| Same webhook delivery key and identical payload, first copy still active | Exactly one receiver owns publication | Other copies return a retryable failure, normally `503`, until the owner durably acknowledges; after acknowledgement they return `2xx` |
| Same webhook delivery key and different payload | Neither payload may redefine the delivery key after its first binding | Return non-retryable `409 Conflict`; do not dispatch the changed payload |
| Different delivery keys for the same logical terminal observation | The first authoritative terminal observation owns publication | Correlate by `(authenticated seller identity, AdCP task_id)` and canonical terminal payload; use stable notification identity as supplemental evidence when present; acknowledge duplicates without republishing |
| Two receivers attempt terminal publication | One durable publication owner is established before the application handler or other externally visible side effect runs | Non-owners wait or return a retryable response. Recording acknowledgement only after both handlers run is non-conformant |
| Pause A is resumed and produces pause B | B becomes the current generation | B MUST be durably established and recoverable before A is consumed; only B can accept later input |
| Crash after B is stored but before A points to B | Recovery completes or rolls back the staged handoff without losing the only usable generation | A remains usable until B is discoverable through the operation, or reconciliation returns B; an unreachable B is non-conformant |
| Crash after A points to B but before B reaches the caller | B remains discoverable from the operation and the old generation | Retrying or reconciling A returns the current descriptor for B without dispatching input again |
| Stale or concurrent resume of A after B is current | B remains current; A cannot dispatch | Fail closed with a typed stale-generation or in-progress result; never advance seller work twice |
| Crash after publication ownership but before durable acknowledgement | The same owner or a recovery owner reconciles the reserved publication | Do not hand the same observation to an unconstrained second publisher; retry remains safe and bounded |
| Legacy atomic operation projected onto multiple compact mutations | No step runs unless the facade can preserve the legacy all-or-none boundary | Otherwise reject before the first mutation. A compensating saga is recovery, not atomic compatibility |
## Webhook delivery-key binding
A webhook publisher MUST bind `(authenticated sender identity,
idempotency_key)` to the complete authenticated payload's RFC 8785 JSON
Canonicalization Scheme (JCS) form for the advertised retry window. Duplicate
object keys MUST be rejected before canonicalization. It reuses that key only
for JCS-equivalent retries of that delivery. A re-emission of the same logical
notification with a changed
envelope or payload uses a fresh delivery key and retains the same
`notification_id` when that event type defines one.
A receiver MUST establish the same immutable binding before application side
effects. It fingerprints the authenticated canonical payload and stores that
fingerprint with the delivery claim. The three outcomes are distinct:
| Delivery state | HTTP behavior | Meaning |
| - | - | - |
| Same key and payload, actively processing | Retryable `503` | No second publisher runs; sender retries later |
| Same key and payload, durably acknowledged | `2xx` | Exact duplicate is complete |
| Same key, different payload | Non-retryable `409` | Delivery identity conflict; sender must not retry that key with either changed payload |
The delivery key prevents duplicate transport processing. The stable terminal
observation identity prevents duplicate terminal publication across distinct
deliveries. Implementations need both protections.
## Resumability and continuation generations
`input-required` and `auth-required` describe why work is paused. They do not,
by themselves, prove that the interaction can be resumed.
An SDK or transport exposes a resume operation only when it has a verified
continuation descriptor containing the native protocol and transport identity
required for that continuation. For A2A, that includes the native A2A Task ID
and context ID. An AdCP `task_id` from `get_task_status` is only a polling
handle and MUST NOT be copied into a missing A2A Task ID or otherwise used to
fabricate a continuation.
AdCP 3.2 defines no transport-neutral continuation request or generic
continuation descriptor in task-body schemas. Application-layer
`input-required` and `auth-required` responses are therefore resumable only
when the active transport independently supplies its native verified resume
identity, such as A2A `Task.id` plus `contextId`. Standardizing a portable
descriptor without a matching redemption method would create an unusable
credential; that wire surface is deferred to AdCP 4.0.
If a transport did not return enough verified identity to continue, the client
fails closed and directs the caller to polling, reconciliation, or a new
operation as allowed by the task. A `context_id` or status label alone does not
authorize a resume.
Continuation tokens are opaque bearer capabilities. They MUST:
* contain at least 128 bits of cryptographically random entropy;
* be bound to the authenticated principal, operation, transport identity, and
one continuation generation;
* be single-generation and expire after a bounded interval;
* never appear in logs, analytics, URLs, error messages, or telemetry; and
* be compared and stored using the same protections as other bearer secrets.
When resuming generation A yields generation B, the transition is
create-B, make-B discoverable from the operation, then consume A. These are
protocol invariants even when an implementation uses more than one durable
store. Ordering that merely prevents duplicate dispatch but can strand B after
a crash is not recoverable and is non-conformant.
## Publication and durable acknowledgement
Deduplication is not complete when a receiver checks a marker and plans to
write an acknowledgement later. Before invoking an adopter callback, billing
hook, fulfillment handler, or other externally visible side effect, the
receiver MUST durably establish a single publication owner for that terminal
observation.
After successful publication it records durable acknowledgement. Exact
duplicates then return success without invoking the handler. If publication
fails, ownership can be released or expire under a bounded recovery policy.
If a crash makes the external side effect uncertain, the receiver reconciles
that side effect or preserves the uncertainty fence; it MUST NOT assume failure
and give a second publisher unrestricted ownership.
## Retry horizons
An agent's capability response advertises the request idempotency replay
window and, when it emits webhooks, its maximum webhook delivery retry window
as `webhook_signing.delivery_retry_horizon_seconds`.
These are guaranteed floors for retained replay evidence, not suggestions to
keep retrying until the last second.
Receivers retain the immutable webhook delivery-key-to-payload binding and
terminal publication proof for at least the greater of 24 hours and the
sender's advertised retry window.
When no webhook retry window is advertised by a 3.x peer, both sides use the
3.x compatibility floor of 24 hours. A publisher MUST NOT retry after the
window it advertised for the delivery.
Retention is measured from the first accepted request or delivery. Extending
retention on every retry would allow a hostile or broken peer to keep state
alive indefinitely. Clock-skew tolerance cannot shorten the advertised
window.
## Composite and compatibility operations
Splitting one legacy task into multiple compact tasks changes transaction and
failure boundaries. A compatibility facade is lossless only if it preserves
the legacy task's validation and atomic-commit semantics, not merely its final
field values.
For example, a legacy `create_media_buy` can include packages, creatives, and
assignments in one request. Structural, reference, and routing validation of
those inline creatives occurs before commit, so one such validation failure
rejects the request without creating the buy. Later asynchronous policy or
human review can still reject a creative without rolling back an already valid
buy. A facade implemented as compact purchase followed by creative sync moves
the pre-commit validation boundary and can commit spend before it discovers a
structural or routing failure. That sequence is not a lossless implementation.
A compatibility facade therefore either:
1. validates and commits every component through one private all-or-none
boundary; or
2. rejects before the first mutation.
When a caller deliberately uses the compact tasks as separate operations,
partial success is valid but MUST be explicit. Each step has its own
authorization, idempotency key, task identity, terminal outcome, and recovery
path. Compensation is a new mutation with its own observable result; it MUST
NOT be described as rollback of the earlier committed step.
See [Legacy and compact lifecycle compatibility](https://github.com/adcontextprotocol/adcp/blob/main/specs/legacy-compact-lifecycle-compatibility.md)
for the media-buy transaction-boundary matrix.
## Implementation checklist
For every asynchronous or compatibility workflow, document and test:
1. every identity and its issuing authority;
2. the point at which seller-work identity becomes stable;
3. the canonical terminal payload and conflict comparison;
4. publication ownership before external effects and acknowledgement after;
5. continuation generation, supersession, and crash discovery;
6. advertised request and webhook retry horizons;
7. every mutation boundary and possible partial-success state; and
8. recovery after a crash at each boundary.
Failing closed prevents an unsafe duplicate. Conformance also requires a
durable route to discover and complete legitimate committed work.
# Async Operations
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L3/async-operations
AdCP async operations guide: handling synchronous, asynchronous, and interactive (input-required) task types with polling, SSE streaming, and timeout strategies.
AdCP operations can take seconds, hours, or days. The server decides how to respond based on how long the operation will take and what's blocking it.
Direct responses, polling, continuations, and webhooks can race while observing
the same work. Implementations MUST apply the [async identity and convergence
contract](/dist/docs/3.2.8/building/by-layer/L3/async-identity-and-convergence); channel
arrival order does not create separate operations.
## The 30-second rule
Any AdCP task can return one of these statuses. The server chooses based on what it knows about the work involved:
| Expected duration | Status | What the caller does |
| - | - | - |
| Under 30 seconds | `completed` / `failed` | Result is inline — done |
| Over 30 seconds, server actively processing | `working` | Out-of-band progress signal. Connection stays open, result arrives when ready. Caller just waits |
| Blocked on external dependency | `submitted` | Truly async — poll by `task_id`; `push_notification_config` can also deliver notifications when configured. Result may take hours or days |
| Blocked on human input | `input-required` | Caller provides the requested input to continue |
`input-required` describes a pause; it does not prove resumability. A client
offers a resume action only when the transport supplied a verified continuation
descriptor. It MUST NOT fabricate one from an AdCP polling `task_id`.
**`working` is not async.** It's a progress signal the server sends out-of-band (via MCP status notifications or SSE) while it continues processing. The caller holds the connection and receives the result when it's ready — no polling, no webhooks. Think of it as "this is taking a moment, but I'm on it."
**`submitted` is async.** The operation is blocked on something outside the server's control — publisher approval, human review, third-party processing. The caller can always poll the AdCP task status surface with `task_id`. A configured webhook is an additional notification channel for background workflows, not a replacement for polling.
:::tip Webhooks for `submitted` operations
**AdCP webhooks** are recommended for background `submitted` operations — they work with MCP, A2A, and REST and can outlive a transport session. The registration is always `push_notification_config` in the typed AdCP task request, including inside an A2A profile invocation's `data.input`. A2A's separate `configuration.taskPushNotificationConfig` follows only the A2A transport Task and does not replace the durable AdCP webhook. When a request includes an AdCP webhook channel and the server accepts the task by returning `submitted`, the server MUST deliver at least the terminal completion or failure notification to that channel. Intermediate progress notifications are optional unless another operation-specific contract requires them. If the server cannot honor the requested webhook channel, it MUST reject the request with a structured error instead of silently downgrading delivery. See [Push Notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks).
**Polling** via the AdCP task polling surface is always valid for `submitted` tasks. The AdCP v3 A2A profile requires `get_task_status`; MCP sellers may expose that name or the legacy AdCP `tasks/get` alias. Both accept the same payload shape; multi-account callers SHOULD include `account` so sellers can scope task visibility to the authenticated account + principal pair. See the [polling pattern](#polling-for-submitted-operations) below.
**Transport-native tasks are not the AdCP lifecycle.** MCP Tasks or A2A task updates may carry or stream an AdCP response, but the durable task state is the AdCP payload: `task_id`, `status`, webhook payloads, and AdCP polling/reconciliation. See [MCP Guide](/dist/docs/3.2.8/building/by-layer/L0/mcp-guide#mcp-tasks-as-a-transport-wrapper).
:::
## Operation examples
### Synchronous (instant)
| Operation | Description |
| - | - |
| `get_adcp_capabilities` | Agent capability discovery |
| `get_adcp_capabilities` | Capability catalog |
| `build_creative` (library retrieval) | Resolving an existing `creative_id` |
### May need human input
| Operation | Description |
| - | - |
| `get_products` | When brief is vague or needs clarification |
| `create_media_buy` | When approval is required |
| `build_creative` (generation) | When creative direction or asset selection is needed |
### May go async (`submitted`)
| Operation | Description |
| - | - |
| `create_media_buy` | Publisher approval workflows |
| `update_media_buy` | Manual seller review for budget, targeting, or creative changes |
| `get_products` (`brief` / `refine`) | Bespoke curation that depends on upstream inventory queries or HITL review |
| `get_signals` (`brief`) | Semantic signal discovery that depends on slow provider queries or review |
| `sync_creatives` | Asset review and transcoding pipelines |
| `build_creative` (with review) | Human creative review before finalizing |
| `get_creative_features` | Sandboxed malware scans or other provider evaluations that complete out of band |
| `sync_catalogs` | Large feeds or feeds requiring content policy review |
| `activate_signal` | Platform deployment pipelines |
These operations integrate with external systems or require human approval. Wholesale feed reads are the exception: `get_products buying_mode: "wholesale"` and `get_signals discovery_mode: "wholesale"` stay synchronous repair/reconciliation reads and report partial completion with `incomplete[]`, not `submitted`.
## Timeout Configuration
Set reasonable timeouts based on status:
```javascript theme={null}
const TIMEOUTS = {
sync: 30_000, // 30 seconds — most operations complete here
working: 300_000, // 5 minutes — server is actively processing
interactive: 300_000, // 5 minutes for human input
submitted: 86_400_000 // 24 hours for external dependencies
};
function getTimeout(status) {
if (status === 'submitted') return TIMEOUTS.submitted;
if (status === 'working') return TIMEOUTS.working;
if (status === 'input-required') return TIMEOUTS.interactive;
return TIMEOUTS.sync;
}
```
`working` uses a connection timeout (how long to hold open), not a poll interval. The server sends progress out-of-band and delivers the result on the same connection. `submitted` uses a polling or webhook delivery window; a 30-second poll interval is a reasonable default even when webhooks are configured as the primary notification path.
## Human-in-the-Loop Workflows
### Design Principles
1. **Optional by default** - Approvals are configured per implementation
2. **Clear messaging** - Users understand what they're approving
3. **Timeout gracefully** - Don't block forever on human input
4. **Audit trail** - Track who approved what when
The human-in-the-loop patterns in async operations embody the [Embedded Human Judgment](/dist/docs/3.2.8/governance/embedded-human-judgment) framework — human judgment is embedded in system design, not bolted on afterward.
### Approval Patterns
```javascript theme={null}
async function handleApprovalWorkflow(response) {
if (response.status === 'input-required' && needsApproval(response)) {
const continuation = verifiedContinuationFor(response);
if (!continuation) return requireReconciliation(response);
// Show approval UI with context
const approval = await showApprovalUI({
title: "Campaign Approval Required",
message: response.message,
details: response, // Task fields are at top level
approver: getCurrentUser()
});
// Send approval decision
const decision = {
approved: approval.approved,
notes: approval.notes,
approver_id: approval.approver_id,
timestamp: new Date().toISOString()
};
return resumeContinuation(continuation, decision);
}
}
```
### Common Approval Triggers
* **Budget thresholds**: Campaigns over \$100K
* **New advertisers**: First-time buyers
* **Policy-sensitive content**: Certain industries or topics
* **Manual inventory**: Premium placements requiring publisher approval
## Progress Tracking
### Progress Updates
Long-running operations may provide progress information:
```json theme={null}
{
"status": "working",
"message": "Processing creative assets...",
"task_id": "task-456",
"progress": 45,
"step": "transcoding_video",
"steps_completed": ["upload", "validation"],
"steps_remaining": ["transcoding_video", "thumbnail_generation", "cdn_distribution"]
}
```
### Displaying Progress
```javascript theme={null}
function displayProgress(response) {
if (response.progress !== undefined) {
updateProgressBar(response.progress);
}
if (response.step) {
updateStatusText(`Step: ${response.step}`);
}
if (response.steps_completed) {
updateStepsList(response.steps_completed, response.steps_remaining);
}
// Always show the message
updateMessage(response.message);
}
```
## Protocol-Agnostic Patterns
These patterns work with both MCP and A2A.
### Product Discovery with Clarification
```javascript theme={null}
async function discoverProducts(brief) {
let response = await adcp.send({
task: 'get_products',
brief: brief
});
// Handle clarification loop
while (response.status === 'input-required') {
const continuation = verifiedContinuationFor(response);
if (!continuation) throw new Error('No verified continuation');
const moreInfo = await promptUser(response.message);
response = await resumeContinuation(continuation, moreInfo);
}
if (response.status === 'completed') {
return response.products; // Task fields are at top level
} else if (response.status === 'failed') {
throw new Error(response.message);
}
}
```
### Campaign Creation with Approval
```javascript theme={null}
async function createCampaign(packages, budget) {
let response = await adcp.send({
task: 'create_media_buy',
packages: packages,
total_budget: budget
});
// Handle approval if needed
if (response.status === 'input-required') {
const continuation = verifiedContinuationFor(response);
if (!continuation) throw new Error('No verified continuation');
const approved = await getApproval(response.message);
if (!approved) {
throw new Error('Campaign creation not approved');
}
response = await resumeContinuation(continuation, { approved: true });
}
// 'working' means the server is actively processing — result will arrive
// 'submitted' means blocked on external dependency — poll by task_id;
// a webhook may also deliver completion if configured.
if (response.status === 'submitted') {
response = await pollForResult(response.task_id);
}
if (response.status === 'completed') {
return response.media_buy_id; // Task fields are at top level
} else {
throw new Error(response.message);
}
}
```
### Polling for `submitted` Operations
Polling is always valid for `submitted` operations. A webhook may also deliver completion when configured, but callers can still reconcile through the task polling surface. Don't poll for `working` — the server delivers the result on the open connection.
```javascript theme={null}
async function pollForResult(taskId, options = {}) {
const { maxWait = 86_400_000, pollInterval = 30_000 } = options;
const startTime = Date.now();
while (true) {
if (Date.now() - startTime > maxWait) {
throw new Error('Operation timed out');
}
await sleep(pollInterval);
const response = await adcp.call('get_task_status', {
task_id: taskId,
include_result: true
});
if (['completed', 'failed', 'canceled'].includes(response.status)) {
return response;
}
}
}
```
## Asynchronous-First Design
### Store State Persistently
Don't rely on in-memory state for async operations:
```javascript theme={null}
class AsyncOperationTracker {
constructor(db) {
this.db = db;
}
async startOperation(taskId, operationType, request) {
await this.db.operations.insert({
task_id: taskId,
type: operationType,
status: 'submitted',
request: request,
created_at: new Date(),
updated_at: new Date()
});
}
async updateStatus(taskId, status, result = null) {
await this.db.operations.update(
{ task_id: taskId },
{
status: status,
result: result,
updated_at: new Date()
}
);
}
async getPendingOperations() {
return this.db.operations.find({
status: { $in: ['submitted', 'working', 'input-required'] }
});
}
}
```
### Handle Restarts Gracefully
Resume tracking after orchestrator restarts:
```javascript theme={null}
async function onStartup() {
const tracker = new AsyncOperationTracker(db);
const pending = await tracker.getPendingOperations();
for (const operation of pending) {
// Check current status on server
const response = await adcp.call('get_task_status', {
task_id: operation.task_id,
include_result: true
});
// Update local state
await tracker.updateStatus(operation.task_id, response.status, response);
// Resume polling if still pending
if (['submitted', 'working'].includes(response.status)) {
startPolling(operation.task_id);
}
}
}
```
Restart recovery also preserves continuation generations. When resuming pause
A produces pause B, B must be durable and discoverable from the operation
before A is consumed. See [Resumability and continuation
generations](/dist/docs/3.2.8/building/by-layer/L3/async-identity-and-convergence#resumability-and-continuation-generations).
## Best Practices
1. **Design async first** - Assume any operation could take time
2. **Persist state** - Don't rely on in-memory tracking
3. **Handle restarts** - Resume tracking on startup
4. **Implement timeouts** - Don't wait forever
5. **Show progress** - Keep users informed
6. **Support cancellation** - Let users cancel long operations
7. **Audit trail** - Log all status transitions
## Next Steps
* **Webhooks**: See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for push notifications instead of polling
* **Task Lifecycle**: See [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle) for status handling details
* **Orchestrator Design**: See [Orchestrator Design](/dist/docs/3.2.8/building/operating/orchestrator-design) for production patterns
# Compliance test controller
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller
Optional sandbox tool that lets the storyboard runner walk full lifecycle state machines by triggering seller-side transitions deterministically.
# Compliance test controller
> [!NOTE]
>
> **The compliance test controller is a dev/staging-only affordance, not a production-time concept.** AgenticAdvertising.org Verified (Sandbox) grading does not require or use it. The compliance heartbeat drives storyboards against the seller's registered production URL with `account.sandbox: true` on every request, and the seller's production stack is responsible for honoring the flag — no controller endpoint needed.
>
> Specialism certification under Verified (Spec) is different: any selected storyboard with `controller_seeding: true` requires a registered dev or staging endpoint that exposes the seed scenarios used by that storyboard. Sellers need only implement the scenarios required by the specialisms they certify; they do not need the full controller surface.
>
> Sellers MAY implement the controller in their dev or staging environment to support their own integration testing — walking lifecycle state machines deterministically, seeding fixtures, forcing transitions that would otherwise require waiting for real time. That's its purpose. It MUST NOT be exposed on production deployments (see [Sandbox gating](#sandbox-gating) below).
>
> Confused about how the controller relates to AgenticAdvertising.org Verified (Sandbox)? See [#4379](https://github.com/adcontextprotocol/adcp/issues/4379) for the framing decision: (Sandbox) attests "real production endpoint correctly handles sandbox-flagged traffic across the full storyboard suite." The controller is the developer-side affordance for deterministic testing and Verified (Spec) specialism fixtures, not the production grading mechanism.
AdCP defines lifecycle state machines for accounts, creatives, media buys, SI sessions, and delivery reporting. Many transitions in these state machines are seller-initiated — creative approval, account suspension, budget depletion, delivery accrual. A storyboard runner can only exercise buyer-initiated flows, leaving seller-initiated transitions untested.
The **compliance test controller** is an optional tool sellers expose in their dev/staging environment to support deterministic local testing. It allows a runner to trigger seller-side state transitions on demand, enabling end-to-end lifecycle verification during development.
## Motivation
Without a test controller, compliance testing is observational: fire an action, read back whatever state exists, move on. This catches schema violations but not behavioral ones.
| Track | Observational (today) | Deterministic (with controller) |
| - | - | - |
| **Creative** | Sync → observe initial status | Walk `processing` → `approved` → `archived`; force `rejected` with reason |
| **Account** | Read existing statuses | Force `suspended` → verify operation gates → reactivate |
| **SI sessions** | Initiate → message → terminate | Force `terminated` with timeout reason → verify [`SESSION_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-session-not-found) on next call |
| **Reporting** | Call [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) → hope data exists | Simulate delivery → verify rollups |
| **Budgeting** | Create buy with budget → read back | Simulate spend to threshold → verify alerts and `payment_required` |
| **Media buy** | Create → pause → resume | Force seller-initiated `rejected` → verify terminal state |
## Sandbox gating
Sellers MUST NOT expose `comply_test_controller` on production deployments — to anyone, on any surface. The tool MUST be absent from `tools/list` (MCP) and from the agent card's `skills[]` (A2A); the `compliance_testing` block MUST be absent from [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities); dispatch MUST return the transport's standard unknown-tool error (e.g., JSON-RPC `-32601 Method not found` for MCP, the unknown-skill rejection for A2A) — indistinguishable from the same-transport response of a seller that does not implement the tool. A production deployment that exposes the tool on any of these surfaces is non-conformant regardless of whether dispatch is gated.
The canonical pattern is two deployments: one production (no controller wired), one sandbox/staging (controller wired for all comers). Sellers expose `comply_test_controller` only on sandbox/staging deployments; any principal that can authenticate to such a deployment can call it.
Sellers MAY instead run a single deployment with mixed sandbox/live principals and project the tool per-principal, gating on the resolved account's mode. This is an implementation pattern, not the canonical model. Sellers picking this pattern MUST gate all three surfaces consistently: `tools/list` (or `skills[]`), the `compliance_testing` capability block, and dispatch. Partial projection — e.g., gating `tools/list` but leaving the `compliance_testing` block visible to live principals, or returning [`FORBIDDEN`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) (rather than unknown-tool) to a live principal who probes by name — is non-conformant; it reopens the discovery side channel that deployment-scoping closes.
`FORBIDDEN` is reserved for the in-sandbox case where the caller is authorized to call the controller but `params` reference a non-sandbox account. Sandbox gating is enforced per-request on the account reference, not just at tool registration time.
The mechanism for provisioning sandbox credentials and for separating production from sandbox/staging deployments is seller-specific and out of scope for this spec. Sellers MUST document their sandbox access mechanism so storyboard runners can connect appropriately.
The storyboard runner MUST treat the presence of `comply_test_controller` in `tools/list` (or `skills[]`) or the presence of the `compliance_testing` block in `get_adcp_capabilities` on a connection it believes is production as a hard conformance failure.
## Tool definition
**Schemas**: [`comply-test-controller-request.json`](https://adcontextprotocol.org/schemas/3.2.8/compliance/comply-test-controller-request.json) | [`comply-test-controller-response.json`](https://adcontextprotocol.org/schemas/3.2.8/compliance/comply-test-controller-response.json)
Sellers that implement compliance test controller MUST:
* Only expose the tool in sandbox mode (see sandbox gating above)
* Enforce the same state transition rules as production — invalid transitions MUST return errors
* Reflect forced state changes in subsequent reads ([`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives), [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys), etc.)
```json theme={null}
{
"name": "comply_test_controller",
"description": "Triggers seller-side state transitions for compliance testing. Sandbox only.",
"inputSchema": {
"type": "object",
"properties": {
"scenario": {
"type": "string",
"enum": [
"list_scenarios",
"force_creative_status",
"force_creative_purge",
"force_account_status",
"force_media_buy_status",
"force_media_buy_purge",
"compact_product_lifecycle_probe",
"compact_direct_buy_lifecycle_probe",
"reporting_core_lifecycle_probe",
"force_create_media_buy_arm",
"force_get_products_arm",
"force_get_signals_arm",
"force_get_creative_features_arm",
"force_task_completion",
"force_session_status",
"simulate_delivery",
"simulate_budget_spend",
"seed_account",
"seed_rights_grant",
"seed_product",
"seed_pricing_option",
"seed_creative",
"seed_plan",
"seed_media_buy",
"seed_creative_format",
"seed_measurement_catalog",
"query_upstream_traffic",
"query_provenance_audit_observations",
"force_upstream_unavailable"
],
"description": "The seller-side transition or fixture-seed to trigger."
},
"params": {
"type": "object",
"description": "Scenario-specific parameters. Omit for list_scenarios. force_creative_status: {creative_id, status, rejection_reason?}. force_creative_purge: {creative_id, purge_kind?, reason_code?, reason_detail?}. force_account_status: {account_id, status}. force_media_buy_status: {media_buy_id, status, rejection_reason?}. force_media_buy_purge: {media_buy_id}. compact_product_lifecycle_probe: {operation: prepare, product_id} or {operation: expire_proposal, proposal_id}. compact_direct_buy_lifecycle_probe: {operation: prepare, product_id}. reporting_core_lifecycle_probe: {operation: prepare | publish_zero_row | publish_nonempty | restate_snapshot | omit_obligation | advance_past_status_deadline | advance_past_escalation}, {operation: advance_time, target_health: delayed | action_required}, or {operation: restate_after_received, received_reporting_revision_id, advance_to?: within_grace | past_grace}. force_create_media_buy_arm: {arm, task_id?, message?} - task_id required when arm = submitted. force_get_products_arm: {arm, task_id?, message?, reason?, suggestions?} - task_id required when arm = submitted; reason required when arm = rejected. force_get_signals_arm: {arm, task_id?, message?} - task_id required when arm = submitted. force_get_creative_features_arm: {arm: submitted, task_id, evaluation_id, message?} or {arm: completed, result}. force_task_completion: {task_id, result}. force_session_status: {session_id, status, termination_reason?}. simulate_delivery: {media_buy_id, delivery_date?, impressions?, clicks?, reported_spend?, conversions?, reach?, frequency?, reach_window?, viewability?}. simulate_budget_spend: {account_id|media_buy_id, spend_percentage}. seed_account: {account_id, fixture?}. seed_rights_grant: {rights_id, fixture?}. seed_product: {product_id, fixture?}. seed_pricing_option: {product_id, pricing_option_id, fixture?}. seed_creative: {creative_id, fixture?}. seed_plan: {plan_id, fixture?}. seed_media_buy: {media_buy_id, fixture?}. seed_creative_format: {format_id, fixture?} (deprecated named-format compatibility tests only). seed_measurement_catalog: {vendor, metrics[]}. query_upstream_traffic: {since_timestamp?, endpoint_pattern?, limit?, attestation_mode?, identifier_value_digests?}. query_provenance_audit_observations: {creative_id}. force_upstream_unavailable: {tool, upstream_name?}."
}
},
"required": ["scenario"]
}
}
```
> [!NOTE]
>
> The `params` description inlines param shapes for each scenario because MCP clients (including LLMs) read descriptions, not conditional schema branches. For formal validation schemas suitable for SDK code generation, see the per-scenario definitions below.
## Scenarios
### `force_creative_status`
Transitions a creative to the specified status. The seller MUST enforce valid transitions per the [creative lifecycle state machine](/dist/docs/3.2.8/creative/specification#creative-status-lifecycle).
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `creative_id` | string | Yes | Creative to transition |
| `status` | `processing` \| `pending_review` \| `approved` \| `suspended` \| `rejected` \| `archived` | Yes | Target status |
| `rejection_reason` | string | When `status` = `rejected` | Reason for rejection |
| `reason_code` | CreativeEventReasonCode | No | Reason code for the lifecycle transition |
| `reason_detail` | string | No | Human-readable detail for the lifecycle transition |
**Example:**
```json theme={null}
{
"scenario": "force_creative_status",
"params": {
"creative_id": "cr-123",
"status": "rejected",
"reason_code": "policy_revocation",
"rejection_reason": "Brand safety policy violation"
}
}
```
### `force_account_status`
Transitions an account to the specified status. The seller MUST enforce the [account lifecycle rules](/dist/docs/3.2.8/accounts/overview#account-status-lifecycle) — terminal states (`rejected`, `closed`) cannot be exited.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `account_id` | string | Yes | Account to transition |
| `status` | `active` \| `pending_approval` \| `rejected` \| `payment_required` \| `suspended` \| `closed` | Yes | Target status |
**Example:**
```json theme={null}
{
"scenario": "force_account_status",
"params": {
"account_id": "acct-456",
"status": "payment_required"
}
}
```
### `force_media_buy_status`
Transitions a media buy to the specified status. The seller MUST enforce the media buy lifecycle — `rejected` is only valid from `pending_creatives` or `pending_start`.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `media_buy_id` | string | Yes | Media buy to transition |
| `status` | `pending_creatives` \| `pending_start` \| `active` \| `paused` \| `completed` \| `rejected` \| `canceled` | Yes | Target status |
| `rejection_reason` | string | When `status` = `rejected` | Reason for rejection |
**Example:**
```json theme={null}
{
"scenario": "force_media_buy_status",
"params": {
"media_buy_id": "mb-789",
"status": "rejected",
"rejection_reason": "Policy violation"
}
}
```
### `force_media_buy_purge`
Physically removes the named sandbox MediaBuy while leaving the seller's
idempotency ledger untouched. This scenario exists to test replay after resource
deletion; it MUST NOT delete, shorten, or rewrite an idempotency entry. Repeating
the controller call is naturally idempotent. A successful purge uses the
`StateTransitionSuccess` response shape and reports both `previous_state` and
`current_state: "purged"`.
Sellers advertise this scenario only when they can guarantee it never reaches
production data.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `media_buy_id` | string | Yes | Sandbox MediaBuy to purge without touching its idempotency ledger |
```json theme={null}
{
"scenario": "force_media_buy_purge",
"params": {
"media_buy_id": "mb-789"
},
"account": {
"sandbox": true
}
}
```
### `compact_product_lifecycle_probe`
Prepares deterministic sandbox behavior for the compact AdCP 3.2 product,
proposal, and resulting MediaBuy lifecycle, or advances one committed proposal
strictly beyond its hold deadline. Sellers advertise this scenario only when
they expose
[`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products), [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals), [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals), [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals),
[`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal), [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy), and [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys); the 3.x [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) compatibility facades remain optional.
`operation: "prepare"` binds the seeded `product_id` to the caller's
authenticated sandbox account and principal for the current compliance run.
For requests that select exactly that product, the seller MUST make each
ordinary lifecycle call deterministic:
* `list_products` returns `outcome: "listed"` with the prepared product;
* `request_proposals` returns a synchronous `outcome: "proposed"` draft rather
than `submitted` or `rejected`;
* `refine_proposals(action: "finalize")` returns a synchronous `finalized`
committed hold rather than `submitted`, `hold_unavailable`, or `batch_aborted`;
* `decline_proposals` returns `declined`;
* `accept_proposal` returns synchronous `status: "completed"` unless the exact
proposal has since been declined or expired. A successful acceptance returns
the initial MediaBuy `revision` and lifecycle state, preserves the committed
proposal ID and terms digest, and exposes a self-serve decrease-only budget
action through `control_media_buy`;
* a valid `control_media_buy` request with the current revision and a lower
`daily_budget_cap` returns synchronous `status: "completed"`, increments the
MediaBuy revision, and preserves its lifecycle state; and
* `get_media_buys` immediately reads back the applied cap, post-control
revision, lifecycle state, acceptance/control revision history, and exact
accepted-proposal linkage.
The seller still derives proposal terms from the request. When the brief states
an explicit budget or flight, the deterministic proposal carries those resolved
values in `commercial_terms` so compatibility-facade probes can repeat the
exact committed terms. Exact retries continue to use each business tool's
normal idempotency cache; preparing the product does not override replay
semantics or make an out-of-envelope increase valid.
`operation: "expire_proposal"` targets a committed proposal issued under the
same sandbox account and principal. The controller advances its effective clock
to the smallest supported instant strictly greater than the proposal's stored
`expires_at`, processes the hold lapse before returning, and reports
`simulated.expiry_processed: true`, `simulated.proposal_id`, and the applied
`simulated.target_time`. It MUST NOT accept a caller-supplied expiry timestamp.
Replaying an identical successful controller-induced expiry returns the same
successful result and `target_time`, including after a lost response. Unknown
or cross-principal IDs return [`NOT_FOUND`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes). A proposal that was never an eligible
committed hold, or whose hold ended through another transition, returns
[`INVALID_STATE`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes).
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `operation` | `prepare` \| `expire_proposal` | Yes | Probe operation |
| `product_id` | string | When `operation` = `prepare` | Seeded product whose compact lifecycle becomes deterministic |
| `proposal_id` | string | When `operation` = `expire_proposal` | Committed proposal whose effective clock advances strictly beyond its stored hold deadline |
The two identity parameters are mutually exclusive. Supplying the identity for
the other operation is invalid.
**Prepare request:**
```json theme={null}
{
"account": {
"sandbox": true
},
"scenario": "compact_product_lifecycle_probe",
"params": {
"operation": "prepare",
"product_id": "compact_lifecycle_video"
}
}
```
**Prepare response:**
```json theme={null}
{
"success": true,
"simulated": {
"prepared": true,
"product_id": "compact_lifecycle_video"
}
}
```
**Expiry request:**
```json theme={null}
{
"account": {
"sandbox": true
},
"scenario": "compact_product_lifecycle_probe",
"params": {
"operation": "expire_proposal",
"proposal_id": "proposal_committed_123"
}
}
```
**Expiry response:**
```json theme={null}
{
"success": true,
"simulated": {
"expiry_processed": true,
"proposal_id": "proposal_committed_123",
"target_time": "2026-10-01T12:00:00.001Z"
}
}
```
### `compact_direct_buy_lifecycle_probe`
Prepares deterministic sandbox behavior for the compact AdCP 3.2 direct-buy
lifecycle. Sellers advertise this scenario only when they expose
[`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products),
[`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products),
[`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy), and
[`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys). Deprecated
[`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products), `create_media_buy`, and [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) facades are not part
of this scenario.
`operation: "prepare"` binds the seeded `product_id` to the caller's
authenticated sandbox account and principal for the current compliance run.
For requests that select exactly that product, the seller MUST make the direct
lifecycle deterministic:
* `list_products` returns synchronous `outcome: "listed"` with the prepared
product, one stable pricing option, `feed_version`, and a separate
`pricing_version`;
* the product and resulting MediaBuy expose a self-serve decrease-only budget
control through `control_media_buy`;
* `buy_products` returns synchronous `status: "completed"` with a non-terminal
MediaBuy, its current `revision`, and an accepted proposal that preserves the
selected product and pricing option, binds `source_feed_version` and
`source_pricing_version`, and carries stable `proposal_id` and `terms_digest`
values;
* a valid `control_media_buy` request that applies a lower `daily_budget_cap`
returns synchronous `status: "completed"`, increments the MediaBuy revision,
and preserves the MediaBuy's lifecycle status; and
* `get_media_buys` immediately reads back the applied cap, lifecycle status,
revision returned by `control_media_buy`, and the creation/control revision
history needed to prove that the mutation incremented the token. Its
`accepted_proposal_id`, `accepted_proposal_terms_digest`, and embedded
accepted proposal preserve the exact proposal identity and digest returned by
`buy_products`.
Exact retries continue to use each business tool's normal idempotency cache.
Preparing the product does not override replay semantics or make an
out-of-envelope increase valid.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `operation` | `prepare` | Yes | Prepare the seeded direct-buy lifecycle |
| `product_id` | string | Yes | Seeded product whose direct-buy lifecycle becomes deterministic |
**Prepare request:**
```json theme={null}
{
"account": {
"sandbox": true
},
"scenario": "compact_direct_buy_lifecycle_probe",
"params": {
"operation": "prepare",
"product_id": "compact_direct_buy_video"
}
}
```
**Prepare response:**
```json theme={null}
{
"success": true,
"simulated": {
"prepared": true,
"product_id": "compact_direct_buy_video"
}
}
```
### `reporting_core_lifecycle_probe`
Prepares and advances a deterministic, caller/account-scoped
[`reporting.core`](/dist/docs/3.2.8/media-buy/reporting-core-implementation-guide)
fixture without waiting for real reporting boundaries. This lets a learner or
storyboard observe that an obligation exists before its first report, then
exercise deadline-based health, publish an explicit empty revision, or
restate a provisional revision after a buyer has read it — including a
restatement bound to a revision the caller already reported as `received`. Two
further operations cross the consumer-status deadline and the
consumer-mismatch escalation boundary, so the counted-silence and escalation
projections are gradable without a wall-clock wait.
The fixture is Core-only: no destination, materialization, readiness doorbell,
canonical digest, or receipt is implied.
| Operation | Additional params | Required observable result |
| - | - | - |
| **prepare** | none | Install a fixed hourly configuration and set `simulated_now` to `2026-08-01T01:30:00.000Z`, past the first `period.end` but before `expected_at`. A `periods` read returns one `waiting` obligation with no revision. |
| **advance_time** | `target_health: delayed` | Set `simulated_now` to `2026-08-01T02:05:00.000Z`, strictly after `expected_at`. The same obligation becomes `delayed` with a stable issue while automated recovery remains open. |
| **advance_time** | `target_health: action_required` | Set `simulated_now` to `2026-08-01T04:05:00.000Z`, strictly after the returned `recovery_deadline`. The same obligation becomes `action_required`. |
| **publish_zero_row** | none | Commit an immutable current revision with `row_count: 0`. The obligation becomes satisfied; this is empty reporting, not missing reporting. |
| **publish_nonempty** | none | Commit the fixed two-row Core test vector from the [`reporting_core`](/compliance/latest/universal/reporting-core.yaml) storyboard for the prepared obligation: its literal rows and `impressions` control total, under the fixed `reporting_revision_id` `reporting-revision.ecc62efa00946aa1e2788ad9`, so `revision_content_sha256` equals the vector's RFC 8785/JCS digest `5199a776b3a99915f084e16c921b2e501fcedd949017236d51a2303c5c2f5cd1`. |
| **restate_snapshot** | none | Commit a new immutable snapshot revision that names the current snapshot in `supersedes_reporting_revision_id`. Reject the operation when no snapshot exists or the current revision is official. |
| **restate_after_received** | `received_reporting_revision_id`, optional `advance_to: within_grace \| past_grace` | Same restatement, but only against the revision the caller already read. Reject the operation unless `received_reporting_revision_id` names the caller's current required revision; a seller advertising `consumer_status_task` MUST additionally require a current `received` consumer status from that caller naming it. Return `stale_received_grace_deadline` and set `simulated_now` inside it (`within_grace`, the default) or one second past it (`past_grace`). Repeating the call is convergent: it reuses the committed restatement and only moves the clock. |
| **omit_obligation** | none | Advance through a second elapsed period while deliberately suppressing its obligation. The response supplies the expected period and ID so a buyer can demonstrate denominator-based detection. Sandbox education only: this intentionally produces a non-conformant ledger. |
| **advance_past_status_deadline** | none | Move `simulated_now` strictly past the buyer's consumer-status deadline — `expected_at` plus the advertised `automated_recovery_window_seconds` — without recording any consumer status. The obligation is then counted in `obligation_counts.consumer_status_pending`, and nothing else in the response moves: silence raises no issue and changes no health. Return the crossed `consumer_status_deadline`. |
| **advance_past_escalation** | none | Move `simulated_now` strictly past the open `CONSUMER_STATUS_MISMATCH` issue's `opened_at` plus the advertised `consumer_mismatch_escalation_seconds`. Reject the operation when no mismatch is open. Return the issue's `issue_id` and `opened_at`, the crossed `consumer_mismatch_escalation_deadline`, and — when the open mismatch is a stale `received` — the still-future `stale_received_grace_deadline`, so a storyboard can grade that the escalation boundary takes precedence over the grace window rather than merely following it. |
Every successful response includes `account_id` and the applied
`simulated_now`. `prepare` returns the resolved configuration, generation
tuple, obligation ID, half-open period, `expected_at`, and `recovery_deadline`;
`advance_time` repeats the generation, obligation, and deadline identities;
`publish_zero_row` adds `reporting_revision_id`, `revision_content_sha256`,
`finality: "snapshot"`, and `row_count`; `restate_snapshot` returns those fields
for the new snapshot plus `supersedes_reporting_revision_id`;
`restate_after_received` returns those plus `received_reporting_revision_id`,
`restated_at`, and `stale_received_grace_deadline`;
`omit_obligation` instead returns `expected_reporting_obligation_id`,
`omitted_period`, and its `expected_at`;
`advance_past_status_deadline` returns `expected_at`,
`automated_recovery_window_seconds`, and the crossed
`consumer_status_deadline`; and `advance_past_escalation` returns `issue_id`,
`issue_opened_at`, `consumer_mismatch_escalation_seconds`,
`consumer_mismatch_escalation_deadline`, `expected_recommended_action`, and any
still-future `stale_received_grace_deadline`. Implementations choose fixture
identifiers — including the sandbox `account_id` — so callers capture the
returned values rather than guessing them. The one exception is
`publish_nonempty`, whose revision identity is part of the fixed test vector,
because the binding digest covers it.
`restate_after_received` exists so the
[stale-received grace projection](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status#consumer-status-mismatch)
can be graded live instead of only in a seller's own integration tests. A buyer
that consumed exactly what the seller required, and is then overtaken by a
restatement, is `delayed` until `stale_received_grace_deadline` and
`action_required` after it. Calling the operation twice — once with
`advance_to: "within_grace"`, once with `advance_to: "past_grace"` — grades both
sides of that boundary against one committed restatement, and the returned
deadline stays anchored to the restatement rather than to the poll.
First provision the sandbox account and install the Core configuration. Copy
the returned `accounts[0].account_id`; use that durable ID for every controller
and status call below.
```json theme={null}
{
"adcp_version": "3.2",
"idempotency_key": "reporting-core-lab-0001",
"accounts": [{
"brand": { "domain": "reporting-lab.example" },
"operator": "pinnacle-agency.example",
"billing": "operator",
"sandbox": true,
"reporting_delivery_configs": [{
"delivery_config_id": "training-pacing-core",
"delivery_config_version": 1,
"offering_id": "pacing-hourly-core",
"active": true,
"feed_purpose": "pacing",
"report_definition_id": "training_delivery_summary_v1",
"reporting_profile": "training_delivery_summary_v1",
"scope": { "all_media_buys": true },
"coverage_requirement": "full",
"required_finality": "snapshot",
"reconciliation_mode": "delivery_only",
"schedule": {
"period_duration": "PT1H",
"alignment": "utc",
"delivery_sla": "PT1H"
}
}]
}]
}
```
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": { "operation": "prepare" }
}
```
Read the waiting obligation through [`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status):
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts" },
"view": "periods"
}
```
Then advance past its SLA to make the missing revision operationally visible:
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": {
"operation": "advance_time",
"target_health": "delayed"
}
}
```
The corresponding escalation, publication, and deliberate omission calls are:
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": { "operation": "advance_time", "target_health": "action_required" }
}
```
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": { "operation": "publish_zero_row" }
}
```
To grade the stale-received grace window, first publish a revision and record a
`received` consumer status for it, then restate it against that exact ID:
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": {
"operation": "restate_after_received",
"received_reporting_revision_id": "rev_copy_from_publish_zero_row",
"advance_to": "within_grace"
}
}
```
Repeat the identical call with `"advance_to": "past_grace"` to cross the
returned `stale_received_grace_deadline` without committing a second
restatement.
The two consumer-status boundaries have their own operations. Neither takes
parameters, because the seller — not the caller — owns the windows being
crossed:
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": { "operation": "advance_past_status_deadline" }
}
```
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": { "operation": "advance_past_escalation" }
}
```
`advance_past_status_deadline` grades counted silence: the response's
`consumer_status_deadline` is `expected_at` plus the seller's advertised
`automated_recovery_window_seconds`, and a `get_reporting_status` summary read
past it must raise `obligation_counts.consumer_status_pending` while leaving
`health` and every other count exactly where they were.
`advance_past_escalation` grades the escalation commitment: the returned
`issue_opened_at` is the open issue's own `opened_at`, never the poll time, so
a re-emission cannot reset the window.
Reset with `prepare` before the negative fixture, then call:
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_copy_from_sync_accounts", "sandbox": true },
"scenario": "reporting_core_lifecycle_probe",
"params": { "operation": "omit_obligation" }
}
```
### `force_create_media_buy_arm`
Shapes the next [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) call from the caller's authenticated sandbox account into a specific response arm. v1 supports two arms: `submitted` (the async task envelope, no `media_buy_id` yet) and `input-required` (the errors-branch). Unlike `force_media_buy_status`, no entity transitions — there is no media buy yet — so the response carries `forced.arm` rather than `previous_state`/`current_state`.
The submitted-arm wire shape is otherwise implementation-dependent: most sellers route most buys synchronously and no buyer-side request shape reliably triggers async. This scenario lets storyboards pin the arm so a regressed seller (e.g., emitting `media_buy_id` under `status: submitted`) cannot pass conformance silently.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `arm` | `submitted` \| `input-required` | Yes | Target response arm for the next `create_media_buy` call |
| `task_id` | string | When `arm` = `submitted` | Deterministic task handle (max 128 chars) the seller MUST emit verbatim on the submitted envelope and MUST accept on subsequent `tasks/get` polls. Sandbox task_ids are caller-opaque strings; production task-id format rules do not apply. |
| `message` | string | No | Human-readable explanation surfaced verbatim on the seller's `create_media_buy` response. Plain text, max 2000 characters. Buyers consuming the resulting response MUST apply the prompt-injection sanitization documented for [`message` on the submitted envelope](https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-response.json) — this scenario is the natural place for a runner to inject adversarial strings to test that buyer-side sanitization. |
**Example:**
```json theme={null}
{
"scenario": "force_create_media_buy_arm",
"params": {
"arm": "submitted",
"task_id": "task_async_signed_io_q2",
"message": "Awaiting IO signature from sales team; typical turnaround 2–4 hours"
}
}
```
**Response.** A `ForcedDirectiveSuccess` shape carrying the registered directive:
```json theme={null}
{
"success": true,
"forced": {
"arm": "submitted",
"task_id": "task_async_signed_io_q2"
},
"message": "Next create_media_buy call will return the submitted arm with task_id task_async_signed_io_q2"
}
```
`forced.task_id` is present only when `arm: submitted`.
**Consumption and idempotency.** The directive is keyed to the caller's authenticated sandbox account (account + principal pair) and is consumed by the next `create_media_buy` call from that account. Subsequent calls without a fresh directive return the seller's default arm. Buyer-side `idempotency_key` semantics are unchanged: if the caller replays a `create_media_buy` request that already consumed a directive, the seller MUST replay the cached response (the request idempotency cache wins) and MUST NOT re-evaluate against the now-empty directive slot. Sellers MUST NOT match a directive against a `create_media_buy` call from a different account or principal, even within the same transport connection. A second `force_create_media_buy_arm` call before the directive is consumed overwrites the prior one.
### `force_get_products_arm` / `force_get_signals_arm` / `force_get_creative_features_arm`
Shape the next curated discovery call from the caller's authenticated sandbox
account (account + principal pair) into a status-specific response arm.
`force_get_products_arm` applies only to [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) with
`buying_mode: "brief"` or `"refine"`.
The `rejected` arm is introduced in AdCP 3.2. Callers using release-precision
negotiation pin `adcp_version: "3.2"`, while callers using the
legacy major-only envelope can send `adcp_major_version: 3` when the seller
resolves that request to 3.2. The controller call and matching `get_products`
call MUST negotiate the same served release.
`force_get_signals_arm` applies only to [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) with
`discovery_mode: "brief"` (or omitted, where brief is the default). Wholesale
feed reads are synchronous feed access and MUST NOT consume these directives or
return the Submitted arm solely because a directive exists.
`force_get_creative_features_arm` applies to the next [`get_creative_features`](/dist/docs/3.2.8/governance/creative/get_creative_features) call. Its `submitted` arm requires both `task_id` and `evaluation_id`; the provider returns those values verbatim on the acknowledgement, and `force_task_completion` requires the terminal result to preserve the same `evaluation_id`. Its `completed` arm requires a schema-valid terminal success `result`, which the provider returns verbatim on the next matching call. This makes synchronous replay and optional economics deterministic without requiring every provider to complete naturally within the initial response window.
The directive exists for the same reason as `force_create_media_buy_arm`:
buyers cannot reliably trigger async discovery or a seller-controlled business
decline from request shape alone, but conformance needs deterministic coverage.
The submitted envelope carries `status` and `task_id`, plus `evaluation_id` for
creative-feature evaluations and optional advisory fields such as `message`;
terminal `products[]`, `proposals[]`, `signals[]`, or feature `results[]` land
on task completion through [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) (legacy
`tasks/get`) and any registered push notification. The rejected get_products
arm carries `status: "rejected"`, `reason`, and optional `suggestions[]`, with no
products, proposals, errors, or envelope-level adcp_error.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `arm` | `submitted` \| `completed` \| `rejected` | Yes | Target response arm for the next matching call. `completed` is valid only for `force_get_creative_features_arm`; `rejected` is valid only for `force_get_products_arm`. |
| `task_id` | string | When `arm` = `submitted` | Deterministic task handle (max 128 chars) the seller MUST emit verbatim on the submitted envelope and MUST accept on subsequent polling. |
| `evaluation_id` | string | For the creative `submitted` arm | Deterministic provider evaluation identity returned on the submitted acknowledgement and terminal success. |
| `result` | object | For the creative `completed` arm | Schema-valid `get_creative_features` terminal success returned verbatim on the next matching call. |
| `message` | string | No | Human-readable explanation surfaced verbatim on the submitted discovery response. Plain text, max 2000 characters. |
| `reason` | string | When `arm` = `rejected` | Sanitized buyer-facing decline reason emitted verbatim on the next get_products response. Plain text, max 2000 characters. |
| `suggestions` | string\[] | No | Actionable alternatives emitted on the next get_products rejection. |
**Examples:**
```json theme={null}
{
"scenario": "force_get_products_arm",
"account": {
"brand": {
"domain": "acmeoutdoor.example"
},
"operator": "pinnacle-agency.example",
"sandbox": true
},
"params": {
"arm": "submitted",
"task_id": "task_async_products_acme_q3",
"message": "Custom product curation queued; typical turnaround 10 minutes"
}
}
```
```json theme={null}
{
"adcp_version": "3.2",
"adcp_major_version": 3,
"scenario": "force_get_products_arm",
"account": {
"brand": {
"domain": "acmeoutdoor.example"
},
"operator": "pinnacle-agency.example",
"sandbox": true
},
"params": {
"arm": "rejected",
"reason": "The requested budget is below the minimum for this inventory.",
"suggestions": ["Increase the campaign budget."]
}
}
```
```json theme={null}
{
"scenario": "force_get_signals_arm",
"account": {
"brand": {
"domain": "novamotors.example"
},
"operator": "pinnacle-agency.example",
"sandbox": true
},
"params": {
"arm": "submitted",
"task_id": "task_async_signals_nova_ev",
"message": "Signal discovery queued; typical turnaround 10 minutes"
}
}
```
**Response.** These scenarios return the same `ForcedDirectiveSuccess` shape as
`force_create_media_buy_arm`. A `submitted` directive carries `forced.arm` and
`forced.task_id`; a `rejected` get-products directive carries `forced.arm`,
`forced.reason`, and optional `forced.suggestions`; a completed creative
directive carries `forced.arm: "completed"`.
**Consumption and idempotency.** The directive is keyed to the caller's
authenticated sandbox account (account + principal pair) and consumed by the
next matching discovery call from that same account. The seller MUST NOT match a
product directive against `get_signals`, a signal directive against
`get_products`, a brief/refine directive against wholesale mode, or any
directive against a different account or principal. A second directive for the
same operation and principal before consumption overwrites the prior directive.
The directive is consumed exactly once. Product and signal discovery calls are
reads, so repeating them after consumption is a new read and is not guaranteed
to replay the forced response. `get_creative_features` is replay-protected:
repeating the exact request with its original `idempotency_key` returns the
cached forced response even though the directive slot has already been consumed.
### `force_task_completion`
Resolves a previously-submitted async task to `completed` with a buyer-supplied result payload. The companion to the `force_*_arm` scenarios: those scenarios drive the seller into a submitted envelope; this one closes the loop by transitioning the task store entry to `completed` and stamping the registered result. The buyer observes completion via the seller's push notification to `push_notification_config.url` and via subsequent `get_task_status` calls reporting `status: "completed"`. When the caller requests `include_result: true`, `get_task_status` returns the typed terminal result payload that matches the original async operation.
The submitted → completed lifecycle is otherwise non-deterministic — real task completions ride on out-of-band signals (IO countersignature, batch processor cron, governance human review). Storyboards cannot wait. This scenario lets a runner pin the completion deterministically immediately after registering the directive, so the buyer-side polling assertion fires on the same wire shape buyers will observe in production.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `task_id` | string | Yes | Task to resolve. MUST resolve within the caller's authenticated sandbox account; sellers MUST return [`NOT_FOUND`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) (not [`FORBIDDEN`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes), per the multi-tenant convention above) for `task_id`s belonging to other accounts. Typically captured from the prior `create_media_buy` submitted-envelope response (or registered via `force_create_media_buy_arm`). |
| `result` | [`async-response-data`](https://adcontextprotocol.org/schemas/3.2.8/core/async-response-data.json) | Yes | Completion payload to record. Validates against the same `anyOf` union the push-notification webhook and `tasks/get` polling responses use. For `create_media_buy`, this is a `CreateMediaBuyResponse` with `media_buy_id` and `packages`. Sellers MUST emit [`INVALID_PARAMS`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) if `result` does not validate against the response branch for the task's original method. Sellers MAY reject `result` payloads exceeding 256 KB with `INVALID_PARAMS`; storyboards MUST stay below this. |
**Example:**
```json theme={null}
{
"scenario": "force_task_completion",
"params": {
"task_id": "task_async_signed_io_q2",
"result": {
"media_buy_id": "mb_async_signed_io_q2",
"status": "active",
"packages": [
{ "package_id": "pkg-0", "product_id": "async_signed_io_q2", "budget": 30000 }
]
}
}
}
```
**Response.** Returns a state-transition success shape:
```json theme={null}
{
"success": true,
"previous_state": "submitted",
"current_state": "completed",
"message": "Task task_async_signed_io_q2 transitioned from submitted to completed"
}
```
Source state MUST be `submitted`, `working`, or `input-required`; any other source returns [`INVALID_TRANSITION`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes). Sellers MUST emit `NOT_FOUND` if `task_id` is unknown to the caller's account, and `INVALID_TRANSITION` if the task is already terminal (`completed` / `failed` / `canceled`). Forcing a task to `failed` is out of scope for this scenario; the input-required arm of `force_create_media_buy_arm` covers the buyer-input-needed failure path.
**Replay semantics.** An identical replay after successful completion is an idempotent no-op and reports `previous_state: "completed"` and `current_state: "completed"`. A replay with a different result after the task is terminal returns `INVALID_TRANSITION`; terminal results cannot be overwritten.
**Cross-protocol obligations.**
* **Push notifications.** If the buyer registered `push_notification_config.url` on the original `create_media_buy`, forcing completion MUST fire the webhook with the registered `result` payload (the canonical 3.0 delivery path for completion data). Otherwise the storyboard can only test polling for terminal status, not push delivery of the result.
* **`simulate_delivery` / `simulate_budget_spend`.** Once forced to completed with a valid `CreateMediaBuyResponse` carrying `media_buy_id`, the resulting media buy MUST be addressable by those scenarios. Round-tripping through `force_task_completion` is the supported path for storyboards that need a media buy without going through the synchronous flow.
**Buyer-side observation.** After this scenario runs, the registered `result` is delivered to the buyer's `push_notification_config.url` (3.0 canonical path) with all caller-supplied fields preserved. Sellers MAY augment with seller-controlled fields (e.g., `created_at`, `dsp_*` IDs, normalized currency casing) but MUST NOT overwrite caller-supplied values. A subsequent `tasks/get(task_id)` MUST return `status: "completed"`. The `result` payload is buyer-controlled in sandbox and round-trips through the seller's store — buyers receiving it via webhook MUST treat the payload as untrusted seller output (per AdCP convention) regardless of the fact that they originated the bytes. This makes `force_task_completion` the natural place for a runner to inject adversarial payloads when testing buyer-side sanitization on the webhook delivery path.
### `force_session_status`
Transitions an SI session to a terminal status. Enables testing timeout and termination scenarios that would otherwise require waiting for real timeouts. The `termination_reason` param simulates the cause so the storyboard runner can verify sellers report the correct reason in subsequent responses.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | Yes | Session to transition |
| `status` | `complete` \| `terminated` | Yes | Target terminal status |
| `termination_reason` | string | When `status` = `terminated` | Reason for termination (e.g., `session_timeout`, `host_terminated`, `policy_violation`) |
**Example:**
```json theme={null}
{
"scenario": "force_session_status",
"params": {
"session_id": "sess-abc",
"status": "terminated",
"termination_reason": "session_timeout"
}
}
```
### `simulate_delivery`
Injects synthetic delivery data for a media buy. Subsequent calls to [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) MUST reflect this data. Delivery simulation is additive — each call adds to existing delivery totals.
**Delivery and budget are independent systems.** `simulate_delivery` records what the ad server would report. `simulate_budget_spend` records what the billing system would track. A seller's production system may or may not couple these — the test controller does not assume coupling.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `media_buy_id` | string | Yes | Media buy to add delivery to |
| `delivery_date` | string (`YYYY-MM-DD`) | No | Calendar date, in the product's reporting timezone, assigned to this simulated batch for reporting-period tests |
| `impressions` | integer | No | Impressions to simulate |
| `clicks` | integer | No | Clicks to simulate |
| `reported_spend` | object | No | `{ amount: number, currency: string }` — spend as reported in delivery data, does not affect budget |
| `conversions` | integer | No | Conversions to simulate |
| `reach` | number | No | Unique reach count to surface at `totals.reach` |
| `frequency` | number | No | Average frequency per reach unit to surface at `totals.frequency` |
| `reach_window` | object | No | Measurement window for simulated reach/frequency. Shape: `{ kind: "cumulative" }`, `{ kind: "period", period: Duration }`, or `{ kind: "rolling", period: Duration }` |
| `viewability` | object | No | Canonical viewability block to surface at both the sole package's `viewability` and `totals.viewability`, including `measurable_impressions`, `viewable_impressions`, `viewable_rate`, `viewed_seconds`, optional `viewed_seconds_percentiles` / `viewed_seconds_histogram`, and `standard`. This media-buy-scoped form is valid only when the buy has one package; multi-package callers receive `INVALID_PARAMS` because the package attribution would be ambiguous. `standard` SHOULD be supplied whenever measured values are present |
When `delivery_date` is present, the controller records the batch as a dated
snapshot. A later `get_media_buy_delivery` request with date bounds includes
snapshots whose dates fall in the exact half-open interval
`[start_date, end_date)`: `start_date` is inclusive and `end_date` is exclusive.
Omitting date bounds preserves cumulative reporting. Implementations that only
store legacy undated simulations continue to expose their cumulative totals
when a caller supplies date bounds.
**Example:**
```json theme={null}
{
"scenario": "simulate_delivery",
"params": {
"media_buy_id": "mb-789",
"delivery_date": "2026-04-15",
"impressions": 10000,
"clicks": 150,
"reach": 4000,
"frequency": 2.5,
"reach_window": { "kind": "rolling", "period": { "interval": 7, "unit": "days" } },
"viewability": {
"measurable_impressions": 9000,
"viewable_impressions": 7200,
"viewable_rate": 0.8,
"viewed_seconds": 4.3,
"viewed_seconds_percentiles": {
"p25": 1.0, "p50": 2.5, "p75": 5.0, "p90": 9.0, "p95": 12.0
},
"viewed_seconds_histogram": [
{ "lower_bound_seconds": 0, "upper_bound_seconds": 1, "impressions": 1800 },
{ "lower_bound_seconds": 1, "upper_bound_seconds": 5, "impressions": 4950 },
{ "lower_bound_seconds": 5, "impressions": 2250 }
],
"standard": "mrc"
},
"reported_spend": { "amount": 150.00, "currency": "USD" }
}
}
```
### `simulate_budget_spend`
Simulates budget consumption to a specified percentage. Enables testing budget threshold alerts and `payment_required` transitions without waiting for real spend. This is the only scenario that affects account-level financial state.
After calling `simulate_budget_spend`, the seller MUST reflect the simulated consumption in [`get_account_financials`](/dist/docs/3.2.8/accounts/tasks/get_account_financials). Specifically:
* `total_spend` (or equivalent) MUST reflect the simulated amount
* `remaining_budget` (or equivalent) MUST be reduced accordingly
* Budget utilization percentages MUST match `spend_percentage`
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `account_id` | string | No | Account (for account-level budget) |
| `media_buy_id` | string | No | Media buy (for buy-level budget) |
| `spend_percentage` | number | Yes | Spend to this % of budget (0–100) |
At least one of `account_id` or `media_buy_id` is required. The target entity MUST have a non-zero budget configured — the controller SHOULD return `INVALID_PARAMS` if it does not.
**Example:**
```json theme={null}
{
"scenario": "simulate_budget_spend",
"params": {
"media_buy_id": "mb-789",
"spend_percentage": 95
}
}
```
### `seed_product`
Creates (or upserts) a product fixture with a caller-supplied `product_id` so subsequent storyboard steps can reference the product by stable ID. The controller MUST make the seeded product discoverable via `get_products` under the authenticated account unless the fixture explicitly marks it hidden.
**Why this scenario exists.** Storyboards hardcode fixture IDs like `"test-product"` and expect the seller to have a matching product. Without a seed scenario, every implementer rediscovers which IDs the conformance suite expects and has to alias them by hand. `seed_product` replaces that discovery with an explicit, storyboard-authored contract.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `product_id` | string | Yes | Stable identifier the storyboard will reference |
| `fixture` | object | No | Product shape. Minimum useful fields: `delivery_type`, `channels`, `pricing_options[]`, `format_options[]`. Sellers MAY fill in defaults for omitted fields. |
For vendor-metric precondition tests, prefer `seed_measurement_catalog` for the external vendor catalog. A product fixture may also carry `measurement_catalogs[]` entries shaped as `{ vendor, metrics[] }` as a compatibility fallback for local harnesses that need the product contract and referenced measurement snapshot in one fixture. If both are supplied for the same vendor, the explicit `seed_measurement_catalog` snapshot takes precedence for that compliance session.
**Example:**
```json theme={null}
{
"scenario": "seed_product",
"params": {
"product_id": "test-product",
"fixture": {
"delivery_type": "non_guaranteed",
"channels": ["display"],
"pricing_options": [
{ "pricing_option_id": "test-pricing", "pricing_model": "cpm", "currency": "USD", "floor_price": 1.0 }
],
"format_options": [{ "format_option_id": "display_300x250", "format_kind": "image", "params": { "width": 300, "height": 250 } }]
}
}
}
```
### `seed_pricing_option`
Adds (or upserts) a pricing option on an existing seeded product. Use this when a storyboard needs a specific pricing option that wasn't included in the initial `seed_product` call, or when the option's attributes need to diverge from the seller's default.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `product_id` | string | Yes | Parent product (must already exist — seed it first) |
| `pricing_option_id` | string | Yes | Stable identifier for the pricing option |
| `fixture` | object | No | Pricing option shape per the [`PricingOption`](https://adcontextprotocol.org/schemas/3.2.8/core/pricing-option.json) schema (`pricing_model`, `currency`, `floor_price` for auction-based, `fixed_price` for fixed, etc.) |
**Example:**
```json theme={null}
{
"scenario": "seed_pricing_option",
"params": {
"product_id": "test-product",
"pricing_option_id": "default",
"fixture": {
"pricing_model": "cpm",
"floor_price": 5.0,
"currency": "USD"
}
}
}
```
### `seed_creative`
Creates a creative fixture at a specific lifecycle status. Lets governance and delivery storyboards reference a pre-approved creative without round-tripping [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) first.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `creative_id` | string | Yes | Stable identifier |
| `fixture` | object | No | Creative shape. Typical fields: `status`, `format_kind`, `assets`, `click_through_url`. |
**Example:**
```json theme={null}
{
"scenario": "seed_creative",
"params": {
"creative_id": "campaign_hero_video",
"fixture": {
"status": "approved",
"format_kind": "video_hosted",
"assets": [{ "type": "video", "url": "https://example.com/hero.mp4" }]
}
}
}
```
### `seed_plan`
Creates a media plan fixture. Used by governance storyboards that assert against a specific plan without running the full briefing + proposal flow first.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `plan_id` | string | Yes | Stable identifier |
| `fixture` | object | No | Plan shape. Typical fields: `budget`, `brand`, `flight`, `line_items[]`. |
**Example:**
```json theme={null}
{
"scenario": "seed_plan",
"params": {
"plan_id": "gov_acme_q2_2027",
"fixture": {
"budget": { "total": 30000, "currency": "USD" },
"brand": { "domain": "acmeoutdoor.example" },
"flight": { "start": "2027-04-01", "end": "2027-06-30" }
}
}
}
```
### `seed_media_buy`
Creates a media buy fixture at a specified lifecycle state, bypassing the `create_media_buy` flow. Used by storyboards that need to assert governance or delivery behavior against a pre-existing buy.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `media_buy_id` | string | Yes | Stable identifier |
| `fixture` | object | No | Media buy shape. Typical fields: `status`, `packages[]`, `budget`, `flight`. |
**Example:**
```json theme={null}
{
"scenario": "seed_media_buy",
"params": {
"media_buy_id": "mb_acme_q2_2026_auction",
"fixture": {
"status": "active",
"packages": [{ "package_id": "pkg_001", "product_id": "test-product" }]
}
}
}
```
### `seed_measurement_catalog`
Seeds a measurement vendor's `get_adcp_capabilities.measurement.metrics[]` snapshot for the compliance session, when the seller's controller advertises this scenario. Media-buy storyboards use an explicit `comply_test_controller` step with this scenario to distinguish a product-level vendor metric capability from the external vendor-catalog discovery precondition. Storyboards may also carry this snapshot in `seed_product.fixture.measurement_catalogs[]` as a compatibility fallback for controllers whose SDK adapter set has not adopted the scenario yet. When both sources are present for the same vendor, the explicit `seed_measurement_catalog` seed is authoritative.
**Params:**
| Field | Type | Required | Description |
| - | - | - | - |
| `vendor` | BrandRef | Yes | Measurement vendor whose catalog is being seeded |
| `metrics` | object\[] | Yes | Catalog entries; each entry must include `metric_id` and may include the optional fields from `measurement.metrics[]` |
**Example:**
```json theme={null}
{
"scenario": "seed_measurement_catalog",
"params": {
"vendor": { "domain": "attentionvendor.example" },
"metrics": [
{
"metric_id": "attention_catalog_baseline",
"unit": "score",
"description": "Baseline attention metric present in this vendor catalog."
}
]
}
}
```
### Seeding semantics and ordering
> [!NOTE]
>
> In AdCP 3.2, IDs in a storyboard `fixtures:` block are run-scoped handles.
> Literal injection remains the compatibility default, and all rules in this
> section apply whenever the runner selects the `seed` strategy. A storyboard may
> separately opt a handle into `discover` or `construct` through explicit
> `fixture_resolution` rules. The seller never has to persist the authored
> literal when one of those strategies binds a seller-issued ID. See
> [Fixture handles and catalog resolution](/dist/docs/3.2.8/building/verification/conformance#fixture-handles-and-catalog-resolution).
* **Fixture shape.** `fixture` is kept permissive (`additionalProperties: true`) so storyboard authors can declare the minimum shape each test needs. Fixtures SHOULD conform to the corresponding domain schema (`core/product.json` for `seed_product`, `core/pricing-option.json` for `seed_pricing_option`, `media-buy/sync-creatives-request.json` creative-item shape for `seed_creative`, `core/media-buy.json` for `seed_media_buy`, the plan schema for `seed_plan`). `seed_measurement_catalog.metrics[]` mirrors `get_adcp_capabilities.measurement.metrics[]`. Sellers MAY reject clearly malformed fixtures with `INVALID_PARAMS`.
* **Idempotency on re-seed.** A second call with the same primary ID and a `fixture` equivalent to the first SHOULD succeed and return `success: true` with `previous_state: "existing"`. A second call with a **diverging** fixture MUST return `INVALID_PARAMS` with `error_detail` explaining which fields diverged — sellers MUST NOT merge or update silently. Storyboards that need to change fixture state mid-run MUST use `force_*` scenarios, not a re-seed. This keeps the same storyboard deterministic across sellers.
* **Foreign-key ordering.** The runner seeds fixtures in dependency order so sellers receive referenced parents before their children. The dependency DAG:
```
product ──┬─→ pricing_option
├─→ plan
└─→ media_buy
creative ────→ media_buy
plan ────────→ media_buy
```
Concretely: `seed_product` before `seed_pricing_option`; `seed_product`, `seed_creative`, and `seed_plan` all before `seed_media_buy` when the fixture references them. Storyboards that declare a `fixtures:` block MUST list entries in an order the runner can topologically sort — sellers that receive a `seed_pricing_option` for a product that does not exist, or a `seed_media_buy` referencing a creative/product/plan that was not seeded first, MUST return `INVALID_PARAMS` rather than auto-create the parent.
* **Sandbox scope.** Seeded fixtures exist only for the authenticated sandbox account. `NOT_FOUND` applies the same way as for `force_*` — a seller that cannot see the parent product for the caller's account MUST return `NOT_FOUND`, not silently fall back to another tenant.
* **Capability advertisement.** Sellers that do not implement a given seed scenario MUST return [`UNKNOWN_SCENARIO`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) for that scenario name. The runner treats `UNKNOWN_SCENARIO` on a `seed_*` as a coverage gap for storyboards whose `prerequisites.controller_seeding` requires the scenario — those storyboards are graded `not_applicable`, not failed. This applies to **unfamiliar** `seed_*` names as well: a runner may emit a scenario the seller has never seen because the enum is open-for-extension (see below). Sellers and runners MUST respond with `UNKNOWN_SCENARIO` rather than schema-reject an unrecognized scenario value.
* **Open-for-extension enum.** The `scenario` enum adds new values over time (new seed scenarios land as specialisms demand them). Runners and sellers MUST accept scenario strings they do not recognize and respond with `UNKNOWN_SCENARIO` rather than hard-fail schema validation — otherwise every new enum value becomes a breaking change for stale implementations.
## Response shape
### State transition responses (`force_*`)
**Success:**
```json theme={null}
{
"success": true,
"previous_state": "processing",
"current_state": "approved",
"message": "Creative cr-123 transitioned from processing to approved"
}
```
**Failure (invalid transition):**
```json theme={null}
{
"success": false,
"error": "INVALID_TRANSITION",
"error_detail": "Cannot transition from archived to processing — archived is terminal",
"current_state": "archived"
}
```
**Failure (unknown entity):**
```json theme={null}
{
"success": false,
"error": "NOT_FOUND",
"error_detail": "Creative cr-unknown not found",
"current_state": null
}
```
### Simulation responses (`simulate_*`)
**`simulate_delivery` response:**
```json theme={null}
{
"success": true,
"simulated": {
"delivery_date": "2026-04-15",
"impressions": 10000,
"clicks": 150,
"reach": 4000,
"frequency": 2.5,
"reach_window": { "kind": "rolling", "period": { "interval": 7, "unit": "days" } },
"viewability": {
"measurable_impressions": 9000,
"viewable_impressions": 7200,
"viewable_rate": 0.8,
"viewed_seconds": 4.3,
"standard": "mrc"
},
"reported_spend": { "amount": 150.00, "currency": "USD" }
},
"cumulative": {
"impressions": 25000,
"clicks": 380,
"reach": 4000,
"frequency": 2.5,
"reach_window": { "kind": "rolling", "period": { "interval": 7, "unit": "days" } },
"viewability": {
"measurable_impressions": 9000,
"viewable_impressions": 7200,
"viewable_rate": 0.8,
"viewed_seconds": 4.3,
"standard": "mrc"
},
"reported_spend": { "amount": 375.00, "currency": "USD" }
},
"message": "Delivery simulated for mb-789: 10000 impressions, 150 clicks, $150.00 spend"
}
```
The `simulated` field echoes back the values injected by this call. The `cumulative` field returns running totals across additive counters and spend for this media buy, plus the latest non-additive reach-window and viewability state, so callers can verify expected state before checking [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery).
**`simulate_budget_spend` response:**
```json theme={null}
{
"success": true,
"simulated": {
"spend_percentage": 95,
"computed_spend": { "amount": 950.00, "currency": "USD" },
"budget": { "amount": 1000.00, "currency": "USD" }
},
"message": "Budget for mb-789 set to 95% consumed ($950.00 of $1000.00)"
}
```
### Error codes
Controllers MUST use structured error codes so the storyboard runner can assert on specific failure modes:
| Error code | When |
| - | - |
| [`INVALID_TRANSITION`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Requested state-machine transition is not valid (e.g., `archived → processing`, `canceled → paused`) |
| [`INVALID_STATE`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Operation is not permitted for the resource's current status (e.g., re-seeding a fixture that already exists with a diverging shape) |
| [`NOT_FOUND`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Entity does not exist or caller does not have access (multi-tenant sandboxes SHOULD treat "not yours" as "not found") |
| [`UNKNOWN_SCENARIO`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Scenario not implemented by this seller |
| [`INVALID_PARAMS`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Missing or malformed params, or precondition not met (e.g., `simulate_budget_spend` on an entity with no budget configured) |
| [`FORBIDDEN`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Production account referenced from a sandbox connection |
| [`JCS_NON_FINITE_NUMBER`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Digest-mode `query_upstream_traffic` cannot canonicalize a parsed JSON-like value tree containing `NaN`, `+Infinity`, or `-Infinity`; controllers must not coerce these values, and runners grade the affected validation `not_applicable` |
| [`INTERNAL_ERROR`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) | Transient seller-side failure (e.g., sandbox database unavailable). The runner SHOULD retry once before treating as a failure. |
> [!NOTE]
>
> **Controller-specific enum.** The `error` field on controller responses uses a controller-specific vocabulary defined in [`comply-test-controller-response.json`](https://adcontextprotocol.org/schemas/3.2.8/compliance/comply-test-controller-response.json), distinct from the canonical seller-response [`error-code.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/error-code.json) enum that governs task-level errors. `INVALID_TRANSITION` is controller-specific (state-machine primitives expose the transition-vs-state distinction that seller-level error codes collapse into `INVALID_STATE`). Storyboard assertions on controller responses use `path: "error"` or direct `field_value` checks, not `check: error_code` — the shape-agnostic `error_code` check is for task-response errors (`adcp_error` / payload `errors[]`), not the controller's own response schema.
### Idempotency
State transition scenarios (`force_*`) are idempotent: forcing a status that matches the current state returns success with `previous_state` equal to `current_state`. This avoids flaky tests when the runner retries after transient failures.
Simulation scenarios (`simulate_*`) are NOT idempotent — `simulate_delivery` adds to existing totals, while `simulate_budget_spend` replaces the current spend level.
## Test surfaces
Where a seller's state-of-record lives determines how the storyboard test loop closes. State-local sellers (typically SSPs, creative agents) write to the seller's DB via the `seed_*` scenarios above; the seller's read handlers consume the same store, and the seed→read loop closes naturally. Upstream-proxy sellers (DSPs proxying to platforms, retail-media networks reading retailer catalogs, signals brokers) cannot close the loop that way because their read handlers reach a system the seller does not control; the TypeScript SDK ships a `TestControllerBridge` that runs the real adapter call first, then merges seeded fixtures into the response. Either path earns the wire-format pass that `AAO Verified (Spec)` attests. Neither path is what `(Sandbox)` attests — that's a separate axis covering whether the seller's production stack honors `account.sandbox: true` without real-world side effects.
The cross-page framing for both implementations of this pattern, the SDK's `_bridge` advisory marker, and the runtime-signals disambiguation table all live in the Conformance Specification → [Test surfaces and the storyboard loop](/dist/docs/3.2.8/building/verification/conformance#test-surfaces-and-the-storyboard-loop).
## Compliance testing modes
The presence of `comply_test_controller` in a seller's tool list determines which mode a compliance tester uses:
### Capability discovery
A seller may implement the test controller without supporting every scenario. The storyboard runner SHOULD call `comply_test_controller` with `scenario: "list_scenarios"` as the first interaction. Sellers that support this return the list of implemented scenarios:
```json theme={null}
{
"success": true,
"scenarios": [
"force_creative_status",
"force_account_status",
"force_media_buy_status",
"force_media_buy_purge"
]
}
```
Sellers that implement `list_scenarios` MUST respond with scenario names that appear verbatim in the `scenario` enum of [`comply-test-controller-request.json`](https://adcontextprotocol.org/schemas/3.2.8/compliance/comply-test-controller-request.json). Custom seller-specific scenario names are not part of the compliance contract; storyboard runners will not dispatch to scenarios outside the canonical enum, so listing them serves no purpose. A seller that supports `seed_product` MUST respond with the string `"seed_product"` — not `"create_test_product"` or any other variant.
Sellers that do not implement `list_scenarios` SHOULD return an error with [`UNKNOWN_SCENARIO`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes). When this happens, the runner tries each scenario individually and treats `UNKNOWN_SCENARIO` responses as coverage gaps (not failures). This means early implementers who skip `list_scenarios` are not penalized — the runner discovers supported scenarios through trial.
### Observational mode (default)
When `comply_test_controller` is not available:
* The runner executes buyer-initiated flows and validates response schemas
* State machine transitions that require seller action are skipped
* Advisory observations note what could not be tested
### Deterministic mode
When `comply_test_controller` is available:
* The runner walks every reachable state in each lifecycle
* Forces edge cases: terminal states, invalid transitions, error codes
* Validates that forced state changes are reflected in subsequent reads
* Tests operation gates (e.g., [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) blocked when account is `suspended`)
The runner distinguishes three outcome categories in deterministic mode:
* **Scenario not supported** — returned by `list_scenarios` or `UNKNOWN_SCENARIO` error. Reported as a coverage gap, not a failure.
* **Transition correctly rejected** — controller returned [`INVALID_TRANSITION`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) for an invalid state change. This is a pass.
* **Unexpected failure** — controller returned an error for a transition that should be valid, or succeeded on a transition that should fail. This is a compliance failure.
### Who is expected to implement the controller
Reference sellers (implementations published to demonstrate full conformance, such as the SDK reference and example sellers that SDK CI grades) SHOULD implement `comply_test_controller`; one that omits it leaves its controller-seeded lifecycle coverage ungraded. Translator and adapter sellers that front platforms which cannot seed state are not expected to implement it. Storyboards that seed through the controller declare `requires: [controller]`, so a seller without the controller receives one storyboard-level `requirement_unmet` skip naming `controller` on each such storyboard it is graded on, not a `missing_test_controller` grade on every seeded step. If the controller disappears mid-run, the runner still grades each affected step `missing_test_controller`.
### Example: creative lifecycle in deterministic mode
```
1. sync_creatives(creative)
2. list_creatives() → verify status = "processing"
3. force_creative_status(creative_id, "pending_review")
4. force_creative_status(creative_id, "approved")
5. list_creatives() → verify status = "approved"
6. force_creative_status(creative_id, "archived")
7. list_creatives() → verify status = "archived"
8. sync_creatives(same creative) → verify unarchive (→ approved or pending_review)
9. force_creative_status(creative_id, "rejected", reason)
10. list_creatives() → verify rejection_reason persisted
11. sync_creatives(same creative) → verify resubmission (rejected → processing)
12. force_creative_status(creative_id, "approved") → expect INVALID_TRANSITION (must go through pending_review)
```
### Example: account operation gates in deterministic mode
```
1. sync_accounts(account) → active
2. force_account_status(account_id, "suspended")
3. create_media_buy() → expect ACCOUNT_SUSPENDED
4. get_media_buys() → expect existing buys still readable
5. force_account_status(account_id, "active")
6. create_media_buy() → expect success
7. force_account_status(account_id, "payment_required")
8. update_media_buy(add packages) → expect ACCOUNT_PAYMENT_REQUIRED
9. get_media_buys() → existing buys still readable
```
### Example: media buy lifecycle in deterministic mode
```
1. create_media_buy() → status = "pending_creatives"
2. force_media_buy_status(media_buy_id, "rejected", reason) → expect success
3. get_media_buys() → verify status = "rejected", rejection_reason persisted
4. force_media_buy_status(media_buy_id, "active") → expect INVALID_TRANSITION (rejected is terminal)
5. create_media_buy() → new buy, status = "pending_creatives"
6. force_media_buy_status(media_buy_id, "pending_start")
7. force_media_buy_status(media_buy_id, "active")
8. force_media_buy_status(media_buy_id, "rejected") → expect INVALID_TRANSITION (rejected only valid from pending_creatives or pending_start)
```
### Example: delivery and budget verification
```
1. create_media_buy(budget: $1000)
2. simulate_delivery(impressions: 10000, reported_spend: $500)
3. get_media_buy_delivery() → verify delivery reflects simulated data
(reported_spend is delivery-only; does not affect account budget)
4. simulate_budget_spend(spend_percentage: 95)
5. get_account_financials() → verify total_spend reflects 95% ($950, not $500 from delivery)
6. simulate_budget_spend(spend_percentage: 100)
7. force_account_status("payment_required")
8. create_media_buy() → expect ACCOUNT_PAYMENT_REQUIRED
```
## Certification tiers
| Tier | Requirement | What it proves |
| - | - | - |
| **Functional compliance** | Pass all storyboards in observational mode | Tools exist, respond correctly, and complete buyer-initiated flows |
| **Stateful compliance** | Pass all storyboards in deterministic mode | State machines enforce correct transitions, error codes match spec, operation gates block correctly |
**Specialism-scoped fixture requirements.** Stateful compliance requires every
fixture used by the specialism's selected storyboards to resolve. A seller may
satisfy a fixture through any strategy that the storyboard explicitly enables:
`seed`, `discover`, or `construct`. Storyboards without `fixture_resolution`
remain seed-only, so their corresponding `seed_*` scenarios are still required
for full coverage. Missing every available strategy produces a visible
`fixture_unsatisfied` coverage gap; it is not a passing result and cannot be
used as a blanket opt-out from conformance.
This relaxation applies only to fixture setup. Sellers must still implement the
`force_*` and `simulate_*` scenarios required by the lifecycle assertions in
their claimed specialisms. If a seller advertises a setup scenario or begins a
normal buyer-flow construction call and that operation fails, the runner grades
the failure rather than falling back to another strategy.
## Implementation guidance
### For sellers
1. Gate `comply_test_controller` at the deployment level — it MUST NOT appear in `tools/list` (or A2A `skills[]`), MUST NOT be advertised via the `compliance_testing` capability block, and MUST dispatch to unknown-tool on production deployments. See [Sandbox gating](#sandbox-gating) for the full rule.
2. Reuse your production state machine logic — the controller should call the same internal transition functions, not bypass them
3. Enforce transition rules — if `rejected` is terminal in production, `force_media_buy_status(rejected → active)` must fail via the controller too
4. Reflect changes immediately — after a forced transition, the next `list_*` or `get_*` call must return the updated state
### For compliance testers
1. Detect the tool during profile discovery via `tools/list`
2. Call `list_scenarios` to discover which scenarios are supported
3. Run observational mode as the baseline — it works everywhere
4. Layer deterministic scenarios on top when the controller is available
5. Report which mode was used and distinguish coverage gaps from failures
6. Test the controller's transition validation itself — invalid transitions should return [`INVALID_TRANSITION`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes), not silently succeed
## Design decisions
1. **Sellers validate transition ordering.** The controller enforces the same state machine rules as production. Calling `force_creative_status(approved)` on a creative that was never `processing` is an error — the controller rejects it just as production would. The lifecycle state machines referenced here are defined in the respective protocol specifications (see [creative lifecycle](/dist/docs/3.2.8/creative/specification#creative-status-lifecycle), [account lifecycle](/dist/docs/3.2.8/accounts/overview#account-status-lifecycle), [media buy lifecycle](/dist/docs/3.2.8/media-buy/specification), [SI session lifecycle](/dist/docs/3.2.8/sponsored-intelligence/specification#session-states)).
2. **Tests are self-contained.** Each test SHOULD create dedicated entities (media buys, creatives, accounts) rather than reusing existing ones. This ensures additive simulation calls (`simulate_delivery`) start from known-zero state without needing a reset mechanism. No `reset` scenario is needed. Compliance testers SHOULD use unique identifiers (e.g., UUIDs) for test entities to avoid collisions when multiple storyboard runner instances run against the same sandbox concurrently. Sandbox entity cleanup (e.g., TTL-based expiration) is the seller's responsibility.
3. **Delivery simulation uses a synthetic marker.** `simulate_delivery` records MAY include a `synthetic: true` field that sellers can use internally for bookkeeping. The runner ignores this marker — it validates [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) responses against the same schema regardless. This lowers the implementation bar for sellers without affecting test correctness.
4. **One tool, many scenarios.** The single-tool design keeps context window cost to \~500 tokens vs \~1,400 for seven separate tools. Sellers implement one sandbox gate. The runner detects one tool. The `list_scenarios` introspection handles partial implementations without requiring per-tool presence detection.
# Error Handling
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L3/error-handling
AdCP error handling: protocol errors, task failures, and validation errors with standard error codes, recovery strategies, and exponential backoff retry logic.
AdCP uses a consistent error handling approach across all operations. Understanding error categories and implementing proper recovery strategies is essential for building robust integrations.
## Compliance Levels
Sellers can adopt error handling incrementally. Each level builds on the previous:
| Level | What to implement | What agents can do |
| - | - | - |
| **Level 1** | Return `code` + `message` on every error | Agents match on error code to classify failures; this is the 3.1 compatibility baseline |
| **Level 2** | Add `recovery`, plus optional `retry_after`, `field`, and `suggestion` | Agents auto-retry transient errors and self-correct correctable ones; 3.2 producers must implement `recovery` |
| **Level 3** | Use [transport bindings](/dist/docs/3.2.8/building/operating/transport-errors) to put errors in `structuredContent` (MCP) or artifact `DataPart` (A2A) | Programmatic clients get typed errors without parsing text |
**Level 1** is the shared-schema minimum and remains valid input from 3.1 and earlier producers. A conformant **3.2 producer** implements the `recovery` portion of **Level 2** on every error; the other Level 2 fields remain optional. **Level 3** is where client libraries like `@adcp/sdk` can provide fully typed error objects.
## Error Categories
### 1. Protocol Errors
Transport/connection issues not related to AdCP business logic:
* Network timeouts
* Connection refused
* TLS/SSL errors
* JSON parsing errors
**Handling:** Retry with exponential backoff.
### 2. Task Errors
Business logic failures returned as `status: "failed"`:
* Insufficient inventory
* Invalid targeting
* Budget validation failures
* Resource not found
**Handling:** Check the `recovery` field to determine whether to retry, fix the request, or escalate.
### 3. Validation Errors
Malformed requests that fail schema validation:
* Missing required fields
* Invalid field types
* Out-of-range values
**Handling:** Fix request format and retry. Usually development-time issues.
## Error Response Format
Failed operations return status `failed` with error details. The error object follows the [`error.json`](https://adcontextprotocol.org/schemas/3.2.8/core/error.json) schema:
```json theme={null}
{
"status": "failed",
"message": "Budget is below the seller's minimum for this product",
"errors": [
{
"code": "BUDGET_TOO_LOW",
"message": "Budget is below the seller's minimum for this product",
"recovery": "correctable",
"field": "budget.total",
"suggestion": "Increase budget to at least 500 USD",
"details": {
"minimum_budget": 500,
"currency": "USD"
}
}
]
}
```
### Envelope vs. payload errors — the two-layer model
AdCP exposes errors in two distinct places, and implementers need to populate the right layer for the right situation. This is the single most common source of error-shape drift between agents and storyboards.
| Layer | Key | When to populate | Shape |
| - | - | - | - |
| **Task payload** | `payload.errors[]` (or top-level `errors[]`, depending on transport) | The task ran; the payload reports one or more issues (fatal or non-fatal) | Array of error objects per [`error.json`](https://adcontextprotocol.org/schemas/3.2.8/core/error.json) |
| **Transport envelope** | `adcp_error` | The task failed and the transport needs a typed, extractable signal | Single error object per [`error.json`](https://adcontextprotocol.org/schemas/3.2.8/core/error.json) |
**A fatal task failure SHOULD populate both layers.** The payload carries the structured `errors[]` array that any protocol can read verbatim, and the transport envelope carries `adcp_error` so MCP/A2A clients can extract a typed error without re-parsing the payload. Populating only one of the two is the source-of-truth for most interop bugs — a runner that reads the transport envelope sees no error, and a runner that reads the payload sees no error signal on the transport:
```json theme={null}
// MCP — structuredContent AND payload both carry the error
{
"content": [{"type": "text", "text": "{\"adcp_error\":{\"code\":\"BUDGET_TOO_LOW\", ...}}"}],
"isError": true,
"structuredContent": {
"adcp_error": { "code": "BUDGET_TOO_LOW", "message": "...", "recovery": "correctable" },
"payload": {
"errors": [
{ "code": "BUDGET_TOO_LOW", "message": "...", "recovery": "correctable", "field": "budget.total" }
]
}
}
}
```
```json theme={null}
// A2A — artifact DataPart carries adcp_error; if the agent also surfaces payload via a sibling DataPart, errors[] lives there
{
"status": { "state": "failed" },
"artifacts": [{
"artifactId": "error-result",
"parts": [
{ "kind": "data", "data": { "adcp_error": { "code": "BUDGET_TOO_LOW", ... } } },
{ "kind": "data", "data": { "errors": [{ "code": "BUDGET_TOO_LOW", "field": "budget.total", ... }] } }
]
}]
}
```
**Non-fatal errors populate only the payload.** A `status: "submitted"` or `status: "input-required"` task reporting a warning (e.g., "this media buy requires manual approval — \[warning details]") populates `errors[]` in the payload with `severity: "warning"` but MUST NOT populate `adcp_error`. The transport envelope signals "the task failed" — it is not a warning channel.
**Storyboard validators.** Prefer `check: error_code` over `check: field_present, path: "errors"` when asserting on a failed task's error code. `error_code` is shape-agnostic — the runner resolves it from either `adcp_error.code` (transport) or `errors[0].code` (payload). Direct `path: "errors"` checks pin the assertion to the payload shape and fail against agents that surface errors only via the transport envelope, even when the agent is conformant. See [Storyboard authoring — Asserting on errors](/dist/docs/3.2.8/contributing/storyboard-authoring#asserting-on-errors).
**Discriminated rejection arms.** When the task response defines a structured rejection arm (e.g., `AcquireRightsRejected`, `CreativeRejected`, `GetProductsRejected` — see the wire-placement guidance on [`GOVERNANCE_DENIED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-governance-denied) for the rule), the spec-correct denial response carries no error code on the wire — the rejection arm enforces mutual exclusion with `errors[]` at the schema layer. `GetProductsRejected` also excludes envelope-level `adcp_error`, `products`, and `proposals`. Asserting `check: error_code` will fail against a conformant agent. Assert on the task-specific discriminator instead: `rights_status: "rejected"` for `AcquireRightsRejected`, `approval_status: "rejected"` for `CreativeRejected`, and top-level `status: "rejected"` for `GetProductsRejected`. Assertions that mix the error and structured-outcome paths bake non-spec opinions into the storyboard.
### Error Object Fields
These fields are defined by the [`error.json`](https://adcontextprotocol.org/schemas/3.2.8/core/error.json) schema. `buyer_reason` is part of the 3.2 release-candidate schema and is not present in the released 3.1 bundle.
| Field | Type | Required | Description |
| - | - | - | - |
| `code` | string | Yes | Machine-readable error code from the [standard vocabulary](#standard-error-codes) or a seller-specific code |
| `message` | string | Yes | Human-readable error description |
| `buyer_reason` | object | No | Buyer-actionable `{ code, message }` classification. `code` comes from the open [buyer reason vocabulary](#buyer-actionable-reasons); `message` must be safe to show across the buyer trust boundary. |
| `recovery` | string | 3.2: Yes; ≤3.1: No | Agent recovery classification: `transient`, `correctable`, or `terminal`. AdCP 3.2 producers MUST populate it on every error; 3.1 producers SHOULD. The shared 3.x schema keeps it optional so legacy errors remain valid. It is required whenever `buyer_reason` is present and classifies that reason, not an upstream wrapper. |
| `retry_after` | number | No | Seconds to wait before retrying. AdCP 3.2 producers emit whole seconds from 1 through 3600; consumers continue accepting legacy fractional values. |
| `field` | string | No | Field path in JSONPath-lite format (e.g., `packages[0].targeting`). When `issues` is present, sellers MUST set this to `issues[0].pointer` translated from RFC 6901 to JSONPath-lite (e.g., `/packages/0/targeting` → `packages[0].targeting`). Will be deprecated in a future major version. |
| `issues` | array | No | Structured list of validation failures. Each entry carries `pointer` (RFC 6901), `message`, `keyword` (JSON Schema keyword that rejected — `required` / `type` / `format` / etc.), and optionally `schema_id`, `schemaPath`, `discriminator`. See [Validator-internals fields](#validator-internals-fields-on-issues) for the `schema_id` / `schemaPath` / `discriminator` semantics, the production-emit rules, and the resolution path for `schema_id`. |
| `suggestion` | string | No | Suggested fix for the error |
| `details` | object | No | Additional context-specific information. Sellers MAY mirror `issues[]` here as `details.issues` for backward compatibility with pre-3.1 consumers; new consumers SHOULD prefer the top-level `issues` field. |
### Buyer-actionable reasons
Use `buyer_reason` when the top-level error is too coarse for a buyer agent to route safely. For example, a seller can retain the coarse [`CREATIVE_REJECTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-rejected) class while identifying that the buyer must replace a mismatched creative:
```json theme={null}
{
"code": "CREATIVE_REJECTED",
"message": "The creative could not be accepted.",
"recovery": "correctable",
"buyer_reason": {
"code": "CREATIVE_SIZE_MISMATCH",
"message": "The creative dimensions (300x250) do not match any accepted size on the selected packages (640x480)."
}
}
```
`buyer_reason.code` reuses the comprehensive standard vocabulary in [`error-code.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/error-code.json), including request, authorization, account, policy, governance, commercial, inventory, and creative failure classes. [`CREATIVE_SIZE_MISMATCH`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-size-mismatch), [`CREATIVE_MISSING_CLICK_URL`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-missing-click-url), and [`CREATIVE_VALIDATION_FAILED_GENERIC`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-validation-failed-generic) cover the motivating creative-validation gaps. The wire field remains an open string: receivers MUST accept unknown codes, use `buyer_reason.message` for human-facing context, and route recovery from the enclosing `error.recovery`. Seller-specific extensions MUST follow the standard `X_{VENDOR}_{CODE}` naming rule. This permits later codes and platform-specific extensions without making older receivers reject the error object.
`buyer_reason.message` MUST be buyer-safe. It MUST NOT contain vendor identifiers, ad-server type names, internal object names, internal IDs, stack traces, or other producer-private implementation details. Producers compose it from buyer-visible request and catalog data; they do not copy raw downstream error text. Buyer clients may display the message, but MUST treat it as untrusted producer text and MUST NOT use the free text for control flow.
When `buyer_reason` is present, `error.recovery` MUST reflect the buyer's required action and MUST match the buyer reason's `enumMetadata.recovery` classification when that code is registered. If both `error.code` and `buyer_reason.code` are registered, their standard recovery classifications MUST agree with each other and with `error.recovery`; sellers MUST choose the closest compatible top-level class instead of retaining a conflicting upstream transport wrapper. This keeps legacy consumers that ignore `buyer_reason` on the same recovery path. If one rejection contains independently actionable failures from different reason classes, sellers MUST emit separate error objects—each with its own `buyer_reason`—or omit `buyer_reason`; a single reason must not misrepresent a multi-issue rejection. Related `issues[]` entries may remain grouped when they share the same buyer reason.
### Validator-internals fields on `issues`
Three optional fields on each `issues[]` entry name the schema element that rejected the payload, so agents can recover from validation errors in one iteration instead of probing variants:
| Field | Shape | Purpose |
| - | - | - |
| `schema_id` | string — a published `$id` (e.g. `/schemas/3.1.0/core/activation-key.json`) | Canonical name of the rejecting (sub-)schema. 3.1+ consumers' primary handle. |
| `schemaPath` | string — a JSON Schema tree path (e.g. `#/properties/packages/items/oneOf/1`) | Validator-internal traversal. Retained for 3.0.x backward compatibility; 3.1+ consumers SHOULD prefer `schema_id`. (Renamed to `schema_path` in a future major.) |
| `discriminator` | array of `{property_name, value}` | Variant the validator selected for const-discriminated `oneOf` / `anyOf`, sourced from values present in the payload. Aligns with OpenAPI 3.x `discriminator.propertyName`. |
**Resolving `schema_id`.** The string is the schema's `$id`. To load the schema:
* **HTTPS canonical:** prepend `https://adcontextprotocol.org` (e.g. `https://adcontextprotocol.org/schemas/3.1.0/core/activation-key.json`). Cacheable; immutable per version.
* **SDK-bundled:** `@adcp/sdk` and `adcp-client-python` ship the schema bundle for offline resolution — look up by `$id` against the bundled tree.
* **Bundled-tree caveat.** Tools served from the pre-resolved bundled tree (`/schemas/{version}/bundled/...`) inline sub-schemas with their `$id` preserved (3.1+, see #3868) — but only on the **first occurrence** of each sub-schema within a bundle. Same source schema referenced from multiple co-locations gets `$id` only on the first inline; subsequent occurrences fall back to the nearest `$id`-bearing ancestor (typically the response root) when SDK error reporting walks up the schema tree. Sub-schemas whose subtrees contain hoisted `$defs` references also have `$id` stripped at bundle time, because preserving `$id` there would break local-fragment resolution. Consumers reading bundles produced before #3868 see only the response-root `$id`. Detect the pre-#3868 case by checking whether the `$id` ends in `/bundled/-response.json` — if so, fall back to walking the bundled schema by `pointer`.
**Discriminator semantics.** Sellers populate `discriminator` only when (a) the rejecting schema is a const-discriminated `oneOf` / `anyOf`, and (b) the discriminator property is present in the payload. The wire field reports the value the caller sent — not a validator inference on partial-match heuristics — so the field is deterministic across Ajv, Python `jsonschema`, and `gojsonschema`. When zero variants survive validation, sellers MUST omit `discriminator` (omission is the signal to the agent that "the validator could not localize a target variant"). For compound discriminators (e.g. `audience-selector`'s `(type, value_type)`), entries are ordered by declaration in the rejecting schema's `properties` block.
When the discriminator property is *missing* from the payload (the validator can't even start branch selection), sellers omit `discriminator` — the recovery signal comes from a sibling `issues[]` entry with `keyword: "required"` whose `pointer` names the absent discriminator property. Agents reading "missing required discriminator field" + "no `discriminator` on this issue" recover by populating the named property; agents seeing a `discriminator` array with a value that didn't match any branch recover by switching to a different value.
**Production-emit rules (the public-spec stance).** All three fields are emit-on-production safe **when the rejecting element is in the published spec at the version the seller advertises via [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities)**. The rationale is replay-locally: schemas are published at adcontextprotocol.org and bundled with every SDK, so an adversary running the same validator against the same payload derives the same branch selection — the wire field carries no information they can't compute.
The replay-locally argument has carve-outs sellers MUST honor:
* **Private extensions.** Sellers running schemas with custom `oneOf` branches, server-only sub-schemas, or enum subsets layered via `additionalProperties: true` MUST NOT emit `schema_id`, `schemaPath`, or `discriminator` when the rejecting element is not present in the published spec. Emission would leak seller-internal validation state the adversary cannot replay. *Implementation:* sellers running a mixed public + private validation tree typically (a) compile public-only and private-only validators separately and emit `schema_id` only from the public run, or (b) instrument compiled schemas with a side-table mapping each `$id` to its source bundle.
* **Version skew.** Sellers validating against a pre-release or post-release schema MUST NOT emit a `schema_id` whose `$id` is not present in the published bundle for the version named in `get_adcp_capabilities`.
* **Server-narrowed public elements.** When the seller server-side filters a public enum, pattern, or numeric range to a tenant-specific subset (e.g. accepts `["a","b","c"]` per the public schema, rejects everything except `["a"]` for this caller), sellers MUST NOT return [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) with `keyword: "enum"` (or `pattern` / `minimum` / `maximum`) against the public `schema_id`. The public-spec replay would accept the value; the seller rejects on private state. Use [`POLICY_VIOLATION`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-policy-violation) or [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) instead so the rejection isn't mis-attributed to a public schema element. The structural delta between "public-replay accepts, seller rejects" is itself a fingerprint of the seller's private subset.
* **Custom keywords.** `keyword` MUST be drawn from the JSON Schema Draft 7 / 2020-12 vocabulary — sellers using validator-specific custom keywords (Ajv `addKeyword`, `instanceof`) MUST NOT emit them on the wire.
* **Probe terseness.** Sellers MAY scope these three fields to dev/sandbox responses on rate-limited endpoints to keep production envelopes terse, even when the carve-outs above don't apply. Field omission is always conformant.
## Standard Error Codes
Standard error codes are defined in [`error-code.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/error-code.json). The vocabulary is **open**: `error.code` is wire-typed as `string`, the standard codes are documentary, and senders MAY emit codes outside the standard set.
### Forward-compatible decoding (normative)
**The error-code vocabulary is open.** `error.code` is typed as `string` in [`core/error.json`](https://adcontextprotocol.org/schemas/3.2.8/core/error.json) — not as a closed enum — so a strict JSON Schema validator MUST accept any string value. The standard vocabulary in `error-code.json` is documentary; it constrains neither sender nor receiver at the wire level.
**Receivers MUST decode unknown codes.** A receiver pinned to AdCP version X that decodes a response carrying an `error.code` introduced in version X+1 (or a platform-specific code outside the standard vocabulary) MUST:
1. Treat the response as well-formed — MUST NOT reject the envelope, throw a deserialization exception, or downgrade to a generic protocol error.
2. Recover the recovery classification from `error.recovery` (top-level field on the error envelope) when present. `error.recovery` is the normative carrier; the `enumMetadata.recovery` in `error-code.json` is the documentary mirror.
3. When `error.recovery` is absent on a legacy error, use the registered `enumMetadata.recovery` classification when the code is known to the receiver. For an unknown code, apply the conservative `transient` default documented by the manifest's [`error_code_policy.default_unknown_recovery`](https://adcontextprotocol.org/schemas/3.2.8/manifest.schema.json). That default is **bounded** by [§ Retry Logic](#retry-logic): receivers MUST apply `maxRetries` and the jittered exponential-backoff schedule and MUST NOT loop indefinitely. A hostile or buggy sender cannot induce unbounded retries against a conformant client; the open-enum decoding rule does not exempt receivers from the retry budget.
**Senders MAY emit codes outside the receiver's pinned vocabulary.** A sender emitting a 3.1-era code (e.g., [`PROPOSAL_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-not-found)) to a 3.0-pinned receiver does not violate the spec — the receiver is required by the rule above to handle it. When a sender knows the receiver's pinned version (via `adcp_version` envelope echo or capability discovery), senders SHOULD prefer a code from that version's vocabulary when an equivalent exists; senders MAY emit newer or platform-specific codes when no equivalent is available.
**Producer requirements are version-gated.** AdCP 3.2 producers **MUST** populate `error.recovery` on every error; 3.1 producers **SHOULD** populate it. This is the normative carrier of recovery semantics across version skew. The field remains schema-optional in the shared 3.x schema so consumers can decode previously valid retained responses and live responses from older peers. A 3.2 producer that omits it is non-conformant, but a consumer still decodes the error using the legacy fallback above.
SDKs can exercise this decision table against the versioned [error-recovery reference vectors](https://adcontextprotocol.org/compliance/latest/test-vectors/error-recovery/vectors.json). Pin `/compliance/{version}/test-vectors/error-recovery/vectors.json` when testing a released protocol artifact rather than relying on the moving `latest` alias.
**Why this matters.** Forward-compatible decoding is the wire-level invariant that lets future maintenance lines (3.1.x, 4.0.x, …) ship new error codes additively without breaking older receivers. Without it, every new code is a wire change held to the next minor — the current drift-lint policy on 3.0.x. With it in 3.1+, new codes can register during a maintenance line's lifetime, which matters as adopters' real-world rejection paths surface new codes.
**3.0.x policy unchanged.** 3.0.x receivers predate this normative rule, so 3.0.x stays wire-stable for the remainder of its support window — new codes still land at the next minor. This rule sets the receiver contract from 3.1 onward.
**Not-found precedence.** When a referenced identifier does not resolve, sellers SHOULD return the resource-specific code when the resolved type is known from the request: [`PRODUCT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-not-found) for `product_id`, [`PACKAGE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-package-not-found) for `package_id`, [`MEDIA_BUY_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-media-buy-not-found) for `media_buy_id`, [`CREATIVE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-not-found) for `creative_id`, [`SIGNAL_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-signal-not-found) for `signal_id`, [`SESSION_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-session-not-found) for SI `session_id`, [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found) for `account_id`, [`PLAN_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-plan-not-found) for governance `plan_id`. Fall back to [`REFERENCE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-reference-not-found) for resource types without a dedicated code (e.g., property lists, content standards, rights grants, SI offerings, proposals, catalogs, event sources, collection lists, brands, individual properties). Typed parameters that lack a dedicated standard code MUST use `REFERENCE_NOT_FOUND` rather than minting a custom `*_NOT_FOUND` code — the vocabulary grows by upstream spec change, not by per-seller inflation. Clients SHOULD switch on `error.code` first; the resource-specific codes let clients dispatch without parsing `error.field`.
**Polymorphic parameters.** When the unresolved identifier was supplied via a polymorphic or untyped parameter (a field that accepts multiple resource types), sellers MUST use `REFERENCE_NOT_FOUND` even if a resource-specific code exists for the resolved type. Using the type-specific code on a polymorphic parameter leaks the resolved type to an unauthorized caller. Polymorphism is evaluated against the parameter's declared shape in the tool schema — **before any lookup** — so a generic `reference_id` parameter dispatches to `REFERENCE_NOT_FOUND` regardless of what the id resolves to. Evaluating on the resolved type after dispatch reintroduces the leak.
A tool's declared parameter shape MUST be identical across all callers for a given tool version; dispatch rules MUST NOT be conditioned on caller identity. A schema that exposes `property_list_id` to tenant B but only `reference_id` to tenant A turns capability discovery itself into an enumeration oracle (read the schema under two identities, diff).
**Uniform response for inaccessible references.** The uniform-response requirement applies to **every** not-found code in this vocabulary (`REFERENCE_NOT_FOUND`, `SIGNAL_NOT_FOUND`, `CREATIVE_NOT_FOUND`, `MEDIA_BUY_NOT_FOUND`, `PACKAGE_NOT_FOUND`, `SESSION_NOT_FOUND`, `ACCOUNT_NOT_FOUND`, `PLAN_NOT_FOUND`): sellers MUST return the same response for "exists but the caller lacks access" as for "does not exist". Never distinguish the two — this is how cross-tenant enumeration lands.
The MUST covers every observable channel, not just `error.code`:
* **Error object.** `error.code`, `error.message`, `error.field`, `error.details` MUST be byte-equivalent between the two cases. On typed parameters that fall back to `REFERENCE_NOT_FOUND`, `error.field` MUST be identical across true-miss and resolve-then-deny — either omitted on both or replaced with a type-neutral name on both. `error.field` MAY name the input parameter when the parameter name is type-neutral (e.g., `reference_id`); when the original parameter name is type-revealing (e.g., `property_list_id`), `error.field` MUST be omitted or replaced with a neutral name. `error.message` MUST be generic (no resource-qualified text like `"Property list not found"`). For `REFERENCE_NOT_FOUND` specifically, sellers MUST NOT leak the resolved resource type via `error.field`, `error.details`, or a resource-qualified `error.message`. When the parameter is an array (e.g., `catalog_ids`, `format_option_refs`), `error.field` MUST name the array parameter itself. Sellers MAY enumerate specific unresolvable elements in `error.details` — but only when the elements were supplied verbatim by the caller. Sellers MUST NOT distinguish "supplied element resolved but caller unauthorized" from "supplied element does not exist" at the element level; that reintroduces the enumeration oracle at the array-entry granularity.
* **Transport status.** HTTP status code, A2A `task.status.state`, and MCP `isError` MUST be identical between the two cases.
* **Response headers.** `ETag`, `Cache-Control`, per-resource-type rate-limit buckets, CDN tags, and any header whose value or presence differs by resource type MUST be identical.
* **Side effects.** Webhook dispatch and audit-log writes MUST be identical — a resolve-then-deny path MUST NOT write tenant audit rows, enqueue background work (search-indexer updates, cache warmers, access-log aggregators), increment per-resource-type quota/rate-limit counters, or fire webhooks to any subscriber (including the resource owner) in ways a true-miss would not. If the resolve-then-deny path touches a per-tenant DB shard or cache, the true-miss path MUST touch the same shape of storage (e.g., route both through a tenant-agnostic resolver) so that co-tenant observers cannot distinguish via storage-layer metrics.
* **Observability.** Downstream logs, APM spans, and third-party error-reporting telemetry (Sentry, Datadog, Rollbar, and equivalents) MUST NOT be tagged with the resolved resource type when the caller lacks access; the trace a true-miss emits MUST be structurally indistinguishable from the trace a resolve-then-deny emits.
To make latency parity a consequence rather than a separate requirement, sellers MUST perform the same resolution-and-authorization work on both paths — **resolve-then-authorize**, never short-circuit on "unknown id." On a true-miss, sellers MUST still execute an authorization decision of equivalent shape (e.g., against an empty principal set, or against the caller's own tenant as a decoy) so that authorizer latency — which varies with the size and shape of the ACL graph — is not a side channel. Pre-lookup input validation (UUID format, length, regex) is permitted iff it is deterministic in request content only (same input → same verdict, regardless of caller or existence).
Non-normative implementation note: a single-query pattern like `SELECT ... WHERE id = ? AND tenant = ?` *looks* uniform but differs in execution plan, buffer-pool touches, and authorizer invocation depending on whether the row exists in another tenant. Prefer the two-step pattern — resolve by id, then authorize against the loaded row (or against an empty row on true-miss) — as the only pattern that naturally produces observational uniformity.
**Cache warmth** is a distinct oracle: a warm cache on tenant B's id indicates someone accessed it recently. Sellers MUST NOT gate cache population on authorization — true-miss ids MUST be cached-as-miss with the same TTL as resolve-then-deny, or cache reads MUST be bypassed for not-found responses.
**Verifying this yourself.** The paired-probe `adcp fuzz` invariant checks uniform-response compliance by comparing two responses per tool. See [Validate Your Agent — Preparing to test uniform error responses](/dist/docs/3.2.8/building/verification/validate-your-agent#preparing-to-test-uniform-error-responses) for tenant-setup requirements and CLI invocation. Full-strength testing requires two isolated tenants; single-tenant runs cover only the "does not exist" leg.
### Authentication and Access
| Code | Recovery | Description | Resolution |
| - | - | - | - |
| [`AUTH_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-required) | correctable\* | Authentication is required, or presented credentials were rejected | Provide credentials when missing; escalate to operator when rejected — see the warning below |
| [`CREDENTIAL_IN_ARGS`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-credential-in-args) | terminal | Authentication material or caller-supplied trust material was placed in request args (top-level, `context`, `ext`, or any nested location) instead of the relevant transport authentication or trust channel. This includes inbound buyer-principal credentials and evaluator-call credentials or JWK/JWKS/JWKS-URI material smuggled into evaluator payload fields. | Do NOT auto-retry — auto-retry re-logs the credential. Move the credential onto the relevant transport authentication/trust channel ([Credential placement](/dist/docs/3.2.8/building/by-layer/L2/authentication#credential-placement)), rotate any leaked credential, then resubmit |
| `ACCOUNT_NOT_FOUND` | terminal | Account reference could not be resolved | Natural key: provision through [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) or omit `account` for public discovery. `account_id`: verify via [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) or contact seller |
| [`ACCOUNT_MOVED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-moved) | correctable | Authorized caller used a tombstoned former natural key after the account was rekeyed | Replace the reference with `details.current_account`, refresh through [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts), and retry with a fresh idempotency key |
| [`ACCOUNT_IDENTITY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-identity-conflict) | correctable | Requested identity is already the natural key of another account | Choose another operator identity or retain the current identity; do not retry unchanged |
| [`ACCOUNT_SETUP_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-setup-required) | correctable | Account needs setup before use | Check `details.setup` for URL or instructions |
| [`ACCOUNT_AMBIGUOUS`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-ambiguous) | correctable | Natural key resolves to multiple accounts | Pass explicit `account_id` or a more specific natural key |
| [`ACCOUNT_PAYMENT_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-payment-required) | terminal | Outstanding balance requires payment | Buyer must resolve billing |
| [`ACCOUNT_SUSPENDED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-suspended) | terminal | Account has been suspended | Contact seller to resolve |
> [!WARNING]
>
> **`AUTH_REQUIRED` sub-cases — do not auto-retry rejected credentials.** The wire code carries two operationally distinct cases that agents MUST handle differently:
>
> * **Credentials missing** → provide credentials and retry once. Correctable inside the agent loop.
> * **Credentials presented but rejected** (expired, revoked, or malformed signature) → do **not** auto-retry; escalate to operator for credential rotation. Re-presenting a rejected credential against an SSO endpoint creates retry-storm patterns indistinguishable from brute-force probes — the seller's fraud detection may rate-limit, suspend, or alert on the calling agent.
>
> `CREDENTIAL_IN_ARGS` is the related — but distinct — case where authentication material or caller-supplied trust material was placed in the **task payload** instead of the relevant transport authentication or trust channel. That code is `terminal` (auto-retry re-logs the credential) and the rule + carve-outs (push-notification webhook auth, relay topology) live in [Credential placement](/dist/docs/3.2.8/building/by-layer/L2/authentication#credential-placement).
>
> A future minor release splits this code into [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing) (correctable) and [`AUTH_INVALID`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-invalid) (terminal). Until then, agents branch on whether credentials were attached to the failing request:
>
> ```javascript theme={null}
> case 'AUTH_REQUIRED': {
> // The caller's request builder records whether an auth header was attached.
> // The error-handling SDK surfaces this on `error.request_had_credentials` (or you
> // pass it in from your own request wrapper).
> const requestHadCredentials = Boolean(error.request_had_credentials);
> if (!requestHadCredentials) {
> // Sub-case (a) — provide credentials and retry.
> await refreshCredentials();
> return retry();
> }
> // Sub-case (b) — credentials were presented and rejected.
> // Treat as terminal at the application layer; surface to operator.
> console.error('Credential rejected — needs human rotation:', error.message);
> throw error;
> }
> ```
### Billing and Account Setup
Returned by [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) when the request's billing or account-shape values are not acceptable to the seller. The two billing-rejection codes distinguish *which gate* fired so agents can dispatch on the right recovery — autonomous retry vs surface-to-human — without parsing prose. See [Buyer-agent identity](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#buyer-agent-identity) for the two-layer identity model these codes sit on top of.
| Code | Recovery | Description | Resolution |
| - | - | - | - |
| [`BILLING_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-supported) | correctable | Seller declines the requested `billing` value at the seller-wide capability level (`supported_billing` does not include the value) or at the per-account-relationship level (e.g., the seller accepts `operator` billing in general but has no direct relationship with the operator on this specific account) | Check [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) for `supported_billing`, resubmit with a supported value, or omit `billing`; when present, dispatch on `error.details.scope` (`"capability"` or `"account"`) per [`billing-not-supported.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/billing-not-supported.json) |
| [`BILLING_NOT_PERMITTED_FOR_AGENT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-permitted-for-agent) | correctable | Seller-wide capability accepts the requested value, but the calling buyer agent's commercial relationship does not (e.g., onboarded as passthrough-only — no payments relationship — so only `operator` billing is permitted) | Retry with `error.details.suggested_billing` (typically `operator`) when present; when absent, the rejection is terminal-pending-onboarding — the agent MUST NOT auto-retry and MUST surface to a human at the buyer to complete payments-relationship onboarding with the seller offline |
| [`PAYMENT_TERMS_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-payment-terms-not-supported) | correctable | Seller does not accept the requested `payment_terms` value | Omit `payment_terms` to accept the default, retry with a different supported value, or negotiate offline |
| [`BRAND_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-brand-required) | correctable | Billable operation attempted without a brand reference | Include `brand` (`domain` plus optional `brand_id`) on the request |
Normative requirements:
* **Uniform response without established agent identity.** `BILLING_NOT_PERMITTED_FOR_AGENT` differs from `BILLING_NOT_SUPPORTED` based on the caller's onboarded commercial state with the seller. Returning the per-agent code without established identity lets unauthenticated probes use the code-choice as an oracle for "is this agent onboarded as agent-billable?" — same shape as the [`*_NOT_FOUND` uniform-response rule](#standard-error-codes). The bright line: sellers MUST emit `BILLING_NOT_PERMITTED_FOR_AGENT` only when agent identity has been established via signed-request derivation per [Agent identity](/dist/docs/3.2.8/building/by-layer/L1/security#agent-identity) or via a credential-to-agent mapping in the seller's onboarding record. In all other cases — including bearer credentials not mapped to a specific agent record — sellers MUST return `BILLING_NOT_SUPPORTED`, and `error.details.scope` MUST be omitted on this path so a `"account"` scope hint cannot itself act as a per-account-relationship oracle.
* **`BILLING_NOT_PERMITTED_FOR_AGENT` details shape is clamped.** `error.details` MUST conform to [`error-details/billing-not-permitted-for-agent.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/billing-not-permitted-for-agent.json): `rejected_billing` (echoed) plus an optional single `suggested_billing` retry value. The schema sets `additionalProperties: false`. The shape MUST NOT carry the agent's full permitted-billing subset, rate cards, payment terms, credit limit, billing entity, or any other per-agent commercial state — full-subset disclosure in a single probe is exactly the oracle the clamp prevents.
* **One-shot retry.** A buyer agent that retries with `error.details.suggested_billing` and receives a second `BILLING_NOT_PERMITTED_FOR_AGENT` MUST surface to a human rather than retrying again. Recovery is bounded to a single seller-suggested fallback; further iteration indicates seller misconfiguration or onboarding state the agent cannot resolve autonomously.
**Recovery dispatch — example.** The two billing codes recover differently. Implementers SHOULD branch explicitly rather than collapsing to a single retry path. The snippet below uses the response shape returned directly by the seller (the `accounts[].errors[]` array on a `sync_accounts` response — see [task reference](/dist/docs/3.2.8/accounts/tasks/sync_accounts)), not the `@adcp/sdk/testing` wrapper used elsewhere in task examples.
```javascript theme={null}
async function syncAccountsWithRecovery(client, account) {
const result = await client.syncAccounts({ accounts: [account] });
const error = result.accounts[0]?.errors?.[0];
if (!error) return result;
switch (error.code) {
case 'BILLING_NOT_SUPPORTED': {
// Seller-wide or per-account gate. Check capabilities, dispatch on scope.
const scope = error.details?.scope; // "capability" | "account"
if (scope === 'capability') {
// The seller never accepts this value. Pick from supported_billing.
const supported = error.details?.supported_billing ?? [];
if (supported.length === 0) return surfaceToHuman(error);
return client.syncAccounts({
accounts: [{ ...account, billing: supported[0] }],
});
}
// Per-account-relationship reject — the operator-on-this-account isn't
// billable directly. Try the next-most-permissive value the seller's
// capability allows.
return tryNextBillingValue(client, account, error);
}
case 'BILLING_NOT_PERMITTED_FOR_AGENT': {
// Per-buyer-agent commercial gate. Autonomous retry only when the seller
// suggests a fallback; otherwise surface — the agent cannot extend its
// own commercial relationship.
const suggested = error.details?.suggested_billing;
if (!suggested) return surfaceToHuman(error);
return client.syncAccounts({
accounts: [{ ...account, billing: suggested }],
});
}
default:
throw error;
}
}
```
**Example envelope** for `BILLING_NOT_PERMITTED_FOR_AGENT` — passthrough-only buyer agent receives a fallback to `operator`:
```json theme={null}
{
"accounts": [{
"brand": { "domain": "nova-brands.com", "brand_id": "spark" },
"operator": "pinnacle-media.com",
"action": "failed",
"status": "rejected",
"errors": [{
"code": "BILLING_NOT_PERMITTED_FOR_AGENT",
"message": "This buyer agent is onboarded as passthrough-only; only operator billing is permitted.",
"recovery": "correctable",
"details": {
"rejected_billing": "agent",
"suggested_billing": "operator"
}
}]
}]
}
```
### Authorization (RBAC)
Returned when the caller is authenticated but lacks the specific scope for the request. Enforcement is seller-local; discoverability is via the `authorization` object on per-account entries in [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) responses. See [Caller authorization](/dist/docs/3.2.8/accounts/overview#caller-authorization) for the full shape.
| Code | Recovery | Description | Resolution |
| - | - | - | - |
| [`PERMISSION_DENIED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-permission-denied) | correctable | Generic authorization failure, or a required signed credential (e.g., `governance_context`) is missing, failed verification, or was issued for a different plan/seller/phase | Call [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) to mint a valid token, or contact the seller to resolve the underlying permission |
| [`SCOPE_INSUFFICIENT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-scope-insufficient) | correctable | The invoked task is not in the caller's `allowed_tasks` for this account | Re-read `authorization` on the account via `sync_accounts` or `list_accounts` to discover the caller's actual `allowed_tasks`; use a permitted task or request a broader scope |
| [`READ_ONLY_SCOPE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-read-only-scope) | correctable | Caller's scope is `read_only: true`; the invoked task would mutate state | Use a non-mutating alternative, or request a scope that permits mutation |
| [`FIELD_NOT_PERMITTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-field-not-permitted) | correctable | A request field is not in the caller's `field_scopes` allowlist for this task | Drop the disallowed field, or request broader field scope |
| [`AGENT_SUSPENDED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-agent-suspended) | terminal | Calling buyer agent's commercial relationship with this seller is temporarily paused | Surface to a human at the buyer; re-onboarding with the seller offline may resolve. The agent cannot unilaterally lift a suspension. |
| [`AGENT_BLOCKED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-agent-blocked) | terminal | Calling buyer agent's commercial relationship with this seller is permanently denied | Surface to a human at the buyer; relationships are reinstated only through offline operator action with the seller. |
Normative requirements:
* **`FIELD_NOT_PERMITTED` MUST populate `error.field`** with the exact offending field path (e.g., `packages[0].budget`, `end_time`). Without it, agents cannot reliably auto-recover by stripping the field and retrying. When multiple fields are disallowed, sellers SHOULD return one error per offending field so each `error.field` is unambiguous; if returning a single error, `error.details.fields` MAY contain the full list.
* **`SCOPE_INSUFFICIENT` SHOULD include `error.details.introspection_hint`** when the seller supports the `authorization` object on sync/list. Strawman shape: `{ "task": "sync_accounts", "account": { ... } }` pointing the caller at where to rediscover scope. This closes the "I hit an error; what do I do?" loop for coding agents.
* **All four codes MUST populate both the `adcp_error` envelope field and the payload `errors[]` array** per the two-layer model above — scope errors carry through to typed client libraries the same way schema errors do.
`SCOPE_INSUFFICIENT` vs. `PERMISSION_DENIED`: use `SCOPE_INSUFFICIENT` when the task itself is not granted to this caller on this account. Reserve `PERMISSION_DENIED` for credential-shaped failures (missing signed context, failed signature verification) and for generic seller policy rejections where scope is not the right abstraction.
`SCOPE_INSUFFICIENT` vs. [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature): when both apply — the seller doesn't implement the task AND the caller wouldn't be scoped for it anyway — sellers SHOULD return `SCOPE_INSUFFICIENT` because it is more actionable (the caller can request broader scope) than `UNSUPPORTED_FEATURE` (the caller must switch sellers). A seller that returns `UNSUPPORTED_FEATURE` for a task it *does* implement but is not exposed to this caller is leaking capability information the caller cannot act on.
`FIELD_NOT_PERMITTED` vs. [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error): the field is valid per the task schema and would be accepted from a differently-scoped caller; it is rejected specifically because this caller's `field_scopes` does not include it.
**About `recovery: correctable` on authorization errors.** All four authz codes classify as `correctable`, meaning *the request can be fixed and re-sent*. This does NOT mean the agent can fix the request autonomously — the "correction" for `SCOPE_INSUFFICIENT` and `READ_ONLY_SCOPE` is an out-of-band scope grant from the operator, which the agent cannot perform on its own. Agents SHOULD surface authz errors to the operator rather than auto-retrying against the same credential; a retry loop against a fixed scope is a bug, not defensive posture — with the narrow exception of the bounded disambiguation retries described below. Only `FIELD_NOT_PERMITTED` has an agent-autonomous recovery path (strip the disallowed field and resubmit).
**Retry disambiguation for `SCOPE_INSUFFICIENT` and `READ_ONLY_SCOPE`.** A single response with either code inside the seller's 300s authorization refresh window is observationally indistinguishable from cross-replica flicker — a transient infrastructure artifact that the spec forbids sellers from producing but buyers will still encounter in practice. Before classifying the error as a definitive `correctable` signal requiring operator intervention, buyers MAY exhaust a bounded retry budget (no more than 3 attempts, each separated by 1–5 seconds of jittered backoff) to establish whether the scope is genuinely insufficient. This is disambiguation logic — not recovery from a correctable error. After bounded retries exhaust without success, buyers MUST surface the error and MUST NOT autonomously continue retrying. This retry exception does NOT apply to `FIELD_NOT_PERMITTED` — the agent-autonomous strip-and-resubmit path supersedes it. See [Buyer response to SCOPE_INSUFFICIENT within the refresh window](/dist/docs/3.2.8/accounts/overview#buyer-response-to-scope_insufficient-within-the-refresh-window) for the full guidance including the `READ_ONLY_SCOPE` caveat on revocation scenarios.
**`FIELD_NOT_PERMITTED` — example envelope and payload populating both layers:**
```json theme={null}
{
"adcp_error": {
"code": "FIELD_NOT_PERMITTED",
"message": "Caller's field_scopes for update_media_buy does not include this field",
"recovery": "correctable",
"field": "packages[0].budget"
},
"payload": {
"errors": [
{
"code": "FIELD_NOT_PERMITTED",
"message": "Caller's field_scopes for update_media_buy does not include this field",
"recovery": "correctable",
"field": "packages[0].budget",
"details": {
"task": "update_media_buy",
"permitted_fields": ["reporting_webhook"]
}
}
]
}
}
```
The `field` value identifies exactly what to strip; `details.permitted_fields` (optional, advisory) lists the allowlist for the offending task so an agent can verify before retrying. For `SCOPE_INSUFFICIENT`, populate `details.introspection_hint: { "task": "list_accounts", "account": { ... } }` to point the caller at where to rediscover scope.
#### Per-Agent Authorization Gate
The per-buyer-agent gate fires across three distinct rejection paths, each with its own discriminator so callers can dispatch without parsing prose:
| Code | `details.scope` | `details.reason` | Meaning |
| - | - | - | - |
| `AGENT_SUSPENDED` | — (no `details.scope`; the code is the discriminator) | — | Agent's commercial relationship with the seller is temporarily paused. Re-onboarding may resolve; `recovery: "terminal"`. |
| `AGENT_BLOCKED` | — (no `details.scope`; the code is the discriminator) | — | Agent's commercial relationship is permanently denied. No autonomous recovery; `recovery: "terminal"`. |
| `PERMISSION_DENIED` | `"agent"` | `"sandbox_only"` | Agent is provisioned for sandbox traffic only and the request was against a non-sandbox account. Per [`error-details/agent-permission-denied.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/agent-permission-denied.json), `additionalProperties: false`. |
Per-agent commercial-status rejections (`AGENT_SUSPENDED`, `AGENT_BLOCKED`) follow the [`BILLING_NOT_PERMITTED_FOR_AGENT`](#billing-and-account-setup) precedent — the code itself is the discriminator and the response carries no explicit `error.details.scope` field. The `PERMISSION_DENIED + scope:"agent"` path is reserved for non-status provisioning gates whose `reason` is registered in the closed enum on `error-details/agent-permission-denied.json`. The `"agent"` value is a registered subset of the shared discriminator vocabulary in [`enums/error-scope.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/error-scope.json).
**When to mint a new code vs. extend the `reason` enum.** Lifecycle-terminal per-agent states (suspended, blocked, future deny-list-style states) get dedicated codes — they carry distinct `recovery` classifications and warrant first-class discriminators. Non-status provisioning gates and transient rejections extend the `error-details/agent-permission-denied.json` `reason` enum (e.g., `sandbox_only`) instead; throttling-shaped rejections reuse [`RATE_LIMITED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-rate-limited), not a new per-agent code. The dedicated-code-per-state pattern composes only because the lifecycle vocabulary is finite — not as an open registry for every new gate.
**Migration note from the 3.0.5 placeholder.** 3.0.5 shipped `agent-permission-denied.json` with a `details.status: ["suspended", "blocked"]` axis as a placeholder for the per-agent lifecycle. 3.1 consolidates that placeholder into the dedicated `AGENT_SUSPENDED` / `AGENT_BLOCKED` codes — the `status` axis is removed from `agent-permission-denied.json` and the schema accepts only `scope:"agent" + reason:"sandbox_only"`. Sellers that integrated against the 3.0.5 placeholder MUST migrate to the dedicated codes; the placeholder shape is not preserved.
Normative requirements (apply to all three codes uniformly):
* **Uniform response without established agent identity.** Per-agent rejections are meaningful only when buyer-agent identity has been established via signed-request derivation per [Agent identity](/dist/docs/3.2.8/building/by-layer/L1/security#agent-identity) or via a credential-to-agent mapping in the seller's onboarding record. Sellers MUST emit `AGENT_SUSPENDED` / `AGENT_BLOCKED` or `PERMISSION_DENIED` with `details.scope: "agent"` ONLY on that path; in all other cases — including bearer credentials not mapped to a specific agent record — sellers MUST return generic `PERMISSION_DENIED` and MUST omit `error.details.scope`. Returning the per-agent code (or per-agent scope) without established identity lets unauthenticated probes use the code-choice as a cross-tenant onboarding oracle, the same shape the [`*_NOT_FOUND` uniform-response rule](#standard-error-codes) and [`BILLING_NOT_PERMITTED_FOR_AGENT`](#billing-and-account-setup) close.
* **Channels covered by the omit-on-unestablished-identity rule.** The MUST applies across every observable channel — `error.code` / `error.message` / `error.field` / `error.details` (message MUST be generic on the unestablished-identity path); HTTP status, A2A `task.status.state`, and MCP `isError`; response headers (ETag, Cache-Control, per-agent rate-limit buckets, CDN tags); side effects (audit-log writes, webhook dispatch, background-job enqueues, per-agent quota counters, DB-shard routing, onboarding-record cache population); observability (logs, APM spans, Sentry/Datadog/Rollbar tags MUST NOT carry agent identity, agent-record references, or per-agent gate classification on the unestablished-identity path). Polymorphism is evaluated against the tool-schema's declared parameter shape *before* any onboarding-record lookup — a tool's declared shape MUST be identical across all callers regardless of whether identity has been established.
* **Latency parity.** Sellers MUST execute the same shape of onboarding-record lookup on both paths (e.g., resolve-then-authorize against an empty agent-record on the unmapped-credential path) so that lookup latency does not distinguish "credential is not mapped to an agent" from "credential maps to a suspended/blocked agent." Resolve-then-authorize, decision-of-equivalent-shape, the same posture the `*_NOT_FOUND` rule requires. Cache population MUST NOT be gated on identity establishment — the cache itself is otherwise an oracle through hit/miss timing.
* **Retry-counter side channel.** The "no autonomous retry" rule (below) MUST NOT itself become a side channel. Sellers MUST NOT increment a per-agent retry/backoff counter, mint a different `retry_after`, or surface different rate-limit headers on the unestablished-identity path than they would on a true-unauthenticated path. Buyer agents that comply with the no-retry rule MUST NOT have that compliance reflected in seller-side per-agent observability that another tenant can read.
* **No per-agent commercial state on any of the three paths.** None of `AGENT_SUSPENDED`, `AGENT_BLOCKED`, or `PERMISSION_DENIED + scope:"agent"` carry the agent's full permitted-billing subset, rate cards, payment terms, credit limit, billing entity, contact channels, custom reason strings, or any other per-agent commercial state — full-subset disclosure in a single probe is exactly the oracle the clamp prevents. `AGENT_SUSPENDED` / `AGENT_BLOCKED` carry no `error.details` payload; `PERMISSION_DENIED + scope:"agent"` MUST conform to `error-details/agent-permission-denied.json` (`scope` + registered `reason`, with `additionalProperties: false`). New `reason` values MUST be added to the schema's enum so cross-language SDKs can dispatch without parsing prose; future per-agent state surfaces (escalation channels, lift-policy URLs) belong on new dedicated codes with their own clamped details shapes, NOT by relaxing this shape. The schema's `additionalProperties: false` is a schema-validation guard; sellers MUST treat unrecognized or extension keys received from a seller-side composer as a defect and drop them before transmission.
* **No autonomous retry on the per-agent gate.** All three codes are terminal in practice: `AGENT_SUSPENDED` and `AGENT_BLOCKED` declare it directly via `recovery: "terminal"` in `enumMetadata`; the `PERMISSION_DENIED + scope:"agent"` path is `correctable` at the wire level (matching the registered `PERMISSION_DENIED` classification) but is terminal-pending-onboarding in practice — the agent cannot unilaterally lift a sandbox-only provisioning. Buyer agents MUST surface to a human at the buyer rather than auto-retrying on any of the three; re-attempts only reinforce the gate.
**Recovery dispatch — example.** Branch on `error.code` first; only fall through to `details.scope` for the `PERMISSION_DENIED` per-agent gate:
```javascript theme={null}
async function dispatchAuthzError(error) {
// Per-agent commercial status — code is the discriminator, no details payload.
if (error.code === 'AGENT_SUSPENDED' || error.code === 'AGENT_BLOCKED') {
return surfaceToHuman({ code: error.code });
}
if (error.code !== 'PERMISSION_DENIED') throw error;
// Generic credential-shaped failure — no scope on details.
if (!error.details?.scope) {
return refreshGovernanceContextAndRetry(error);
}
// Per-agent provisioning gate — terminal-pending-onboarding.
if (error.details?.scope === 'agent') {
const { reason } = error.details;
// reason: 'sandbox_only'
return surfaceToHuman({ code: error.code, reason });
}
throw error; // Unknown scope — surface rather than guess.
}
```
**Example envelope** for `AGENT_SUSPENDED`:
```json theme={null}
{
"adcp_error": {
"code": "AGENT_SUSPENDED",
"message": "Buyer agent's commercial relationship with this seller is suspended.",
"recovery": "terminal"
}
}
```
**Example envelope** for `PERMISSION_DENIED` with the sandbox-only provisioning gate:
```json theme={null}
{
"adcp_error": {
"code": "PERMISSION_DENIED",
"message": "This buyer agent is provisioned for sandbox traffic only.",
"recovery": "correctable",
"details": {
"scope": "agent",
"reason": "sandbox_only"
}
}
}
```
The wire-level `recovery: "correctable"` on the sandbox-only path is the registered classification on `PERMISSION_DENIED` per [`error-code.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/error-code.json) `enumMetadata` — SDKs MUST NOT switch the registered value based on `details.scope`. Buyer agents MUST treat the rejection as terminal-pending-onboarding regardless of the wire-level `recovery` field, surface to a human, and not auto-retry. (For the suspended/blocked paths, the code itself carries `recovery: "terminal"` directly, so this caveat does not apply.)
### Request Validation
| Code | Recovery | Description | Resolution |
| - | - | - | - |
| [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) | correctable | Request is malformed or violates schema constraints | Check request parameters and fix |
| `UNSUPPORTED_FEATURE` | correctable | Requested feature not supported by this seller | Check `get_adcp_capabilities` and remove unsupported fields |
| [`POLICY_VIOLATION`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-policy-violation) | correctable | Request violates content or advertising policies | Review policy requirements in the error details |
| [`COMPLIANCE_UNSATISFIED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-compliance-unsatisfied) | correctable | Required disclosure cannot be satisfied by the target format | Choose a format that supports the required disclosure capabilities |
| [`GOVERNANCE_DENIED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-governance-denied) | correctable | A registered governance agent denied the transaction | Restructure the buy, escalate to human spending authority, or contact the governance agent |
### Inventory and Products
| Code | Recovery | Description | Resolution |
| - | - | - | - |
| [`PRODUCT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-not-found) | correctable | Referenced product IDs are unknown | Remove invalid IDs, or re-discover with [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) |
| [`PRODUCT_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-expired) | correctable | Referenced configured products passed `expires_at` and remain recognizable to the seller | Re-discover with [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) |
| [`PRODUCT_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-unavailable) | correctable | Product is sold out or no longer available | Choose a different product |
| [`PROPOSAL_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-expired) | correctable | Referenced proposal has passed its `expires_at` | Call [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals), then finalize a fresh proposal |
| `PROPOSAL_NOT_FOUND` | correctable | `proposal_id` is unknown to the seller (never issued, wrong tenant, or evicted from cache) | Request and finalize a fresh proposal, then retry |
| [`MULTI_FINALIZE_UNSUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-multi-finalize-unsupported) | correctable | A legacy `get_products` request attempted to finalize multiple proposals where the seller cannot guarantee atomic commitment | Sequence single-proposal legacy `get_products` finalize calls |
| [`REQUOTE_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-requote-required) | correctable | Requested update falls outside the envelope (budget, dates, volume, targeting) the original quote was priced against; `pricing_option` remains locked | In 3.2, use optional `error.details.decline_reason` to inform refinement of `accepted_proposal_id`; legacy 3.1 callers adjust or rediscover. |
| `SIGNAL_NOT_FOUND` | correctable | Referenced signal does not exist in the catalog | Verify `signal_id` via [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals), or confirm availability from this agent |
| [`AUDIENCE_TOO_SMALL`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-audience-too-small) | correctable | Audience segment below minimum size | Broaden targeting or upload more audience members |
For `REQUOTE_REQUIRED`, details SHOULD follow [`error-details/requote-required.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/requote-required.json). For [`ACTION_NOT_ALLOWED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-action-not-allowed) with `reason: "not_supported_on_buy"`, the existing [`error-details/action-not-allowed.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/action-not-allowed.json) shape also permits `decline_reason`. Sellers SHOULD emit the coarse reason when they have a structured seller-policy classification and disclosure does not expose private thresholds or enforcement controls. Buyers MUST tolerate its absence and MUST NOT infer that an undisclosed policy does not exist. Structural action denials SHOULD omit it.
**Implementation note (non-normative).** Repeated out-of-envelope controls can be used to map a seller's exact share-of-voice, notice-window, frequency, or commitment thresholds. Consider rate-limiting these deterministic probes using the same posture as [`refine_proposals`](/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation#log-for-audit-without-leaking-terms), and omit `decline_reason` when even the coarse category would disclose sensitive enforcement logic.
### Budget and Creative
| Code | Recovery | Description | Resolution |
| - | - | - | - |
| [`BUDGET_TOO_LOW`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-budget-too-low) | correctable | Budget below seller's minimum | Increase budget or check `capabilities.media_buy.limits` |
| [`BUDGET_EXHAUSTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-budget-exhausted) | terminal | Account or campaign budget fully spent | Buyer must add funds or increase budget cap |
| `CREATIVE_NOT_FOUND` | correctable | Referenced creative does not exist in the library | Verify `creative_id` via [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives), or register it via [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) |
| [`CREATIVE_REJECTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-rejected) | correctable | Creative failed content-policy, brand-safety, or accessibility review | Revise according to the applicable policy or validated accessibility criteria |
### System
| Code | Recovery | Description | Resolution |
| - | - | - | - |
| `RATE_LIMITED` | transient | Request rate exceeded | Wait for `retry_after` seconds, then retry |
| [`SERVICE_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-service-unavailable) | transient | Seller service temporarily unavailable | Retry with exponential backoff |
| [`STALE_RESPONSE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-stale-response) | transient (advisory) | Non-fatal: seller served a populated payload from cache past its freshness target because an upstream/sub-agent was unreachable. Distinct from `SERVICE_UNAVAILABLE` (empty payload + fatal). `error.details` follows [`error-details/stale-response.json`](pathname:///schemas/v3/error-details/stale-response.json) | Accept the cached payload, or retry later for fresh data — inspect `error.details.cache_age_seconds` to decide |
| [`CONFIGURATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-configuration-error) | terminal | Seller-side deployment misconfiguration (e.g., missing `mock_upstream_url`, undeclared `upstream_url`, unset env var). Distinct from `SERVICE_UNAVAILABLE` (transient) and `INVALID_REQUEST` (buyer-fixable). Sellers MUST flip transport failure markers (HTTP 5xx, MCP `isError: true`, A2A `failed`); `error.message` carries operator-actionable detail and MUST NOT include credentials, connection strings, or stack traces | Surface to the seller's operator; do not auto-retry — retries will not resolve a misconfigured deployment |
| [`CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflict) | transient | Concurrent modification detected | Re-read the resource and retry with current state |
| `REFERENCE_NOT_FOUND` | correctable | Generic fallback for referenced resources without a dedicated not-found code. See [Not-found precedence](#standard-error-codes) | Verify the identifier via the appropriate discovery task; prefer a resource-specific code when one exists |
## Recovery Classification
Use the `recovery` field to determine how to handle errors. When a legacy error omits it, use the registered classification for a known code and `transient` for an unknown code:
| Recovery | Meaning | Action |
| - | - | - |
| `transient` | Temporary failure (rate limit, service unavailable, conflict) | Retry after `retry_after` or with exponential backoff |
| `correctable` | Request can be fixed and resent (invalid field, budget too low, creative rejected) | Modify the request and retry |
| `terminal` | Requires human action (account suspended, payment required) | Escalate to a human operator |
For unknown `recovery` values (forward compatibility), treat as `terminal`.
```javascript theme={null}
function recoveryFor(error, knownRecoveryByCode) {
if (['transient', 'correctable', 'terminal'].includes(error.recovery)) {
return error.recovery;
}
if (error.recovery !== undefined) {
return 'terminal'; // Unknown future recovery value: fail closed
}
return knownRecoveryByCode[error.code] ?? 'transient';
}
function isRetryable(error, knownRecoveryByCode) {
return recoveryFor(error, knownRecoveryByCode) === 'transient';
}
```
## Retry Logic
The rules in this section bound every `transient`-classified error a caller may retry, including the `transient` default applied to unknown error codes under [§ Forward-compatible decoding](#forward-compatible-decoding-normative). A receiver that decodes an unknown code and falls back to `transient` MUST apply `maxRetries` and the jittered exponential-backoff schedule below; the open-enum decoding rule does not exempt receivers from the retry budget. A hostile or buggy sender emitting `code=GO_FOREVER, recovery=transient` cannot induce unbounded retries against a conformant client.
### Normative retry scheduling
Classification happens before scheduling. `retry_after` specifies when a retry may run; it never changes whether the error is retryable.
* Callers **MUST NOT** automatically retry an error whose effective recovery is `correctable` or `terminal`, even when `retry_after` is present. A delay is not permission to repeat an uncorrected request or bypass required human action.
* When automatically retrying a `transient` error with `retry_after`, callers **MUST NOT** retry sooner than the indicated delay. AdCP 3.2 producers **MUST** emit an integer. A caller that receives a legacy finite fractional value **MUST** round it up before clamping to `[1, 3600]` so it never schedules earlier than intended.
* Callers retrying a `transient` error without `retry_after` **SHOULD** use exponential backoff with jitter. A base of 2 seconds, a cap of 60 seconds, and ±25% jitter is a safe default.
* Every automatic retry path **MUST** consume the caller's bounded retry budget, including retries selected from a known-code classification or the unknown-code `transient` fallback.
* Callers **SHOULD** surface repeated throttling to their operator rather than retrying indefinitely; a persistent [`RATE_LIMITED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-rate-limited) response is a capacity or policy signal, not a transient blip.
* Sellers **SHOULD** return `RATE_LIMITED` with a populated `retry_after` rather than silently queuing or dropping requests, so well-behaved callers can back off intentionally.
* Sellers **MAY** populate the [`rate-limited`](https://adcontextprotocol.org/schemas/3.2.8/error-details/rate-limited.json) detail shape (`limit`, `remaining`, `window_seconds`, `scope`) to let callers plan ahead rather than react per-429.
### Exponential Backoff
Implement exponential backoff for retryable errors:
```javascript theme={null}
async function retryWithBackoff(fn, knownRecoveryByCode, options = {}) {
const {
maxRetries = 3,
baseDelay = 1000,
maxDelay = 60000
} = options;
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
if (!isRetryable(error, knownRecoveryByCode) || attempt === maxRetries) {
throw error;
}
let delay;
if (Number.isFinite(error.retry_after)) {
const seconds = Math.min(3600, Math.max(1, Math.ceil(error.retry_after)));
delay = seconds * 1000;
} else {
const backoff = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
delay = backoff * (0.75 + Math.random() * 0.5);
}
await sleep(delay);
}
}
}
```
### Rate Limit Handling
```javascript theme={null}
async function handleRateLimit(error, knownRecoveryByCode, retryState, retryFn) {
if (recoveryFor(error, knownRecoveryByCode) !== 'transient') {
throw error;
}
if (retryState.retriesAttempted >= retryState.maxRetries) {
throw error;
}
const retryAfter = Number.isFinite(error.retry_after)
? Math.min(3600, Math.max(1, Math.ceil(error.retry_after)))
: 60;
console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
await sleep(retryAfter * 1000);
return retryFn({
...retryState,
retriesAttempted: retryState.retriesAttempted + 1,
});
}
```
## Error Handling Patterns
### Basic Error Handler
```javascript theme={null}
async function handleAdcpError(error, knownRecoveryByCode, retryState) {
switch (recoveryFor(error, knownRecoveryByCode)) {
case 'transient': {
if (retryState.retriesAttempted >= retryState.maxRetries) {
throw error;
}
const delay = Number.isFinite(error.retry_after)
? Math.min(3600, Math.max(1, Math.ceil(error.retry_after))) * 1000
: 5000;
await sleep(delay);
return retry({
...retryState,
retriesAttempted: retryState.retriesAttempted + 1,
});
}
case 'correctable':
// Surface suggestion so the request can be fixed
if (error.suggestion) {
console.log('Suggestion:', error.suggestion);
}
if (error.field) {
console.log('Problem field:', error.field);
}
throw error;
case 'terminal':
console.error('Terminal error:', error.message);
throw error;
}
// Fall back to error code matching
switch (error.code) {
case 'AUTH_REQUIRED': {
// Two sub-cases share this code; see the AUTH_REQUIRED warning above.
const requestHadCredentials = Boolean(error.request_had_credentials);
if (!requestHadCredentials) {
await refreshCredentials();
return retry();
}
// Credentials were presented and rejected — surface to operator.
throw error;
}
case 'INVALID_REQUEST':
console.error('Validation error:', error);
throw error;
default:
console.error('AdCP error:', error);
throw error;
}
}
```
### User-Friendly Messages
Convert technical errors to user-friendly messages:
```javascript theme={null}
const USER_MESSAGES = {
'RATE_LIMITED': 'Too many requests. Please wait a moment and try again.',
'BUDGET_TOO_LOW': 'This is below the seller\'s minimum budget. Increase your budget.',
'PRODUCT_NOT_FOUND': 'One or more products could not be found. Try searching again.',
'ACCOUNT_SUSPENDED': 'Your account has been suspended. Contact the seller to resolve.',
'SERVICE_UNAVAILABLE': 'The service is temporarily unavailable. Please try again in a few minutes.',
'CREATIVE_REJECTED': 'Your creative did not pass creative review. Check the validated diagnostics for details.',
'AUDIENCE_TOO_SMALL': 'Your target audience is too small. Try broadening your targeting.'
};
function getUserMessage(code, fallbackMessage) {
return USER_MESSAGES[code] || fallbackMessage || 'An unexpected error occurred. Please try again.';
}
```
### Structured Error Logging
Log errors with context for debugging:
```javascript theme={null}
function logError(error, context = {}) {
console.error('AdCP Error:', {
code: error.code,
recovery: error.recovery,
message: error.message,
field: error.field,
timestamp: new Date().toISOString(),
...context,
// Don't log sensitive data
// NO: credentials, briefs, PII
});
}
```
## Webhook Error Handling
### Failed Webhook Delivery
When webhook delivery fails, fall back to polling:
```javascript theme={null}
class WebhookErrorHandler {
async onDeliveryFailure(taskId, error) {
console.warn(`Webhook delivery failed for ${taskId}:`, error);
// Start polling as fallback
this.startPolling(taskId);
// Track failure for monitoring
this.metrics.incrementCounter('webhook_failures');
}
async startPolling(taskId) {
const response = await adcp.call('tasks/get', {
task_id: taskId,
include_result: true
});
if (['completed', 'failed', 'canceled'].includes(response.status)) {
await this.processResult(taskId, response);
} else {
// Schedule next poll
setTimeout(() => this.startPolling(taskId), 30000);
}
}
}
```
### Webhook Handler Errors
Handle errors in your webhook endpoint gracefully:
```javascript theme={null}
app.post('/webhooks/adcp', async (req, res) => {
try {
// Always respond quickly
res.status(200).json({ status: 'received' });
// Process asynchronously
await processWebhookAsync(req.body);
} catch (error) {
// Log error but don't fail the response
console.error('Webhook processing error:', error);
// Move to dead letter queue for investigation
await deadLetterQueue.add(req.body, error);
}
});
```
## Recovery Strategies
### Continuation Recovery
If a verified continuation descriptor expires, reconcile durable state and start a new transport conversation. Do not retry by deleting or replacing a request-body `context_id`:
```javascript theme={null}
async function callWithContinuationRecovery(continuation, request) {
try {
return await resumeContinuation(continuation, request);
} catch (error) {
if (error.code === 'CONTINUATION_EXPIRED') {
await reconcileDurableTaskState(request.task_id);
return startNewTransportConversation(request);
}
throw error;
}
}
```
### Partial Success Handling
Some operations may partially succeed:
```json theme={null}
{
"status": "completed",
"message": "Created media buy with warnings",
"media_buy_id": "mb_123",
"errors": [
{
"code": "COMPLIANCE_UNSATISFIED",
"message": "Required disclosure position not supported by one placement",
"field": "packages[0].placements[2]",
"suggestion": "Choose a format that supports the required disclosure positions"
}
]
}
```
Handle partial success:
```javascript theme={null}
function handlePartialSuccess(response) {
if (response.status === 'completed' && response.errors?.length) {
// Show warnings to user
for (const warning of response.errors) {
showWarning(warning.message, warning.suggestion);
}
}
// Continue with successful result
return response;
}
```
## Governance Error Patterns
[`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) returns a `status` field rather than an error object. Governance results are not errors in the protocol sense — they are decisions. Handle them separately from AdCP task errors.
| Governance status | Meaning | Action |
| - | - | - |
| `approved` | Plan passes governance | Proceed |
| `conditions` | Approved with constraints | Apply conditions, re-check |
| `denied` | Plan violates governance | Block the operation |
If the governance agent needs human review internally (e.g., the action exceeds the agent's authority), `check_governance` behaves like any async task — it returns `submitted`/`working` status and eventually resolves to `approved` or `denied`. Handle this with the standard [async task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle), not special-case logic.
Governance errors from the protocol layer (as opposed to governance decisions) use the standard error format. The most common:
| Code | Recovery | When it occurs |
| - | - | - |
| [`PLAN_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-plan-not-found) | correctable | [`sync_plans`](/dist/docs/3.2.8/governance/campaign/tasks/sync_plans) was not called before `check_governance` |
| [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) | correctable | Missing required fields (e.g., `plan_id`, `caller`) |
| [`AUTH_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-required) | correctable | Governance agent requires authentication |
## Configuration Error Patterns
[`CONFIGURATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-configuration-error) signals a seller-side deployment defect — an account declared with `mode: 'mock'` but no `mock_upstream_url`, a platform on `mode: 'live'` or `mode: 'sandbox'` with no `upstream_url`, a required environment variable unset on the seller process. The buyer cannot fix it; retries cannot resolve it; an operator at the seller has to. The catalog has no generic `INTERNAL_ERROR` code by design, and `CONFIGURATION_ERROR` is deliberately narrower — it covers the actionable slice where the remediation is "report this to the seller's operator." Opaque crashes that don't fit that profile remain catalog-uncoded; sellers MAY return platform-specific codes, and buyers fall back to the `recovery` classification per the [forward-compatibility rule](#recovery-classification).
### Aggregate signal: per-request terminal, per-seller outage
A single `CONFIGURATION_ERROR` is `terminal` for the request that received it — the buyer MUST surface to a human at the seller and MUST NOT auto-retry. Repeated `CONFIGURATION_ERROR` from the same seller in a short window is an operational signal of a different kind: a seller-side outage. Buyer-side dashboards and alerting SHOULD treat aggregate `CONFIGURATION_ERROR` rate per seller as an outage indicator (e.g., page on N occurrences in M minutes from a single seller), distinct from the per-request-terminal handling. This convergence matters because a buyer that buckets aggregate `CONFIGURATION_ERROR` with generic terminal errors loses the seller-isolated outage signal that motivated the code's existence.
### error.message: operator-actionable, not deployment-internal
The code itself is the discriminator — `CONFIGURATION_ERROR` carries no `error.details` shape (the [minimal-disclosure precedent](#per-agent-authorization-gate) of [`AGENT_SUSPENDED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-agent-suspended) / [`AGENT_BLOCKED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-agent-blocked) applies). `error.message` carries the diagnostic, and sellers SHOULD calibrate it to a level useful to a seller-side operator without leaking deployment internals to the buyer. The message is wire-visible — it MUST NOT include credentials, connection strings, full file paths, or stack traces.
Useful (operator can act, buyer learns nothing exploitable):
```json theme={null}
{
"code": "CONFIGURATION_ERROR",
"message": "account is mode='mock' but no mock_upstream_url declared in metadata; populate it in the AccountStore",
"recovery": "terminal"
}
```
Not useful (the operator already knew there was a problem; the buyer learns where the seller's filesystem is):
```json theme={null}
{
"code": "CONFIGURATION_ERROR",
"message": "configuration error",
"recovery": "terminal"
}
```
Leaks (don't):
```json theme={null}
{
"code": "CONFIGURATION_ERROR",
"message": "ECONNREFUSED postgres://admin:hunter2@10.0.1.42:5432/prod (at /opt/seller/src/db/pool.ts:127)",
"recovery": "terminal"
}
```
## Best Practices
1. **Check `recovery` first** — it's the most reliable signal for how to handle an error
2. **Implement retries** — use exponential backoff for transient errors
3. **Respect rate limits** — honor `retry_after` values
4. **Handle unknown codes gracefully** — fall back to `error.recovery`; default to `transient` when absent (see [Forward-compatible decoding](#forward-compatible-decoding-normative))
5. **Log with context** — include `code`, `recovery`, and `field` for debugging
6. **Fallback strategies** — always have a backup (e.g., polling for webhooks)
7. **Don't retry terminal errors** — escalate to a human operator
8. **Handle partial success** — process warnings in successful responses
## Next Steps
* **Transport Bindings**: See [Transport Errors](/dist/docs/3.2.8/building/operating/transport-errors) for how errors travel over MCP and A2A
* **Task Lifecycle**: See [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle) for status handling
* **Webhooks**: See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for webhook error handling
* **Security**: See [Security](/dist/docs/3.2.8/building/by-layer/L1/security) for authentication errors
# L3 — Protocol semantics
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L3/index
Protocol-semantics layer of the AdCP stack. Lifecycle state machines, idempotency, error catalog, async-task contract, conformance test surface, webhook emission. Where most of an SDK's value lives.
L3 enforces what AdCP *means* on the agent side. The wire shape is well-formed (L0); the caller is authentic (L1) and authorized (L2); now: is the request legal given the current state of the world?
For agents, L3 is the bulk of the protocol surface — the [3–4 person-month from-scratch build](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#why-sdks-matter-more-in-adcp-than-in-eg-http) lives almost entirely here. For callers, L3 is consumer-side: weeks of handler glue, classifying error codes and handling state transitions rather than enforcing them.
## What an SDK at L3 must provide
If you're picking an SDK or porting one to a new language, this is the L3 build target:
* **Lifecycle state-machine graphs** for all spec-defined resources, with a transition-assertion primitive that emits the spec-correct error code (`NOT_CANCELLABLE` / `INVALID_STATE` / etc.).
* **Idempotency cache** with cross-payload conflict detection and the no-payload-echo invariant on `IDEMPOTENCY_CONFLICT` envelopes.
* **Async-task store + dispatcher** — tools opt into async; the SDK returns `task_id`, accepts polling, and emits the terminal artifact.
* **Webhook emitter** — signed, retried, idempotent.
* **The conformance test surface** (`comply_test_controller`), wired to drive state deterministically when the resolved account is in sandbox or mock mode (and rejected otherwise).
* **Per-resource persistence primitives** that handle the spec's echo contracts.
* **Server-construction entry point** that ties all of the above together with sane defaults.
For the cumulative cross-layer story (what L0+L1+L2+L3 buys you), see the [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#l3--protocol-semantics). For what changed at L3 between 2.5 and 3.0, see [What changed at L3 in 3.0](/dist/docs/3.2.8/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0).
## Pages in this layer
* **[Task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle)** — status values, transitions, polling.
* **[Async operations](/dist/docs/3.2.8/building/by-layer/L3/async-operations)** — sync, async, and interactive task handling.
* **[Async identity and convergence](/dist/docs/3.2.8/building/by-layer/L3/async-identity-and-convergence)** — normative identity boundaries, cross-channel races, resumability, and single-winner publication.
* **[Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks)** — push notifications, signing, retry, idempotency.
* **[Error handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling)** — error categories, codes, recovery classification.
* **[`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller)** — sandbox-only conformance test surface.
# Task Lifecycle
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle
AdCP task lifecycle: status values (submitted, working, input-required, completed, failed), state transitions, response structure, and polling patterns for all operations.
Every AdCP response includes a `status` field that tells you exactly what state the operation is in and what action you should take next. This is the foundation for handling any AdCP operation.
:::note Application-layer task state
The status values and lifecycle described here are transport-independent AdCP application state. MCP and A2A task mechanisms may wrap, stream, or deliver an AdCP response, but they do not replace AdCP's `task_id`, webhook payloads, or polling/reconciliation surfaces.
For `submitted` operations, observe the AdCP task with [push notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks) or the AdCP polling surface. The [AdCP v3 A2A profile](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension) standardizes fresh `get_task_status` invocations; MCP sellers may expose either `get_task_status` or the legacy AdCP `tasks/get` alias. Transport-native MCP/A2A task methods use their own wire shapes and are separate from AdCP task polling.
All channels follow the [async identity and convergence
contract](/dist/docs/3.2.8/building/by-layer/L3/async-identity-and-convergence). In
particular, A2A `Task.id`, AdCP `task_id`, operation IDs, request idempotency
keys, and webhook delivery keys are distinct and MUST NOT be substituted.
:::
## Status Values
AdCP uses the same status values as the [A2A protocol's TaskState enum](https://a2a-protocol.org/dev/specification/#63-taskstate-enum):
| Status | Meaning | Your Action |
| - | - | - |
| `submitted` | Task queued, blocked on external dependency | Configure webhook, show "queued" indicator |
| `working` | Agent actively processing (>30s) | Wait for result — out-of-band progress signal, not a polling trigger |
| `input-required` | Needs information from you | Resume only with a verified transport continuation descriptor; otherwise reconcile or fail closed |
| `completed` | Successfully finished | Process `data`, show success message |
| `canceled` | User/system canceled task | Show cancellation notice, clean up |
| `failed` | Error occurred | Show error from `message`, handle gracefully |
| `rejected` | Agent rejected the request | Show rejection reason, don't retry |
| `auth-required` | Authentication needed | Prompt for auth; resume only through the verified transport continuation or start a permitted new attempt |
| `unknown` | Indeterminate state | Log for debugging, may need manual intervention |
## Response Structure
Every AdCP response uses a **flat structure** where task-specific fields are at the top level:
```json theme={null}
{
"status": "completed", // Always present: what state we're in
"message": "Found 5 products", // Always present: human explanation
"context_id": "ctx-123", // Transport metadata; not MCP continuation state
"context": { // Application-level context echoed back
"ui": "buyer_dashboard"
},
"products": [...] // Task-specific fields at top level
}
```
:::warning Single status field required
Agents MUST NOT emit the legacy `task_status` or `response_status` fields alongside `status`. The `status` field is the single authoritative task state. Agents emitting either alongside `status` are non-conformant.
:::
## Status Handling
### Basic Pattern
```javascript theme={null}
function handleAdcpResponse(response) {
switch (response.status) {
case 'completed':
// Success - process the data (task fields are at top level)
showSuccess(response.message);
return processData(response);
case 'input-required':
// A status alone is not a continuation capability.
const continuation = verifiedContinuationFor(response);
if (!continuation) {
return requireReconciliation(response);
}
const userInput = await promptUser(response.message);
return resumeContinuation(continuation, userInput);
case 'working':
// Server is actively processing — just wait, result will arrive
showProgress(response.message);
return response;
case 'failed':
// Error - show message and handle gracefully
showError(response.message);
return handleError(response.errors);
case 'auth-required':
// Authentication needed; status/context alone do not authorize resume.
const authContinuation = verifiedContinuationFor(response);
if (!authContinuation) return requireReconciliation(response);
const credentials = await getAuth();
return resumeContinuation(authContinuation, { credentials });
default:
// Unexpected status
console.warn('Unknown status:', response.status);
showMessage(response.message);
}
}
```
### Clarification Flow
When status is `input-required`, the message tells you what's needed. The
transport or SDK must separately supply verified continuation identity before
the client can resume:
```json theme={null}
{
"status": "input-required",
"message": "I need more information about your campaign. What's your budget and target audience?",
"context_id": "ctx-123",
"products": [],
"suggestions": ["budget", "audience", "timing"]
}
```
**Client handling:**
```javascript theme={null}
const continuation = verifiedContinuationFor(response);
if (response.status === 'input-required' && continuation) {
// Extract what's needed from the message
const missingInfo = extractRequirements(response.message);
// Prompt user with specific questions
const answers = await promptForInfo(missingInfo);
return resumeContinuation(continuation, answers);
}
```
### Approval Flow
Human approval at the task layer is modelled as `input-required` (when the buyer must respond, e.g. confirm a budget) or `submitted` (when the seller is waiting on an internal human, e.g. IO signing). These implement the [Embedded Human Judgment](/dist/docs/3.2.8/governance/embedded-human-judgment) principle that judgment cannot be delegated to software — when an action exceeds autonomous authority, the system halts for human review rather than proceeding.
> `pending_approval` is an Account status, not a task status and not a MediaBuy status. It indicates the seller is reviewing an account (credit, contracts) before it can be used. Don't reuse the name for task-level approval.
```json theme={null}
{
"status": "input-required",
"message": "Media buy exceeds auto-approval limit ($100K). Please approve to proceed with campaign creation.",
"context_id": "ctx-123",
"approval_required": true,
"amount": 150000,
"reason": "exceeds_limit"
}
```
**Client handling:**
```javascript theme={null}
if (response.status === 'input-required' && response.approval_required) {
const continuation = verifiedContinuationFor(response);
if (!continuation) return requireReconciliation(response);
// Show approval UI
const approved = await showApprovalDialog(response.message, response);
// Send approval decision
const decision = approved ? "Approved" : "Rejected";
return resumeContinuation(continuation, { decision });
}
```
### Operations Over 30 Seconds
Operations that take longer than 30 seconds return either `working` or `submitted`. These statuses mean different things:
* **`working`**: The server is actively processing and will deliver the result when ready. No polling needed — the server sends progress out-of-band and the result arrives on the open connection.
* **`submitted`**: The operation is blocked on an external dependency (human approval, publisher review). Configure a webhook or poll.
```json theme={null}
{
"status": "submitted",
"message": "Media buy submitted for publisher approval",
"context_id": "ctx-123",
"task_id": "task-456"
}
```
**Handling for `submitted` operations:**
* **All transports**: Use [push notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks) (recommended) or poll the AdCP task with `get_task_status` / legacy `tasks/get`.
* **MCP/A2A transport tasks**: Treat native task state as transport state. A native task can finish once it has delivered an AdCP payload that still says `status: 'submitted'`.
## Status Progression
Tasks progress through predictable states:
```
submitted → working → completed
↓ ↓ ↑
input-required → → → → →
↓
failed
```
* **`submitted`**: Task queued, blocked on external dependency — configure webhook or poll
* **`working`**: Agent actively processing (>30s) — wait for result, no polling needed
* **`input-required`**: Need user input; resume only through verified transport-native continuation identity
* **`completed`**: Success, process results
* **`failed`**: Error, handle appropriately
## Polling and Timeouts
### Polling is for `submitted` only
Don't poll for `working` — the server delivers the result on the open connection. Polling is a backup for `submitted` operations (webhooks are preferred).
Send `include_result: true` to receive the canonical terminal task payload when
the task produced one. The `result` object carries the same task-specific shape
the original task would have returned—for example, a completed
`create_media_buy` task returns its media buy and packages. Failed and rejected
tasks also return their canonical terminal artifact when one exists; the
legacy singular `error` field on a failed poll is only a convenience summary
and must agree with that artifact. Canceled tasks can have no result. Webhooks
remain the supported delivery mechanism (see [Push
Notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks)); `include_result` is the
typed polling alternative for buyers that prefer pull over push.
### Typed task results in SDKs
AdCP 3.2 deliberately keeps the polling envelope's `result` property generic. Draft-07 cannot select a `$ref` dynamically from the sibling `task_type` value without enumerating every task, and embedding that enumeration made `get_task_status` grow whenever any async-capable tool grew. Exact result validation is still required; it is selected through the release manifest instead of duplicated into the polling schema.
The release `manifest.json` artifact therefore publishes `task_result_resolution`. For a terminal result, first check `terminal_schema_overrides[task_type]`; when no override exists, replace `{task_type}` in `/tools/{task_type}/response_schema`. A tool's canonical response schema already contains its task-local terminal branches, including the structured `get_products` rejection. SDK generators SHOULD use that rule to expose a generic relationship equivalent to:
```ts theme={null}
type ToolTaskType = Extract;
type TaskHandle = { taskId: string; taskType: T };
type TaskResult =
T extends keyof TaskResultOverrides
? SchemaType
: T extends ToolName
? ToolResponse
: never;
type TaskStatus = {
task_id: string;
task_type: T;
status: AdcpTaskStatus;
result?: TaskResult;
};
```
A tool call that returns `submitted` can retain its tool name in `TaskHandle`, so a later `getTaskStatus(handle)` returns the precise result type without importing a global union. SDKs SHOULD keep a string-only overload for recovered or persisted task IDs; that overload returns an unknown result until the response's `task_type` is checked, then resolves and validates the matching manifest schema or override. If a typed handle's expected tool differs from the returned `task_type`, the SDK MUST reject the response as a task-correlation failure.
Webhook envelopes retain their separate async payload schema. For 3.x compatibility, task reconciliation also continues to accept the historically shared event value `media_buy_delivery`; its manifest override selects `media-buy-delivery-webhook-result.json`. AdCP 4.0 can separate event types from tool task types, remove the legacy `tasks/get` alias, and make this generic SDK relationship part of the canonical task model.
```javascript theme={null}
// Polling is only for 'submitted' operations
async function pollForResult(taskId, pollInterval = 30_000) {
while (true) {
await sleep(pollInterval);
const response = await adcp.call('get_task_status', {
task_id: taskId,
include_result: true
});
if (['completed', 'failed', 'canceled'].includes(response.status)) {
// response.result carries the terminal payload when status === 'completed'
// response.error carries error details when status === 'failed'
return response;
}
}
}
```
### Timeout Configuration
```javascript theme={null}
const TIMEOUTS = {
sync: 30_000, // 30 seconds — most operations complete here
working: 300_000, // 5 minutes — connection timeout for active processing
interactive: 300_000, // 5 minutes for human input
submitted: 86_400_000 // 24 hours for external dependencies
};
function getTimeout(status) {
if (status === 'submitted') return TIMEOUTS.submitted;
if (status === 'working') return TIMEOUTS.working;
if (status === 'input-required') return TIMEOUTS.interactive;
return TIMEOUTS.sync;
}
```
## Task Reconciliation
Use `list_tasks` (or legacy `tasks/list` in 3.x) to recover from lost state:
```javascript theme={null}
// Find all pending operations
const pending = await session.call('list_tasks', {
filters: {
statuses: ["submitted", "working", "input-required"]
}
});
// Reconcile with local state
const missingTasks = pending.tasks.filter(task =>
!localState.hasTask(task.task_id)
);
// Resume tracking missing tasks
for (const task of missingTasks) {
startPolling(task.task_id);
}
```
## Best Practices
1. **Always check status first** - Don't assume success
2. **Handle all statuses** - Include a default case for unknown states
3. **Use transport-native context** - A2A uses native `contextId`; MCP request-body `context_id` is a compatibility no-op
4. **Use task_id for tracking** - Especially for long-running operations
5. **Implement timeouts** - Don't wait forever
6. **Log status transitions** - Helps with debugging and auditing
## Next Steps
* **Async Operations**: See [Async Operations](/dist/docs/3.2.8/building/by-layer/L3/async-operations) for handling different operation types
* **Webhooks**: See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for push notification patterns
* **Error Handling**: See [Error Handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling) for error categories and recovery
# Push Notifications
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L3/webhooks
AdCP push notifications: how sellers deliver async task status updates to your webhook endpoint via RFC 9421–signed POST requests (with legacy HMAC fallback). Setup, URL templates, and idempotency.
Push notifications let sellers deliver task status updates to you directly, instead of requiring you to poll. You provide a webhook URL in the task request; the seller POSTs status changes to that URL as the task progresses.
## How it works
1. A unique operation ID is generated per task invocation for webhook correlation
2. A webhook URL is built for your receiver. The URL may contain your own routing token, but it is opaque to the seller
3. `push_notification_config` is injected into the task request body with the URL and explicit `operation_id` — no shared secret required
4. The seller POSTs webhook notifications to your URL as the task status changes, signing each POST with its `adcp_use: "request-signing"` key published in its own brand.json `agents[]` entry; deprecated `webhook-signing` keys remain accepted during the compatibility window
5. You verify the signature against the seller's published JWKS and dedupe by `idempotency_key`
6. Each notification echoes the explicit `operation_id` back in the payload so you can correlate it without parsing the URL
```
create_media_buy request
└── push_notification_config
└── url: "https://you.com/adcp/webhook/create_media_buy/agent_123/route_abc123"
└── operation_id: "op_456"
// No shared secret — the seller signs with its own key, you verify against
// its published JWKS. See "Signature verification" below.
↓ seller processes task ↓
POST https://you.com/adcp/webhook/create_media_buy/agent_123/route_abc123
Signature-Input: sig1=("@method" "@target-uri" "@authority" "content-type" "content-digest");
created=1706097600;expires=1706097900;nonce="...";keyid="seller-webhook-2025";
alg="ed25519";tag="adcp/webhook-signing/v1"
Signature: sig1=::
Content-Digest: sha-256=::
Content-Type: application/json
{
"idempotency_key": "whk_01HW9D3H8FZP2N6R8T0V4X6Z9B", ← dedup by this
"task_id": "task_456",
"operation_id": "op_456", ← echoed from push_notification_config.operation_id
"status": "completed",
"result": { ... }
}
```
Webhook v1 retains this legacy unpadded Base64URL encoding throughout AdCP 3.x; it does not inherit the 3.2 request-signing migration to RFC 8941 padded Base64. SDKs select the webhook parser from the configured callback route, never as fallback after request-profile parsing fails.
If you're using the `@adcp/sdk` library, this entire flow is handled automatically. As a **buyer**, configure `webhookUrlTemplate` and your agent URL on the client; `push_notification_config` is injected into every outgoing task call, and incoming webhooks are verified against the seller's JWKS automatically. As a **seller emitting webhooks**, publish a signing JWK at your brand.json `agents[]` entry. New signers use `adcp_use: "request-signing"`; if you want webhook-only key material, publish a second `request-signing` JWK with a distinct `kid`.
:::warning Legacy HMAC fallback (deprecated)
Buyers integrating with receivers that have not yet adopted the RFC 9421 webhook profile MAY opt into the legacy HMAC-SHA256 scheme by populating `push_notification_config.authentication.credentials`. That path is deprecated and removed in AdCP 4.0 — see [Legacy HMAC-SHA256 fallback](#legacy-hmac-sha256-fallback-deprecated) below. Because the inbound request that registers the webhook is typically not 9421-signed in 3.0, the `authentication` block is susceptible to on-path strip/inject — see [Downgrade and injection resistance](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-callbacks) for the operational mitigations.
:::
## Naming: snake_case vs camelCase
This trips people up. There are two naming conventions in play:
| Context | Field name | Example |
| - | - | - |
| **MCP task arguments** (AdCP JSON) | `push_notification_config` | `{ push_notification_config: { url: ..., operation_id: ... } }` |
| **A2A transport configuration** | `taskPushNotificationConfig` | `configuration: { taskPushNotificationConfig: { id: ..., url: ... } }` |
The AdCP field name is always **`push_notification_config`** (snake_case). It goes in the task request body alongside your other task parameters.
The two objects are not aliases. `push_notification_config` registers an AdCP
application webhook and includes `operation_id`. A2A
`taskPushNotificationConfig` registers delivery for the A2A transport Task and
does not define `operation_id`.
## Adding push_notification_config to a request
### MCP
Include `push_notification_config` as a task argument, merged with the rest of your task parameters:
```json theme={null}
{
"brand": { "brand_id": "acme" },
"start_time": { "type": "date", "date": "2025-03-01" },
"end_time": "2025-06-30T23:59:59Z",
"packages": [...],
"push_notification_config": {
"url": "https://you.com/webhooks/adcp/create_media_buy/route_abc123",
"operation_id": "op_abc123"
}
}
```
`authentication` is omitted in the default case — the seller signs with its own `adcp_use: "request-signing"` key. Deprecated `webhook-signing` keys remain accepted during the compatibility window. Include `authentication.credentials` only if you need the legacy HMAC-SHA256 fallback.
### A2A
For a durable AdCP operation invoked through the v3 A2A profile, keep the AdCP
webhook registration inside the typed task input:
```json theme={null}
{
"message": {
"messageId": "msg-create-001",
"role": "ROLE_USER",
"parts": [{
"data": {
"skill": "create_media_buy",
"input": {
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"account": { "account_id": "acc_demo_001" },
"brand": { "domain": "brand.example" },
"proposal_id": "proposal_001",
"total_budget": { "amount": 100000, "currency": "USD" },
"start_time": "asap",
"end_time": "2027-06-30T23:59:59Z",
"push_notification_config": {
"url": "https://you.example/webhooks/adcp/create-media-buy",
"operation_id": "op_abc123"
}
}
}
}]
}
}
```
If the buyer also wants updates while the A2A handler itself is running, it
may separately set `configuration.taskPushNotificationConfig` with the A2A
fields `id`, `url`, optional `token`, and optional `authentication`. On an
initial `SendMessage`, omit `taskId`; the server has not assigned it yet. That
transport registration ends with the A2A Task and does not replace AdCP
polling or the application webhook above.
## Operation IDs and URL templates
Operation IDs let you correlate incoming webhooks to the right task invocation. The pattern:
1. Buyer generates a unique operation ID per task call
2. Buyer threads it through to the seller as `push_notification_config.operation_id`. The webhook URL structure is the buyer's choice and is **opaque to the seller**
3. Seller echoes `operation_id` verbatim in every webhook payload — no URL parsing needed
**Normative wire contract:**
* **Buyers SHOULD** supply `operation_id` to the seller for every webhook registration and generate a unique value per task invocation (UUID recommended). Sellers MAY reject a webhook registration that omits `operation_id` with `INVALID_REQUEST`.
* **Sellers MUST** echo the buyer-supplied `operation_id` value in every webhook payload exactly as received. The payload field is the **only** source of truth for correlation.
* **Sellers MUST NOT** derive `operation_id` by parsing `push_notification_config.url` — the URL structure (path template, query parameters, opaque token, etc.) is implementation-defined from the seller's point of view and cannot be reliably reversed across implementations. A buyer's URL convention is not part of the protocol.
* **Receivers MAY** dispatch HTTP endpoints by URL path or query string, but **MUST NOT** use URL-derived values as the operation correlation key. The wire-level correlation identifier is the payload field.
This matches the precedent set by every comparable async-notification protocol in ad tech (OpenRTB `nurl`/`burl`, VAST tracking pixels, A2A `PushNotificationConfig`): the entity firing the HTTP call never parses the receiver's URL for correlation data.
**URL template pattern (buyer-side convention only):**
```
https://you.com/webhooks/{task_type}/{agent_id}/{route_token}
```
The template above is a useful **server-side routing aid for the buyer** — it lets a buyer's HTTP server dispatch on path segments without first parsing the body — but it is not normative and sellers cannot rely on it. A buyer who prefers `?route=…`, a flat path, or an entirely opaque token is fully conformant as long as the seller-side `operation_id` is supplied through the SDK's send-side API.
**Example (client library handles this automatically):**
```typescript theme={null}
import { randomUUID } from 'crypto';
const operationId = randomUUID(); // e.g. "cd51e063-2b79-4a6d-afac-ed7789c3a443"
const routeId = randomUUID(); // receiver-local routing token; opaque to the seller
const webhookUrl = `https://you.com/adcp/webhook/create_media_buy/${agentId}/${routeId}`;
// pass both webhookUrl and operationId in push_notification_config
```
The seller's webhook payload will include `"operation_id": "cd51e063-2b79-4a6d-afac-ed7789c3a443"`, so your handler can correlate to the right pending operation by reading the payload field directly. URL paths can select an HTTP handler, but not the protocol operation ID.
**Seller-SDK implementations** surface `operation_id` as an explicit parameter on the send-side webhook API (e.g., Python `WebhookSender.send_mcp(url=…, operation_id=…)`). The seller's application code threads the value through from the original task request to the webhook fire; the SDK never attempts to recover it from the URL.
### Echoing the caller's `context` object
When the originating request carried a top-level `context` object, the seller MUST echo the same JSON value in every webhook payload for the same operation, alongside `operation_id`. This is the same contract that applies to synchronous and async-status responses — see [Context and sessions — Normative echo contract](/dist/docs/3.2.8/building/by-layer/L2/context-sessions#normative-echo-contract). The echo MUST carry through `working`, `input-required`, `completed`, `failed`, and `canceled` deliveries; dropping `context` between the initial response and a later webhook breaks buyer-side correlation exactly where it's needed most. Buyers routing by `context.trace_id` or `context.internal_campaign_id` rely on the same-value echo on every delivery.
## When webhooks fire
Webhooks are sent for each status change after the initial response, as long as `push_notification_config` is in the request.
If the task completes synchronously (initial response is already terminal, such as `completed`, `failed`, or `rejected`), no webhook is sent — you already have the result.
Only operations whose initial response is non-terminal (`working` or `submitted`) may later emit AdCP task webhooks. For an inline terminal response, sellers MUST NOT synthesize a task webhook by inventing a `task_id` or replaying the inline result to `push_notification_config.url`; sync-only operations, and sync-only operation modes where `push_notification_config` is not meaningful, MAY reject that field as a well-formed runtime error instead. This is a seller-to-buyer wire rule: buyer SDKs MAY normalize synchronous responses into local callbacks, promises, or handler invocations, but those local SDK conveniences are not AdCP webhooks. If a future AdCP version adds a buyer-signaled sync-completion notification mode, it will be explicit and capability-advertised; the 3.x task webhook contract does not define one.
**Status changes that trigger webhooks:**
| Status | Meaning |
| - | - |
| `working` | Task is processing — may include progress info |
| `input-required` | Waiting for human approval or clarification |
| `completed` | Final result available |
| `failed` | Task failed with error details |
| `canceled` | Task was canceled |
## Webhook payload formats
### MCP
```json theme={null}
{
"idempotency_key": "whk_01HW9D3H8FZP2N6R8T0V4X6Z9B",
"task_id": "task_456",
"operation_id": "cd51e063-2b79-4a6d-afac-ed7789c3a443",
"task_type": "create_media_buy",
"domain": "media-buy",
"status": "completed",
"timestamp": "2025-01-22T10:30:00Z",
"message": "Media buy created successfully",
"result": {
"media_buy_id": "mb_12345",
"packages": [
{ "package_id": "pkg_001", "context": { "line_item": "li_ctv_sports" } }
]
}
}
```
Every webhook payload carries a required `idempotency_key` — a sender-generated key that is stable across retries of the same event. This is the canonical dedup field; see [Reliability](#reliability) below.
### Payload anatomy: envelope vs. result
Webhook receivers must distinguish the **wire envelope** from the task-specific **result**. The full MCP webhook envelope is the JSON object sent as the HTTP POST body. Delivery-report content lives under `result`; it is not valid as the top-level POST body by itself.
For a delivery reporting fire, the full wire payload looks like:
```json theme={null}
{
"idempotency_key": "whk_20260526_example_000031",
"operation_id": "delivery_report_67_2026_04",
"task_id": "delivery_report_67_2026_04_000031",
"task_type": "media_buy_delivery",
"status": "completed",
"timestamp": "2026-05-26T09:00:44.582Z",
"message": "Scheduled media buy delivery report available",
"result": {
"notification_type": "scheduled",
"sequence_number": 31,
"reporting_period": {
"start": "2026-05-25T00:00:00Z",
"end": "2026-05-25T23:59:00Z"
},
"currency": "USD",
"media_buy_deliveries": [
{
"media_buy_id": "mb_001",
"status": "active",
"totals": {
"impressions": 125000,
"spend": 5625.0,
"clicks": 250
},
"by_package": []
}
]
}
}
```
This inner result object is valid delivery-report content, but it is **not valid as the top-level webhook POST body**:
```json theme={null}
{
"notification_type": "scheduled",
"sequence_number": 31,
"reporting_period": {
"start": "2026-05-25T00:00:00Z",
"end": "2026-05-25T23:59:00Z"
},
"currency": "USD",
"media_buy_deliveries": []
}
```
The top-level `status` is the async webhook status (`completed`, `failed`, `working`, and so on). The nested `media_buy_deliveries[].status` is the media buy lifecycle or reporting state (`active`, `paused`, `reporting_delayed`, and so on). Do not collapse the two fields.
For delivery-report data events such as `scheduled`, `final`, `delayed`, `adjusted`, and `window_update`, `notification_id` is absent by design; dedupe the transport event with `idempotency_key`. The `aggregated_totals` field is API-only for `get_media_buy_delivery` responses and must not be emitted in reporting webhook result payloads.
Signatures and content digests are computed over the exact raw JSON bytes sent as this full envelope. Re-serializing just the `result` object, adding whitespace, or changing field order before verification changes the bytes and breaks signature validation.
### A2A
A2A sends a `Task` object (for final states) or `TaskStatusUpdateEvent` (for progress). For final states (`completed`, `failed`), AdCP result data is in `.artifacts[0].parts[]`. For interim states (`working`, `input-required`), data is in `status.message.parts[]`.
```json theme={null}
{
"task": {
"id": "task_456",
"contextId": "ctx_123",
"status": {
"state": "TASK_STATE_COMPLETED",
"timestamp": "2025-01-22T10:30:00.000Z"
},
"artifacts": [{
"artifactId": "result",
"parts": [
{ "text": "Media buy created successfully" },
{
"data": {
"media_buy_id": "mb_12345",
"packages": [
{ "package_id": "pkg_001", "context": { "line_item": "li_ctv_sports" } }
]
}
}
]
}]
}
}
```
### Protocol comparison
| | MCP | A2A |
| - | - | - |
| **Config field** | `push_notification_config` (in task args) | `configuration.taskPushNotificationConfig` (separate from skill params) |
| **Envelope** | `mcp-webhook-payload.json` | Native `Task` / `TaskStatusUpdateEvent` |
| **Result location** | `result` field | `.artifacts[0].parts[].data` (final) / `status.message.parts[].data` (interim) |
| **Data schemas** | Identical AdCP schemas | Identical AdCP schemas |
### Registration channel determines envelope shape
Webhook envelope shape is determined by **which registration mechanism the buyer used**, not by which transport the sync request was sent over:
| Registered via | Delivered envelope |
| - | - |
| AdCP `push_notification_config` (task argument, MCP/A2A/REST) | [`mcp-webhook-payload.json`](#mcp) |
| A2A `TaskPushNotificationConfig` ([`CreateTaskPushNotificationConfig`](https://a2a-protocol.org/latest/specification/) RPC, or inline `configuration.taskPushNotificationConfig` on `SendMessage`) | A2A native `Task` / `TaskStatusUpdateEvent` per A2A 1.0 §4.3.3 |
| Account-level `sync_accounts.accounts[].notification_configs[]` | Event-specific payloads such as `creative-status-changed-webhook.json`, `creative-assignment-changed-webhook.json`, `indicators-changed-webhook.json`, `account-status-changed-webhook.json`, or `wholesale-feed-webhook.json` |
| Agent-level `sync_principal.configuration.notification_configs[]` or `sync_agent_notification_configs.notification_configs[]` | Event-specific AdCP payload schemas such as `capabilities-changed-webhook.json` |
The two channels are independent. A buyer MAY register both for the same task and receive both webhooks per status change.
**Why this is the model, not "match inbound transport".** Each channel is purpose-built for its envelope: AdCP `push_notification_config` is the AdCP-layer registration for the AdCP `mcp-webhook-payload` shape; A2A `TaskPushNotificationConfig` is the A2A-layer registration for A2A's own `StreamResponse`-wrapped delivery. The buyer picks the channel that matches the receiver — there's no need for a discriminator field, and no ambiguity to override.
**Typical case: A2A sync, AdCP-shape webhooks.** A buyer orchestrating from an MCP-native runtime that uses A2A for one specific high-throughput sync operation puts `push_notification_config` in the AdCP task arguments inside its `SendMessage` body. The seller honors it as an AdCP-shape registration, regardless of A2A being the sync transport. The buyer's receiver gets the same `mcp-webhook-payload` shape it gets from every other AdCP webhook in its pipeline.
**A2A buyers wanting A2A-shape webhooks** register through A2A's native push notification mechanism; AdCP doesn't need to add anything for that case.
### Status-specific result data
| Status | `result` / `data` contains |
| - | - |
| `completed` / `failed` | Full task response |
| `working` | Progress: `percentage`, `current_step`, `total_steps` |
| `input-required` | Reason and any validation errors |
| `submitted` | Minimal acknowledgment |
## Signature verification
Every AdCP 3.0 webhook is signed under the [RFC 9421 webhook profile](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-callbacks). The seller signs with its `adcp_use: "request-signing"` key published in its own brand.json `agents[]` entry; deprecated `webhook-signing` keys remain accepted during the compatibility window. You verify against the seller's published JWKS. No shared secret crosses the wire.
**Publisher sends three headers** (plus `Content-Type`):
```
Signature-Input: sig1=("@method" "@target-uri" "@authority" "content-type" "content-digest");
created=;expires=;nonce=;
keyid=;alg="ed25519";tag="adcp/webhook-signing/v1"
Signature: sig1=::
Content-Digest: sha-256=::
```
These two binary headers use the webhook-v1 legacy encoding. The AdCP 3.2 request profile uses RFC 8941 padded Base64 instead; a receiver selects one parser from the trusted route/profile and never tries both.
Covered components are fixed: `@method`, `@target-uri`, `@authority`, `content-type`, `content-digest`. `content-digest` is REQUIRED — the body is the event; a signature that doesn't cover it isn't protecting the attack surface that matters.
Property-list change payloads retain a required body-level `signature: "rfc9421"` compatibility marker through 3.x because the previously published schema required a string at that location without defining interoperable signature semantics. Receivers MUST accept any string in that field from an older 3.x sender, ignore it for authentication, and verify only the HTTP signature headers above. Property-list registration exposes no legacy authentication selector, so this delivery surface is RFC 9421-only. The marker is removed in 4.0. Collection-list webhook schema and behavior remain unchanged; migrating that contract requires separately versioned work.
**Verification** follows the 14-step [request verifier checklist](/dist/docs/3.2.8/building/by-layer/L1/security#verifier-checklist-requests) with three webhook substitutions:
* Error codes use the `webhook_signature_*` prefix (see [Webhook error taxonomy](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-error-taxonomy)).
* `tag` MUST be `adcp/webhook-signing/v1`.
* Resolve `keyid` via the seller operator's `brand.json` `agents[].jwks_uri`, applying any publisher `adagents.json` `signing_keys[]` pin when present (you already have the seller's agent URL from your integration).
**Receiver implementation sketch:**
```typescript theme={null}
import { createRemoteJWKSet, jwtVerify } from 'jose';
// Use a validated RFC 9421 library (e.g., `http-message-signatures`) pinned to the AdCP profile.
app.post('/webhooks/adcp/*', async (req, res) => {
try {
// 1. Parse Signature-Input / Signature headers and reject on malformed.
// 2. Resolve keyid against the seller operator's brand.json JWKS.
// 3. Run the AdCP webhook verifier checklist (14 steps).
await verifyAdcpWebhookSignature(req, {
sellerAgentUrl: req.sellerContext.agentUrl, // known from your integration
requiredTag: 'adcp/webhook-signing/v1',
allowedAlgs: ['ed25519', 'ecdsa-p256-sha256'],
});
} catch (err) {
return res.status(401)
.setHeader('WWW-Authenticate', `Signature error="${err.code}"`)
.end();
}
// 4. Dedup by idempotency_key before applying side effects (see Reliability below).
processWebhook(req.body);
res.status(200).end();
});
```
:::caution Raw body and content-digest
Your `Content-Digest` verification (step 11 of the checklist) requires the raw HTTP body bytes. Capture them before JSON parsing — any re-serialization will break the digest match.
In Express:
```typescript theme={null}
app.use(express.json({
verify: (req, _res, buf) => { (req as any).rawBody = buf.toString('utf-8'); },
}));
```
:::
:::note Replay protection
The `created`/`expires`/`nonce` sig-params enforce a 5-minute max validity window and `(keyid, nonce)` replay dedup. See [Transport replay dedup](/dist/docs/3.2.8/building/by-layer/L1/security#transport-replay-dedup) for the per-keyid cap and memory-bounding rules.
:::
### Legacy HMAC-SHA256 fallback (deprecated)
:::warning Deprecated — removed in AdCP 4.0
The HMAC-SHA256 scheme below is a compatibility affordance for 3.x only. New integrations SHOULD omit `push_notification_config.authentication` and use the [9421 webhook profile](#signature-verification) above. Sellers MAY decline to support the legacy scheme.
:::
Buyers can opt into HMAC-SHA256 by populating `push_notification_config.authentication.credentials`. When present, the seller signs with HMAC-SHA256 using a shared secret and includes a timestamp for replay protection.
**Configuration (legacy):**
```json theme={null}
{
"authentication": {
"schemes": ["HMAC-SHA256"],
"credentials": "your_shared_secret_min_32_chars"
}
}
```
**Publisher sends two headers (legacy):**
```
X-ADCP-Signature: sha256=
X-ADCP-Timestamp:
```
**Signature algorithm (legacy):**
The signed message is `{unix_timestamp}.{raw_json_body}` — the Unix timestamp (in seconds), a dot, then the exact JSON bytes being sent in the HTTP body.
```
Signature = sha256= + hex( HMAC-SHA256( secret, "{timestamp}.{rawBody}" ) )
```
The `rawBody` **must** be the exact bytes sent on the wire. When serializing a JSON payload to produce the body, use **compact separators** (`","` and `":"`, no surrounding whitespace) — this matches JavaScript `JSON.stringify` and most HTTP-client defaults, and is what the receiver sees as `raw_body`. The common cross-SDK failure here is a signer that calls a language default which inserts spaces (e.g., Python `json.dumps(payload)`) while the HTTP client writes compact bytes on the wire — the signer then signs over bytes the receiver never sees. Use `json.dumps(payload, separators=(",", ":"))` (or equivalent) for byte-equality. See [Webhook Security — legacy normative rules](/dist/docs/3.2.8/building/by-layer/L1/security#legacy-hmac-sha256-fallback-deprecated-removed-in-40) for the full rules on canonical on-wire form and verifier input handling.
**Publisher implementation (legacy):**
```typescript theme={null}
import { createHmac } from 'crypto';
function signWebhook(rawBody: string, secret: string): { signature: string; timestamp: string } {
const timestamp = Math.floor(Date.now() / 1000).toString();
const message = `${timestamp}.${rawBody}`;
const hex = createHmac('sha256', secret).update(message).digest('hex');
return { signature: `sha256=${hex}`, timestamp };
}
```
**Receiver implementation (legacy):**
```typescript theme={null}
import { createHmac, timingSafeEqual } from 'crypto';
function verifyWebhook(
rawBody: string, signature: string, timestamp: string, secret: string,
): boolean {
const ts = parseInt(timestamp, 10);
if (isNaN(ts)) return false;
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - ts) > 300) return false;
const message = `${ts}.${rawBody}`;
const expected = `sha256=${createHmac('sha256', secret).update(message).digest('hex')}`;
if (signature.length !== expected.length) return false;
return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
```
Normative rules for the legacy scheme are in [Webhook Security](/dist/docs/3.2.8/building/by-layer/L1/security#legacy-hmac-sha256-fallback-deprecated-removed-in-40).
### Legacy Bearer token (deprecated)
The A2A `authentication.schemes: ["Bearer"]` scheme is also supported for compatibility and removed in AdCP 4.0. Bearer provides no tamper protection on the body. The 9421 profile is stronger on signer identity (JWKS-anchored, rotatable, revocable) and key management (no shared secret on the wire); body-integrity protection is comparable to the legacy HMAC scheme since both cover the body bytes. Sellers SHOULD refuse Bearer for any mutating callback.
```json theme={null}
{
"authentication": {
"schemes": ["Bearer"],
"credentials": "your_bearer_token_min_32_chars"
}
}
```
```javascript theme={null}
app.post('/webhooks/adcp', (req, res) => {
const token = req.headers.authorization?.replace('Bearer ', '');
if (token !== process.env.ADCP_WEBHOOK_TOKEN) return res.status(401).end();
processWebhook(req.body);
res.status(200).end();
});
```
## Reliability
Webhooks use **at-least-once delivery** — you may receive the same event more than once, and events may arrive out of order.
Webhook deliveries that report task progress or settlement also follow the
[async identity and convergence
contract](/dist/docs/3.2.8/building/by-layer/L3/async-identity-and-convergence). Delivery
deduplication and terminal publication are separate protections: a receiver
must prevent duplicate side effects both for retries under one delivery key and
for re-emissions of one logical terminal observation under different keys.
### Dedup by `idempotency_key`
Every webhook payload — MCP task envelope, governance list-change webhooks (`collection_list_changed`, `property_list_changed`), artifact push webhooks, and rights `revocation-notification` — carries a required `idempotency_key`. Publishers generate this key once per distinct event and reuse it on every retry. Receivers MUST dedupe by it.
**Sender requirements:**
* The key MUST be cryptographically random (UUID v4 recommended). Sequential, timestamp-only, or otherwise predictable values are non-conformant: receivers dedupe on the raw value, so a predictable key lets an attacker pre-seed a receiver's cache to suppress a later legitimate event.
* The key MUST be stable across RFC 8785 JCS-equivalent retries of the complete authenticated payload and MUST NOT be reused for a changed payload or distinct event. Receivers reject duplicate object keys before canonicalization.
* Retry attempts keep every payload member, including `timestamp`, unchanged so that the complete body remains JCS-equivalent. JSON member ordering, whitespace, wire bytes, and fresh signature headers, nonce values, connection metadata, and RFC 9421 `created` parameters may differ; each raw body is signed independently.
* The binding between key and canonical payload lasts for the seller's advertised retry window. A logical notification re-emitted with a changed envelope uses a fresh delivery key and retains its `notification_id` when that event type defines one.
**Receiver requirements:**
* Dedup scope is `(authenticated sender identity, idempotency_key)`. "Authenticated sender identity" means the sender's cryptographic identity as established by signature verification — under the 9421 default, the resolved `keyid` → signer `agents[]` entry URL; under the legacy fallback, the credential binding from the verified HMAC secret or Bearer token. Never derive identity from a payload field. Keys from different senders MUST be kept in independent keyspaces; a receiver integrated with multiple sellers MUST NOT collapse them. During an HMAC→9421 migration, a receiver SHOULD map both sender-identity forms for the same logical seller to one keyspace so that a duplicate across schemes still dedupes.
* **Cross-endpoint dedup (MUST).** A receiver that exposes more than one webhook endpoint (per-integration, per-environment, per-tenant, or per-pod in a horizontally-scaled fleet) MUST share the `(sender identity, idempotency_key)` keyspace across every endpoint a given sender can reach — per-pod in-memory caches are non-conformant. Without a shared tier, the same signed event replayed to a sibling endpoint executes twice. See [Webhook replay dedup sizing](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-replay-dedup-sizing) for the transport-layer companion rule on `(keyid, nonce)` scoping.
* Dedup state, its canonical payload fingerprint, and terminal publication proof MUST persist for at least the greater of 24h and `webhook_signing.delivery_retry_horizon_seconds` in durable storage that survives process restarts, pod replacements, and region failovers. For a 3.x sender that does not advertise a window, the compatibility floor is 24h. An in-memory-only cache (per-pod `Map` or LRU without a backing tier) is non-conformant — the asymmetry between the \~360 s signature-nonce window and the longer delivery window creates a **displaced-replay window** in which a legitimate signed retry (fresh nonce, same `idempotency_key`) passes signature verification after the receiver forgot its first payload. Side effects can run twice.
* Receivers SHOULD bound dedup cache size per sender and return `429 Too Many Requests` (or drop the connection) rather than grow unbounded — a misbehaving or hostile seller emitting high-volume fresh keys is otherwise a storage-amplification vector.
* **Durably completed duplicates MUST be answered with `2xx`** (typically `200 OK`), not `409 Conflict`. At-least-once senders interpret any non-2xx response as "delivery failed" and retry with exponential back-off; returning `4xx` on a successfully completed duplicate turns correct receiver behavior into a retry storm. A still-active identical delivery is handled separately below.
* **An identical delivery already being processed MUST NOT start a second publisher.** Return a retryable response, normally `503 Service Unavailable`, until the current owner durably acknowledges the delivery. After acknowledgement, return `2xx` without republishing.
* **Same key plus a changed canonical payload is not a duplicate.** The receiver returns non-retryable `409 Conflict`, preserves the first binding, and does not dispatch the changed payload. A sender MUST stop retrying that key after `409`.
* The receiver establishes one durable publication owner before invoking application callbacks or externally visible side effects, then records acknowledgement after successful publication. A check followed by a post-handler acknowledgement is not sufficient because two receivers can both pass the check.
```javascript theme={null}
app.post('/webhooks/adcp', async (req, res) => {
const payload = req.body;
const { idempotency_key, task_id, status, timestamp, result } = payload;
// Scope dedup to the authenticated sender — never trust a payload field for identity.
const sender = req.verifiedSenderId; // set by 9421 verifier (keyid → agent URL) or legacy HMAC/Bearer middleware
// Atomically bind this key to the authenticated canonical payload and claim
// publication. The claim state is one of: claimed, processing, completed,
// or conflict, and a successful claim includes its owner fence. This helper
// is durable across every receiver instance.
const { state: claimState, owner: claimOwner } = await db.claimWebhook({
sender,
idempotencyKey: idempotency_key,
payloadFingerprint: canonicalFingerprint(payload)
});
if (claimState === 'conflict') return res.status(409).end();
if (claimState === 'processing') return res.status(503).end();
if (claimState === 'completed') return res.status(200).end();
// Converge all channels on one seller task. This operation validates the
// task/operation/account binding, normalizes a terminal result, preserves the
// first authoritative terminal winner, and claims publication across
// different webhook delivery keys.
const convergence = await db.convergeTaskObservation({
seller: sender,
taskId: task_id,
taskType: payload.task_type,
status,
timestamp,
terminalRecord: normalizeTerminalObservation(payload)
});
if (convergence === 'terminal_conflict') {
await db.rejectWebhookClaim(sender, idempotency_key, claimOwner);
return res.status(409).end();
}
if (convergence === 'publication_in_progress') {
await db.releaseWebhookClaim(sender, idempotency_key, claimOwner);
return res.status(503).end();
}
if (convergence === 'exact_duplicate_or_stale') {
await db.acknowledgeWebhook(sender, idempotency_key, claimOwner);
return res.status(200).end();
}
await triggerBusinessLogic(task_id, convergence.authoritativeResult);
await db.acknowledgeWebhook(sender, idempotency_key, claimOwner);
res.status(200).end();
});
```
**Always implement polling as backup.** Webhooks can fail due to network issues or server downtime. Use a slower poll interval when webhooks are configured (e.g., every 2 minutes instead of 30 seconds), and stop polling once you receive a terminal status via webhook.
### Diagnosing missing fires
When a buyer suspects a webhook isn't reaching its endpoint — gateway 5xx, stale-sequence dedup, drifted webhook URL, suppressed fires under a tripped circuit breaker — call [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys#webhook-activity) with `include_webhook_activity: true`. Each returned media buy will carry a `webhook_activity` array of recent fires for the calling principal, including `idempotency_key` (matches the payload's dedup key — correlate against your own endpoint log), `status` (`success` / `failed` / `timeout` / `connection_error` / `pending`), `http_status_code`, `attempt`, and `error_message`. The scope is the calling principal's own fires; no operator ticket required.
## Best practices
1. **Always implement polling as backup** — webhooks can fail; poll at a reduced interval (e.g. every 2 minutes) when webhooks are configured, and stop once you receive a terminal status
2. **Bind `idempotency_key` to its payload** — every payload carries a required key stable across exact retries; retain the binding for the advertised retry window, or at least 24h for an undeclared 3.x peer
3. **Return 2xx on completed duplicates** — return `503` while an identical delivery is still active and `409` for the same key with a different payload
4. **Verify signatures before processing** — run the 9421 webhook verifier checklist (or the legacy HMAC check if you opted in) before any side effects
5. **Acknowledge durably** — before `2xx`, either complete publication or durably enqueue one owned publication; if neither is complete, return `503` so the sender retries
6. **Don't rely on URL structure** — use `operation_id` from the payload for business correlation; URL paths may only demux endpoints
7. **Plan for HMAC removal in 4.0** — if you're currently on the legacy HMAC fallback, migrate to the 9421 webhook profile during 3.x
## Payload extraction
Webhook receivers need to detect the format and extract AdCP data. The buyer typically knows the format because it configured the transport, but defensive detection is useful for multi-format receivers.
### Format detection
| Signal | Format |
| - | - |
| `status` is a string, `task_id` present | MCP |
| `status` is an object with `.state` | A2A |
### Extraction
**MCP webhooks:** Extract data from the `result` field directly.
**A2A webhooks:** Use the [A2A response extraction](/dist/docs/3.2.8/building/by-layer/L0/a2a-response-extraction) algorithm — final states extract from `.artifacts[0].parts[]` (last DataPart), interim states from `status.message.parts[]` (first DataPart).
```javascript theme={null}
function extractAdcpResponseFromWebhook(payload, knownFormat) {
const format = knownFormat || detectFormat(payload);
if (format === 'mcp') return payload.result ?? null;
if (format === 'a2a') return extractAdcpResponseFromA2A(payload);
return null;
}
function detectFormat(payload) {
if (payload.status && typeof payload.status === 'object'
&& !Array.isArray(payload.status) && payload.status.state) return 'a2a';
if (typeof payload.status === 'string' && payload.task_id) return 'mcp';
return null;
}
```
### Security requirements
* **Content-Type validation**: Senders MUST send `application/json`. Receivers MUST reject other types before signature verification.
* **Payload size limit**: Receivers SHOULD enforce a 1MB limit. Reject before signature verification — computing a digest or HMAC over large payloads is a DoS vector. Return `413 Payload Too Large`.
* **Deduplication**: `idempotency_key` is the canonical dedup field. Signature verification (9421 or legacy HMAC) plus replay dedup protect the transport; `idempotency_key` protects against duplicate side effects at the application layer.
* **Format detection**: Auto-detection is a defensive fallback. Receivers SHOULD use the known format from their transport configuration (`knownFormat` parameter) rather than relying solely on payload inspection. A compromised intermediary could craft an ambiguous payload that routes extraction to the wrong path.
### Test vectors
Machine-readable test vectors are available at [`/static/test-vectors/webhook-payload-extraction.json`](https://adcontextprotocol.org/test-vectors/webhook-payload-extraction.json). Client libraries SHOULD validate their format detection and extraction logic against these vectors.
## Reporting webhooks
Reporting webhooks are separate from task status webhooks. They deliver periodic performance data for active media buys and are configured via `reporting_webhook` in `create_media_buy`, not via `push_notification_config`.
### AdCP 3.2 interim reporting correlation
AdCP 3.2.1 requires `operation_id` in the `media_buy_delivery` webhook envelope, but its `reporting_webhook` registration schema does not define that field. This gap is tracked in [#7885](https://github.com/adcontextprotocol/adcp/issues/7885); [#7895](https://github.com/adcontextprotocol/adcp/pull/7895) proposes a core field for AdCP 3.3.
Until that field is standardized, cooperating buyers and sellers can agree to carry `reporting_webhook.operation_id` as an additive field. The published 3.2.1 registration schema has `additionalProperties: true`, so this uses the existing [extensibility allowance](/dist/docs/3.2.8/reference/versioning#extensibility). No `ext.{namespace}` wrapper is needed inside this container. This is opt-in implementation guidance, not a new requirement for all 3.2 implementations; accepting the field does not establish that a seller supports it. Confirm support during integration onboarding before depending on scheduled delivery.
For integrations adopting this interim agreement:
* The buyer supplies a unique reporting-stream ID of 1–255 characters from `A–Z`, `a–z`, `0–9`, `_`, `.`, `:`, and `-`, matching `push_notification_config.operation_id` constraints. Its SDK preserves the field when validating and serializing every registration or update.
* The seller stores that value with the reporting registration and copies it verbatim to `mcp-webhook-payload.operation_id` on each `media_buy_delivery` notification, including retries. The registration's value is independent of any task-status `push_notification_config.operation_id`.
* A registration without a buyer-supplied ID cannot enable this interim delivery path. Flag the missing value for the buyer and suppress scheduled sends; do not fabricate an ID or extract one from the URL. Existing buyers need to update their registration with an ID before reports resume. They can use `get_media_buy_delivery` while arranging support.
* Keep existing webhook authentication, required envelope fields, and delivery deduplication unchanged. The stream ID is a correlation value, not a delivery-specific `idempotency_key`.
For example, the reporting registration below validates against the published 3.2.1 schema; `operation_id` is an agreed additional field:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.1/core/reporting-webhook.json",
"url": "https://buyer.example.com/webhooks/reporting",
"operation_id": "op_reporting_001",
"authentication": {
"schemes": ["Bearer"],
"credentials": "example_reporting_credential_32_chars"
},
"reporting_frequency": "daily"
}
```
The Python SDK restoration is tracked in [adcp-client-python#1092](https://github.com/adcontextprotocol/adcp-client-python/issues/1092). Adding model support alone does not persist the seller's registration or resume existing subscriptions. Verify registration → storage → scheduled send → authenticated receipt together. When a later release defines this field in core, its definition takes precedence over the interim agreement.
See [Task Reference](/dist/docs/3.2.8/media-buy/task-reference) for details on `reporting_webhook`.
## Agent-level webhooks
Agent-level webhooks outlive any account or media buy. They are registered with [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal), or with the specialized [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) compatibility task, not with account-level `notification_configs[]` or per-task `push_notification_config`.
The initial agent-level event type is `capabilities.changed`. It invalidates cached [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) responses. The webhook payload is deliberately small and does not contain the full capability document; receivers re-read `get_adcp_capabilities` and replace their cached snapshot from the fresh response. Sellers MUST publish the new capability snapshot before firing so the webhook's `capabilities_version` is observable on read. Receivers SHOULD retry the read with normal transient-error backoff if the webhook revision is not yet observable.
## Persistent channel contract
Task webhooks fire once per logical task and stop when the task settles. **Persistent webhooks** — `reporting_webhook`, `push_notification_config` on a media buy, account-level `notification_configs[]`, and agent-level subscribers managed by `sync_principal` or `sync_agent_notification_configs` — outlive any single operation and fire repeatedly for the life of the resource or agent. The contract below applies to persistent channels.
This section is the transport half of the [Snapshot and log contract](/dist/docs/3.2.8/protocol/snapshot-and-log). For the read-side rules (snapshot is authoritative, replay = re-read), see that page.
### Delivery semantics
* **At-least-once delivery.** Sellers MAY re-fire the same logical event under retry. Receivers MUST dedupe transport retries by `idempotency_key`. For state-shaped events that also carry a typed `notification_id` (see [`mcp-webhook-payload.json`](https://adcontextprotocol.org/schemas/3.2.8/core/mcp-webhook-payload.json) and [snapshot-and-log Rule 1](/dist/docs/3.2.8/protocol/snapshot-and-log#1-separate-transport-event-and-resource-identity)), receivers MUST also track `notification_id` to correlate fires to current snapshot state — seeing the same `notification_id` under two different `idempotency_key` values is a re-emission signal, not a transport retry.
* **No ordering guarantee.** Two events on the same resource within seconds MAY arrive out of order. Receivers MUST reconcile via the resource snapshot rather than treating webhook ordering as canonical.
* **Idempotent application.** Apply the same payload twice and the resulting receiver state MUST be identical.
### Coalescence
For state-shaped event types, sellers SHOULD coalesce multiple near-simultaneous changes on the same resource into a single push. **Coalescence windows are per event type and not a flat ceiling** — a latency-sensitive event (fraud, brand safety) cannot wait the same window an indicator can.
| Event type | Default coalescence window | Notes |
| - | - | - |
| `impairment` (general) | 5 minutes (SHOULD NOT exceed) | Default for resource-state impairments — audience suspended, creative revoked, etc. |
| `impairment` (latency-sensitive) | Sub-minute / no coalescence | Fraud-driven, brand-safety-driven, or other classes where the buyer's response window is short. Sellers MUST NOT apply the general default to these. |
| Future indicator events | Hours to daily | Higher noise tolerance; bigger window appropriate. |
| Future defect events | Minutes to hours | Between impairment and indicator in urgency. |
Sellers MAY declare a shorter coalescence window via `get_agent_capabilities` for receivers that need sub-default latency. Sellers MUST NOT exceed the per-type default without explicit buyer opt-in declared on the receiver side. Delivery report fires (`scheduled`, `final`) follow their own cadence and are not subject to this coalescence rule.
### Replay and recovery
If a buyer's receiver was offline and missed a fire, recovery is **read the snapshot**. Two paths exist for every persistent channel and they're at parity in content:
* Missed `impairment` event → call `get_media_buys` and read `impairments[]` (full state recovery).
* Missed delivery report fire → call `get_media_buy_delivery` for the window in question with `time_granularity` set to the granularity the seller declared in `reporting_capabilities.windowed_pull_granularities` (#4590). The pull returns the same per-window slices the webhook delivered. Sellers that have not yet declared a windowed granularity return date-range aggregates and daily breakdowns only and cannot reconstruct sub-daily fires.
* Missed any other state-shaped event → call the corresponding `get_*` task.
AdCP does not commit to an event-replay primitive at the transport layer. The webhook delivery visibility surface (`webhook_activity[]` on `get_media_buys`, proposed in [#4278](https://github.com/adcontextprotocol/adcp/issues/4278)) exposes recent fires within a retention window for **debugging** — buyers use it to verify that the seller fired and what HTTP status the receiver returned. It is not a data recovery channel; that's what the snapshot's per-window pull (#4590) is for.
### Mutability and rotation
`push_notification_config` and `reporting_webhook` on a media buy MAY be updated via `update_media_buy` without re-creating the buy. Common reasons: rotating the receiver URL, replacing an expired bearer token, swapping signing keys.
Sellers MUST honor the updated config on the next fire after the update is acknowledged. There is no formal handoff window — buyers MAY receive a small number of fires against the prior URL during the propagation window and SHOULD treat both URLs as live until the prior URL has been quiet for a coalescence window.
### Auth renewal
Persistent webhooks outlive bearer tokens. Receivers using bearer auth (legacy HMAC profile or token-based mTLS) SHOULD rotate tokens via `update_media_buy` before expiry. Receivers using the 9421 signing profile do not need token rotation — verification is against the seller's published JWKS, which the seller rotates independently.
If a seller's fire receives a 401 from the receiver, the seller SHOULD treat this as a transient receiver-side configuration error: retry per the standard schedule, surface the failure in `webhook_activity[]` for debugging, and do not auto-disable the webhook.
### Termination
Persistent webhooks fire through the buy's terminal lifecycle moves:
* `final` delivery report fires after the buy reaches `completed`, `canceled`, or `rejected`.
* Any pending `impairment` events fire (or are coalesced and fired) before termination if the seller has them queued.
* After the final fire, no further events fire against the configured URLs. Sellers MAY retain `webhook_activity[]` for the retention window after termination so buyers can audit the closing sequence.
## Next steps
* [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle) — status values and transitions
* [Async Operations](/dist/docs/3.2.8/building/by-layer/L3/async-operations) — handling long-running tasks
* [Error Handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling) — webhook error patterns
# Build a caller
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L4/build-a-caller
Client-side guide for AdCP buyers and demand-side applications. Install the SDK, discover an agent's capabilities, make calls, handle async responses and errors, and ingest reporting. Weeks of handler glue, not months.
If you're building the **buy side** — a DSP, planning tool, agentic client, or any application that calls AdCP agents to plan, buy, and report — start here. Caller-side L0–L3 is weeks of handler glue, not the [3–4 person-month build](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#why-sdks-matter-more-in-adcp-than-in-eg-http) the agent side requires. The full-stack SDK in your language carries L0–L3; you write the calling logic, response handling, and whatever your application does with the data.
> [!NOTE]
>
> **Spec-level reference vs build-shaped guide.** This page walks you through the build. The wire-level invariants — every rule that applies to every mutating call — live at [Calling an AdCP agent](/dist/docs/3.2.8/protocol/calling-an-agent). Read it once before going to production; refer back whenever you're debugging a wire-shape error.
> [!TIP]
>
> **Try it against a live agent.** AAO runs a public test agent at `https://test-agent.adcontextprotocol.org` with per-domain endpoints — `/sales/mcp`, `/creative/mcp`, `/signals/mcp`, `/governance/mcp`. Point your client at the matching endpoint and `getAdcpCapabilities()` works without auth. Use it to verify your install before pointing at a real seller.
## Install the SDK
The same SDKs that ship server primitives also ship the calling client. Install one and you have both.
> [tab] JavaScript/TypeScript
>
> ```bash theme={null}
> npm install @adcp/sdk
> ```
>
> ```typescript theme={null}
> import { createSingleAgentClient } from '@adcp/sdk';
>
> const client = createSingleAgentClient({
> id: 'sales',
> name: 'Sales agent',
> agent_uri: 'https://sales.example.com/mcp',
> protocol: 'mcp',
> });
> ```
>
> For multi-agent fan-out (one client driving many sellers in parallel) use `ADCPMultiAgentClient` instead — same call surface, indexed by agent id.
>
> * [NPM Package](https://www.npmjs.com/package/@adcp/sdk)
> * [GitHub Repository](https://github.com/adcontextprotocol/adcp-client)
> [tab] Python
>
> ```bash theme={null}
> pip install adcp
> ```
>
> ```python theme={null}
> from adcp import ADCPClient, AgentConfig, Protocol
>
> client = ADCPClient(AgentConfig(
> id="sales",
> agent_uri="https://sales.example.com/mcp",
> protocol=Protocol.MCP,
> ))
> ```
>
> * [PyPI Package](https://pypi.org/project/adcp/)
> * [GitHub Repository](https://github.com/adcontextprotocol/adcp-client-python)
> [tab] Go
>
> ```bash theme={null}
> go get github.com/adcontextprotocol/adcp-go/adcp
> ```
>
> The Go caller surface is in active development. See the [adcp-go README](https://github.com/adcontextprotocol/adcp-go) for current coverage.
## Authenticate
Most agents require credentials before they'll respond to anything beyond `get_adcp_capabilities`. The SDK accepts auth at construction:
> [tab] Bearer / API key
>
> ```typescript theme={null}
> const client = createSingleAgentClient({
> id: 'sales',
> name: 'Sales agent',
> agent_uri: 'https://sales.example.com/mcp',
> protocol: 'mcp',
> auth_token: process.env.ADCP_API_KEY,
> });
> ```
> [tab] Signed requests (RFC 9421)
>
> ```typescript theme={null}
> const client = createSingleAgentClient({
> id: 'sales',
> name: 'Sales agent',
> agent_uri: 'https://sales.example.com/mcp',
> protocol: 'mcp',
> signing: { keyId: 'your-key-id', privateKey: /* PEM or KMS handle */ },
> });
> ```
If your first call returns a 401 / `AUTH_REQUIRED`, the credentials aren't reaching the agent — check the constructor option, not the request payload. See the [L1 security implementation profile](/dist/docs/3.2.8/building/by-layer/L1/security) for the full credential model.
## First call: discover the agent
Before calling tools by hand, ask the agent what it supports.
```typescript theme={null}
const capabilities = await client.getAdcpCapabilities();
// → { supported_protocols: [...], adcp_versions: [...], features: {...} }
```
`get_adcp_capabilities` returns the agent's protocol coverage, AdCP version range, and feature flags. Use it to gate calls — if `media_buy` isn't in `supported_protocols`, don't call `create_media_buy` against this agent. See the [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) reference for the full response shape.
For the rest of the discovery chain (agent card, `tools/list`, `get_schema`), see the [Discovery chain section of Calling an agent](/dist/docs/3.2.8/protocol/calling-an-agent#discovery-chain).
## Make a call
Typed methods on the client correspond to AdCP tools. The SDK validates your request against the bundled schemas before sending and parses the response into a typed value.
```typescript theme={null}
const products = await client.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655442046',
buying_mode: 'brief',
brief: 'Video campaign for pet owners, 18–34, US, $50K monthly',
});
const buy = await client.createMediaBuy({
idempotency_key: crypto.randomUUID(),
account: { brand: { domain: 'acme.com' }, operator: 'sales.example' },
packages: [/* … */],
});
```
Two things worth knowing on the first call:
* **Generate a fresh `idempotency_key` per logical operation.** Same key on retry → server replays the same response. Fresh key after a failure creates duplicate buys. See the [Idempotency rules](/dist/docs/3.2.8/protocol/calling-an-agent#idempotency-replay-vs-new-operation).
* **`account` is a discriminated `oneOf`.** Pick one variant (`{account_id}` from `sync_accounts` / `list_accounts`, or `{brand, operator}` as the natural key — `brand.domain` is the buyer's brand domain, `operator` is the seller agent's deployment hostname or brand.json identifier) and send only its required fields. Merging them fails both. See [`account` is `oneOf`](/dist/docs/3.2.8/protocol/calling-an-agent#account-is-oneof--pick-exactly-one-variant).
## Handle the three response shapes
Every mutating tool returns one of three shapes. Handle them explicitly.
```typescript theme={null}
const response = await client.createMediaBuy({/* … */});
if ('errors' in response) {
// Error: don't retry without fixing — read response.adcp_error.issues[]
// for correctable failures (validation, oneOf, etc.)
} else if (response.status === 'submitted') {
// Async: the work is queued, NOT done. The completion payload arrives
// later — either via webhook (preferred) or by polling the AdCP task.
} else {
// Sync success: response carries the completion payload directly.
// (e.g., response.media_buy_id, response.packages)
}
```
The SDK steers you to webhooks for async completion. Configure `webhookUrlTemplate` and a status-change handler at construction; the SDK verifies the inbound webhook against the seller's JWKS and fires your handler with the same `result` shape that synchronous responses carry — see [Receive webhooks](#receive-webhooks) below.
If you must poll instead of using webhooks (e.g. inside a one-shot script), call the AdCP polling surface: `get_task_status` when the seller advertises it, otherwise legacy AdCP `tasks/get` in 3.x. The [Async responses section of Calling an agent](/dist/docs/3.2.8/protocol/calling-an-agent#async-responses-status-submitted-means-queued) has the wire contract.
## Recover from errors
When you see `adcp_error` in a response, read `issues[]` and act based on `recovery`:
```typescript theme={null}
const { code, recovery, issues } = response.adcp_error;
switch (recovery) {
case 'correctable':
// Buyer-side fix. Patch the JSON pointers from issues[], resend with
// the SAME idempotency_key (fresh key = new operation).
break;
case 'transient':
// Retry with the SAME idempotency_key. Same key on retry replays the
// cached response if the work landed.
break;
case 'terminal':
// Human action required. Don't retry.
break;
}
```
`issues[]` is the actionable part: each entry has a JSON Pointer (`pointer`), an Ajv keyword (`required`, `oneOf`, `enum`, etc.), and — for `oneOf` failures — a `variants[]` array listing each variant's required fields. See the [Error recovery section](/dist/docs/3.2.8/protocol/calling-an-agent#error-recovery--read-issues) for the full envelope and recovery semantics.
## Receive webhooks
For async tasks, you can either poll or register a webhook. The webhook delivers the same `result` payload as AdCP task polling with `include_result: true`. The SDK ships an RFC 9421 webhook verifier (`createWebhookVerifier` from `@adcp/sdk/signing/server`) that resolves keys via the seller's brand.json, enforces the replay window, and surfaces structured errors for the [webhook error taxonomy](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-error-taxonomy).
If you wire the multi-agent client with a `webhookUrlTemplate` and status-change handlers (per the [@adcp/sdk README](https://github.com/adcontextprotocol/adcp-client#readme)), incoming webhooks are verified and dispatched into your handlers automatically — your HTTP route is one line that hands the request to the client.
For the wire-level requirements your endpoint MUST satisfy regardless of how it's wired (covered components, `content-digest` enforcement, dedup discipline), see [L3 — Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks#signature-verification).
## Ingest reporting
Reporting is read-only and follows the same call/response shape as everything else. Pull delivery for the buys you own and iterate on a windowed cadence:
```typescript theme={null}
const delivery = await client.getMediaBuyDelivery({
media_buy_ids: ['mb_123', 'mb_456'],
window: { start: '2026-05-01T00:00:00Z', end: '2026-05-02T00:00:00Z' },
});
```
For sellers that support performance webhooks, you'll receive deltas via the same webhook receiver shown above; otherwise poll on whatever cadence your reporting needs. Caller L4 — optimization, pacing alerts, attribution joins, dashboards — is your application code on top of the typed `delivery` object.
## What you didn't have to write
Caller-side L0–L3 is weeks of handler glue because the SDK already shipped:
* **L0** — typed request builders, response parsers, schema validation against the bundled schemas.
* **L1** — outbound RFC 9421 signing (per-call), inbound webhook verification, key rotation.
* **L2** — agent registry lookup, agent-card publication, credential composition.
* **L3** — async-task polling, webhook receiver, idempotency-key generation helpers, error-recovery classification.
The [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack) decomposes each layer; the [server-vs-client comparison table](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#server-vs-client-at-each-layer) is the side-by-side view of the cost asymmetry.
## What's next
* **[Calling an agent](/dist/docs/3.2.8/protocol/calling-an-agent)** — the canonical wire-contract reference. Read once before going to production.
* **[Schemas](/dist/docs/3.2.8/building/by-layer/L0/schemas)** — schema bundle, type generation, version pinning.
* **[Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks)** — push notifications, signing, retry, reliability patterns.
* **[Error handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling)** — error categories, codes, recovery classification.
* **[Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** — storyboards also exist for caller-side wire conformance; run them once your calls are working.
Per-protocol task references:
* [Media buy task reference](/dist/docs/3.2.8/media-buy/task-reference/index)
* [Creative task reference](/dist/docs/3.2.8/creative/task-reference)
* [Signals task reference](/dist/docs/3.2.8/signals/tasks/get_signals)
* [Brand protocol tasks](/dist/docs/3.2.8/brand-protocol)
# Build an Agent
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L4/build-an-agent
Use AdCP SDK skill files to generate storyboard-compliant agents with a coding agent in minutes.
The fastest way to build an AdCP agent is to point a coding agent (Claude Code, Codex, Cursor, Windsurf) at a skill file from an AdCP SDK. Each skill produces a protocol-compliant, storyboard-validated agent in 2–8 minutes.
> [!NOTE]
>
> **Publisher without an engineering team?** Protocol compliance is one piece of going live — product management, activation into your ad server, and hosting are separate lifts. See **[Operating an Agent](/dist/docs/3.2.8/building/operating/operating-an-agent)** for the three paths: partner with a managed platform, self-host a prebuilt agent, or build your own.
## Install the SDK
Each SDK handles protocol compliance — schema validation, error formats, version negotiation, and response builders — so you write business logic, not protocol plumbing.
> [tab] JavaScript/TypeScript
>
> ```bash theme={null}
> npm install @adcp/sdk
> ```
>
> The JS/TS SDK provides typed tool registration, response builders, and a built-in storyboard runner. Most agents in production use this SDK.
>
> * [NPM Package](https://www.npmjs.com/package/@adcp/sdk)
> * [GitHub Repository](https://github.com/adcontextprotocol/adcp-client)
> [tab] Python
>
> ```bash theme={null}
> pip install adcp
> ```
>
> The Python SDK provides the same capabilities — subclass `ADCPHandler`, implement tools, and use response builders for every return value:
>
> ```python theme={null}
> from adcp.server import ADCPHandler, serve
> from adcp.server.responses import capabilities_response
>
> class MySeller(ADCPHandler):
> async def get_adcp_capabilities(self, params, context=None):
> return capabilities_response(["media_buy"])
>
> # ... implement tools, use response builders for every return
>
> serve(MySeller(), name="my-seller")
> ```
>
> Response builders (`adcp.server.responses`) handle schema compliance so you don't construct raw JSON. Use them for every tool return.
>
> * [PyPI Package](https://pypi.org/project/adcp/)
> * [GitHub Repository](https://github.com/adcontextprotocol/adcp-client-python)
> [tab] Go
>
> ```bash theme={null}
> go get github.com/adcontextprotocol/adcp-go/adcp
> ```
>
> The Go SDK provides typed tool registration, response builders, and a compliance test controller. Types are generated from canonical AdCP schemas.
>
> | Component | Import |
> | - | - |
> | Tool registration | `adcp.AddTool(server, name, desc, handler)` |
> | HTTP server | `adcp.Serve(createAgent)` |
> | Response builders | `adcp.ProductsResponse(data)`, `adcp.MediaBuyResponse(data)` |
> | Test controller | `adcp.RegisterTestController(server, store)` |
>
> See the [Go SDK README](https://github.com/adcontextprotocol/adcp-go) for complete examples.
>
> Response builders (`adcp.ProductsResponse()`, `adcp.MediaBuyResponse()`, etc.) handle schema compliance so you return typed structs, not raw JSON.
>
> * [GitHub Repository](https://github.com/adcontextprotocol/adcp-go)
> [!NOTE]
>
> **Use the SDK for your language.** All three SDKs — JS/TS, Python, and Go — handle schema validation, error formats, and protocol negotiation. You do not need to use a different language for protocol compliance.
## Choose a skill
Each SDK ships skills that walk a coding agent through building a specific agent type. Common skills across SDKs:
* `build-seller-agent` — publisher, SSP, or media network selling inventory
* `build-signals-agent` — CDP or data provider serving audience segments
* `build-creative-agent` — ad server or CMP rendering creatives
* `build-generative-seller-agent` — AI ad network generating ads from briefs
* `build-retail-media-agent` — retail media network with catalog-driven creative
For example, the JS/TS seller skill lives at [`adcp-client/skills/build-seller-agent/SKILL.md`](https://github.com/adcontextprotocol/adcp-client/tree/main/skills/build-seller-agent). Skill coverage and naming vary per language since each SDK includes implementation guidance specific to its stack. Browse the directory for your language:
* **JS/TS** — [adcp-client/skills](https://github.com/adcontextprotocol/adcp-client/tree/main/skills)
* **Python** — [adcp-client-python/skills](https://github.com/adcontextprotocol/adcp-client-python/tree/main/skills)
* **Go** — [adcp-go/skills](https://github.com/adcontextprotocol/adcp-go/tree/main/skills)
### Which domain and specialisms do you claim?
Each agent declares its `supported_protocols` (domains) and `specialisms` on `get_adcp_capabilities`. Each skill's storyboard verifies the domain baseline — to also claim a specialism, your agent must pass that specialism's storyboard. Skills-to-specialism mapping:
| Skill | Typical `supported_protocols` | Typical `specialisms` (pick one or combine) |
| - | - | - |
| `build-seller-agent` | `["media_buy", "creative"]` | `sales-guaranteed`, `sales-non-guaranteed`, `sales-dooh` |
| `build-generative-seller-agent` | `["media_buy", "creative"]` | `creative-generative` + `sales-non-guaranteed` |
| `build-retail-media-agent` | `["media_buy", "creative"]` | `sales-catalog-driven` |
| `build-signals-agent` | `["signals"]` | `signal-owned`, `signal-marketplace` |
| `build-creative-agent` | `["creative"]` | `creative-ad-server`, `creative-template` |
**Picking a sales specialism:** See [Choosing a sales specialism](/dist/docs/3.2.8/building/verification/compliance-catalog#choosing-a-sales-specialism) in the Compliance Catalog for the full decision tree. Quick reference:
* **`sales-guaranteed`** — IO approval, fixed pricing. Set `media_buy.supports_proposals: true` if you support RFP/proposal flows; `false` (or omit) for direct-buy only.
* **`sales-non-guaranteed`** — auction / PMP.
* **`sales-dooh`** — non-guaranteed digital out-of-home venue and screen inventory.
* **`sales-broadcast-tv`**, **`sales-catalog-driven`**, **`sales-social`** — channel-specific; see the decision tree.
You can claim more than one. See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for the full taxonomy and per-specialism storyboards.
Building a **brand rights** agent (licensing talent, music, stock media)? There's no skill today — see the [Brand Protocol docs](/dist/docs/3.2.8/brand-protocol) and claim `brand-rights` under the `brand` domain.
See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for every domain and specialism with its storyboard and status (stable, preview, deprecated).
Storyboard passing earns the **[AAO Verified (Spec)](/dist/docs/3.2.8/building/verification/aao-verified)** qualifier — validated against seeded test data on a test-mode endpoint. Once your agent is running against real production inventory, consider enrolling in the **(Live)** qualifier, which adds continuous observability of real delivery on a dedicated compliance account. An agent can hold (Spec), (Live), or both; enterprise buyers that treat AdCP as production infrastructure filter on (Live).
## Build the agent
Point your coding agent at the skill file for your agent type. In Claude Code:
> [tab] JavaScript/TypeScript
>
> ```
> Fetch https://raw.githubusercontent.com/adcontextprotocol/adcp-client/main/skills/build-seller-agent/SKILL.md, then build a seller agent for a premium sports news publisher with guaranteed CTV and OLV inventory.
> ```
> [tab] Python
>
> ```
> Fetch https://raw.githubusercontent.com/adcontextprotocol/adcp-client-python/main/skills/build-seller-agent/SKILL.md, then build a seller agent for a premium sports news publisher with guaranteed CTV and OLV inventory.
> ```
>
> Point at the `adcp-client-python` skill for your agent type. If the exact skill isn't there yet, browse [adcp-client-python/skills](https://github.com/adcontextprotocol/adcp-client-python/tree/main/skills) for the closest match.
> [tab] Go
>
> ```
> Fetch https://raw.githubusercontent.com/adcontextprotocol/adcp-go/main/skills/build-seller-agent/SKILL.md, then build a seller agent for a premium sports publisher.
> ```
In Cursor or Windsurf, download the skill file and include it as context with your prompt. Each skill walks the coding agent through:
1. Business model decisions (what you sell, how you price, approval workflow)
2. Tool registration with correct schemas
3. Response shapes that pass storyboard validation
4. Error handling and edge cases
## Validate with storyboards
> [!NOTE]
>
> The storyboard runner requires Node.js, regardless of what language your agent is written in.
Once the agent is running, validate it against the matching storyboard:
```bash theme={null}
# JS/TS agent
npx tsx agent.ts &
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller --json
# Python agent
python agent.py &
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller --json
# Go agent
go run main.go &
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller --json
```
Storyboards exercise every required tool call and validate response shapes. The storyboard runner uses sandbox mode by default — your agent receives `sandbox: true` on all account references and should return simulated data without real platform calls. A passing run means your agent is protocol-compliant.
```
media_buy_seller (9 steps)
✓ get_adcp_capabilities
✓ sync_accounts
✓ get_products
✓ create_media_buy
✓ canonical creative capability declarations
✓ sync_creatives
✓ list_creatives
✓ get_media_buy_delivery
✓ provide_performance_feedback
9/9 passed
```
> [!WARNING]
>
> **Protocol-compliant ≠ production-ready.** A passing run means your agent speaks AdCP correctly. Going live requires business infrastructure behind each tool call — products and pricing, activation into your ad server, order management, hosting, and discovery registration via `adagents.json`. See **[Operating an Agent](/dist/docs/3.2.8/building/operating/operating-an-agent)** for the full list and whether to partner, self-host, or build.
> [!TIP]
>
> Each skill includes variant storyboards for different business models — non-guaranteed, guaranteed with approval, proposal mode, and more. Run `npx @adcp/sdk@latest storyboard list` to see all available storyboards.
See **[Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** for the full testing workflow — debugging failing steps, running compliance checks, and validating interactively through Addie. If your agent **wraps an upstream platform** (DSP, SSP, retail data, creative server, signal marketplace), see **[Validate adapter agents with mock upstream fixtures](/dist/docs/3.2.8/building/verification/validate-with-mock-fixtures)** for the pre-staging gate that surfaces façade bugs storyboards alone don't catch.
## Additional resources
The JS/TS SDK includes documentation designed for both humans and coding agents:
| Resource | JS/TS location | Purpose |
| - | - | - |
| Protocol spec | `node_modules/@adcp/sdk/docs/llms.txt` | Full protocol in one file — tools, types, error codes, examples |
| Server guide | `node_modules/@adcp/sdk/docs/guides/BUILD-AN-AGENT.md` | Server-side implementation patterns |
Python and Go equivalents are in each SDK's GitHub repository. See [adcp-client-python](https://github.com/adcontextprotocol/adcp-client-python) and [adcp-go](https://github.com/adcontextprotocol/adcp-go).
## What's next
* **[Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** — Storyboards, compliance checks, and the build-validate-fix loop
* **[Operating an Agent](/dist/docs/3.2.8/building/operating/operating-an-agent)** — What sits behind the protocol layer, and whether to partner, self-host, or build
* **[Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk)** — Schema access, CLI tools, and SDK package exports
* **[MCP integration guide](/dist/docs/3.2.8/building/by-layer/L0/mcp-guide)** — Transport, sessions, and auth details
* **[Task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle)** — Status values, transitions, and polling
* **[Error handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling)** — Error categories, codes, and recovery
# Choose your SDK
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk
Pick the AdCP SDK for your language. Coverage matrix, install commands, and what each SDK ships at L0–L3 so you can focus on L4 business logic.
The AdCP SDKs absorb L0–L3 (wire, signing, auth, protocol semantics) so you write L4 business logic. Pick the SDK in the language you're already in — all three SDKs target the same wire conformance bar.
> [!NOTE]
>
> **For production, start with a maintained SDK.** AdCP remains an open wire
> protocol, and raw schemas are appropriate for SDK authors, code generators,
> and specialized infrastructure. A production implementation built directly on
> the wire must independently get version negotiation, validation, signing,
> authorization, async state, idempotency, retry, compatibility, and audit
> behavior right. That is a legitimate enterprise investment, but it should be a
> deliberate one—not the default integration path.
For the layered model behind this — what each layer contains and what an SDK at each layer should provide — see the [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack).
## Coverage matrix
What "shipped" means at each layer is the [L0–L3 checklist](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#what-an-sdk-at-each-layer-should-provide).
*Last updated: 2026-09-30.*
| SDK | Current package | 3.2 support | L0 | L1 | L2 | L3 |
| - | - | - | :-: | :-: | :-: | :-: |
| **`@adcp/sdk`** (TypeScript) | `14.0.0` | Exact `3.2.1` support | ✅ | ✅ | ✅ | ✅ |
| **`adcp`** (Python) | `8.0.0` | Exact `3.2.1` schemas and types; higher-level helpers remain partial | ✅ | ⚠️ | ⚠️ | ⚠️ |
| **`adcp/v3`** (Go) | `v3.2.1` | Embeds `3.2.0-rc.1` generated schemas and types and defaults to the `"3.1"` wire pin; final 3.2 support is planned as a follow-up | ✅ | ⚠️ | ⚠️ | ⚠️ |
Legend: ✅ shipped · ⚠️ partial / role-dependent · ❌ not yet covered. The L0–L3 columns describe the current package, not a 3.2 support claim.
`@adcp/sdk@14.0.0` is on the npm `latest` dist-tag (also `adcp-3.2`) and includes the seller-side reporting modules (`@adcp/sdk/reporting/source` and `@adcp/sdk/reporting/ledger`) and the buyer-side consumer module (`@adcp/sdk/reporting/consumer`). Python `adcp==8.0.0` embeds the final 3.2 schemas. Final 3.2 support for Go is planned as a follow-up release; check the [adcp-go releases](https://github.com/adcontextprotocol/adcp-go/releases).
Integrations that stay on 3.1 keep using the 3.1 lines: `@adcp/sdk` 13.x (npm `adcp-3.1` dist-tag) and `adcp` 7.x. The [SDK version map](/dist/docs/3.2.8/reference/migration/3-1-to-3-2#sdk-versions-for-3-2) lists the 3.1 and 3.2 line for each language and each SDK's upgrade guide.
> [!NOTE]
>
> **The TypeScript and Python SDKs embed AdCP 3.2 (`3.2.1`).** Send
> `adcp_version: "3.2"` to peers that list `"3.2"` in
> `get_adcp_capabilities.adcp.supported_versions`; keep `"3.1"` for peers that
> do not. Raw-wire and code-generation workflows can use the
> [signed `3.2.1` bundle](https://adcontextprotocol.org/protocol/3.2.1.tgz)
> (see [verifying protocol tarballs](/dist/docs/3.2.8/reference/verifying-protocol-tarballs)).
The TypeScript SDK currently provides the broadest L0–L3 surface. Python is a
first-class SDK with complete schema/type coverage and role-dependent higher
layers. The Go `adcp/v3` module provides typed AdCP 3.x surfaces, signing, and
transport/server building blocks with role-dependent coverage. Check the
release links below for changes after this matrix date.
For the status of every published protocol version, see [Versions & Compatibility](/dist/docs/3.2.8/reference/versions). Migration and archived-version guidance lives under [Release notes & migration](/dist/docs/3.2.8/reference/migration/index).
**TypeScript and Python are the first-class supported languages**, with the
layer coverage shown in the matrix above. **Go** is moving in the same
direction. **Other languages** are not on the official roadmap;
community-maintained ports are welcome — see the [Builders Working Group](/dist/docs/3.2.8/community/working-group)
and the [Slack community](/dist/docs/3.2.8/community/joining-slack).
### Media-buy compatibility across 3.x
Sharing a protocol schema bundle does not imply identical workflow automation.
Keep the SDK package version, the served AdCP version, and the seller's
advertised lifecycle tools separate.
| SDK | Entry point for mixed-version buying | Current boundary |
| - | - | - |
| TypeScript | `agent.negotiateMediaBuyLifecycle()` selects native or established tools per operation. | Named `allowedLosses` permit supported legacy mutations; results expose the executed tools and losses. Direct `agent.listProducts()` / `agent.buyProducts()` calls use the native tools. |
| Python | Established client methods remain available; `adcp.compat.purchase_continuation.LegacyPurchaseCoordinator` handles explicit legacy purchase continuations. | Compact methods such as `client.buy_products()` dispatch the same-named tool. The continuation coordinator requires a store and executor; it is not a general automatic lifecycle router. |
| Go | Version helpers, generated request/response types, and typed server registration. | Buyer lifecycle selection and continuation orchestration remain application-owned. |
The TypeScript coordinator already supports ordinary legacy purchase behavior
with explicit loss opt-ins. Its current listing adapter rejects compact
`criteria`, and its direct-buy adapter still requires a real `feed_version`,
even when the caller accepts non-atomic fencing. Products-only brief purchase
continuations provide a separate legacy path. A missing new guarantee does
not make the seller's established creation API unusable.
On the seller side, the frameworks keep registered legacy handlers available;
implementing compact handlers alone does not generate every legacy behavior.
Retain the established handlers when serving older buyers and choose an
unversioned default appropriate to those integrations.
See the [SDK lifecycle compatibility audit](https://github.com/adcontextprotocol/adcp/blob/main/specs/sdk-lifecycle-compatibility-audit.md)
for the nine buyer–seller combinations, exact audited releases, current gaps,
and reproducible probes. TypeScript's existing
[compatibility guide](https://github.com/adcontextprotocol/adcp-client/blob/2b27442fbaf972f7a4236af227800feec268aeb0/docs/guides/MEDIA-BUY-3.2-COMPATIBILITY.md)
documents coordinator options, continuation storage, and supported projections.
## JavaScript / TypeScript
[](https://www.npmjs.com/package/@adcp/sdk)
```bash theme={null}
npm install @adcp/sdk@14.0.0
```
```javascript theme={null}
import { createSingleAgentClient } from '@adcp/sdk';
const client = createSingleAgentClient({
id: 'sales',
name: 'Sales agent',
agent_uri: 'https://sales.example.com/mcp',
protocol: 'mcp',
});
const products = await client.listProducts({
adcp_version: '3.2',
account: { account_id: 'account_123' },
criteria: {
offer_filters: { channels: ['ctv'] },
},
});
```
**Resources:**
* [NPM Package](https://www.npmjs.com/package/@adcp/sdk)
* [GitHub Repository](https://github.com/adcontextprotocol/adcp-client)
**Package exports:**
* `@adcp/sdk` — main entry: caller (`createSingleAgentClient`, `ADCPMultiAgentClient`) and shared types
* `@adcp/sdk/server` — agent-side server primitives (`createAdcpServerFromPlatform`, decisioning-platform interfaces); the lower-level `createAdcpServer` export is retained under `@adcp/sdk/server/legacy/v5`
* `@adcp/sdk/signing` — RFC 9421 signing primitives
* `@adcp/sdk/signing/server` — webhook + request verifiers (`createWebhookVerifier`, `verifyRequestSignature`, `createExpressVerifier`)
* `@adcp/sdk/signing/client` — outbound signing (`signRequest`, `signWebhook`, `createSigningFetch`)
* `@adcp/sdk/testing` — buyer-side storyboard runner (`runStoryboard`, `comply`, `testAgent`) and seller-side controller scaffold (`createComplyController` — see [Get Test-Ready](/dist/docs/3.2.8/building/verification/get-test-ready))
* `@adcp/sdk/conformance` — assertion + storyboard helpers for conformance harnesses
* `@adcp/sdk/schemas` — bundled AdCP JSON Schemas
* `@adcp/sdk/types` — TypeScript type definitions
> [accordion] Maintaining older integrations
>
> SDK 14 keeps the established 3.0/3.1 tools and compatibility adapters for
> mixed-version deployments. It also retains `@adcp/sdk/server/legacy/v5` and
> `@adcp/sdk/types/v2-5` for applications actively migrating older code. New 3.2
> integrations should use the main server and per-tool type exports.
## Python
[](https://pypi.org/project/adcp/)
```bash theme={null}
pip install adcp==8.0.0
```
```python theme={null}
from adcp import ADCPClient, AgentConfig, Protocol, GetProductsRequest
client = ADCPClient(AgentConfig(
id='sales',
agent_uri='https://sales.example.com/mcp',
protocol=Protocol.MCP,
))
result = await client.get_products(
GetProductsRequest(
idempotency_key='550e8400-e29b-41d4-a716-446655442045',
buying_mode='brief',
brief='Video campaign for pet owners',
),
)
```
**Resources:**
* [PyPI Package](https://pypi.org/project/adcp/)
* [GitHub Repository](https://github.com/adcontextprotocol/adcp-client-python)
## Go
```bash theme={null}
go get github.com/adcontextprotocol/adcp-go/adcp/v3@v3.2.1
```
The Go SDK's `adcp/v3` module provides `3.2.0-rc.1` generated schemas and types, typed
tool registration, response builders, signing, a compliance test controller,
and transport/server building blocks. Higher-layer coverage remains
role-dependent. The `/v3` suffix is required by Go semantic import versioning.
Go module versions are not AdCP versions: `v3.2.1` is an SDK release that
defaults to the `"3.1"` wire pin, not AdCP 3.2.1. Final 3.2 support for Go is
planned as a follow-up release; check the [adcp-go releases](https://github.com/adcontextprotocol/adcp-go/releases).
| Component | Import |
| - | - |
| Tool registration | `adcp.AddTool(server, name, desc, handler)` |
| HTTP server | `adcp.Serve(createAgent)` |
| Response builders | `adcp.ProductsResponse(data)`, `adcp.MediaBuyResponse(data)`, etc. |
| Test controller | `adcp.RegisterTestController(server, store)` |
| Skills | [github.com/adcontextprotocol/adcp-go/skills](https://github.com/adcontextprotocol/adcp-go/tree/main/skills) |
See the [Go SDK README](https://github.com/adcontextprotocol/adcp-go) for the full API reference.
**Resources:**
* [GitHub Repository](https://github.com/adcontextprotocol/adcp-go)
## CLI tools
The JavaScript and Python SDKs include command-line tools for testing and development.
Both SDKs share the same positional shape: `adcp [tool] [payload]`. The first positional is an alias, a built-in (`test-mcp`, `test-a2a`), or a URL — protocol is auto-detected. Save aliases with `--save-auth` to avoid retyping.
### JavaScript CLI
```bash theme={null}
npx @adcp/sdk@14.0.0 --help
npx @adcp/sdk@14.0.0 --save-auth my-agent https://sales.example.com/mcp
npx @adcp/sdk@14.0.0 my-agent list_products '{"adcp_version":"3.2","account":{"account_id":"account_123"}}'
# or against the built-in public test agent:
npx @adcp/sdk@14.0.0 test-mcp list_products '{"adcp_version":"3.2"}'
```
The `adcp_version` in the payload is a wire pin the CLI passes through, so it
can name a release other than the one the SDK embeds. Request and response
validation still uses the SDK's embedded bundle.
The CLI also drives storyboards (`adcp storyboard run`), conformance grading (`adcp grade`), and registry diagnostics. See `--help` for the full surface.
### Python CLI
```bash theme={null}
uvx --from adcp==8.0.0 adcp --help
uvx --from adcp==8.0.0 adcp --save-auth my-agent https://sales.example.com/mcp
uvx --from adcp==8.0.0 adcp my-agent get_products '{"adcp_version":"3.2","idempotency_key":"550e8400-e29b-41d4-a716-446655442064","buying_mode":"brief","brief":"CTV campaign"}'
```
## What's next
* **[Build an agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent)** — server-side L4 path. Skill files + coding agent.
* **[Build a caller](/dist/docs/3.2.8/building/by-layer/L4/build-a-caller)** — client-side L4 path. Install, call, handle responses, ingest reporting.
* **[Schemas](/dist/docs/3.2.8/building/by-layer/L0/schemas)** — schema bundle, type generation, version pinning.
* **[Migrate from hand-rolled](/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled)** — already running an AdCP agent built before the SDKs covered much? Swap one layer at a time.
# L4 — Business logic
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L4/index
Business-logic layer of the AdCP stack. What an SDK leaves to you: inventory and pricing on the agent side, planning and buying on the caller side. The default starting layer for ~95% of adopters.
L4 is what makes your agent or caller yours. An AdCP SDK ships L0–L3 (wire, signing, auth, protocol semantics) and leaves L4 to you. For most adopters this is the right starting layer — your team's value-add lives here, not in re-implementing the protocol underneath.
See the [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack) for what each layer below contains and what an SDK at each layer must provide.
## Pages in this layer
* **[Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk)** — language coverage matrix, install commands, package exports, CLI tools. Start here if you haven't picked an SDK.
* **[Build an agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent)** — server side. Point a coding agent at a skill file; get a storyboard-compliant AdCP agent.
* **[Build a caller](/dist/docs/3.2.8/building/by-layer/L4/build-a-caller)** — client side. Install the SDK, discover the agent, make calls, handle responses, ingest reporting.
* **[Migrate from hand-rolled](/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled)** — already running an AdCP agent built before the SDKs were mature? Swap one layer at a time.
# Migrate from a hand-rolled agent
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled
Incremental migration path for adopters with a working AdCP agent in production. Inventory step, lowest-risk-first swap order, conflict modes (idempotency, account-mode, webhook signing, state-machine drift), per-step rollback playbook, intermediate states that pass conformance, and when not to migrate.
This guide is for adopters with a **working AdCP agent in production** who want to move to an official SDK without a flag-day rewrite. Your agent serves real traffic; you have engineers who built the current stack and will defend it; you can't afford a multi-week freeze. The path is incremental — swap one layer at a time, ship after each step, re-certify as you go.
If you're greenfield, you're in the wrong doc — see [Build an Agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent). If you're still deciding whether to migrate at all, see the [hand-rolled re-evaluation check](/dist/docs/3.2.8/building#two-checks-before-you-start) on the building overview.
## 0. Inventory what you own today
Before swapping anything, write down what your hand-rolled stack provides at each layer of [the AdCP stack](/dist/docs/3.2.8/building/cross-cutting/sdk-stack). Use the L0–L3 checklists in that doc as the rubric. Mark each row: *shipped* / *partial* / *not yet*.
This determines order of operations. The lowest-risk swap is usually the layer where you have the **least** coverage today, because there's the least existing behavior to reconcile.
## 1. Get to spec compliance first, before changing any code
Single most important step:
1. Stand up a **mock-mode account** in your agent. (If you don't have the live/sandbox/mock distinction yet, see [Account-mode mismatch](#account-mode-mismatch) below — add the flag at your boundary first.)
2. Route mock-mode traffic to the reference mock-server.
3. Run the AdCP storyboards against your agent (see [Conformance](/dist/docs/3.2.8/building/verification/conformance) and [Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent)).
4. Read the pass/fail report.
The failure list is your migration backlog, ordered. It converts "I think the SDK adds value" into "here are the storyboards we fail and which L3 component each one points at." Without this step you're buying an SDK based on a sales pitch instead of measured gap.
You may discover you're more conformant than you thought (in which case the migration is smaller than you expected) or less (in which case the case for adopting the SDK strengthens). Either outcome is useful.
## 2. Order of operations (lowest risk first)
Recommended swap order:
1. **Conformance test surface** ([`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller)). Pure additive — mock-mode traffic now goes through the SDK; live traffic untouched. Earns spec-compliance certification on the spot.
2. **Error code catalog**. Replace your error-envelope construction with the SDK's error builders. Recovery classifications and code precedence (e.g., `NOT_CANCELLABLE` over `INVALID_STATE`) come for free. See [Error handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling).
3. **Idempotency cache**. Riskiest swap — see [Two idempotency caches in series](#two-idempotency-caches-in-series). Spec contract: [Idempotency](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency).
4. **Async-task store + dispatcher**. Adopt the SDK's `task_id` + terminal-artifact contract. Often touches your worker queue. See [Task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle).
5. **State machines**, one resource at a time. MediaBuy first ([lifecycle reference](/dist/docs/3.2.8/media-buy/media-buys/lifecycle)) if it's where you spend the most maintenance time. Re-run lifecycle storyboards after each.
6. **Webhook emission** (signed, retried, idempotent). Independent of 1–5; can be parallelized. See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks).
7. **RFC 9421 signing + verification**. Independent of everything above; can be parallelized. See [Security implementation](/dist/docs/3.2.8/building/by-layer/L1/security).
8. **Auth / account store**. Last. Your hand-rolled L2 probably encodes business decisions that don't move easily.
You can stop at any step. Adopting at L3 (steps 1–6) without L2 is a perfectly valid endpoint — your auth layer keeps doing what it does, the SDK takes over protocol semantics. See [What you can leave hand-rolled](#5-what-you-can-leave-hand-rolled).
## 3. Conflict modes to watch for
These are the "two stacks fighting each other" failure modes that make incremental migration painful if you don't see them coming.
### Two idempotency caches in series
Your existing cache fields requests at the perimeter; the SDK's cache fields requests at the protocol boundary. Symptoms: same `idempotency_key` returns different envelopes depending on which cache hit first; cross-payload reuse is detected by one and not the other.
**Resolution.** Pick one, retire the other. Usually retire yours — the SDK's enforces the *no-payload-echo* invariant on `IDEMPOTENCY_CONFLICT` (stolen-key read-oracle threat) and the cross-payload conflict detection that the spec mandates. If you need to keep your storage backend (Redis, Postgres), point the SDK's cache contract at it as a custom backend instead of forking the SDK.
### Account-mode mismatch
The SDK distinguishes `live` / `sandbox` / `mock` accounts (see [Sandbox](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox)). If your hand-rolled stack lacks the distinction, mock-mode storyboards may dispatch to live handlers. Symptoms: storyboards mutate production state; conformance certification refuses to dispatch.
**Resolution.** Add the account-mode flag at your boundary before adopting the SDK's conformance controller. The `comply_test_controller` refuses to run against any account that isn't sandbox or mock — that refusal is a feature, not a bug.
### Webhook signature ownership
If both stacks try to sign outbound webhooks, the receiver sees two `Signature` headers (or one wins and the other is silently overwritten by the proxy). Either way, signatures don't verify.
**Resolution.** Pick one signer at the boundary; usually the SDK's, since it tracks key rotation against the public key registry and handles the RFC 9421 canonicalization correctly. Keep your KMS-backed key material; configure the SDK's signing-provider abstraction to use it.
### State machine drift
Your hand-rolled state machine probably has edges the SDK rejects (e.g., direct `pending_creatives → completed` skipping `active`, or `active → canceled` without distinguishing the `NOT_CANCELLABLE` vs `INVALID_STATE` precedence). Symptoms: lifecycle storyboards fail with `INVALID_STATE` where you expected to succeed.
**Resolution.** Run the lifecycle storyboards against your agent *before* swapping the state machine. Reconcile your edge set to the spec — fix obvious bugs, file spec issues for ambiguities. Then swap the SDK's state machine in; it'll enforce what you just hand-converged on.
### Webhook delivery transport
If your queue/worker stack delivers webhooks today, the SDK's emitter would double-deliver if you wire it on without retiring yours. Symptoms: receivers see duplicate idempotency keys with the same payload at slightly different times.
**Resolution.** The SDK builds the envelope; how you ship it is yours. Configure the SDK to hand off to your existing transport instead of running its built-in HTTP delivery — that's the seam.
### Schema validation collisions
If you validate inbound payloads against your own schema bundle, and the SDK validates again at its boundary, you get either duplicate work (cheap) or contradictory verdicts (a real bug — your bundle drifted from the published schemas).
**Resolution.** Retire your local validator after the SDK is in. While both run, treat any discrepancy as your bundle being stale, not the SDK being wrong.
## 4. Intermediate states that pass conformance
After each step, you can re-run mock-mode storyboards and re-certify. You don't need to finish the migration to claim conformance — you only need to pass the storyboards at whatever cut-line the SDK's conformance suite enforces.
| After step | What you have | Conformance status |
| - | - | - |
| 1 | Conformance controller wired; agent unchanged | **Spec compliance** (mock-mode storyboards run against your unchanged L3) |
| 2 | + SDK error envelopes | Same; better recovery semantics |
| 3 | + SDK idempotency | Same; tighter security on cross-payload reuse |
| 4 | + SDK async-task contract | Same; uniform task lifecycle |
| 5 | + SDK state machines | Same; transition validation no longer your problem |
| 6 | + SDK webhook envelope | Same; signed, retried, dedup-keyed |
| 7 | + SDK signing | **Live compliance** (when that storyboard set ships) |
| 8 | + SDK account store | Full L4-on-SDK |
You ship after each step. Production traffic stays up.
### Rollback per step
Every step in the swap order should be reversible inside \~5 minutes. The general pattern: each swap is a **feature-flagged switch between your hand-rolled component and the SDK's**, not a deletion. You ship the swap behind a per-account flag, observe, then flip the default. Rollback is the same flag in the other direction.
What to plan for, swap by swap:
| Step | Revert mechanism | What state may have leaked | First thing to verify on rollback |
| - | - | - | - |
| 1. Conformance controller | Disable the SDK route on mock-mode accounts | None — mock-mode is sandbox-only by design | Mock storyboards still pass against your hand-rolled L3 |
| 2. Error envelopes | Flip back to your error builder | Outbound envelopes from the swap window may carry SDK-shape error codes; downstream consumers that key off your old codes may have logged them | Your error-monitoring dashboard is reading the right envelope shape again |
| 3. Idempotency cache | Flip back to your cache | **Both caches saw traffic during the swap window.** Same `idempotency_key` may now exist in both stores with different envelopes. After rollback, your cache is authoritative; flush the SDK's cache on revert | No `IDEMPOTENCY_CONFLICT` storms from the dual-cache window |
| 4. Async-task contract | Flip back to your task store | Outstanding tasks that started under the SDK's contract may have a different terminal-artifact shape than your worker expects | Drain or abort tasks created during the swap window before the revert lands |
| 5. State machines | Flip back to your state machine | The SDK may have rejected transitions your machine would have accepted (or vice versa). Affected resources are in a state your code may not know how to advance | Run a one-shot reconciliation query: "any resources in a state that's legal under both machines? Any in a state that's only legal under one?" |
| 6. Webhook envelope | Flip back to your emitter | Receivers got SDK-shape webhooks during the swap window. They may have already acked. Don't re-emit on rollback | Your dedup table accepts both old and new `idempotency_key` shapes (transitional) |
| 7. RFC 9421 signing | Flip back to your signer | Receivers got SDK-signed webhooks/responses during the window. Their key registry must still resolve your old `keyid` | Your old `keyid` is still published in your JWKS |
| 8. Account store | Flip back to your store | Account resolution decisions made under the SDK's store may have routed traffic to different tenants than your store would have | Run a reconciliation on accounts that were resolved during the swap window before fully reverting |
### The 2 a.m. production failure
If swap N fails in production at 2 a.m., the on-call recipe:
1. **Flip the per-account flag back** to your hand-rolled component for the affected accounts (or globally if you can't isolate the blast radius). This is the only step required to stop the bleeding.
2. **Confirm the leakage row** above for that step. Most steps leave residual state somewhere — note what it is so the morning debug doesn't start cold.
3. **Don't rerun the conformance suite mid-incident.** It runs against mock-mode; production failures are a different signal.
4. **File the incident against the swap step**, not against the SDK in general. The migration guide's swap-order is the unit of investigation; the SDK's coverage matrix is downstream of that.
**Don't plan for irreversible swaps.** If a step doesn't fit the flag-and-flip pattern (e.g., a destructive schema migration), do it as a separate, named project — not as part of the swap order.
## 5. What you can leave hand-rolled
The SDK is opinionated where the spec is opinionated, and pluggable where it isn't. You don't have to give up your existing infra:
* **Signing provider.** Keep your KMS integration. The SDK accepts a custom signer.
* **Account store.** Keep your multi-tenant routing. The SDK's account-store interface is the seam.
* **Idempotency backend.** Keep your Redis / Postgres. The SDK's cache contract is pluggable.
* **Webhook delivery transport.** Keep your queue. The SDK builds the envelope; how you ship it is yours.
* **Schema validation library.** Keep your validator if you want; the SDK uses its own at its boundary, not yours.
If your hand-rolled stack has good answers to these, swap them in as **configuration**, not as forks.
## 6. Versioning during the migration
Two version axes you'll be juggling:
* **Spec version of your buyers.** A migration is a great moment to add per-call `adcpVersion` pinning so you stop forking handlers by buyer-version. See [Version Adaptation](/dist/docs/3.2.8/building/cross-cutting/version-adaptation).
* **SDK version.** Don't migrate to a legacy import path as a final state — migrate *through* it. The legacy subpath exists so you can adopt one specialism at a time on the new entry point while the rest stays on the old one. Greenfield code in the same project uses the new framework directly.
### Worked example: two buyers, mid-swap
You're on step 3 (idempotency), buyer A is temporarily on end-of-life AdCP 2.5 while migrating, and buyer B is on AdCP 3.0. You've adopted the SDK's controller, error envelopes, and idempotency cache for the accounts you've cut over. Buyer A is mid-flight to the SDK; buyer B is greenfield on the SDK. This is a migration bridge, not a supported production endpoint state.
Your inbound side: identify each peer's spec version up front (from the agent registry, the agent card, or the `adcp_version` field if present), pin `adcpVersion` on the agent / per call, and let the SDK adapt the wire shape. Example with `@adcp/sdk`:
```ts theme={null}
import { ADCPMultiAgentClient } from '@adcp/sdk';
const buyerA = new ADCPMultiAgentClient([{
id: 'buyer-a',
agent_uri: 'https://buyer-a.example.com/mcp/',
protocol: 'mcp',
auth_token: process.env.BUYER_A_TOKEN,
adcpVersion: 'v2.5', // ← per-agent pin, no fork in handlers
}]);
const buyerB = new ADCPMultiAgentClient([{
id: 'buyer-b',
agent_uri: 'https://buyer-b.example.com/a2a',
protocol: 'a2a',
auth_token: process.env.BUYER_B_TOKEN,
adcpVersion: '3.0', // ← canonical / current
}]);
```
Your outbound (server) side, declaring what *you* accept:
```ts theme={null}
import { createAdcpServer } from '@adcp/sdk/server';
createAdcpServer({
capabilities: {
major_versions: [3],
supported_versions: ['3.0'],
},
// …handlers, all on the canonical 3.0 shape;
// 2.5 callers are translated by client-side adapters before they reach you.
});
```
What this looks like for one call from each buyer, mid-step-3:
| | Buyer A (2.5 wire) | Buyer B (3.0 wire) |
| - | - | - |
| **Inbound shape** | 2.5 `create_media_buy` | 3.0 `create_media_buy` |
| **Adapter does** | Translates 2.5 → 3.0 shape | Pass-through |
| **Your handler sees** | 3.0 typed object | 3.0 typed object (same) |
| **Idempotency cache** | SDK's (you're on step 3) | SDK's |
| **Error envelope** | SDK's, translated back to 2.5 on outbound | SDK's |
| **Outbound shape** | 2.5 (translated by adapter on the way out) | 3.0 |
One handler codebase. Two wire versions. Both buyers see the envelope shape they expect. Adopting `adcpVersion` pinning at step 3 is cheap — most of the version work is in the adapter modules, which the SDK already ships.
If you fall back (rollback step 3 to your hand-rolled cache), buyer A still goes through the SDK's translation adapters — the version machinery and the idempotency machinery are independent. You don't re-fork your handler code on rollback.
## 7. When to *not* migrate
If your agent serves a frozen wire surface for a small set of named buyers and your engineers spend \~zero time on protocol maintenance, the migration ROI is low. Reasonable holds:
* You serve a frozen, supported 3.x wire surface and have a dated plan to adopt the current release before that surface reaches end of life.
* Your conformance gap (from step 1) is small enough to fix in place without adopting the SDK.
* You have a hard regulatory or operational reason for owning every layer end-to-end.
In those cases, do step 1 anyway — route mock-mode through the reference mock-server for spec compliance certification — and revisit the migration question at AdCP 4.0 or when your buyer mix moves.
The migration is for adopters whose **maintenance load is real and growing**. The cost claim ([\~3–4 person-months for L0–L3 from scratch](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#why-sdks-matter-more-in-adcp-than-in-eg-http)) is what you're *buying back* by adopting incrementally — but only if that maintenance load actually exists.
## See also
* [The AdCP stack](/dist/docs/3.2.8/building/cross-cutting/sdk-stack) — layered architecture reference
* [Where to start](/dist/docs/3.2.8/building) — decision page
* [Version Adaptation](/dist/docs/3.2.8/building/cross-cutting/version-adaptation) — three-mechanism reference
* [Conformance](/dist/docs/3.2.8/building/verification/conformance) — how the storyboard suite grades your agent
* [Build an Agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent) — greenfield path; useful as a reference for what the L4-on-SDK end state looks like
# AdCP and OpenRTB
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/concepts/adcp-vs-openrtb
AdCP vs OpenRTB: how they differ and work together. AdCP handles agent workflows, OpenRTB handles impression-time decisions, and the Trusted Match Protocol connects the two for use cases like cross-publisher frequency capping.
AdCP and OpenRTB are complementary standards that operate at different layers of the advertising stack. They are not competing — a platform can (and often will) implement both.
One of the most important connection points is **cross-publisher frequency capping**. AdCP enables it the same way OpenRTB enables programmatic buying: by exposing each impression to a buyer-controlled real-time decision layer before the ad server serves. In AdCP, that integration point is the **[Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match)**.
## What each standard does
| | OpenRTB | AdCP |
| - | - | - |
| **Layer** | Impression-level transactions | Agent-level workflows |
| **Core operation** | Real-time bid request/response | Task-based campaign management |
| **Participants** | DSPs and SSPs | AI agents and advertising platforms |
| **Timing** | Real-time (milliseconds) | Asynchronous (seconds to days) |
| **Scope** | Single impression auction | End-to-end campaign lifecycle |
| **Maintained by** | IAB Tech Lab | AgenticAdvertising.org |
| **Maturity** | Production (v2.6) | Production (v3.0) |
| **Transport** | HTTP POST | MCP (tool calling) or A2A (agent-to-agent) |
## Where they overlap
Both standards touch media buying, but at different granularities:
* **OpenRTB** handles individual impression decisions: "Should I bid on this impression, and how much?"
* **AdCP** handles campaign-level decisions: "What inventory is available? Execute this campaign with this budget and targeting."
A single AdCP `create_media_buy` task might result in thousands of OpenRTB bid requests over the campaign's lifetime.
## Where they're different
**Scope.** OpenRTB is focused on the auction — bid requests, bid responses, win notifications, and billing events. AdCP covers the full campaign lifecycle: product discovery, creative management, audience activation, campaign execution, and delivery reporting. AdCP also works independently of real-time bidding: a direct-sold publisher, sponsored content business, broadcast seller, or commerce media network can implement AdCP without any OpenRTB integration.
**Communication model.** OpenRTB uses synchronous HTTP: a bid request arrives, and the bidder must respond within a few hundred milliseconds. AdCP is asynchronous: an agent submits a `create_media_buy` task, and the platform processes it on its own timeline, returning status updates.
**Participants.** OpenRTB connects demand-side platforms (DSPs) to supply-side platforms (SSPs) in automated auctions. AdCP connects AI agents to any advertising platform — including but not limited to DSPs and SSPs.
**Data model.** OpenRTB defines impression objects, bid objects, and deal objects. AdCP defines media products, media buys, creative formats, audience signals, and brand governance rules.
## How they work together
A typical integration uses both standards at different layers:
1. A **buyer agent** uses AdCP to discover available products on a publisher's platform (`get_products`)
2. The agent creates a campaign via AdCP (`create_media_buy`) with budget, targeting, and scheduling
3. At impression time, the publisher sends a **TMP Context Match** (page content, available packages) and an **Identity Match** (opaque user token, package IDs) to the TMP Router
4. TMP evaluates cross-publisher exposure and returns offers and eligibility decisions — the publisher joins them locally
5. The buyer agent checks delivery via AdCP (`get_media_buy_delivery`) to monitor overall campaign performance
In this model, AdCP handles the strategic layer (what to buy, how much to spend, who to target), TMP handles the real-time execution layer (which packages activate on which impressions), and OpenRTB handles the tactical auction layer where applicable (which specific impressions to win).
## TMP: The Real-Time Bridge
The [Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match) is how AdCP reaches impression-time decisioning. It gives the buyer a real-time look at each impression opportunity so cross-publisher data can affect the serve decision, without turning AdCP itself into an auction protocol.
TMP defines two structurally separated operations:
```mermaid theme={null}
flowchart LR
buyer["**Buyer Agent**
Creates media buy in AdCP"]
pub["**Publisher**
Impression opportunity"]
ctx["**Context Match**
Page content + packages
(no user identity)"]
id["**Identity Match**
User token + package IDs
(no page context)"]
join["**Publisher Join**
Intersect offers × eligibility"]
decision["**Activate or suppress**"]
buyer --> pub
pub --> ctx
pub --> id
ctx --> join
id --> join
join --> decision
```
For cross-publisher frequency capping, this means:
1. AdCP defines the campaign, budget, and packages
2. At impression time, the publisher sends a Context Match request (which packages match this content?) and an Identity Match request (is this user eligible for these packages?)
3. The buyer's Identity Match agent checks exposure history across all publishers connected to the TMP Router — frequency caps, audience membership, and purchase history are evaluated here
4. The publisher joins the two responses locally: packages that matched the context *and* passed identity eligibility activate; everything else is suppressed
The buyer never sees both context and identity simultaneously. Cross-publisher frequency capping is enforced through the Identity Match path, where the buyer maintains a shared exposure store across publishers.
## Other standards in the ecosystem
AdCP and OpenRTB exist alongside several other standards:
| Standard | Purpose | Maintained by |
| - | - | - |
| **MCP** (Model Context Protocol) | AI tool calling — how an AI model calls external tools | Anthropic |
| **A2A** (Agent-to-Agent Protocol) | Multi-agent collaboration — how autonomous agents communicate | Google |
| **VAST** / **VPAID** | Video ad serving and interactive video | IAB Tech Lab |
| **ads.txt** / **sellers.json** | Supply chain transparency and authorized seller verification | IAB Tech Lab |
| **Open Measurement SDK** | Viewability and attention measurement | IAB Tech Lab |
AdCP uses MCP and A2A as transport layers. It references IAB content taxonomies and audience segment standards where applicable.
## Frequently asked questions
> [accordion] Does AdCP replace OpenRTB?
>
> No. They serve different purposes. OpenRTB handles real-time impression auctions. AdCP handles campaign-level agent workflows. A platform can implement both.
> [accordion] Do I need to implement OpenRTB to use AdCP?
>
> No. AdCP works independently. A platform that doesn't use real-time bidding (for example, a direct-sold publisher or a commerce media network) can implement AdCP without any OpenRTB integration.
> [accordion] Can an AdCP agent trigger OpenRTB transactions?
>
> Yes. When a buyer agent creates a media buy via AdCP, the sell-side platform can use any internal mechanism to fulfill the order — including OpenRTB auctions, direct insertion orders, private marketplace deals, or TMP-mediated real-time activation for things like cross-publisher frequency caps.
> [accordion] Is AgenticAdvertising.org part of IAB Tech Lab?
>
> No. AgenticAdvertising.org is an independent member organization. It is not a subsidiary, working group, or affiliate of IAB Tech Lab. However, AdCP is designed to be compatible with IAB standards.
# How AI agents communicate ad specs across platforms
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/concepts/how-agents-communicate
How AI advertising agents discover inventory, exchange campaign data, and execute buys across platforms using AdCP's standardized task schemas and MCP transport.
When an AI agent manages a campaign across multiple platforms, it needs to do the same things on each one: find available inventory, submit a buy, provide creatives, and check delivery. The challenge is that every platform describes these operations differently.
AdCP solves this by defining a standard set of tasks — each with a fixed request schema and response schema — that agents use regardless of which platform they're talking to.
## The communication problem
Consider a buyer agent managing campaigns across three platforms:
| Operation | Platform A | Platform B | Platform C |
| - | - | - | - |
| Find inventory | `GET /api/products` | `POST /inventory/search` | `GET /catalogue` |
| Execute a buy | `POST /api/campaigns` | `PUT /orders/new` | `POST /media-buys` |
| Check delivery | `GET /api/reports` | `POST /analytics/query` | `GET /stats/{id}` |
Without a standard, the agent needs custom code for each platform — different endpoints, different field names, different response formats. This limits how many platforms an agent can work with.
With AdCP, the agent uses the same tasks everywhere:
| Operation | AdCP task |
| - | - |
| Find inventory | `get_products` |
| Execute a buy | `create_media_buy` |
| Check delivery | `get_media_buy_delivery` |
The schemas are identical across platforms. Only the transport connection differs.
## Two transport protocols
AdCP tasks travel over two protocols, depending on the integration type:
### MCP (Model Context Protocol)
MCP is how AI assistants call external tools. An AdCP MCP server exposes tasks as tools that Claude, Cursor, or any MCP-compatible client can call.
```
AI Assistant → MCP Client → AdCP MCP Server → Platform
```
The agent calls `get_products` as a tool. The MCP server translates the request to the platform's internal API and returns a standardized response.
**Best for:** Human-in-the-loop workflows where an AI assistant helps a media buyer interact with platforms.
### A2A (Agent-to-Agent Protocol)
A2A is how autonomous agents communicate with each other. A buyer agent sends structured messages to a seller agent, which processes them and returns results — potentially over long-running operations.
```
Buyer Agent → A2A Client → Seller Agent → Platform
```
The buyer agent sends a `create_media_buy` task as a message. The seller agent processes it (which might take seconds or hours), streaming status updates back.
**Best for:** Automated workflows where agents operate independently, with human approval at key checkpoints.
### Same tasks, different transport
The critical point: AdCP task definitions are transport-agnostic. A `get_products` request has the same fields whether it travels over MCP or A2A. A platform implements the domain logic once and serves it over both transports.
## What agents exchange
AdCP defines tasks across several domains. Here's what agents actually send back and forth in a typical campaign:
### Product discovery
The buyer agent asks "what can I buy?" and gets back a structured catalog of media products — each with pricing, formats, targeting options, and delivery types.
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442007",
"buying_mode": "brief",
"brief": "Premium video inventory on sports content for Q2"
}
```
The response includes product IDs, pricing models (CPM, CPC, flat rate), available creative formats, and audience reach estimates. The agent can compare products across platforms because the schema is the same everywhere.
### Creative specs
Before submitting creatives, the agent reads the product's canonical `format_options[]`. The declaration is already complete: it carries the accepted canonical kind, parameters, and asset slots.
```json theme={null}
{
"format_options": [
{
"format_option_id": "video_preroll_16x9",
"publisher_domain": "streamhaus.example",
"format_kind": "video_hosted",
"params": {
"width": 1920,
"height": 1080,
"slots": [{ "asset_group_id": "video_main", "asset_type": "video", "required": true }]
}
}
]
}
```
When production is needed, the buyer finds a compatible creative agent through the registry and selects one of that agent's `creative.supported_formats[]` entries with `build_creative.target_capability_id`.
### Audience data
Agents exchange audience signals — targeting segments, contextual data, first-party data — through `get_signals`. The buyer describes what they need, and the data provider returns matching segments with reach estimates and pricing, which the agent can evaluate before activating via `activate_signal`.
### Campaign execution
The agent creates a media buy with budget, schedule, and brand identity:
```json theme={null}
{
"account": { "account_id": "acct-12345" },
"brand": { "brand_id": "nova-electronics" },
"proposal_id": "prop-sports-video",
"total_budget": { "amount": 25000, "currency": "USD" },
"start_time": "2026-04-01T00:00:00Z",
"end_time": "2026-06-30T23:59:59Z"
}
```
The platform can process this immediately or asynchronously. AdCP's status system (`completed`, `working`, `submitted`, `input-required`) communicates progress back to the agent.
### Delivery reporting
The agent calls `get_media_buy_delivery` to pull performance data — impressions, clicks, spend, and conversion events — in a standardized format. Because the delivery schema is the same across platforms, the agent can aggregate and compare performance without reconciling different metric names or calculation methods.
## A worked example
Pinnacle Media, a fictional agency, runs a campaign for a consumer electronics brand across three AdCP-enabled platforms.
### Discover agents
The buyer agent checks `adagents.json` on each publisher's domain to find their sales agents and supported protocols.
### Compare inventory
The agent calls `get_products` on all three platforms in parallel. It receives structured product catalogs and compares pricing, formats, and reach — all in the same schema.
### Check creative requirements
The agent compares the products' canonical `format_options[]` declarations and identifies a compatible shared constraint envelope across all three, reducing creative production to a shared set.
### Execute buys
The agent calls `create_media_buy` on each platform with budget allocations based on its comparison analysis. Some platforms confirm immediately; others return `working` status and confirm later.
### Monitor delivery
The agent polls `get_media_buy_delivery` across all three platforms daily, aggregating results into a unified performance view for the agency's planning team.
The agency's team sets strategy and reviews results. The agent handles the cross-platform execution, format negotiation, and unified reporting.
## Getting started
> [card] [Protocol comparison](/dist/docs/3.2.8/building/concepts/protocol-comparison)
>
> Detailed technical comparison of MCP and A2A as AdCP transports.
> [card] [Building with AdCP](/dist/docs/3.2.8/building)
>
> Implementation guides, SDKs, and integration patterns.
> [card] [Media buy protocol](/dist/docs/3.2.8/media-buy/index)
>
> The buyer-side perspective: how agents automate media buying across platforms.
> [card] [Seller integration](/dist/docs/3.2.8/building/operating/seller-integration)
>
> How platforms expose their inventory to AI buyer agents.
> [card] [Operating an agent](/dist/docs/3.2.8/building/operating/operating-an-agent)
>
> What sits behind a protocol-compliant agent, and whether to build or buy.
# Why AdCP
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/concepts/index
Why AdCP exists: the fragmentation problem across RTB, platform APIs, and direct IO — and how a universal agent protocol for advertising solves it.
## Allocation, Not Day Trading
RTB treats advertising like day trading: *"What is this impression worth?"* It works for fungible inventory but commoditizes everything.
AdCP enables portfolio-level allocation: *"How should I invest my ad budget?"* This mirrors how advertisers actually think—they buy outcomes, not impressions.
> [card] [Agentic Advertising is for Allocation](https://bokonads.com/p/agentic-advertising-is-for-allocation)
>
> Why the RTB mental model doesn't fit how advertisers actually make decisions.
## The Structural Problem
Programmatic advertising defaults to a single question: *"What is this impression worth right now?"* That framing embeds CPM-based, auction-centric assumptions into the transaction layer — assumptions that do not hold for most global ad spend. Direct deals, sponsorships, broadcast, out-of-home, and retail media all operate on different pricing models, different timelines, and different success metrics. They are not edge cases; they are the majority.
AdCP sits at the **campaign-workflow layer**, above the auction. It does not replace OpenRTB or compete with serve-time decisioning — it coordinates the planning, negotiation, proposal, and deal-creation steps that happen before and after the auction fires. The [protocol comparison](/dist/docs/3.2.8/building/concepts/adcp-vs-openrtb) explains how AdCP and OpenRTB coexist.
By structuring these workflow steps as protocol-level tasks, AdCP enables agents to apply [brand identity](/dist/docs/3.2.8/brand-protocol/brand-json), [content standards](/dist/docs/3.2.8/governance/content-standards/), and governance checks at decision time — not as an afterthought. Agents that use these tasks can reason about brand suitability, creative fit, and compliance as part of the buying process rather than bolting them on post-execution. The protocol makes this possible; individual agents decide how much of it to use.
## The Fragmentation Problem
Today, advertisers face three completely different buying systems:
| Paradigm | Era | How It Works |
| - | - | - |
| **RTB/Biddable** | Legacy web | Real-time bidding via OpenRTB |
| **API-based** | Modern social, AI | Platform-specific APIs (Meta, TikTok) |
| **Direct IO** | Legacy | Insertion orders, manual deals |
Each requires different integrations, tools, workflows, and expertise. 90% of ad spend never touches RTB—it lives in walled gardens, direct deals, and premium inventory.
AdCP creates a **universal API standard** that unifies all three under one umbrella.
## Omnichannel By Design
Buying billboards is fundamentally different from buying social links:
* **Different pricing**: Flat rate vs CPM vs engagement-based
* **Different creatives**: Static images vs dynamic video vs conversational AI
* **Different measurement**: Impressions vs engagement vs footfall
AdCP creates a conceptual layer that abstracts these differences while preserving what makes each channel unique. One protocol, any channel.
## Why Agents?
Intelligent agents reduce the cost of managing complex, negotiated deals:
* **Adapt to nuances** without over-specifying everything in code
* **Handle variability** across platforms and channels
* **Natural language** lets buyers describe intent, not configure parameters
* **Scale relationships** from 3-5 platforms to 20+ without scaling teams
## The Protocol Layer for AI
AdCP isn't just unifying legacy systems—it's the protocol layer for emerging AI surfaces.
### Sponsored Intelligence
Like VAST defined video ad serving, SI defines conversational brand experiences in AI assistants. When an AI says *"Delta has flights to Boston—want me to connect you with their assistant?"*—SI defines what happens next.
> [card] [Sponsored Intelligence and the Trillion Dollar Sentence](https://bokonads.com/p/sponsored-intelligence-and-the-trillion)
>
> How conversational AI changes the economics of advertising.
### Brand identity
Standardized brand identity for AI-powered creative generation. Brands express who they are—colors, tone, assets—in formats AI systems can consume.
Together, these support fully AI-powered systems like Performance Max that need structured brand inputs, not manual campaign configuration.
> [card] [Sponsored Intelligence](/dist/docs/3.2.8/sponsored-intelligence/overview)
>
> Monetizing AI surfaces — the reversed data flow, product spectrum, and SI Chat Protocol.
> [card] [Brand identity](/dist/docs/3.2.8/brand-protocol/brand-json)
>
> Standardized brand identity for AI creative generation.
## Design Implications
These goals drive AdCP's technical design:
* **Asynchronous**: Deals take time. This is not a real-time protocol—operations may take minutes to days.
* **Human-in-the-loop**: Some decisions need human approval. Publishers can require manual sign-off.
* **Multiple transports**: MCP and A2A provide the same tasks through different protocols.
## The Protocol Family
| Protocol | Purpose | Key Tasks |
| - | - | - |
| **Media Buy** | Campaign execution | `get_products`, `create_media_buy` |
| **Signals** | Audience targeting | `get_signals`, `activate_signal` |
| **Creative** | Ad creative management | `build_creative`, `sync_creatives` |
| **Governance** | Brand suitability, quality, compliance | Property lists, content standards |
| **Sponsored Intelligence** | Conversational brand experiences | `si_initiate_session` |
| **Curation** | Inventory packaging | Coming soon |
## Next Steps
> [card] [Protocol Comparison](/dist/docs/3.2.8/building/concepts/protocol-comparison)
>
> MCP vs A2A—when to use which, and what's the same.
> [card] [Security Model](/dist/docs/3.2.8/building/concepts/security-model)
>
> Why agentic advertising raises the stakes, what AdCP defends against, and a checklist for brand IT and CISOs.
> [card] [Client SDKs](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk)
>
> JavaScript and Python libraries for AdCP.
# AI advertising standards landscape
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/concepts/industry-landscape
AI advertising standards landscape: how AdCP, OpenRTB, MCP, and A2A relate. Comparison of protocols, standards bodies, and their roles in agentic advertising.
The key standards shaping AI-powered advertising are AdCP (agent workflow coordination), OpenRTB (impression auctions), MCP (AI tool calling), and A2A (agent-to-agent communication). Advertising is moving from programmatic (machine-executed auctions) to agentic (AI agents managing full campaign lifecycles), and these protocols define how the pieces connect.
This page maps the landscape: what exists, who maintains it, and how they fit together.
## Active protocols
### Ad Context Protocol (AdCP)
AdCP defines how AI agents interact with advertising platforms. It covers the full campaign lifecycle: product discovery, media buying, creative generation, audience activation, brand governance, and delivery reporting.
| | |
| - | - |
| **Scope** | Agent-level advertising workflows |
| **Transport** | MCP (tool calling) or A2A (agent-to-agent) |
| **Maintained by** | [AgenticAdvertising.org](https://agenticadvertising.org) |
| **License** | Apache 2.0 (open source) |
| **Current version** | 3.0 (GA, April 2026) |
| **Key tasks** | `get_products`, `create_media_buy`, `build_creative`, `activate_signal` |
AdCP is transport-agnostic: the same task definitions work over both MCP and A2A. A platform implements once; agents connect via either transport.
### OpenRTB
OpenRTB handles real-time impression auctions — the bid request / bid response cycle that powers most programmatic display and video advertising.
| | |
| - | - |
| **Scope** | Impression-level transactions |
| **Transport** | HTTP POST |
| **Maintained by** | [IAB Tech Lab](https://iabtechlab.com) |
| **Current version** | 2.6 / 3.0 |
| **Key objects** | Bid request, bid response, win notice, billing notice |
OpenRTB and AdCP are complementary. OpenRTB handles "should I bid on this impression?"; AdCP handles "create a campaign with this budget and targeting." See [AdCP and OpenRTB](/dist/docs/3.2.8/building/concepts/adcp-vs-openrtb) for details.
### Model Context Protocol (MCP)
MCP defines how AI models call external tools. Developed by Anthropic, it's the standard for connecting AI assistants to APIs, databases, and services.
| | |
| - | - |
| **Scope** | AI tool calling |
| **Transport** | JSON-RPC over stdio or SSE |
| **Maintained by** | [Anthropic](https://modelcontextprotocol.io) |
| **Used by** | Claude, Cursor, Windsurf, and other AI assistants |
AdCP uses MCP as one of its transport layers. An AdCP MCP server exposes advertising tasks (like `get_products` or `create_media_buy`) as tools that any MCP-compatible AI assistant can call.
### Agent-to-Agent Protocol (A2A)
A2A defines how autonomous agents communicate with each other. Developed by Google, it enables multi-agent workflows where specialized agents collaborate.
| | |
| - | - |
| **Scope** | Agent-to-agent collaboration |
| **Transport** | HTTP + JSON-RPC with SSE streaming |
| **Maintained by** | [Google](https://google.github.io/A2A/) |
| **Used by** | Multi-agent orchestration frameworks |
AdCP uses A2A as its other transport layer. In an A2A setup, a buyer agent sends AdCP tasks to a seller agent as structured messages, with support for long-running operations via streaming.
## Standards bodies and organizations
| Organization | Focus | Key outputs |
| - | - | - |
| **[AgenticAdvertising.org](https://agenticadvertising.org)** | AI agent advertising standards | AdCP specification, JSON schemas, client SDKs |
| **[IAB Tech Lab](https://iabtechlab.com)** | Digital advertising standards | OpenRTB, VAST, ads.txt, sellers.json, content taxonomy, AAMP |
| **[Anthropic](https://anthropic.com)** | AI safety and research | MCP specification |
| **[Google](https://google.github.io/A2A/)** | AI and cloud | A2A specification |
| **[W3C](https://www.w3.org)** | Web standards | Privacy Sandbox APIs, Topics API |
AgenticAdvertising.org is an independent member organization. It is not a subsidiary or working group of IAB Tech Lab, Anthropic, Google, or any other company. Its members include platform providers, advertisers, agencies, and developers.
## Other standards in the ecosystem
| Standard | Purpose | Maintained by |
| - | - | - |
| **AAMP** | Agentic advertising framework — components include ARTF (Agentic Real Time Framework), Agentic Direct, Agentic Audiences, and the Agent Registry; overlaps AdCP in scope with different primitives (see the [FAQ comparison](/dist/docs/3.2.8/faq#how-adcp-relates-to-other-standards)) | IAB Tech Lab |
| **VAST** / **VPAID** | Video ad serving and interactive video | IAB Tech Lab |
| **ads.txt** / **sellers.json** | Supply chain transparency | IAB Tech Lab |
| **Open Measurement SDK** | Viewability and attention measurement | IAB Tech Lab |
| **Unified ID 2.0** | Privacy-preserving identity | The Trade Desk / Prebid |
| **Privacy Sandbox** | Cookie-less targeting APIs | Google / W3C |
## How the layers fit together
These protocols operate at different layers of the stack:
```
┌──────────────────────────────────────────────┐
│ Strategy layer (AdCP) │
│ Campaign planning, budget allocation, │
│ cross-platform coordination │
├──────────────────────────────────────────────┤
│ Transport layer (MCP / A2A) │
│ How agents call tools and exchange data │
├──────────────────────────────────────────────┤
│ Execution layer (OpenRTB / platform APIs) │
│ Impression-level auctions, ad serving, │
│ creative rendering │
├──────────────────────────────────────────────┤
│ Measurement layer (OMSDK / UID2 / Privacy) │
│ Viewability, attribution, identity │
└──────────────────────────────────────────────┘
```
A typical workflow: an AI agent uses **MCP** to call **AdCP** tasks on a publisher's platform, creating a campaign. The publisher's ad server uses **OpenRTB** to execute impression-level delivery. **OMSDK** measures viewability. **ads.txt** verifies the supply chain.
## What's changing
Three trends are reshaping how these standards interact:
**Agent-mediated buying.** Instead of humans navigating dashboards, AI agents will manage campaigns across platforms. This creates demand for standardized agent interfaces — which is what AdCP provides.
**Protocol convergence.** MCP and A2A are establishing the transport layer for agent communication. Domain-specific protocols like AdCP build on top of them. This mirrors how HTTP became the transport layer and domain-specific APIs built on top.
**Vertical specialization.** Generic agent protocols (MCP, A2A) handle communication. Vertical protocols handle domain logic. AdCP handles advertising. The same transport-plus-domain pattern may emerge in other verticals as agent adoption grows.
## Getting involved
> [card] [Introduction to AdCP](/dist/docs/3.2.8/intro)
>
> Understand the protocol architecture and core concepts.
> [card] [Join AgenticAdvertising.org](https://agenticadvertising.org/membership)
>
> Participate in working groups that shape protocol direction.
> [card] [AdCP and OpenRTB](/dist/docs/3.2.8/building/concepts/adcp-vs-openrtb)
>
> Detailed comparison of AdCP and OpenRTB — how they complement each other.
> [card] [Protocol comparison](/dist/docs/3.2.8/building/concepts/protocol-comparison)
>
> Technical comparison of MCP and A2A as AdCP transport layers.
# Managing Response Size
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/concepts/managing-response-size
How to keep AdCP responses lean with proposal planning, product field selection, pagination, feed versioning, and client-side projection.
When a buyer agent calls an AdCP seller, the response can range from a few
seller-planned proposals to a wholesale mirror containing detailed product,
signal, and placement metadata. This page covers the controls that keep those
responses right-sized—and the client-side projection that matters most.
## Interoperability size target
MCP hosts and gateways impose different undocumented response ceilings. For pageable reads and other read-only tasks that offer field projection, AdCP producers SHOULD keep each serialized MCP response at or below **128 KiB (131,072 bytes)**. This is an interoperability target, not permission for a client to allocate without bounds: clients SHOULD still enforce the streamed 1 MiB whole-message cap described in [MCP response extraction](/dist/docs/3.2.8/building/by-layer/L0/mcp-response-extraction#size-limits).
For those read paths, use the task's cursor, reduce the requested fields or breakdowns, or return a smaller schema-valid page with continuation metadata before the response exceeds 128 KiB. Do not invent a partial response for a task whose schema does not define one.
Do not apply the 128 KiB target by turning a completed mutation into an error. If a producer can determine before execution that it cannot return the mutation's required result within a host limit, it MUST reject the request before side effects. Once side effects occur, it MUST return the schema-valid committed result or a task-defined asynchronous handoff; it must not report failure merely to satisfy the size target.
`tools/list` is cursor-pageable at the MCP layer even though it is not an AdCP task. Servers SHOULD paginate the live tool catalog so each page remains under the same 128 KiB target. Clients that need the complete catalog MUST follow `nextCursor` until it is absent. Capability-selected tool registration and concise `x-tool-summary` descriptions reduce each page further; do not publish the full AdCP catalog, response schemas, or long reference prose in a session's `tools/list` result.
## Wire response ≠ model context
The single most important point: **the bytes on the wire are not what your model has to consume.**
AdCP responses are structured data. An MCP response arrives as `structuredContent` — typed JSON that the client parses before any model sees it. An A2A response pairs a human-readable `TextPart` with an authoritative `DataPart`. In both cases, a well-built client stores the full response and projects or summarizes it before prompting the next model turn.
```
Seller agent → structured response (full data)
↓
Client stores raw response
↓
Client projects / summarizes → model context (lean)
```
If your agent is forwarding raw tool results into the model context unchanged, the fix is in the client, not the protocol. Store the response, extract what the model needs for its next decision, and reference the stored data by ID when details are needed later.
> [!WARNING]
>
> **Naive-host caveat.** Some MCP hosts pass the entire `structuredContent` blob into the model context as-is. If you control the host, project before prompting. If you don't, the controls below become your primary defense against oversized context.
## Ask for a plan when you want curation
Use `request_proposals` when the seller should turn a campaign brief into a
small set of actionable plans:
```json theme={null}
{
"adcp_version": "3.2",
"idempotency_key": "550e8400-e29b-41d4-a716-446655442001",
"account": { "account_id": "account_123" },
"brand": { "domain": "acme-outdoor.example" },
"brief": "Build a concise premium-video plan for Acme Outdoor's Q4 launch. Prioritize completed views.",
"criteria": {
"offer_filters": { "channels": ["olv"] },
"targeting_overlay": { "geo_countries": ["US"] }
}
}
```
The seller returns immutable draft proposals rather than a catalog page. Use
typed `refine_proposals` requests to narrow the plan without retransmitting the
full source response.
Use `list_products` instead when the buyer wants published offers or maintains
a wholesale mirror. A mirror is a feed-synchronization topology, not a cheaper
proposal mode.
## `fields` selector for lightweight discovery
When you only need a subset of published product data, pass `fields` to
`list_products`:
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "account_123" },
"criteria": {
"offer_filters": { "channels": ["olv"] }
},
"fields": ["product_id", "name", "pricing_options"],
"max_results": 10
}
```
This is useful when:
* Your agent is scanning multiple sellers and only needs IDs and prices for initial comparison
* You want to skip heavy fields like `product_card`, `product_card_detailed`, `placements`, or signal metadata
* You're building a summary view before drilling into specific products
Without `fields`, the seller returns the full product object — including visual card definitions, placement specs, and any bundled signal metadata. For a first-pass discovery across multiple sellers, that's more data than you need.
## Pagination for cardinality control
`list_products` uses cursor-based pagination:
| Parameter | Description |
| - | - |
| `max_results` | Maximum products per page |
| `cursor` | Opaque cursor from the previous response |
Response:
| Field | Description |
| - | - |
| `next_cursor` | Cursor for the next page; omitted on the terminal page |
| `feed_version` | Opaque version of the selected offer feed |
| `pricing_version` | Optional separately versioned pricing layer |
| `cache_scope` | Whether versions describe the public or account layer |
Pass `next_cursor` into the next `list_products` request. A mirror stores
`feed_version` with its `cache_scope` and uses account-level product webhooks
for routine changes. Conditional reads with `if_feed_version` repair gaps or
confirm that a selected feed is unchanged; they do not replace a healthy
webhook stream.
## Truncation flags on delivery
[`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) returns breakdown arrays (by geo, by creative, by day, etc.) that can grow large. Each breakdown array has a sibling boolean flag — `by_geo_truncated`, `by_creative_truncated`, etc. — that tells you whether the returned rows are the complete set or just the top-N:
| Flag value | Meaning |
| - | - |
| `false` | All rows are present |
| `true` | Additional rows exist beyond what was returned |
When a flag is `true`, the returned rows are ordered by the applied sort metric in the applied direction (descending by default — the most significant breakdowns; `sort_direction: "asc"` deliberately returns the least significant, e.g. worst performers) and the tail is omitted. The response echoes the applied sort per breakdown (`by_X_sorted_by` / `by_X_sort_direction`), so a fallback to spend is visible. This is by design: delivery breakdowns are for optimization decisions, not archival reporting. If you need the full dataset, use the seller's native reporting API.
## Putting it together
A token-efficient AdCP integration follows this pattern:
1. **Use `request_proposals` for seller curation.** Ask for plans instead of downloading a feed and prompting a model to rediscover seller expertise.
2. **Use typed `refine_proposals`.** Carry proposal IDs and changes, not the full prior response, into the next turn.
3. **Store raw responses client-side.** Don't feed full product objects into the model context. Extract what matters, summarize the rest.
4. **Read truncation flags before paginating delivery.** If `by_geo_truncated: false`, you already have everything — no need for follow-up calls.
5. **Treat wholesale as synchronization.** Bootstrap with `list_products`, apply product webhooks, and use versioned reads for repair.
> [card] [Discovery and planning](/dist/docs/3.2.8/media-buy/product-discovery/)
>
> Choose published offers, wholesale mirroring, or seller-planned proposals.
> [card] [list_products reference](/dist/docs/3.2.8/media-buy/task-reference/list_products)
>
> Field selection, cursor pagination, feed versions, and mirror repair.
> [card] [Delivery reporting](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)
>
> Breakdown arrays, truncation flags, and sort semantics.
> [card] [How agents communicate](/dist/docs/3.2.8/building/concepts/how-agents-communicate)
>
> MCP vs A2A transport and how responses are structured.
> [card] [Media products](/dist/docs/3.2.8/media-buy/product-discovery/media-products)
>
> Product structure, `product_card` vs `product_card_detailed`, and rendering.
# Protocol Comparison
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/concepts/protocol-comparison
MCP vs A2A for AdCP: side-by-side comparison of transport formats, async handling, status systems, and when to use each protocol for advertising agent integration.
Both MCP and A2A provide identical AdCP capabilities using the same unified status system. They differ only in transport format and async handling.
## Quick Comparison
| Aspect | MCP | A2A |
| - | - | - |
| **Request Style** | Tool calls | Task messages |
| **Response Style** | Direct JSON | Artifacts |
| **Status System** | Unified status field | Unified status field |
| **Async Handling** | AdCP status payloads over tool calls; optional MCP Tasks wrapper | AdCP status payloads in A2A artifacts; optional SSE streaming |
| **Webhooks** | `push_notification_config` in tool args | Native PushNotificationConfig |
| **Task Management** | AdCP `task_id` via webhooks or AdCP polling (`get_task_status`, legacy `tasks/get`) | AdCP `task_id` via webhooks or AdCP polling |
| **Context** | Authenticated transport session; no AdCP session argument | Native `contextId` |
| **Best For** | Claude, AI assistants | Agent workflows |
## Unified Status System
Both protocols use the same status field with consistent values.
### Status Handling (Both Protocols)
Every response includes a status field that tells you exactly what to do:
```json theme={null}
{
"status": "input-required", // Same values for both protocols
"message": "Need your budget", // Same human explanation
// ... protocol-specific formatting below
}
```
| Status | What It Means | Your Action |
| - | - | - |
| `completed` | Task finished | Process data, show success |
| `input-required` | Need user input | Read message, prompt user, follow up |
| `working` | Processing (\< 120s) | Wait for the open call/stream result; show progress |
| `submitted` | Long-running (hours to days) | Provide webhook or poll less frequently |
| `failed` | Error occurred | Show error, handle gracefully |
| `auth-required` | Need auth | Prompt for credentials |
See [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle) for complete status handling guide.
## Transport Format Differences
Same status and data, different packaging:
### MCP Response Format
```json theme={null}
{
"status": "input-required",
"message": "I need your budget and target audience",
"task_id": "task-123",
"context_id": "ctx-123", // optional compatibility metadata, not MCP session state
"products": [],
"suggestions": ["budget", "audience"]
}
```
### A2A Response Format
```json theme={null}
{
"status": "input-required",
"contextId": "ctx-123",
"artifacts": [{
"artifactId": "artifact-product-discovery-xyz",
"name": "product_discovery",
"parts": [
{
"kind": "text",
"text": "I need your budget and target audience"
},
{
"kind": "data",
"data": {
"products": [],
"suggestions": ["budget", "audience"]
}
}
]
}]
}
```
## Async Operation Differences
Both protocols carry the same AdCP status progression:
`submitted` → `working` → `completed`/`failed`
The progression above is AdCP application state. MCP Tasks and A2A task state are transport mechanics that can deliver an AdCP payload, but they are not a replacement for AdCP task polling or reconciliation.
### MCP Task-Augmented Call (Transport Wrapper)
```javascript theme={null}
// Task-augmented tool call — returns CreateTaskResult immediately
const createResult = await mcp.callTool({
name: "create_media_buy",
arguments: {
buyer_ref: "acme_q1",
packages: [...],
push_notification_config: { // Optional: webhook for session-outliving ops
url: "https://buyer.com/webhooks/adcp/create_media_buy/op_123",
authentication: { schemes: ["HMAC-SHA256"], credentials: "secret" }
}
},
task: { ttl: 86400000 } // Request task-augmented execution
});
// createResult.task = { taskId: "task-456", status: "working", pollInterval: 5000 }
// Client polls via MCP Tasks protocol (outside the LLM loop)
const status = await mcp.getTask({ taskId: "task-456" });
// status = { taskId: "task-456", status: "completed", ... }
// Retrieve the actual CallToolResult, then inspect the AdCP payload inside it
const result = await mcp.getTaskResult({ taskId: "task-456" });
// result = { content: [...], isError: false }
const adcpResponse = result.structuredContent;
if (adcpResponse.status === "submitted") {
// The MCP task delivered the AdCP response; the media-buy workflow is still open.
await adcp.call("get_task_status", {
task_id: adcpResponse.task_id,
include_result: true
});
}
```
### A2A Async Pattern
The AdCP v3 profile returns an AdCP Submitted result inside a completed A2A
Task. The two IDs remain independent:
```json theme={null}
{
"task": {
"id": "a2a-task-456",
"contextId": "ctx-123",
"status": { "state": "TASK_STATE_COMPLETED" },
"artifacts": [{
"artifactId": "adcp-result",
"parts": [{
"data": {
"status": "submitted",
"task_id": "adcp-task-456"
}
}]
}]
}
}
```
Poll the durable operation with a fresh activated `{ skill:
"get_task_status", input: { task_id: "adcp-task-456" } }` invocation. Do not
poll `a2a-task-456`. For transport progress while a handler is executing, use
the official A2A `SendStreamingMessage` or `SubscribeToTask` operations and
consume their `StreamResponse` SSE frames. Durable AdCP webhooks are registered
as `push_notification_config` inside the typed task input; A2A
`configuration.taskPushNotificationConfig` tracks only the transport Task.
## Context Management
### MCP: Transport Session Context
```javascript theme={null}
async function callAdcp(request) {
// Reuse the authenticated MCP connection when the host offers continuity.
// Do not add a request-body context_id.
return mcp.call('get_products', request);
}
```
Where the selected request schema admits `context_id` for 3.x compatibility,
MCP servers ignore it.
It cannot select session state, identity, account, authorization, task
continuation, or idempotency scope.
### A2A: Message Context
```javascript theme={null}
// The server assigns contextId on the first typed invocation.
const response1 = await a2a.send({
message: {
messageId: crypto.randomUUID(),
role: "ROLE_USER",
parts: [{ data: {
skill: "get_products",
input: { buying_mode: "brief", brief: "Find video products" }
} }]
}
});
// The next Message explicitly carries the returned contextId.
const response2 = await a2a.send({
message: {
messageId: crypto.randomUUID(),
contextId: response1.contextId,
role: "ROLE_USER",
parts: [{ data: {
skill: "get_products",
input: { buying_mode: "brief", brief: "Focus on premium video inventory" }
} }]
}
});
```
## Clarification Handling
Both protocols use the same `status: "input-required"` pattern:
```javascript theme={null}
// Works for both MCP and A2A
function handleResponse(response) {
if (response.status === 'input-required') {
const info = promptUser(response.message);
const continuation = verifiedContinuationFor(response);
if (!continuation) return requireReconciliation(response);
return resumeContinuation(continuation, info);
}
if (response.status === 'completed') {
return processResults(response);
}
}
```
## Error Handling
Both use `status: "failed"` with same error structure:
```json theme={null}
{
"status": "failed",
"message": "Insufficient inventory for your targeting criteria",
"context_id": "ctx-123",
"error_code": "insufficient_inventory",
"suggestions": ["Expand targeting", "Increase CPM"]
}
```
## Choosing a Protocol
### Choose MCP if you're using:
* Claude Desktop or Claude Code
* MCP-compatible AI assistants
* Simple tool-based integrations
* Direct JSON responses
### Choose A2A if you're using:
* Google AI agents or Agent Engine
* Multi-modal workflows (text + files)
* Real-time streaming updates
* Artifact-based data handling
### Both protocols provide:
* Same AdCP tasks and capabilities
* Unified status system for clear client logic
* Transport-native conversation handling
* Async operation support
* Human-in-the-loop workflows
* Error handling and recovery
## Next Steps
* **MCP Guide**: See [MCP Guide](/dist/docs/3.2.8/building/by-layer/L0/mcp-guide) for tool calls and transport sessions
* **A2A Guide**: See [A2A Guide](/dist/docs/3.2.8/building/by-layer/L0/a2a-guide) for artifacts and streaming
* **Both protocols**: Provide the same capabilities with unified status handling
# Security Model
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/concepts/security-model
Why agentic advertising raises the stakes for security, the threats AdCP is designed to defend against, and a checklist for security and IT leaders evaluating an AdCP deployment.
For CISOs, security architects, and third-party risk reviewers evaluating an AdCP deployment — on either side of the transaction (brands, agencies, publishers, platforms, data providers). The [implementation reference](/dist/docs/3.2.8/building/by-layer/L1/security) has the normative rules; this page explains the model behind them.
## Why security is foundational, not an add-on
In traditional advertising, a human reviews an insertion order before money moves. In agentic advertising, the agent is the human. It evaluates briefs, negotiates terms, places buys, handles reporting, and decides whether to retry a failed transaction — often without a person in the loop until something already happened.
That shift concentrates risk in three ways:
* **Authority is portable.** A credential that can spend \$10M/year fits in a token. A stolen token with the right scope can create real media buys against real budget, and the buy will look legitimate to every downstream system because it *is* legitimate — from the protocol's point of view.
* **Decisions are fast.** An agent can run a full plan-to-purchase loop in seconds. A compromised loop can burn through a day's budget in minutes. There is no ad ops team watching line items populate.
* **The attacker uses the same tools you do.** AI can red-team an API as fast as it can use one. If your agent has a documented surface (and it should — that's how other agents discover it), an adversary's agent can enumerate it, probe it, and fuzz it at machine speed. Security-by-obscurity is not a control.
These are the conditions AdCP was built to withstand. The rest of this page is how.
A breach surface in agentic ad tech is not "data exposure." It is **unauthorized financial commitments**, **bypassed governance**, **cross-tenant data leakage between advertisers on the same platform**, and **tampering with audit trails that regulators will later ask to see**. Each of those has a named threat model in the implementation reference. This page steps back and explains why.
## What changes in the threat model
**Everything from traditional API security still applies** — authentication, authorization, rate limiting, input validation, transport security, data-at-rest encryption, endpoint hardening, logging. An agent is an HTTP service on the public internet; every control you would apply to a REST API you still apply here. AdCP does not replace that baseline, and this page does not re-teach it.
What agentic advertising *adds* is a second layer of concerns, on top of the traditional ones:
| Traditional API security already covers... | Agentic advertising additionally requires... |
| - | - |
| Authenticating the human user | Authenticating the [agent](/dist/docs/3.2.8/reference/glossary#a) *on behalf of* a brand or agency, and proving that brand authorized this specific spend |
| Preventing data exfiltration | Preventing *unauthorized state changes* — agents retry, loop, and fan out; a single successful injection can execute many times |
| Rate limiting abusive callers | Preventing **replay attacks**: an agent retrying a \$1M media buy on a network timeout must never create two |
| Input validation | **Counterparty URL validation**: agents fetch from URLs other agents supply (webhooks, registries, JWKS, reporting buckets) — each is an [SSRF](/dist/docs/3.2.8/reference/glossary#s) vector into your internal network |
| Audit logging | **Cryptographically signed governance attestation** that survives the transaction and is verifiable by a regulator years later, without trusting either party |
| Single-tenant isolation | **Multi-agent, multi-account isolation on shared infrastructure** — one compromised agent must not see another agent's buys, creatives, or targeting |
None of this is novel cryptography. What's new is the combination — well-understood primitives operating autonomously, at machine speed, across party boundaries — with the controls on the left now backstopping decisions humans used to make.
### Threats specific to agentic advertising
Three attack classes don't appear in a traditional API threat model but belong in this one:
* **Credential reuse across accounts under one agent.** An agency agent typically holds credentials that work across every brand in its authorized-account set. A stolen agent token is therefore a multi-brand breach, not a single-brand one. AdCP's per-`(agent, account)` cache scoping (see [Agent and Account Isolation](/dist/docs/3.2.8/building/by-layer/L1/security#agent-and-account-isolation)) and signed governance tokens (bound to a specific plan and seller) limit *what* can be done with a stolen credential, but don't prevent the theft. Credential hygiene in agentic systems is proportionally more critical than in single-tenant APIs.
* **Shared-governance-agent supply chain.** A governance agent often signs for many brands from a single origin. Its compromise is a multi-tenant breach. The JWKS / revocation-list requirements in the [governance profile](/dist/docs/3.2.8/building/by-layer/L1/security#signed-governance-context) limit the blast radius and make rotation observable, but the buyer's due-diligence posture toward its governance agent is a real-world security dependency — treat the governance agent as a processor with multi-customer blast radius and assess it accordingly.
* **Cross-principal key reuse on multi-tenant operators.** Any operator hosting agents on behalf of more than one principal — a governance agent serving multiple brands, a buyer agent serving multiple advertisers, a sales agent serving multiple publishers — MUST scope signing keys per principal rather than reuse one key across the fleet. Concretely, each `keyid` MUST bind to a single principal so that a single compromised key reduces to a single-principal breach and revocation is granular. A convention such as `{operator}:{principal}:{key_version}` is a useful operator-side bookkeeping aid, but the `kid` value itself is opaque to verifiers per RFC 7517 — verifiers MUST NOT parse `kid` structure to derive principal identity or make authorization decisions, and MUST resolve the owning principal via the authenticated signature → JWKS → agent entry chain, using the `kid` only as an index into the JWKS. Operators that invent a structured convention thus create an internal bookkeeping tool, not an on-wire authorization input. Operators SHOULD advertise the isolation property in their capability surface as `identity.per_principal_key_isolation: true` so counterparties can verify the property without reading out the JWKS by hand.
* **Prompt injection exfiltrating agent-side credentials.** Planners, creative-review agents, brief-interpretation pipelines all process untrusted text (briefs, creative metadata, product descriptions, campaign names) while holding credentials. A successful injection can cause the agent to issue unauthorized tool calls or leak tokens into logs, external URLs, or downstream agent messages. AdCP cannot prevent this at the protocol layer, but every operator running an LLM-powered agent needs input sandboxing, egress controls on tool calls (which URLs / which tools can the agent reach from within a given prompt context), and monitoring for anomalous credential use. The protocol-layer slice that *is* addressable — keeping buyer-principal credentials off the LLM-visible task payload entirely — is the [Credential placement](/dist/docs/3.2.8/building/by-layer/L2/authentication#credential-placement) rule: credentials MUST arrive on the transport's authentication channel and never inside request args. This is the most likely near-term breach vector in the space and is not solved by protocol compliance alone.
* **Cross-principal tool-call confusion.** A buyer agent typically holds active credentials for *multiple* principals at once — several sellers (one set of credentials per seller) and several brand accounts (inside a single agency agent's authority set). LLM-driven agents often expose every one of those tool surfaces to the same planning loop. A prompt injected via text returned from seller X (a product description, a campaign name, a rejection reason) can cause the agent to call a tool on seller Y's endpoint, or to call `create_media_buy` for brand A using a budget authorized for brand B. This is the classical [confused deputy](https://en.wikipedia.org/wiki/Confused_deputy_problem) problem at LLM-tool-call granularity. The protocol-layer defense is in Layer 2 (account scoping on every tool call, refusing any cross-account action the caller does not hold authority for); the operator-layer defense is to tag each inbound string with its principal of origin, refuse tool calls whose target principal differs from the principal that supplied the string unless a human approves, and forbid a single LLM context from holding credentials for principals whose interests can conflict. This threat is distinct from ordinary prompt injection: the attacker does not need to escape the sandbox to use the *victim principal's* credentials — the victim's own agent does it for them.
### Structural privacy separation
AdCP is designed so that parties learn only what they need to act. This is enforced by protocol structure, not just policy. Examples:
* **[Trusted Match Protocol](/dist/docs/3.2.8/trusted-match)** splits impression-time decisions into two independent calls: *Context Match* carries content signals (topic, sentiment, embeddings) with no user identity; *Identity Match* carries an opaque user token with no page context. Neither call alone reveals which user visited which page — the decomposition is the privacy property.
* **Signals Protocol** returns `activation_key` values to authenticated callers with deployment access only, and structurally separates marketplace catalog access (public) from private-signal disclosure (account-scoped).
* **Governance tokens** use `policy_decision_hash` instead of inline `policy_decisions` when the buyer's compliance posture is sensitive — the full decision log remains available to auditors via the signed `audit_log_pointer`, under the governance agent's access control.
* **Audience members** in `sync_audiences` use `hashed_email` and `hashed_phone` fields whose schemas require SHA-256 hashing on the buyer side and structurally reject cleartext. Note that an unsalted SHA-256 of an email or phone is pseudonymous PII, not anonymous — it is recoverable via precomputed dictionaries, so operators MUST treat hashed identifiers as PII for retention and consent. See [Privacy Considerations](/dist/docs/3.2.8/reference/privacy-considerations#unsalted-hashed-identifiers-are-pseudonymous-not-anonymous).
"Structural" here means an attacker who compromises one leg of a split workflow gains no information that was designed to live only in the other leg. It's a weaker guarantee than cryptographic confidentiality but a stronger one than policy alone.
## AdCP's layered defense model
AdCP defends against these threats with five layers. Each one is a separate control; a failure in one does not collapse the others. This is the same defense-in-depth pattern used in payment systems — the five layers below describe *what* every compliant implementation must get right. *How* you build them is yours.
```mermaid theme={null}
flowchart TB
A[Request arrives] --> B["Layer 1: Identity
mTLS / signed requests / API key"]
B --> C["Layer 2: Isolation
Per-agent, per-account scope"]
C --> D["Layer 3: Idempotency
At-most-once execution"]
D --> E["Layer 4: Signed Governance
JWS from governance agent"]
E --> F["Layer 5: Auditability
Replay-proof audit trail"]
F --> G[Execute side effects]
style B fill:#e0f2fe,stroke:#0369a1
style C fill:#e0f2fe,stroke:#0369a1
style D fill:#e0f2fe,stroke:#0369a1
style E fill:#e0f2fe,stroke:#0369a1
style F fill:#e0f2fe,stroke:#0369a1
```
### Layer 1: Identity — who is actually calling?
Before any other check, the seller must establish *which authenticated agent* is making the request. AdCP defines three mechanisms. The endpoint's advertised security contract, including `request_signing.required_for`, determines which are accepted for which operation:
* **RFC 9421 signed HTTP requests** — the buyer signs each request with a key declared in its public agent registry. *Optional and capability-advertised throughout 3.x. In 3.2, every accepted signature on a request with a body covers `content-digest`. Required for spend-committing operations in 4.0.*
* **mTLS** — the buyer presents a client certificate resolving to a registered domain. *Permitted for any operation.*
* **Bearer tokens** (pre-provisioned API key or JWT) — issued by the seller at onboarding, mapped to the buyer. *Permitted throughout 3.x unless the endpoint lists the operation in `request_signing.required_for`.*
The mechanism matrix lives in [Authentication](/dist/docs/3.2.8/building/by-layer/L2/authentication#authentication-method), and the canonical signing rules and [transport migration timeline](/dist/docs/3.2.8/building/by-layer/L1/security#transport-migration-timeline) live in the implementation security reference. The capability-gated posture is also logged under [known limitations](/dist/docs/3.2.8/reference/known-limitations#authentication-and-identity).
**What this defends against.** An attacker cannot claim to be Acme by setting an `iss` field or a `caller` header. Identity is bound to something the attacker cannot forge (a private key, a certificate, or a pre-shared secret). Every subsequent layer uses the authenticated agent as its scope — get this wrong and the rest of the stack is decorative.
### Layer 2: Isolation — one agent cannot see another
Every piece of state — media buys, creatives, idempotency cache entries, session IDs, governance tokens — is scoped to the agent that created it and the [account](/dist/docs/3.2.8/reference/glossary#a) that authorized the work. Queries that forget the scope leak data across tenants; AdCP requires sellers to scope every read by the authenticated agent and its authorized accounts, and to return a generic "not found" rather than leak existence across the boundary.
Implementations typically enforce this at the database layer (Postgres row-level security is the canonical pattern) so a bug in one handler cannot punch through the wall.
Within the tenant boundary, not every caller gets the same grant. A seller may issue one agent a full media-buy scope and another agent a narrow read + webhook-attach scope (e.g., the [`attestation_verifier`](/dist/docs/3.2.8/accounts/overview#standard-named-scope-attestation_verifier) scope for AAO Verified compliance engines). Callers discover their own grant via the `authorization` object attached to per-account entries in [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) responses; sellers enforce locally and reject out-of-scope requests with `SCOPE_INSUFFICIENT`, `READ_ONLY_SCOPE`, or `FIELD_NOT_PERMITTED`.
**What this defends against.** Competitive intelligence leaks. An attacker authenticated as Agent A cannot probe Agent B's media buys, creatives, or idempotency keys — not by ID guessing, not by timing side-channels, not by error-message differencing. A legitimately-authenticated agent with a narrow scope cannot escalate into tasks or fields it was not granted.
### Layer 3: Idempotency — at-most-once execution
Every mutating AdCP request carries a required [`idempotency_key`](/dist/docs/3.2.8/reference/glossary#i). The seller stores the first successful response under that key, scoped to the authenticated agent, with a declared replay TTL (minimum 1h, recommended 24h, maximum 7d). A retry with the same key and the same payload returns the cached response and marks it `replayed: true`. A retry with a *different* payload under the same key is rejected with `IDEMPOTENCY_CONFLICT`.
This is the control that makes retries safe. Without it, a network timeout on `create_media_buy` forces the buyer to choose between double-booking (retry) and abandoning a legitimate buy (don't retry). With it, the same bytes always produce the same outcome — exactly once.
**What this defends against.** Double-booking from retries. Replay attacks from a stolen-then-reused request. Duplicate webhooks from agent side effects ("Campaign created!" notifications, downstream tool calls, LLM memory writes). `replayed: true` lets every downstream system know whether a response represents a new event or a cached one.
The full normative rules, including payload canonicalization and the oracle-resistance properties of the error taxonomy, are in [Request Safety](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency).
### Layer 4: Signed governance — cryptographic proof of approval
When a plan is approved for spend, the governance agent issues a signed JWS token — not a shared secret, not an opaque cookie, but a public-key-verifiable attestation bound to:
* **`sub`** — an issuer-generated opaque governed-action binding; the seller cannot derive the buyer's plan ID from it
* **`aud`** — the specific seller allowed to act on it
* **`phase`** — whether this is intent, purchase, modification, or delivery
* **`exp`** — when the authorization expires (15 min for intent, ≤30 days for execution)
* **`jti`** — a unique token ID used for replay dedup
The seller fetches the governance agent's public keys via JWKS, verifies the signature, runs the 15-step verification checklist, and only then treats the request as approved. Auditors and regulators can verify the same token years later using the same public keys — neither buyer nor seller can retroactively forge an approval.
**What this defends against.** Unauthorized spend. A compromised buyer credential alone cannot create a media buy — the attacker also needs a valid, unrevoked governance token signed by the buyer's governance agent, bound to this specific seller, for this specific plan, for this specific operation, within its validity window (±60s clock-skew tolerance on `iat`/`nbf`/`exp`; see the [implementation reference](/dist/docs/3.2.8/building/by-layer/L1/security#signed-governance-context) for exact bounds), whose `jti` has not been seen before.
### Layer 5: Auditability — the trail survives the transaction
Every mutation and webhook event produces structured, correlated records: the signed governance token when applicable, the `idempotency_key` and its `replayed` flag, the request ID chain, and — for governance-controlled events — a revocable audit log pointer. These are *queryable by auditors* via `get_plan_audit_logs`, not private to either buyer or seller.
Key properties:
* **Revocation.** Governance agents publish a signed revocation list at a well-known path. Compromised keys and rescinded plans can be invalidated without trusting the CDN serving the list.
* **Retention.** Revoked public keys remain discoverable for 7+ years so historical tokens remain verifiable after rotation.
* **Approval provenance.** Because the governance attestation is signed and public-key-verifiable, any party holding the artifact can verify it was approved by the holder of the signing key at the stated time. This approaches non-repudiation — but only conditionally. The buyer cannot later claim the plan was *never approved* so long as (a) the signing key was not compromised at time-of-signing (revocation lists bound this — a post-hoc claim of "the key was already stolen when I signed" is falsifiable against the revocation timeline) and (b) the signer retains ordinary custody of its signing key. The seller side is *weaker*: an attestation proves the plan existed, not that it was delivered or acknowledged. For full bilateral non-repudiation, the seller should emit a signed `plan_receipt` binding `{plan_id, received_at, plan_sha256}` as a signed webhook using an `adcp_use: "request-signing"` key — durable seller-side acknowledgement flows through the same at-rest webhook path as every other webhook artifact (see [What gets signed](#what-gets-signed--and-what-doesnt) below). Absent a signed receipt, "never received" remains deniable.
**What this defends against.** After-the-fact tampering. Claim drift between parties in a dispute. Regulatory inquiries that arrive long after the credentials have rotated.
## What gets signed — and what doesn't
AdCP 3.2 has six application-layer signing surfaces — five sharing the JWKS publication pattern, plus TMP's own envelope:
* **Inbound request signing.** Buyers (and sellers acting as buyer-side clients) sign their outbound tool calls with [RFC 9421](/dist/docs/3.2.8/building/by-layer/L1/security#request-signing). Key purpose `adcp_use: "request-signing"`.
* **Outbound webhook signing.** Sellers sign asynchronous [webhook deliveries](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-callbacks) — task completion, status changes, downstream events, and any specialism-scoped durable artifact (brand-rights, AAO Verified compliance, sales-intelligence relay, governance receipts). RFC 9421. Key purpose `adcp_use: "request-signing"`; deprecated `adcp_use: "webhook-signing"` keys remain accepted on the webhook path for backward compatibility.
* **Governance attestation signing.** Governance agents sign the JWS tokens that authorize spend (Layer 4 above). Distinct profile from RFC 9421, with its own key purpose (`adcp_use: "governance-signing"`), JWKS, and revocation list.
* **Designated-task response payload signing.** A closed list of tasks — currently `verify_brand_claim` and its bulk variant `verify_brand_claims` — sign their response *payload* as a [JWS envelope](/dist/docs/3.2.8/building/by-layer/L1/security#request-signing) carried inside the response body. Key purpose `adcp_use: "response-signing"`. The signature is load-bearing for the brand-protocol direction-asymmetric trust model; receivers parse the response body and verify the JWS against the responding agent's published key. This is payload-envelope JWS, not RFC 9421 §2.2.9 transport response signing — the latter is not defined in 3.x for any task, including the designated ones. See [Brand Protocol: trust model](/dist/docs/3.2.8/brand-protocol/tasks/verify_brand_claim#trust-model).
* **Portable credential signing.** Proof formats carried through the shared attestation model sign independently issued credentials. When an AdCP agent publishes the credential verification key through its `agents[].jwks_uri`, that JWK uses the generic `adcp_use: "attestation-signing"` purpose; domain profiles such as rights grants do not coin their own key purpose. The proof format defines its signature input and algorithm, while AdCP binds issuer policy, subject, resolution, and consuming-action evaluation.
* **Trusted Match Protocol envelope.** TMP signs match-time requests with its own Ed25519 envelope, scaled to TMP's per-request budget (sample-verify at \~5%); it shares JWKS publication with the five surfaces above but is its own profile. See [TMP signing model](/dist/docs/3.2.8/trusted-match/specification#signing-model).
**Synchronous AdCP responses are NOT signed at the transport layer.** Outside the designated-task list (`verify_brand_claim` family — payload-envelope JWS, not RFC 9421 transport), buyers MUST NOT rely on response signatures; integrity guarantees for synchronous replies are delivered by TLS within the authenticated session. Artifacts requiring at-rest attestation MUST be delivered via signed webhooks. This applies symmetrically to MCP `tools/call` replies and to A2A non-streaming responses (and their streaming `artifactUpdate` frames); A2A push-notification delivery already rides the signed-webhook path covered by the second surface above.
### Why the split is deliberate
This is two delivery surfaces with one RFC 9421 signing purpose, not a synchronous-response coverage gap.
* **TLS-scoped synchronous + signed-webhook async is the design.** The synchronous reply is consumed inside the authenticated session that carried the request — the buyer holds TLS-bound proof that the seller's authenticated edge answered, with the same edge-termination caveats that govern request-side body integrity at body-modifying CDNs (see [Transport security: edge-termination](/dist/docs/3.2.8/building/by-layer/L1/security#what-this-section-does-not-replace)). A signature on the body would protect against post-edge tampering but does not protect against anything the authenticated TLS session hasn't already established between the parties' authenticated edges. At-rest integrity, by contrast, is what webhooks are for: the artifact survives past the original transport and verifies long after the session has closed, against keys that long-outlive the TCP connection.
* **Webhook-only is a forcing function for sellers.** Making "this artifact needs at-rest integrity" an *explicit modeling decision* — emit a webhook — rather than a free rider on every reply pushes operators toward intentional design. Sellers who would otherwise reach for a generic response-signing primitive "for completeness," without asking *which* artifacts actually warrant attestation, are pushed to make the call up front.
* **Doubling the signing surface is operationally fragile.** Every additional signing purpose or profile is another key declaration in the JWKS, another rotation cycle, another verifier code path, another conformance grader, another revocation entry to monitor. The cost is borne by every adopter for every deployment; the benefit accrues to a narrow set of audit and forwarding flows that have a cleaner path through webhooks. Net negative across the ecosystem.
### Cases that look like response signing but aren't
* **Audit and forensics on tool-call replies.** A buyer that needs to attest "the seller said X at time T" requests the artifact via a webhook-emitting tool path, not via the synchronous reply. The asymmetry forces the right design question: which replies actually need at-rest integrity? In practice, fewer than instinct suggests.
* **Cross-agent forwarding** (sales-intelligence relay, brand-rights handoff, AAO Verified compliance attestations). The durable artifact in each of these flows rides the standard signed-webhook path using `adcp_use: "request-signing"` — there is no per-specialism `adcp_use` value in 3.x, and no general-purpose response-signing primitive (the closed designated-task list above is the only response-payload-signing surface, and these flows aren't on it). The specialism delivers its attestable payload as a signed webhook from its own agent; that's already the answer.
* **Bilateral non-repudiation receipts** (e.g., a seller's signed `plan_receipt` binding `{plan_id, received_at, plan_sha256}`). Where the spec recommends the seller emit such a receipt, it is delivered as a signed webhook using the same `adcp_use: "request-signing"` key purpose — not on the synchronous reply that acknowledged the inbound governance attestation.
### The request-the-webhook pattern
If you genuinely need an attestable artifact from a tool that today returns it synchronously, the spec-supported path is to structure the tool to emit a signed webhook carrying the canonical version, and treat the synchronous reply as transport-only acknowledgement. The buyer registers a webhook on the request; the seller delivers the durable artifact via that webhook with `adcp_use: "request-signing"` (deprecated `webhook-signing` keys are still accepted during the compatibility window). Verification is uniform with every other at-rest seller-to-buyer message, no new specialism, no new grader.
Some 3.x tools that today return durable artifacts synchronously (e.g., `acquire_rights` returning `rights_constraint` and `generation_credentials` on the synchronous reply, or any tool whose seller-side receipt is currently delivered inline) are candidates to either restructure under this pattern or accept that their durable-integrity path is the webhook variant — not a future synchronous-response signature.
This decision is the resolution of [#3737](https://github.com/adcontextprotocol/adcp/issues/3737); revisitable in 4.0 if the threat model evolves (e.g., a transport pattern emerges where a synchronous reply carries durable state that does not also flow through a webhook).
## What to verify before going live
If you are approving an AdCP deployment — as a brand CISO, a security architect at a publisher, or the IT lead at an agency — these are the questions to ask your team (or your vendor). Each maps to one of the layers above.
### Identity
* [ ] How is the calling agent authenticated? (RFC 9421 signed requests, mTLS, or Bearer/API key — not a header field, not `iss`. For mutating / financial operations, plan the migration off Bearer before the 3.1 sunset — see [Authentication](/dist/docs/3.2.8/building/by-layer/L2/authentication#authentication-method).)
* [ ] Where are tokens stored? (KMS / secret manager — not files, not env vars at rest)
* [ ] Is the rotation cadence right-sized to blast radius and documented? (≤24h is a reasonable default for write-capable tokens; tighter windows are appropriate for tokens that commit spend at scale or cross organizational boundaries.)
* [ ] What is the revocation path, and who can execute it in under an hour?
### Isolation
* [ ] Is agent/account isolation enforced at the database layer (row-level security), not just in application code?
* [ ] Do error messages leak existence across agents or accounts? ("Not found" for both "doesn't exist" and "exists but not yours")
* [ ] Are idempotency keys, session IDs, and governance tokens scoped per authenticated agent, never shared across the tenant boundary?
### Idempotency
* [ ] Is `capabilities.idempotency.replay_ttl_seconds` declared, and does the declared value match the implementation's actual cache retention?
* [ ] Does the implementation reject missing or malformed keys on mutating requests with `INVALID_REQUEST` before touching business logic, while tolerating optional keys on pure reads?
* [ ] Is the idempotency cache shared across instances (so a restart doesn't allow a silent double-execution)?
* [ ] Are successful responses cached? (Errors must not be cached, or the system locks buyers out for their TTL.)
### SSRF discipline
* [ ] Does every outbound fetch to a counterparty URL (webhooks, JWKS, adagents.json, reporting buckets) run the full 6-point check: HTTPS-only, reserved-IP deny list, IP pinning, no redirects, size and timeout caps, suppressed error detail?
* [ ] Is the reserved-IP deny list enumerated from an authoritative source (IANA, cloud-provider documentation) and reviewed each time you add a new cloud provider or region? See the [implementation reference](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-url-validation-ssrf) for the current enumeration.
### Governance verification
* [ ] If this agent accepts `governance_context`, does it run all 15 verification steps or reject?
* [ ] Is the revocation list polled on the declared cadence with a documented fetch-failure safe default?
* [ ] Are JWKS caches bounded above by the revocation polling interval?
### Auditability
* [ ] Is the full governance token persisted verbatim (including the envelope it arrived in) for the retention period?
* [ ] Can an auditor query by `jti`, `plan_id`, or authenticated agent identifier and reconstruct the full chain of custody?
* [ ] Are logs append-only and tamper-evident (e.g., object storage with legal hold, not a mutable table)?
### Operational readiness
* [ ] Is there a runbook for: compromised credential revocation, webhook secret rotation, governance key rotation, incident communication to counterparties?
* [ ] Is there monitoring for: `IDEMPOTENCY_CONFLICT` rate spikes (probing attacks), failed governance verifications (spoofing attempts), SSRF rejections from a single counterparty, unusual cross-agent or cross-account access patterns, 401/403 spikes from a single peer?
* [ ] Has the team tabletopped at least one of: credential theft, governance key compromise, cross-tenant data leak, prompt-injection-driven credential exfiltration?
* [ ] Is there a documented DR/RPO target for the idempotency cache specifically (not just the application database)? The cache is correctness-critical, not just performance-critical.
* [ ] What is the penetration-test cadence, and does the scope include the MCP and A2A surfaces (not only REST)?
### Data handling and subprocessors
* [ ] Is there a documented subprocessor list for the agent's data flow, and does it include the LLM providers the agent uses?
* [ ] Is the DPA with each LLM provider explicit about whether prompts, brand assets, first-party signals, or creative metadata may be retained or used for model training?
* [ ] Is data residency configurable to meet EU / UK / other regional requirements, and is the configuration visible in the agent's capabilities or contract?
* [ ] Is log retention aligned with both forensics needs (90 days minimum for security logs) and privacy obligations (limits on PII retention)? The two can conflict; the runbook should name the decision.
* [ ] If the agent is an LLM-powered planner, is there a sandbox model for tool calls arising from prompts authored from untrusted text (briefs, user chat, creative metadata)? What egress controls limit which URLs / which tools the agent can reach from within a given prompt context?
> [!NOTE]
>
> **On using this checklist.** Internal use or under NDA is fine. Publishing a fully-answered copy externally — especially one with specific "no" answers — gives adversaries a map of which controls a vendor hasn't invested in. Treat a completed checklist as reconnaissance-sensitive.
## Where humans stay in the loop
Security in agentic advertising is not an argument for removing humans — it's an argument for placing them where they have the most leverage and the least latency cost. AdCP's [Embedded Human Judgment](/dist/docs/3.2.8/governance/embedded-human-judgment) principles specify five load-bearing places:
1. **Intent setting** — humans define campaign goals, audiences, and budget envelopes before any agent acts.
2. **Boundary setting** — humans define the policies, constraints, and thresholds the agent must operate within. Plan-level `audience_constraints` and governance policies are machine-enforceable expressions of human judgment.
3. **Exception handling** — when governance returns `conditions` or `denied`, or when a `TERMS_REJECTED` lands, the decision escalates to a human by design.
4. **Override authority** — humans can pause, cancel, or modify an active buy at any time. The protocol's lifecycle tasks (`pause`, `resume`, `cancel`, `update_media_buy`) are explicit about which states accept which interventions.
5. **Audit and accountability** — every spend commitment produces a signed, replay-proof trail a human can inspect after the fact.
A useful reading: the security controls on this page defend the *boundary* the humans set. They do not replace the humans.
## What AdCP does not do in 3.0
Knowing what a protocol doesn't do is part of evaluating it. The canonical, maintained list lives at [**Known Limitations**](/dist/docs/3.2.8/reference/known-limitations) and spans security, privacy, commerce, authentication, governance, and conformance. The security-relevant items it covers include: no end-user authentication, no protocol-level breach-notification SLA or CVD policy, no protocol-level PII transport, no LLM prompt-injection guarantee, no data-residency mechanism at the protocol layer, no OAuth 2.1 normative requirement, no general-purpose synchronous RPC response signing — designated-task payload envelopes (`verify_brand_claim` family) excepted (see [What gets signed](#what-gets-signed--and-what-doesnt) above), no cross-currency buy support, no protocol-level delivery-dispute flow, and no in-protocol payment or settlement.
None of these are hidden. Each is a visible edge of the specification and a candidate for future work.
## Trust anchors and the key-discovery gap
The identity, governance, and pointer-file layers above all rest on the same hidden assumption: that the public keys verifying signatures can be discovered honestly. In 3.0, that discovery path is counterparty-rooted in every case:
* **RFC 9421 buyer keys** — JWKS fetched from the buyer agent's own domain or `.well-known` path.
* **Governance JWS keys** — JWKS fetched from the governance agent's own domain.
* **Agent signing keys** — operator-attested through `brand.json` `agents[].jwks_uri`, with publisher `adagents.json` `authorized_agents[].signing_keys[]` pins for mutating seller authorizations.
* **`adagents.json` authoritative pointers** — fetched from the publisher's own `/.well-known`, with the pointer-swap threat documented in [managed-networks security](/dist/docs/3.2.8/governance/property/managed-networks#security-considerations).
Every one of those steps trusts the counterparty's own infrastructure as the root of trust. TLS does not close this — the certificate is issued to the hostname the attacker has compromised, so it verifies clean. An attacker who controls a counterparty's CDN, DNS, or `/.well-known` path can therefore serve attacker-controlled keys, and every signature made with those keys will verify against them.
What 3.0 actually delivers is **trust-on-first-use with continuity**: verifiers cache the first-seen keys, pin rotations against the prior key set, and alert on unexpected changes. This raises the bar — an attacker must either control the counterparty origin for long enough to look routine, or swap keys at onboarding before the victim has cached anything — but it does not close the gap. It is an honest description of the 3.x posture, not a claimed cryptographic root of trust.
### What raises the bar in 3.x
Implementers SHOULD layer independent attestation sources rather than rely on any single origin. Each control below converts a silent key-swap into a detectable event within a bounded window:
* **Multi-source cross-check.** When a signing key appears in `brand.json`, verify it matches the key used on signed agent responses *and* a DNS-based attestation (a TXT record at the publisher's apex binding the key fingerprint to the domain, rotated in lock-step with the key material). Compromise of the HTTPS origin alone does not also forge DNS; an attacker must break both surfaces simultaneously.
* **Publication-delay / continuity windows.** Treat a never-before-seen key as provisional for a declared period (24–72 h) during which high-value operations continue to be verified against the previously cached key, and alerts fire on the rotation. A legitimate rotation survives this with operator acknowledgement; an attacker-injected key surfaces before any spend moves.
* **Out-of-band key-change signalling.** Publishers, governance agents, and buyer agents SHOULD announce key rotations through channels the counterparty origin cannot forge — vendor status pages, ads.txt cross-references, partner announcement lists, direct operator notification. The protocol does not prescribe the channel; the requirement is that a channel exists and the verifier watches it.
* **Rotation-validity discipline.** Keys past their declared rotation window are an attack surface, not a preference signal. Verifiers SHOULD reject signatures made with a key past its declared validity rather than silently falling back to older cached material, and SHOULD refuse to accept a rotation that sets `not_after` in the past as a legitimate rollover.
These controls do not substitute for a root of trust. They make a key-swap attack detectable and costly rather than silent and cheap — which is the security posture 3.x can honestly deliver.
### What AdCP 4.0 needs: a centralized publisher-key registry
The permanent fix is a centralized registry analogous in spirit to Certificate Transparency for TLS or `sellers.json` for the ad-tech identity layer. The minimal protocol-relevant properties:
1. **Publisher enrollment.** Each publisher, governance agent, and sales-agent domain registers a root verification key under its domain identity. The registry binds `{domain, root_key_fingerprint, enrolled_at}` and attests domain control through a documented challenge (DNS, HTTPS, or equivalent).
2. **Append-only rotation log.** Rotations are appended, not overwritten. The registry publishes a transparency log so a key rotation cannot be backdated, withdrawn, or selectively served to different verifiers.
3. **Public queryability.** Buyers, sellers, and validators query the registry by domain and receive the current root-key set plus the rotation history. The registry is a discovery index, not a signing authority — it never holds private keys and cannot issue signatures on any party's behalf.
4. **Governance-neutral operation.** The registry is operated by an industry body with published governance, documented key-ceremony transparency for the registry's own signing keys, and a succession plan independent of any single vendor.
5. **Backwards-compatible wire format.** Keys in the registry surface through the same JWKS format that verifiers already consume. A 3.x verifier's switch to registry-anchored trust is a configuration change (point JWKS discovery at the registry-index URL), not a new protocol surface.
This is **explicitly not a 3.x requirement.** It is logged as a 4.0 track so implementers who build the in-protocol attestation surfaces today — `brand.json` `agents[].jwks_uri`, publisher `adagents.json` `authorized_agents[].signing_keys[]`, `authoritative_location`, signed governance JWS — can shape their data so a later registry lookup can anchor it without protocol breakage. Specifically, implementers SHOULD keep key declarations at stable single-purpose URIs, SHOULD carry key fingerprints alongside full key material (the registry can only anchor what it can unambiguously identify), and SHOULD NOT conflate signing keys with transport keys.
Until the registry exists, the multi-source controls above are the 3.x normative baseline. They are the difference between "an attacker who compromises one counterparty origin gets silent authority" and "the compromise produces a detectable signal within a bounded window." 3.x promises the second; it does not promise the first.
## What is outside the protocol
AdCP specifies the wire. It does not specify — and cannot substitute for — any of the following:
* **Secret storage.** Use KMS, Vault, Secrets Manager, or equivalent. Protocol compliance does not magically protect a token sitting in a committed `.env` file.
* **Endpoint hardening.** Your agent is a service on the public internet. WAF, rate limiting, DDoS protection, TLS configuration, OS patching, dependency scanning — all on you.
* **Monitoring and incident response.** The protocol emits the signals worth watching (idempotency conflicts, governance failures, SSRF rejections). Detecting and responding to them is your operations team's job.
* **Human controls.** Approval thresholds, spend caps, pause authority — these are policy configurations inside your agent or your governance platform, not the protocol.
* **Physical and personnel security.** The usual controls over who can touch production, who holds break-glass credentials, and who can push to main.
Think of AdCP as specifying the locks on the doors. You still own the building.
## Further reading
* **[Security (implementation reference)](/dist/docs/3.2.8/building/by-layer/L1/security)** — Normative rules for HMAC, idempotency, SSRF, agent/account isolation, and governance verification
* **[Embedded Human Judgment](/dist/docs/3.2.8/governance/embedded-human-judgment)** — The five principles that keep humans in the loop on decisions with real consequences
* **[Trusted Match Protocol](/dist/docs/3.2.8/trusted-match)** — The two-call decomposition (Context Match / Identity Match) that delivers structural privacy separation at serve time
* **[Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks)** — Signature format, replay windows, rotation
* **[Signed Governance Context](/dist/docs/3.2.8/building/by-layer/L1/security#signed-governance-context)** — The 15-step verification checklist
* **[Operating an Agent](/dist/docs/3.2.8/building/operating/operating-an-agent)** — Credential management, monitoring, and incident response as operating concerns
* **[How Agents Communicate](/dist/docs/3.2.8/building/concepts/how-agents-communicate)** — `adagents.json`, `brand.json`, and the discovery trust chain
# Known spec ambiguities
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/cross-cutting/known-ambiguities
Open AdCP spec gaps that affect compliance testing — with workarounds and issue links. Entries are removed as the underlying issues close.
This page enumerates spec gaps that currently affect storyboard conformance. Each entry covers one of three patterns: a spec `MAY` branch where vectors assert one outcome, a response field storyboards assert that the schema does not yet require, or a testing-infrastructure quirk that prevents a vector from probing through the reference SDK.
**Entries persist until the fix ships in a tagged `@adcp/sdk` or spec release** — closing the GitHub issue is not the removal trigger, because an implementer on an SDK version that predates the fix still hits the symptom. Each entry's Workaround names the release gate when relevant. If an entry here doesn't match what you're seeing, check the GitHub issue for the latest state — the fix may have landed in a release you haven't pulled yet.
## How to use this page
If a storyboard fails on a behavior you believe is spec-conformant, search this page for the storyboard name or the assertion text. Each entry describes the gap, the workaround that gets you past the blocker, and the issue that tracks the fix. Entries are removed when the fix ships in a tagged release, not when the issue closes — pair this page with the linked issue and the SDK / spec release notes for the authoritative state.
For the opposite direction — failures that are **not** in this list and do have clean fixes — see the [storyboard troubleshooting guide](/dist/docs/3.2.8/building/operating/storyboard-troubleshooting).
## Current ambiguities
### `check_governance` `conditions` field shape
* **Schema**: `check-governance-response.json` defines `conditions[]` items as `{ field, required_value?, reason }` with `field` and `reason` required. The `status: conditions` status now requires `conditions` with `minItems: 1`.
* **Resolution**: [#2603](https://github.com/adcontextprotocol/adcp/issues/2603). The schema tightening lands in the protocol patch release following this entry's removal.
* **Workaround (until you pull the fix)**: emit `conditions[]` with the canonical `{ field, reason }` shape on every `status: conditions` response. Agents following the prose description already do this; the schema tightening just makes enforcement mechanical.
### PRM required for non-OAuth agents
* **Storyboard**: `universal/security.yaml` phases `oauth_discovery` + `mechanism_required`.
* **Gap**: the RFC 9728 / RFC 8414 probes run for every agent by default. API-key-only sandboxes were standing up fake issuer URLs to "pass" the probes, which is worse than skipping them.
* **Resolution**: [#2606](https://github.com/adcontextprotocol/adcp/issues/2606) and [#5042](https://github.com/adcontextprotocol/adcp/issues/5042) — the storyboard narrative now explicitly directs static-credential-only agents to declare `auth.api_key` or `auth.basic` in the test kit and omit PRM entirely. Optional-phase semantics make `oauth_discovery` failures non-fatal; `mechanism_required` passes via the matching static-credential path.
* **Workaround**: if your agent has no OAuth issuer, do not serve `/.well-known/oauth-protected-resource/...`. Configure your agent to accept the test kit's probe credential as valid. For Bearer agents, the default test kit (`acme-outdoor`) probes with `demo-acme-outdoor-v1`, and your agent must accept that value alongside your production key. For Basic agents, provide a test kit with `auth.basic.username`/`auth.basic.password` or `auth.basic.credentials`. This satisfies either `test_kit.auth.api_key` or `test_kit.auth.basic` and lets the matching static-credential phase run; without it the phase is skipped and `assert_mechanism` fails with `actual: []`. See the [storyboard troubleshooting guide — static-credential agent: assert_mechanism](/dist/docs/3.2.8/building/operating/storyboard-troubleshooting#static-credential-agent-no-auth-mechanism-contributed-assert_mechanism) for the concrete fix.
### Idempotency missing-key probe via SDK
* **Storyboard**: `universal/idempotency.yaml` step `missing_key/create_media_buy_missing_key`.
* **Gap**: the reference `@adcp/sdk` SDK auto-injects `idempotency_key` on mutating tasks, so a vector that tries to probe "missing key rejection" never reaches the agent with a missing key — the runner would inject one before dispatch.
* **Resolution**: [#2607](https://github.com/adcontextprotocol/adcp/issues/2607) — the step declares `omit_idempotency_key: true`, which signals the runner to skip both its own `applyIdempotencyInvariant` and the SDK's auto-inject. The request arrives at your agent without a key, letting the vector probe the rejection path honestly.
* **Workaround**: nothing required — honor the existing spec requirement (reject missing `idempotency_key` on mutating tasks with `INVALID_REQUEST` or `VALIDATION_ERROR`).
### Response schema fields asserted by storyboards
* **Storyboards**: `sales_catalog_driven` (catalog counts), `creative_ad_server` (pricing_options), `media_buy_seller/inventory_list_targeting` (property_list echo), `creative_ad_server` (vendor_cost required).
* **Gap**: historical drift between what storyboard vectors assert and what the response schemas require.
* **Resolution**: [#2604](https://github.com/adcontextprotocol/adcp/issues/2604). Audit complete:
* `sync-catalogs-response.json` now requires `item_count` on catalog entries when `action` is `created`/`updated`/`unchanged`.
* `property_list` / `collection_list` echo: already canonical via `packages[].targeting_overlay`.
* `list-creatives-response.json` `pricing_options`: already canonical (array, `minItems: 1`, items require `pricing_option_id`).
* `report-usage-request.json` `vendor_cost`: already required.
* **Workaround**: emit `item_count` on every non-failed/non-deleted catalog entry. Conformant agents already do this; the schema tightening catches gaps at `response_schema` validation.
### Rights-holder vs advertiser `brand_id` in brand protocol
* **Storyboard**: `specialisms/brand-rights/index.yaml` phases `identity_discovery` + `rights_search`.
* **Gap**: `get_brand_identity.brand_id` identifies the advertiser (e.g., `acme_outdoor`); `get_rights.brand_id` scopes the search to a specific rights-holder brand (e.g., talent like `daan_janssen`). Same field name, different entities — before the #2627 fix the storyboard threaded the advertiser id through to the rights-holder filter, and a conformant agent either returned empty rights (fail) or added a "return all when no match" fallback (masking bugs).
* **Resolution**: [#2627](https://github.com/adcontextprotocol/adcp/issues/2627) — the storyboard now sends `buyer_brand` (advertiser for compatibility filtering) and omits the rights-holder `brand_id` filter so the agent returns its full catalog.
* **Workaround**: treat `get_rights.brand_id` as a rights-holder filter only; populate `buyer_brand` for compatibility filtering against the buyer's `brand.json`.
### Re-cancel error code — `NOT_CANCELLABLE` vs `INVALID_STATE`
* **Storyboards**: `protocols/media-buy/state-machine.yaml > recancel_buy` and `scenarios/invalid_transitions.yaml > double_cancel/second_cancel`.
* **Gap**: `specification.mdx` §128 (MAY `NOT_CANCELLABLE`) and §129 (MUST `INVALID_STATE` on terminal-state updates) both applied to re-cancel of a `canceled` buy. State-machine-first implementations returned `INVALID_STATE` per §129; cancellation-first implementations returned `NOT_CANCELLABLE`. Vectors historically pinned one.
* **Resolution**: [#2617](https://github.com/adcontextprotocol/adcp/issues/2617) / [#2619](https://github.com/adcontextprotocol/adcp/pull/2619) + [#2628](https://github.com/adcontextprotocol/adcp/issues/2628) — §129 now carves out the cancellation case: when the terminal-state update IS a cancellation attempt, agents MUST return `NOT_CANCELLABLE`. Other illegal transitions (pause/resume on canceled) still return `INVALID_STATE`. Both storyboards now assert `NOT_CANCELLABLE` on re-cancel.
* **Workaround**: return `NOT_CANCELLABLE` on `canceled: true` updates to buys already in `canceled`. Return `INVALID_STATE` on pause/resume of terminal-state buys. The cancellation-specific code wins on re-cancel; the generic code wins on everything else.
### Branch-set step grading (`peer_branch_taken`)
* **Storyboards**: any with parallel `optional: true` phases sharing a `contributes_to:` flag.
* **Gap**: a conformant agent picks one branch (for example, immediate success); the other branch's assertion (for example, `status: pending_review`) fails because the agent took the opposite behavior. Runners before the #2629 fix surfaced this as `× (unknown step)` in the summary even though the `any_of` aggregate passed — implementers debugged a branch they weren't on.
* **Resolution**: [#2629](https://github.com/adcontextprotocol/adcp/issues/2629) — runners now grade non-chosen branch steps with skip reason `peer_branch_taken` (distinct from `not_applicable`, which is reserved for protocol/specialism coverage gaps). See `storyboard-schema.yaml` § "Per-step grading in any_of branch patterns" for the authoring rules and `runner-output-contract.yaml > skip_result.reasons.peer_branch_taken` for the canonical `detail` shape.
* **Workaround**: if your runner reports an unexpected branch failure, check whether a peer optional phase contributed the same `contributes_to` flag. If so, you're conformant on the branch you chose — the runner needs the #2629 update.
### SDK request-builder overriding spec-conformant `sample_request`
* **Storyboard**: `sales_catalog_driven` `optimization_loop/provide_feedback`, exposed via the `@adcp/sdk` compliance runner.
* **Gap**: the storyboard's `sample_request` correctly declares `performance_index`, `metric_type`, `feedback_source` per the `provide-performance-feedback-request.json` schema. But `@adcp/sdk`'s internal `request-builder.js` had a hardcoded override for `provide_performance_feedback` that replaced the payload with a non-spec `feedback: { satisfaction, notes }` shape, so conformant agents rejected with `INVALID_REQUEST` and failed the vector.
* **Resolution**: upstream [adcontextprotocol/adcp-client#689](https://github.com/adcontextprotocol/adcp-client/issues/689) + [#2626](https://github.com/adcontextprotocol/adcp/issues/2626) — remove the override and let the storyboard's `sample_request` drive the payload.
* **Workaround**: bump to an `@adcp/sdk` release that includes the adcp-client#689 fix. Until then, the `provide_performance_feedback` vector will fail on any agent that validates its requests against the spec schema.
## When an ambiguity isn't listed
If you're blocked on a behavior you believe the spec leaves ambiguous but it's not on this list, open an issue at [adcontextprotocol/adcp](https://github.com/adcontextprotocol/adcp/issues/new). Include the storyboard, the vector's assertion text, the conformant branch you picked, and why you believe the spec allows it. The fastest resolutions come from issues that cite the specific spec paragraph and the specific vector assertion — that's enough for a maintainer to either point you at an existing fix or confirm the gap and schedule it.
# The AdCP stack
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/cross-cutting/sdk-stack
Layered reference for AdCP implementers. The five layers (L0 wire, L1 signing, L2 auth, L3 protocol semantics, L4 business logic), what each layer contains, what an SDK at each layer should provide, how SDKs absorb version drift, and what 'from scratch' actually signs you up for.
> [!NOTE]
>
> **AdCP spans the transaction/control plane and its own serve-time execution layer.** Planning, deal creation, creative submission, and reporting use AdCP's MCP/A2A task surfaces. Impression-time activation of pre-negotiated packages uses [Trusted Match Protocol](/dist/docs/3.2.8/trusted-match), while auctions and rendering still sit in adjacent protocols such as RTB and VAST. Most AdCP task latency budgets are seconds and often async-by-design; TMP is the AdCP surface built for millisecond serve-time decisions.
The first question when you sit down to build an AdCP agent is **where you want to spend your engineering time**. By the time a buyer's `create_media_buy` reaches your business logic, it has crossed five distinct layers — wire format, signing, auth, protocol semantics, and finally what you actually want to build. The lower you start, the more of the stack you own.
This page lays out those layers, what an SDK provides at each one, and what's left for you to write either way. Use it to pick the entry point that fits your team — whether that's letting an SDK absorb the protocol surface so you can focus on the L4 logic that differentiates your agent, or going lower because you have a specific reason to. The cost decompositions further down ([per-component L3 breakdown](#why-sdks-matter-more-in-adcp-than-in-eg-http), [version-adaptation](#version-adaptation)) are there to make either choice deliberate.
Two notes on framing before the layers:
* **The protocol surface has grown.** AdCP 3.0 added [a substantial L3 floor](/dist/docs/3.2.8/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0) — mandatory idempotency, published lifecycle state machines, the conformance test surface, RFC 9421 signatures as a baseline, expanded error catalog. If you last evaluated SDKs against an earlier version, the line between "what the SDK does" and "what I'd write myself" has moved.
* **AdCP looks like a thin protocol from the outside.** From the inside it has more L3 (state machines, idempotency, async-task contract, error semantics, conformance) than implementers tend to expect on a first read. The decompositions on this page exist so the L3 estimate is visible up front.
Audience: AdCP implementers in any language — whether you're building an agent, authoring an SDK, or evaluating one.
## The five layers
The same five layers exist on both sides of an AdCP conversation — **agent (server)** and **caller (client)**. The work is asymmetric, though: an agent **enforces** the protocol (state machines, idempotency, error semantics, conformance surface, webhook emission), while a caller **consumes** it (reads state, supplies idempotency keys, handles errors, receives webhooks). L0 (wire) and L1 (signing) are mostly symmetric; L2 (auth) and especially L3 (protocol semantics) are where the surface diverges. L4 exists on both sides, but it's a different shape — the agent's L4 is its inventory and decisioning, the caller's L4 is its planning and buying logic.
When this page describes a layer in agent-shaped terms, look for the *Client side* note at the end — it names the (typically smaller) caller-side surface. Most of the per-page cost commentary, the L3 person-month estimates, and the conformance discussion all describe the server side; building a caller is meaningfully lighter at L2–L3 because most of the work is consuming the protocol, not enforcing it.
**Caller-only?** Skim the *Client side* notes on each layer below, then jump to [Server vs client at each layer](#server-vs-client-at-each-layer) for the cost comparison.
```mermaid theme={null}
%%{init: {"flowchart": {"htmlLabels": true, "wrappingWidth": 9999}, "themeVariables": {"fontSize": "14px"}}}%%
flowchart TB
subgraph yours["yours, always"]
L4["L4 — Business logic
Inventory forecasting · pricing · creative review · upstream ad-server calls
(GAM / FreeWheel / Kevel / your decisioning engine)
The agent's competitive surface — what makes your agent yours"]
end
subgraph sdk["what an AdCP SDK provides"]
direction TB
L3["L3 — Protocol semantics
Lifecycle state machines · idempotency · error catalog · transition validation
Async-task contract · webhook emission · conformance surface · response envelope"]
L2["L2 — Auth & registry
Agent identity verification · brand resolution · AAO bridge
Multi-tenant account resolution · principal scoping · sandbox-vs-live routing"]
L1["L1 — Identity & signing
RFC 9421 HTTP message signatures · public-key registries
Signature verification · replay-window enforcement · key rotation"]
L0["L0 — Wire & transport
JSON-over-HTTP framing · MCP message envelopes · A2A SSE streams
JSON schema validation · language-native type generation"]
L3 ~~~ L2
L2 ~~~ L1
L1 ~~~ L0
end
L4 ~~~ L3
```
### L0 — Wire & transport
What it does: takes protocol bytes off the wire and turns them into typed in-memory values. Schema validation catches malformed payloads at the door.
What's in it:
* HTTP routing (or stdio for MCP-over-stdio).
* MCP message framing (`tools/call` envelope, JSON-RPC 2.0).
* A2A SSE event streams.
* JSON schema validation against the spec's `*.json` files (see [Schemas](/dist/docs/3.2.8/building/by-layer/L0/schemas)).
* Type generation: producing language-native types from the spec's schemas, so application code is statically checked.
If you only have L0, you have a parser. The buyer's `create_media_buy` is a typed object on your stack — and you have to do everything else yourself.
*Client side:* same primitives, mirror direction. The client serializes outbound requests against the same schemas and consumes responses through the same type-generation pipeline. L0 is essentially symmetric.
### L1 — Identity & signing
What it does: cryptographically verifies that the request came from who the headers claim it did, and that the body wasn't modified in transit. See [Security model](/dist/docs/3.2.8/building/concepts/security-model) and the [implementation profile](/dist/docs/3.2.8/building/by-layer/L1/security).
What's in it:
* RFC 9421 HTTP message signatures (`Signature-Input`, `Signature` headers).
* Public-key resolution from agent registries (or operator-published JWKS).
* Signature verification against the canonicalized request.
* Replay-window enforcement (`created` / `expires` parameters).
* Key rotation: handling `keyid` changes without dropping in-flight requests.
If you have L0+L1, you know who's calling you. You still don't know *what* they're allowed to do.
*Client side:* signs outbound requests with its own key; verifies webhook callbacks from the agent. Same RFC 9421 + replay-window + key-rotation primitives, just one inbound path (webhooks) instead of every request.
### L2 — Auth & registry
What it does: turns a verified identity into a scoped principal — which buyer, which brand, which advertiser account, which sandbox-vs-live tier. See [Accounts](/dist/docs/3.2.8/accounts/overview) and [Calling an agent](/dist/docs/3.2.8/protocol/calling-an-agent).
What's in it:
* Agent registry lookup (resolving agent metadata from a published [agent card](/dist/docs/3.2.8/protocol/calling-an-agent)).
* Brand resolution: mapping the requesting agent to a buyer brand / advertiser identity via [Brand Protocol](/dist/docs/3.2.8/brand-protocol).
* AAO ([AgenticAdvertising.org](https://agenticadvertising.org)) bridge: resolving an agent's member org, AAO Verified badges, and registry visibility — see [Registering an agent](/dist/docs/3.2.8/registry/registering-an-agent) and [AAO Verified](/dist/docs/3.2.8/building/verification/aao-verified).
* Multi-tenant account resolution: the same wire request maps to different accounts depending on the principal.
* Sandbox-vs-live account flagging — see [Sandbox](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox).
* Permission scoping: which AdCP tools this principal is allowed to call.
If you have L0+L1+L2, you have a verified, scoped principal asking to do something. You still don't know if the *something* is legal in the current state.
*Client side:* a small subset. The client publishes its own identity (agent card, brand domain), looks up the agent it's calling via the registry, and presents its credentials. There's no multi-tenant routing, no principal scoping, no sandbox/live boundary to enforce — the client *is* the principal, and chooses which agent to talk to.
### L3 — Protocol semantics
What it does: enforces what AdCP *means*. The wire shape is well-formed (L0); the caller is authentic (L1) and authorized (L2); now: is the request legal given the current state of the world?
What's in it:
* **Lifecycle state machines** — `MediaBuy` ([reference](/dist/docs/3.2.8/media-buy/media-buys/lifecycle)), `Creative`, `Account`, `SISession`, `CatalogItem`, `Proposal`, `Audience`. Each with legal edges defined by the spec.
* **Transition validation** — enforce the legal edges per resource; emit `NOT_CANCELLABLE` for cancel-attempts against a state that forbids it; `INVALID_STATE` for other illegal moves. The cancellation-specific code takes precedence over the generic one whenever the attempted action is a cancel.
* **Idempotency** — `idempotency_key` required on every mutating tool; same key replays the cached response within TTL; cross-payload reuse fails with `IDEMPOTENCY_CONFLICT` (with no payload echo, per the stolen-key read-oracle threat model). See the [idempotency profile](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency).
* **Error code catalog** — codes with recovery semantics (`transient` / `correctable` / `terminal`). Choosing the right code is part of the spec contract. See [Error handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling).
* **Async-task contract** — tools that don't complete synchronously return a `task_id`; clients poll or receive webhook callbacks; the task's terminal artifact carries the original tool's response shape. See [Task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle).
* **Webhook emission** — state changes notify subscribed buyers, with retry, idempotency, and signature. See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks).
* **Conformance test surface** — `comply_test_controller` (sandbox-only) exposes `seed_*` / `force_*` / `simulate_*` so storyboards can drive state deterministically. See [comply_test_controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) and [Conformance](/dist/docs/3.2.8/building/verification/conformance).
* **Response envelope** — `context`, `task_id`, `status` field, error envelope shape, `adcp_version` echo, capability advertisement.
If you have L0+L1+L2+L3, you have a complete AdCP protocol implementation. You still haven't done any business logic.
*Client side:* the consumer-side mirror, which is much smaller. The client *reads* state machines (handles each terminal status correctly) rather than enforcing transitions. It *supplies* `idempotency_key` on retries rather than maintaining the cache. It *classifies* error codes by recovery semantics (`transient` → retry, `correctable` → fix and resubmit, `terminal` → don't retry) rather than choosing the right one to emit. It *polls or receives* async-task results and webhook callbacks rather than emitting them. There's no `comply_test_controller` surface to expose, and no conformance bar to certify against on the consumer side. The L3 person-month estimate later on this page is server-side; client L3 is weeks of handler glue, not months.
### L4 — Business logic
This is what makes your agent yours.
What's in it:
* Inventory forecasting against your real ad server.
* Pricing logic, deal terms, contract semantics.
* Creative review policy (brand safety, format compliance).
* Upstream calls to GAM / FreeWheel / Kevel / Yahoo / your in-house decisioning engine.
* Optimization, pacing, fraud detection — anything that differentiates your inventory from a competitor's.
This is the layer an AdCP SDK leaves to you, **and only this layer**.
*Client side:* L4 is also yours, just a different shape. The caller's L4 is media planning, budget allocation, target-audience selection, deal evaluation, reporting ingest — whatever your buy-side application does with the agents it calls. See [Calling an agent](/dist/docs/3.2.8/protocol/calling-an-agent) for the spec-side reference. The asymmetry runs through the whole stack: agent L4 differentiates *inventory*, caller L4 differentiates *demand*.
## Server vs client at each layer
The same five layers; very different cost. Use this when sizing the work for a caller-only build vs. an agent build.
| Layer | Agent (server) | Caller (client) |
| - | - | - |
| **L4** | Inventory, pricing, creative review, ad-server integration. What differentiates you as a seller. | Planning, budgeting, agent selection, reporting consumption. What differentiates you as a buyer. |
| **L3** | **Enforces** state machines, idempotency, error semantics, conformance test surface, webhook emission. \~3–4 person-months. | **Consumes** the same. Reads state, supplies idempotency keys, classifies errors, polls/receives async + webhooks. Weeks of handler glue. |
| **L2** | Multi-tenant principal resolution, sandbox/live boundary, brand resolution, permission scoping. | Publishes own identity; looks up the agent it's calling. Much smaller surface. |
| **L1** | Verifies inbound on every request; signs outbound webhooks. | Signs outbound on every request; verifies inbound webhooks. Same crypto, mirrored path. |
| **L0** | Receives + parses + validates against schemas. | Serializes + sends + validates against schemas. Symmetric. |
A from-scratch caller is a weeks-long job across L0–L3 — handler glue, signing, registry lookup, response parsing — not the [3–4 person-month L3 build](#why-sdks-matter-more-in-adcp-than-in-eg-http) the agent side requires. The rest of this page concentrates on the agent side because that's where the cost lives, but the layer model and the SDK coverage matrix apply equally to a caller-only build.
## What an SDK at each layer should provide
Implementer-facing checklist. An SDK that claims coverage of layer L*n* should expose, at minimum, the primitives below. Adopters use this as a self-evaluation tool when picking an SDK; SDK authors use it as a build target.
The checklist describes **server-side coverage** — the agent surface is where the bulk of an SDK's value lives. **Client-side coverage** at each layer is a subset: typed request builders + response parsers (L0), outbound signing + webhook verification (L1), agent-card publication + registry lookup (L2), state-machine *handlers* + idempotency-key generation + error-recovery classification + async-result polling (L3). A full-stack SDK ships both.
### L0 coverage
* Generated language-native types from the published JSON schemas (one type per request/response pair, plus shared resource types).
* A schema validator wired against the bundled schemas — so adopters can validate inbound and outbound payloads without hand-rolling the schema-loading dance.
* Transport adapters for at least one of \{MCP, A2A}; ideally both. These typically wrap upstream protocol SDKs rather than reimplementing them.
* A schema-bundle accessor that finds the right schema files for the active AdCP version without forcing the adopter to hardcode paths.
### L1 coverage
* RFC 9421 message-signature signing for outbound requests.
* RFC 9421 verification for inbound requests, including replay-window enforcement on `created` / `expires` and `keyid`-based key lookup.
* A pluggable signing-provider abstraction: in-process keys for development, KMS / HSM providers for production.
* Test fixtures or a verifier-test harness so adopters can assert their signing wiring is correct without booting a full agent.
### L2 coverage
* An account-store abstraction that resolves an authenticated principal to a scoped account, with hooks for multi-tenant routing.
* Authentication primitives for at least API-key and bearer-token shapes, plus a way to compose them.
* Brand-resolution / agent-registry lookup (or a documented extension point if the SDK doesn't ship it natively).
* The sandbox-vs-live account flag, enforced at the SDK boundary so the conformance-test surface refuses to dispatch on production accounts.
### L3 coverage
* Lifecycle state-machine graphs for all spec-defined resources, with a transition-assertion primitive that emits the spec-correct error code (`NOT_CANCELLABLE` / `INVALID_STATE` / etc.).
* Idempotency cache with cross-payload conflict detection and the no-payload-echo invariant on `IDEMPOTENCY_CONFLICT` envelopes.
* Async-task store + dispatcher: tools opt into async; the SDK returns `task_id`, accepts polling, and emits the terminal artifact.
* Webhook emitter: signed, retried, idempotent.
* The conformance test surface (`comply_test_controller`), wired to drive state deterministically when the resolved account is in sandbox or mock mode (and rejected otherwise).
* Per-resource persistence primitives that handle the spec's echo contracts.
* Server-construction entry point that ties all of the above together with sane defaults.
### L4 coverage
Out of scope for any SDK. The adopter writes this.
## SDK coverage varies
Different language SDKs cover different subsets of L0–L3. There is no single SDK every implementer must use; what matters is that an implementation reaches the [conformance bar](/dist/docs/3.2.8/building/verification/conformance) at L3, regardless of how much hand-rolling it took to get there.
Within a given language, the full-stack SDK is the default starting point. The layered model in this doc exists to explain what you'd be reimplementing if you went lower (special-purpose proxies, custom-stack integrations) or ported the SDK to a new language — not to suggest there's a meaningful win in starting lower for a typical agent build.
### Current SDK coverage
**Python and TypeScript are the first-class languages.** Both are committed to full L0–L4 coverage — TypeScript is GA across L0–L3 today; Python is finishing its 4.x cycle to the same bar. **Go** is moving in the same direction, with L0 and partial L1 in active development. **Other languages** are not on the official roadmap today, but we're open to community-maintained ports — if you want to help, see the [Builders Working Group](/dist/docs/3.2.8/community/working-group) and the [Slack community](/dist/docs/3.2.8/community/joining-slack).
Snapshot of what each official SDK ships today. Refresh this table on SDK majors and on AdCP spec revs.
*Last updated: 2026-05-03.*
| SDK | Production GA | Beta / dev | L0 | L1 | L2 | L3 |
| - | - | - | :-: | :-: | :-: | :-: |
| **`@adcp/sdk`** (TS) | `6.9.0` | — | ✅ | ✅ | ✅ | ✅ |
| **`adcp`** (Python) | `3.x` | `4.x` | ✅ | ⚠️ | ⚠️ | ⚠️ |
| **`adcp-go`** | — | `v1.x` | ⚠️ | ❌ | ❌ | ❌ |
Legend: ✅ shipped · ⚠️ partial / in flight · ❌ not yet covered. **Production GA** is the line you should pin to today. **Beta / dev** is what's in flight on the next major. `@adcp/sdk` 6.x carries full L0–L3 — adopters write L4 only. Python 3.x is the production line with full L0; the 4.x rewrite (in beta) closes L1–L3. Go ships types + transport in dev; L1–L3 in scope. See [Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk) for install commands, package exports, and per-language gap detail.
What "shipped" means at each layer is the L0–L3 checklist above — these rows should not claim ✅ until every checklist item is satisfied in the published SDK build. For coverage detail beyond this snapshot, see each SDK's repo.
For shape comparison purposes, here are the three coverage archetypes an SDK can land in regardless of language:
| Archetype | L0 | L1 | L2 | L3 | Adopter writes |
| - | - | - | - | - | - |
| Full-stack SDK | ✅ | ✅ | ✅ | ✅ | L4 only |
| Transport + signing only | ✅ | ✅ | ⚠️ | ❌ | L2 + L3 + L4 |
| Types-only / generated bindings | ✅ | ❌ | ❌ | ❌ | L1 + L2 + L3 + L4 |
### Hosted implementations
Different shape from an SDK: a **deployable agent** you run rather than a library you import. Adopters configure rather than code. Useful when you want an AdCP surface in front of an existing system without writing handler code yourself.
| Implementation | Maintainer | Stack | Notes |
| - | - | - | - |
| **AdCP mock-server** | spec maintainers | Reference | The black-box AdCP agent storyboards run against. All language SDKs forward mock-mode traffic to it; shared infrastructure for [spec compliance](/dist/docs/3.2.8/building/verification/conformance). |
| **Prebid SalesAgent** | [Prebid community](https://github.com/prebid/salesagent) | Python | Open-source seller-side AdCP agent. Publishers run it as their AdCP-facing implementation; hand-rolled at L0–L3 today, evolving alongside the official SDKs. |
Hosted implementations satisfy the same L3 conformance bar that SDKs do — the spec is implementation-agnostic. The difference is operational shape: a hosted implementation is a service you deploy and configure, an SDK is code you compile into your own service.
The choice is a tradeoff between leverage and control. A full-stack SDK ships you the most code for free but couples you to its choices. A transport-only SDK gives you maximum control but signs you up for months of L1–L3 work before you can certify. Most production adopters want the full stack with the option to swap individual layers (custom signing provider, custom account store, custom idempotency backend) — which a well-architected full-stack SDK exposes as configuration, not as a fork.
## Where can you start?
You can implement at any layer. The lower you start, the more you build.
| Starting layer | What you write | What's done for you |
| - | - | - |
| L0 (from scratch) | All five layers | Nothing |
| L1 (you have a JSON-over-HTTP toolkit) | L1+L2+L3+L4 | L0 (parser, schema validation) |
| L2 (you have HTTP signatures via a library) | L2+L3+L4 | L0+L1 |
| L3 (you have an auth/registry library) | L3+L4 | L0+L1+L2 |
| L4 (you use a full-stack AdCP SDK) | L4 only | L0+L1+L2+L3 |
A full-stack AdCP SDK lifts you to L4. You implement upstream calls. The SDK threads the protocol envelope around them. Pick one if your team's value-add is L4 differentiation; build lower if you have a specific reason — and budget for the L1–L3 scope honestly.
See [Where to start](/dist/docs/3.2.8/building) for a short decision page that picks an entry point based on what you're building.
## Why SDKs matter more in AdCP than in (e.g.) HTTP
A common comparison: *"HTTP is a protocol. People build HTTP servers from scratch all the time. Why would AdCP be different?"*
The answer is layer L3. HTTP's protocol semantics are minimal — methods, status codes, headers. A from-scratch HTTP server can ship in a weekend with an off-the-shelf parser.
AdCP's L3 is large:
* **State machines** — 7 resource types with published lifecycle graphs.
* **Async tasks** — every mutating tool can be sync or async; the contract for which terminal artifact closes the task is non-trivial.
* **Idempotency** — cache, replay, conflict, TTL — all wired correctly.
* **Error catalog** — codes with recovery classification. Picking the wrong one fails [conformance](/dist/docs/3.2.8/building/verification/conformance).
* **Conformance test surface** — storyboards drive your state via the [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) tool. You ship a non-trivial controller surface.
* **Webhook emission** — signed, retried, idempotent.
A from-scratch AdCP agent is **\~3–4 person-months of L3 work alone**, before any L4 differentiation. The breakdown, for one senior engineer to a mock-mode conformance bar, is roughly:
| L3 component | Honest estimate |
| - | - |
| 7 lifecycle state machines (define edges, validate transitions, emit the right `NOT_CANCELLABLE` / `INVALID_STATE` codes) | \~1 week each = **6–7 weeks** |
| Idempotency cache (cross-payload conflict detection + no-payload-echo invariant) | **1 week** |
| Async-task store + dispatcher (correct terminal-artifact contract per tool) | **1–2 weeks** |
| Error-code catalog wiring (recovery classification, code precedence) | **1–2 weeks** |
| `comply_test_controller` conformance surface (`seed_*` / `force_*` / `simulate_*`) | **1–2 weeks** |
| Webhook emission (signed, retried, idempotent, dedup-keyed) | **1 week** |
| RFC 9421 signing + verification + replay-window + key rotation (counted separately as L1, but commonly bundled in the same scope) | **2–3 weeks** |
| Integration, conformance debugging, spec re-reading | **2–3 weeks** |
That's **\~14–18 weeks**, depending on team familiarity with HTTP message-signatures and lifecycle modeling. The estimate **excludes version-adaptation work** — every spec rev that adds a tool, an edge, or an error code adds rows to a translation matrix you carry forever. SDK adopters get those for free; from-scratch implementers pay them every release.
This is a single-engineer-to-mock-conformance estimate. **At publisher / large-platform scale, multiply by \~2× to \~3×** for SRE, security review, KMS / HSM integration with existing key infrastructure, load testing, and on-call burden — none of which is L3 spec work, all of which is real cost before the surface is production-grade.
"From scratch" reads cheap when L0 (the wire shape) is the only layer in view. L3 is where the actual scope hides — the table above is what we'd point a team at before they commit either way.
## Version adaptation
Three "version" axes move at the same time, and an SDK's job is to keep them from colliding inside your business logic:
| Axis | Example | What changes when it moves |
| - | - | - |
| **Spec version** | AdCP `2.5 → 3.0.5 → 3.1` | Wire shapes, error codes, lifecycle states, new tools |
| **SDK version** | SDK `5.x → 6.x` | API surface, ergonomics, compile-time guarantees |
| **Peer version (per call)** | Buyer at v3.0, seller at v2.5 | A single conversation crosses versions; payloads need translation |
A from-scratch agent has to handle all three by hand. SDKs ship three concrete mechanisms so adopters don't:
1. **Per-call spec-version pinning.** Set `adcpVersion` (or the language equivalent) on an agent; the SDK runs requests and responses through adapter modules so handler code stays on the canonical (current) shape regardless of what the peer speaks.
2. **SDK-major migration via co-existence imports.** Bumping an SDK major doesn't force a same-day rewrite — the prior major's surface remains available alongside the new entry point. Migrate one specialism at a time.
3. **Wire-level negotiation.** Every request carries `adcp_major_version`; servers declare what they support and return `VERSION_UNSUPPORTED` (a recovery-classified error) if the caller is out of range.
Code-level recipes per mechanism live in [Version Adaptation](/dist/docs/3.2.8/building/cross-cutting/version-adaptation). For the spec-side rules, see [Versioning](/dist/docs/3.2.8/reference/versioning).
### Why this matters
Versioning in AdCP is **continuous, not episodic**. Once 3.1 ships, you'll be talking to 3.0 and 3.1 callers simultaneously, indefinitely. Without translation adapters this is a fork in your codebase. With them it's a constructor flag.
The spec itself has already done one of these crossings. **2.5 → 3.0** added a substantial L3 floor — see [What changed at L3 in 3.0](/dist/docs/3.2.8/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0) for the canonical list. A from-scratch 2.5 agent was tractable; a from-scratch 3.0 agent is the [\~3–4 person-month L3 build](#why-sdks-matter-more-in-adcp-than-in-eg-http) decomposed above.
The from-scratch path that worked for 2.5 doesn't scale to 3.0, and 3.0 isn't where the spec stops. SDKs exist because L3 grew faster than implementers could hand-roll, and the version-adaptation surface keeps growing each release.
## Where the work actually lives
Five places L3 cost concentrates, in rough order of magnitude. Useful as a self-check whether you're scoping a from-scratch build or re-evaluating a hand-rolled one:
1. **L3 is most of the work.** State machines, idempotency, error catalog, async tasks — \~3–4 person-months before any L4 differentiation. See the [decomposition](#why-sdks-matter-more-in-adcp-than-in-eg-http) for per-component weeks.
2. **Conformance is L3-driven.** Storyboards probe state transitions and error shapes (see [Conformance](/dist/docs/3.2.8/building/verification/conformance)). Without transition validators, the spec gets re-derived from test failures.
3. **Versioning compounds.** Each spec rev that adds a tool, a lifecycle edge, or an error code is a new translation row the adapter layer carries. Owning the adapter layer means owning that matrix every release.
4. **RFC 9421 + key rotation is its own project.** Signing providers, KMS integration, replay windows — real engineering, none of it L4 differentiation.
5. **The mock-server is shared infrastructure.** SDKs wire mock-mode dispatch to it for free. Hand-rolled implementations either skip mock-mode (and lose spec-compliance certification) or rebuild it.
If you built before the SDKs covered much, this list is the input to a re-evaluation — not a verdict either way. The [migration guide](/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled) walks the swap-one-layer-at-a-time path for teams who decide a partial swap is worth it: which layer to swap first, conflict modes to watch for, which intermediate states still pass conformance.
## What this means for compliance
Two kinds of compliance, both shaped by the layered model:
* **Spec compliance (L3 protocol test)** — does the implementation satisfy the AdCP wire contract? Storyboards walk the state machines, exercise the error codes, test the async-task contract. The adopter's upstream is irrelevant. Runs against **mock-mode** accounts: the agent forwards every tool call to the reference mock-server. This certifies the SDK's (or hand-rolled implementation's) L3 layer.
* **Live compliance (full-stack test, planned)** — does the actually deployed agent (adopter's L4 code against their test infra) behave correctly under storyboards end-to-end? Runs against **sandbox-mode** accounts: the adopter's code path is exercised, not the mock. This certifies that L0–L3 plus the adopter's upstream combined produce the right wire behavior.
The reference mock-server is the **spec-compliance oracle** — a black-box AdCP agent that storyboards run against. All language SDKs forward mock-mode traffic to it over HTTP, so the reference path is shared across the ecosystem. The mock-server is SDK-independent: a hand-rolled L0–L3 implementation can pass spec compliance by routing its own mock-flavored accounts to the same mock-server and verifying storyboard pass/fail against its own L3 wire behavior. For the authority chain and triage order when a failure implicates an SDK or the mock itself, see [Mock-server authority and failure triage](/dist/docs/3.2.8/building/verification/conformance#mock-server-authority-and-failure-triage).
## TL;DR
* AdCP has five layers; the spec lives at L0–L3, your agent lives at L4.
* "From scratch" means implementing L0–L3 yourself. That's a lot — see the [per-component breakdown](#why-sdks-matter-more-in-adcp-than-in-eg-http).
* A full-stack AdCP SDK lifts you to L4. You write business logic; the SDK handles the protocol. Different language SDKs cover different subsets of L0–L3; pick one that matches how much of the protocol you want to inherit — see the [coverage matrix](#current-sdk-coverage).
* **Version adaptation is an SDK feature, not an adopter project.** Per-call spec-version adapters, co-existence imports across SDK majors, and on-wire `adcp_major_version` negotiation let you talk to peers on any supported version without forking your handlers. Hand-rolled agents inherit the entire translation matrix forever.
* Compliance comes in two flavors: **spec compliance** (mock-mode, protocol-only, L3 reference test) and **live compliance** (sandbox-mode, full-stack, L0–L4 end-to-end; planned).
* If you last evaluated SDKs before 3.0, the comparison has moved — see [the L3 floor 3.0 added](/dist/docs/3.2.8/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0). Re-evaluate against today's coverage, not the one you remember.
# Version Adaptation
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/cross-cutting/version-adaptation
Three version axes move at the same time when you ship an AdCP agent — spec version, SDK version, and per-peer version. SDKs ship three concrete mechanisms (per-call pinning, co-existence imports, on-wire negotiation) so adopters don't carry the translation matrix in handler code.
Three versions move at the same time when you ship an AdCP agent or client:
| Axis | Example | What changes |
| - | - | - |
| **Spec version** | AdCP `2.5 → 3.0 → 3.1` | Wire shapes, error codes, lifecycle states, new tools |
| **SDK version** | SDK `5.x → 6.x` | API surface, ergonomics, compile-time guarantees |
| **Peer version** (per call) | Buyer at v3.0, seller at v2.5 | A single conversation crosses versions |
Official SDKs ship three concrete mechanisms so adopters don't carry the translation matrix in handler code. This page is the recipe per mechanism. For the conceptual background see the [SDK stack — Version adaptation section](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#version-adaptation). For the spec-side rules see [Versioning](/dist/docs/3.2.8/reference/versioning).
> [!WARNING]
>
> AdCP v2.5 is end of life. The v2.5 examples below describe a temporary migration bridge for existing integrations, not a supported production configuration. New integrations must use v3.
## Mechanism 1 — Pin the spec version per call
Use this when you're a **client** talking to a peer that's pinned to an older (or newer beta) spec version. The SDK runs your request and the peer's response through adapter modules so your handler code stays on the canonical (current) shape.
### Pin the version on a single agent
JavaScript / TypeScript (`@adcp/sdk`):
```ts theme={null}
import { ADCPMultiAgentClient } from '@adcp/sdk';
const client = ADCPMultiAgentClient.simple(
'https://legacy-agent.example.com/mcp/',
{
auth_token: process.env.AGENT_TOKEN,
adcpVersion: 'v2.5', // ← pin here
},
);
const agent = client.agent('default-agent');
const result = await agent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655442052',
buying_mode: 'brief',
brief: 'CTV inventory',
});
```
Python and Go SDKs expose the same mechanism under their idiomatic call sites — see each SDK's repo. The shape is consistent: per-agent or per-call version pin, validated at construction time, with adapter modules translating to/from the canonical shape transparently.
### Validate the version up front
`adcpVersion` (or the language equivalent) is validated at construction time. The SDK only accepts versions whose **schema bundle ships with the build** — if the bundle isn't present (e.g., you pinned a beta channel that hasn't been synced into your installed SDK), construction throws a typed configuration error with a pointer to the schema-sync tooling.
To see what your installed SDK actually has bundled, query the SDK's compatibility-list export — every official SDK exposes one. For the spec-side authoritative list of what each AdCP version means on the wire, see [`schemas/`](https://github.com/adcontextprotocol/adcp/tree/main/dist/schemas).
### What the adapters actually do
Each SDK ships per-tool adapter modules — pure shape translations (field renames, default population, structural reshaping). The SDK applies them transparently when the version pin is set; your handler sees the current shape regardless of which version the peer speaks.
When AdCP 3.1 ships and you bump the SDK, a new adapter folder appears for the now-legacy 3.0. Your handlers don't move.
### Same-major tool replacements
AdCP 3.2's compact lifecycle replaces the broad `get_products`, `create_media_buy`, and `update_media_buy` facades with narrower tool names. This is not ordinary version-shape adaptation: some current operations need more than one legacy call, and one has no faithful legacy equivalent. The release manifest makes that distinction machine-readable through `legacy_fallback` on each replacement and `superseded_by` on each compatibility facade.
| Current SDK method | Legacy peer tool | Fallback mode | Required behavior |
| - | - | - | - |
| `listProducts` | `get_products` wholesale | `orchestrated` | Translate only the representable criteria subset. A normal compact result requires a real seller-issued feed version and cache scope; exact `product_ids` require paging one stable feed until every ID is found or the feed is exhausted. 3.0 and 2.5 cannot supply the ordinary fenced result. |
| `requestProposals` | `get_products` brief | `orchestrated` | Project genuine proposals only when every canonical commercial term is present. A products-only legacy result becomes the projection-only `products_available` compatibility outcome with an actionable continuation; never fabricate a proposal or digest. |
| `refineProposals` | `get_products` refine or proposal finalize | `orchestrated` | Translate only dimensions the legacy peer represents exactly. Mint and durably map immutable successors; finalize batches require the same all-or-none hold boundary. |
| `declineProposals` | none | `none` | Throw a typed capability error before sending a call; never silently discard terminal feedback |
| `buyProducts` | `create_media_buy` explicit packages | `orchestrated` | Translate product purchases to packages without adding creatives, then materialize the accepted proposal snapshot expected by the current result |
| `acceptProposal` | `create_media_buy` proposal mode | `orchestrated` | Execute a new-buy proposal directly; amendment/cancellation proposals require an SDK-managed compatibility workflow or a typed capability error when the legacy seller cannot preserve it |
| `controlMediaBuy` | `update_media_buy` | `orchestrated` | Map only canonical operational fields and never route creative, flight, package-addition, or billing-term mutations through this adapter |
Client SDKs SHOULD expose the current methods as their primary API and choose the peer path from `media_buy.lifecycle_tools`. A directly advertised current tool always wins. A `direct` fallback may run transparently. An `orchestrated` fallback may run transparently only when the SDK ships a handwritten adapter that preserves the current tool's result completeness, terminal state, atomicity, and idempotency semantics; the manifest classification does not synthesize that state machine. In particular, SDKs adapting a direct 3.x creation MUST retain the accepted commercial snapshot locally when the legacy seller cannot return it, and MUST not pretend a legacy seller supports proposal-based amendments. Each underlying legacy mutation needs its own deterministic replay identity, and retrying the current SDK call must resume rather than restart the sequence. Otherwise the SDK MUST throw a typed `CapabilityUnsupportedError` carrying `requested_tool`, the peer's advertised tools, and `fallback_mode`.
`orchestrated` is conditional, not a promise that every valid compact payload can
be sent to every earlier 3.x peer. Adapters MUST preflight each structured field
and fail before calling the peer when the older version has no exact
representation. They MUST preserve legacy `incomplete[]`, time-budget, and
product-pagination semantics instead of turning a partial result into complete
success. In particular, 2.5 has no wholesale-feed contract, while 3.0 has
wholesale pagination but no seller-issued feed or pricing fence. Released 3.1
can support a normal `listProducts` projection only when the seller returns a
real scope-correct wholesale feed version and all requested criteria map
exactly.
### Products-only brief results
A valid 2.5, 3.0, or 3.1 brief may return useful products and no proposals.
Compact compatibility preserves that result as `products_available`. This is a
projection-only compatibility outcome: native 3.2 sellers do not emit it, and
ordinary `request_proposals` success still contains a genuine proposal.
Its `purchase_continuation` is discriminated:
* `listed_purchase` is available only after the coordinator re-reads the exact
selected products through a real seller-issued, account-scoped feed and
obtains its feed and pricing fences. Those seller values flow unchanged into
`buyProducts`.
* `legacy_create` routes to established explicit-package `create_media_buy`
when no truthful fence exists. It declares
`feed_version_not_atomic` and `pricing_version_not_atomic`. For AdCP 2.5 it
additionally declares `mutation_idempotency_not_guaranteed`; 3.0 and 3.1
declare that loss when the actual peer cannot provide their mutation replay
guarantee. It fails closed unless the caller explicitly accepts every
returned loss before mutation.
Client SDKs expose that second path through an SDK-local
`continueLegacyPurchase` operation using the generated
`CompatibilityPurchaseCoordinatorInput` type. The input carries a coordinator
idempotency key, the opaque token, the bound account, selected product IDs, the
exact accepted loss set, and the proposed source-version `create_media_buy`
payload. It is not an AdCP tool payload. The coordinator validates every
binding, exact consent, expiry, source-version request schema, and token claim
before sending only the legacy create request. Exact retries resume durable
state; crash-ambiguous mutations fail unless they can be reconciled
authoritatively.
The coordinator never promotes products into a feed on the seller's behalf and
never synthesizes `feed_version`, `pricing_version`, a proposal,
`commercial_terms`, or `terms_digest`. A projection token may bind the observed
response to the caller, account, and selected payload, but it is not a
seller-issued atomic fence. The legacy seller still revalidates availability
and price during create. This compatibility outcome and its legacy continuation
are deprecated in 3.2 and removed in AdCP 4.0.
In the reverse direction, a 3.2 seller advertising established
`get_products` and `create_media_buy` facades keeps products returned by a
products-only brief executable through that same legacy create facade. An
established buyer is never required to understand `products_available` or an
SDK-local continuation token.
For every proposal revision and finalization, the adapter MUST retain a durable mapping from the current successor `proposal_id` to the legacy source ID. A later `acceptProposal` sends the mapped legacy ID to `create_media_buy` while returning and retaining the current immutable successor snapshot. The mapping is part of the adapter's replay state: losing it, reusing the source ID as the current ID, or minting a second successor on retry violates the 3.2 contract. A legacy proposal may be projected only when the adapter can source every required purchase price, resolved flight, brand, and other canonical term. Valid legacy proposals may omit those facts; the adapter returns `products_available` or a typed capability error rather than filling the gaps itself.
Simple free-text refinement and product `include`/`omit` operations may map when
their result is a complete successor. Typed budget, CPM, impression, flight,
alternative-count, criteria-replacement, amendment, and cancellation semantics
need exact adapters or a pre-mutation failure. Legacy `more_like_this` maps to
free text only with explicit lossy consent. Legacy proposal `omit` is response
filtering and MUST NOT be interpreted as terminal `declineProposals`; no legacy
decline fallback exists.
Released legacy `get_products` does not provide the compact tasks' required
mutation-idempotency contract. Durable local replay state is necessary but is
not sufficient when a process can crash after the seller commits and before the
adapter records the response. Unless the adapter can authoritatively reconcile
that state, it MUST fail the fallback rather than claim compact exactly-once
behavior.
These tools deliberately retain distinct `operation_family` values. Fallback metadata describes SDK adaptation, not cross-name authorization, idempotency equivalence, task recovery, or webhook identity. A client adapter MUST be authorized for the actual legacy call; a grant for a split tool does not transfer across names. Server SDKs may implement the current lifecycle once and derive the deprecated facades for 3.x callers, but may advertise only behavior the adapter actually preserves.
The complete version and transaction-boundary matrix is in
[`specs/legacy-compact-lifecycle-compatibility.md`](https://github.com/adcontextprotocol/adcp/blob/main/specs/legacy-compact-lifecycle-compatibility.md).
## Mechanism 2 — Migrate SDK majors via co-existence
Use this when you bump your SDK from one major to the next and don't want to rewrite every handler the day you upgrade. Each SDK keeps the prior major's surface available alongside the new entry point.
### Example: `@adcp/sdk` 5.x → 6.x
In v6.0, the v5 entry point was hard-removed from the top-level export. Existing v5 code keeps working by swapping one import path:
```ts theme={null}
// v5 code — change only the import path
import { createAdcpServer } from '@adcp/sdk/server/legacy/v5';
serve(() => createAdcpServer({
name: 'My Agent',
version: '1.0.0',
// …existing v5 handler bag — unchanged
}));
```
Greenfield code in the same project uses the v6 entry point side by side:
```ts theme={null}
import { createAdcpServerFromPlatform } from '@adcp/sdk/server';
const platform = new MyPlatform(); // implements DecisioningPlatform
const server = createAdcpServerFromPlatform(platform, {
name: 'my-agent',
version: '1.0.0',
});
```
Both compile, both run, both pass conformance. You migrate one handler — or one specialism — at a time. The legacy subpath is a documented co-existence path, not a deprecation warning.
Other-language SDKs follow the same pattern: prior-major surfaces remain importable from a versioned subpath alongside the current entry point. Check each SDK's release notes for the specific import paths.
### When to actually migrate
Stay on the legacy surface as long as it keeps compiling and passing [conformance](/dist/docs/3.2.8/building/verification/conformance). Migrate a specialism when you want the new features (compile-time specialism enforcement, capability projection, idempotency / signing / async-task / status-normalization pre-wiring on greenfield code). There's no rush.
## Mechanism 3 — Wire-level negotiation
Use this when you're a **server** and you want to be explicit about which spec versions you accept.
### Declare what you support
`supported_versions` (release-precision strings) and/or `major_versions` go on your agent's capability declaration. Use release-precision strings — `'3.0'`, `'3.1'` — not the legacy aliases (`'v2.5'`, `'v3'`) used for client-side pinning. A 3.x server with no v2.5 handler logic should not declare `'v2.5'` here — its 2.5 callers go through *client-side* adapters at the buyer end, not the server's accepted-version set. If you want to surface your deployment's patch build for incident triage, use the `build_version` capability field — not `supported_versions`.
Example with `@adcp/sdk` (lower-level handler-bag API):
```ts theme={null}
import { createAdcpServer } from '@adcp/sdk/server';
const server = createAdcpServer({
name: 'My Agent',
version: '1.0.0',
capabilities: {
major_versions: [3],
supported_versions: ['3.0', '3.1'],
// …other capability fields
},
// …handlers
});
```
The union of `supported_versions` (parsed to majors) and `major_versions` defines the seller's accepted set on inbound `adcp_major_version` / `adcp_version` claims. See [Versioning — version negotiation](/dist/docs/3.2.8/reference/versioning#version-negotiation) for the spec rules and the bidirectional negotiation flow introduced in 3.1.
### What happens on a mismatch
If a buyer's request carries an `adcp_major_version` (or `adcp_version`) that isn't in the accepted set, the SDK returns a `VERSION_UNSUPPORTED` error envelope. The envelope echoes the seller's `supported_versions` so the buyer can downgrade their pin without an out-of-band lookup. See [VERSION_UNSUPPORTED error data](/dist/docs/3.2.8/reference/versioning#version-unsupported-error-data) for the envelope shape.
### Buyer side: two surfaces
There are two places version mismatch can surface on the client, and they fire in different conditions:
**1. Pre-flight typed exception.** When the client already has the peer's capabilities cached and knows up front that the call won't go through, the SDK throws a typed `VersionUnsupportedError` (or language equivalent) *before* sending the request. Catch it from the call site:
```ts theme={null}
import { VersionUnsupportedError } from '@adcp/sdk';
try {
const result = await agent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655442053',
buying_mode: 'brief',
brief: '…',
});
} catch (err) {
if (err instanceof VersionUnsupportedError) {
// peer doesn't support this call at the pinned version —
// re-pin adcpVersion or switch agents
}
throw err;
}
```
**2. `VERSION_UNSUPPORTED` envelope from the wire.** When the mismatch is only detected on the server side (e.g., the buyer's `adcp_major_version` parses different than the buyer's `adcp_version` string), the response carries a typed `VERSION_UNSUPPORTED` error envelope that echoes the seller's `supported_versions`:
```ts theme={null}
const result = await agent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655442054',
buying_mode: 'brief',
brief: '…',
});
if (!result.success && result.adcpError?.code === 'VERSION_UNSUPPORTED') {
const supported = result.adcpError.details?.supported_versions ?? [];
// pick a version you also support, then re-issue with adcpVersion pinned
}
```
`VERSION_UNSUPPORTED` is recovery-classified `correctable` — clients that handle it programmatically retry against a supported version.
This is the third mechanism rather than a fallback to the first: negotiation tells you *what's possible*; per-call pinning tells the SDK *which one to use*.
## Putting it together
A supported multi-version production setup, with an optional migration-only bridge for an end-of-life v2.5 peer:
1. **Server**: declare `supported_versions: ['3.0', '3.1']` in capabilities. The SDK accepts both on the wire and returns `VERSION_UNSUPPORTED` to anyone outside the set. (Only declare a version your handlers actually satisfy.)
2. **Client (per peer)**: pin `adcpVersion` to a supported release based on what the registry or peer's capabilities advertise. Use `'v2.5'` only as a short-lived migration bridge for an existing end-of-life peer; the client-side adapters translate its wire shape so your application code stays on the current spec.
3. **SDK upgrades**: bump the SDK on your schedule; switch to the new entry point per specialism over time; keep the rest on the legacy import until you're ready.
The combined effect: **one handler codebase, three version axes, no fork.**
## What this saves you from building
A from-scratch agent has to:
* Maintain a translation matrix between every spec version it claims to support, and update it every time a release ships.
* Hand-roll API stability across its own internal refactors.
* Implement the negotiation handshake (`adcp_major_version` parsing, `adcp_version` cross-checks, `VERSION_UNSUPPORTED` envelope shaping with the supported-versions echo).
* Keep its conformance test surface in sync as new versions ship.
Each of these compounds at every spec revision. SDKs absorb them so your team's effort goes into L4 differentiation, not into versioning plumbing.
## What changed at L3 in 3.0
If you're scoping a hand-rolled agent against today's spec, the L3 surface added with AdCP 3.0 is the largest delta from 2.5. Most of what an SDK does at L3 didn't exist as a published primitive before 3.0:
* **Mandatory idempotency** — `idempotency_key` required on every mutating tool, with the `replayed: true` / `IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_EXPIRED` semantics declared on `get_adcp_capabilities`. See [Idempotency on Calling an agent](/dist/docs/3.2.8/protocol/calling-an-agent#idempotency-replay-vs-new-operation).
* **Published lifecycle state machines** — seven resource types (`MediaBuy`, `Creative`, `Account`, `SISession`, `CatalogItem`, `Proposal`, `Audience`) with legal-edge enforcement and the `NOT_CANCELLABLE` / `INVALID_STATE` precedence.
* **Conformance test surface** — [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) (sandbox-only) so storyboards drive state deterministically. Replaces ad-hoc per-seller test endpoints.
* **RFC 9421 signatures as a baseline** — optional in 3.0, mandatory under AAO Verified. Replaces the loose-bearer-token posture of 2.5.
* **Expanded error catalog with recovery classification** — 18 standard error codes with `transient` / `correctable` / `terminal` recovery semantics. Hand-rolled 2.5 agents typically returned unstructured error strings.
* **Async-task contract** — every mutating tool can be sync or async; the contract for which terminal artifact closes the task is specified.
* **Webhook signing** — push notifications signed with the same RFC 9421 profile as outbound requests; replay-window + retry semantics specified.
For the full 3.0 changelog (protocol-wide, not just L3), see [What's new in v3](/dist/docs/3.2.8/reference/whats-new-in-v3). For the migration path, see [Migrate from a hand-rolled agent](/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled).
A from-scratch 2.5 agent was tractable; a from-scratch 3.0 agent is the [3–4 person-month L3 build](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#why-sdks-matter-more-in-adcp-than-in-eg-http) decomposed in the SDK stack reference. SDKs exist because L3 grew faster than implementers could hand-roll.
## See also
* [The AdCP stack](/dist/docs/3.2.8/building/cross-cutting/sdk-stack) — layered architecture reference
* [Where to start](/dist/docs/3.2.8/building) — decision page
* [Versioning](/dist/docs/3.2.8/reference/versioning) — spec-side version rules
* [What's new in v3](/dist/docs/3.2.8/reference/whats-new-in-v3) — protocol-wide 3.0 changelog
* [Migrate from a hand-rolled agent](/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled) — when adopting a stack with mid-flight buyers on different spec versions
# Building with AdCP
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/index
Single decision page for AdCP implementers. Pick the right entry point — caller, agent, or migration — based on what you're building and how much of the protocol you want to inherit.
You're about to write AdCP code. The first decision is **where you want to spend your engineering time** — letting an AdCP SDK handle the protocol surface so you focus on what makes your agent or caller yours, or going lower.
This page picks an entry point. The [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack) is the reasoning.
## The five layers
Every AdCP request crosses five layers between the wire and your business logic. SDKs absorb L0–L3; **L4 is the part you write either way.**
```mermaid theme={null}
%%{init: {"flowchart": {"htmlLabels": true, "wrappingWidth": 9999}, "themeVariables": {"fontSize": "14px"}}}%%
flowchart TB
subgraph yours["yours, always"]
L4["L4 — Business logic
Inventory · pricing · creative review · planning · buying · reporting
What makes your agent or caller yours"]
end
subgraph sdk["what an AdCP SDK provides"]
direction TB
L3["L3 — Protocol semantics
Lifecycle state machines · idempotency · error catalog · async tasks · webhooks · conformance"]
L2["L2 — Auth & registry
Principal resolution · brand resolution · multi-tenant account routing"]
L1["L1 — Identity & signing
RFC 9421 message signatures · JWKS · replay-window · key rotation"]
L0["L0 — Wire & transport
JSON-over-HTTP · MCP envelopes · A2A SSE · schema validation · typed bindings"]
L3 ~~~ L2
L2 ~~~ L1
L1 ~~~ L0
end
L4 ~~~ L3
```
Where you start determines how much of L0–L3 you own. The work is asymmetric across the two sides of an AdCP conversation: an agent **enforces** the protocol (\~3–4 person-months at L0–L3); a caller **consumes** it (weeks of handler glue). The [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack) decomposes each layer and the [server-vs-client comparison](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#server-vs-client-at-each-layer) makes the cost asymmetry concrete.
## Recommended path
For \~95% of adopters: **start at L4 with the full-stack SDK in your language.**
> [card] [Build an agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent)
>
> Server side, with engineering capacity. Point a coding agent at a skill file, get a storyboard-compliant AdCP agent in 2–8 minutes (protocol layer only — see [Operating an agent](/dist/docs/3.2.8/building/operating/operating-an-agent) for the full going-live scope).
> [card] [Build a caller](/dist/docs/3.2.8/building/by-layer/L4/build-a-caller)
>
> Client side. Install the SDK, write the calls, handle async responses and errors, ingest reporting. Weeks-of-handler-glue scope, not months.
> [card] [Run a prebuilt agent](/dist/docs/3.2.8/building/operating/operating-an-agent)
>
> Small team or no engineering capacity. Self-host [Prebid SalesAgent](https://github.com/prebid/salesagent), or partner with a managed platform that runs an AdCP agent on your behalf. Configuration over code.
> [card] [Migrate from hand-rolled](/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled)
>
> Already running an AdCP agent built before the SDKs were mature? Swap one layer at a time, with conflict modes, per-step rollback, and intermediate states that pass conformance.
> [card] [Go lower than L4](/dist/docs/3.2.8/building/cross-cutting/sdk-stack)
>
> Porting an SDK to a new language, building a special-purpose proxy, or integrating into a stack that already owns L0–L2. Read the SDK stack reference for the per-layer contract.
After your first build: run [Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent) to confirm conformance against the storyboards, then enroll for the [AAO Verified](/dist/docs/3.2.8/building/verification/aao-verified) trust mark.
## Two checks before you start
**1. What's your team's value-add?**
* **Inventory, pricing, creative review, decisioning** (agent L4) or **planning, buying, reporting** (caller L4) → start at L4.
* **You're an SDK author / language porter, building a proxy, or integrating into a stack that already owns L0–L2** → go lower. Read the [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack) for what each layer must satisfy.
* **Anything else** → default to L4. See [what you write at each layer](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#where-can-you-start) before going lower.
**2. Do you already have a working agent built before the SDKs were mature?**
If yes: re-evaluate against [today's SDK coverage](/dist/docs/3.2.8/building/cross-cutting/sdk-stack#current-sdk-coverage), not the SDK you remember. The [L3 changelog from 2.5](/dist/docs/3.2.8/building/cross-cutting/version-adaptation#what-changed-at-l3-in-3-0) names the new floor; the [migration guide](/dist/docs/3.2.8/building/by-layer/L4/migrate-from-hand-rolled) walks the swap-one-layer-at-a-time path.
## Cross-cutting concerns
Things every AdCP implementation needs, regardless of starting layer:
* **[Schemas](/dist/docs/3.2.8/building/by-layer/L0/schemas)** — schema bundles, type generation, version pinning, supply-chain verification.
* **[Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk)** — language coverage matrix, install commands, package exports, CLI tools.
* **[Version adaptation](/dist/docs/3.2.8/building/cross-cutting/version-adaptation)** — per-call spec-version pinning, co-existence imports across SDK majors, on-wire `VERSION_UNSUPPORTED` negotiation. Lets you talk to peers on any supported version without forking handler code.
* **[Conformance](/dist/docs/3.2.8/building/verification/conformance)** — the L3 protocol bar every agent must reach. Storyboards probe state transitions, error shapes, and the async-task contract.
* **[AAO Verified](/dist/docs/3.2.8/building/verification/aao-verified)** — the public trust mark. Storyboard pass earns `(Spec)`; observed live traffic earns `(Live)`.
* **[Operating an agent](/dist/docs/3.2.8/building/operating/operating-an-agent)** — runtime concerns once you're past first launch: monitoring, on-call, version drift, multi-tenant scaling.
## Going deeper
* **[Concepts](/dist/docs/3.2.8/building/concepts)** — why AdCP exists, protocol comparison, security model, industry context. Start here if you're new and want context before code.
* **[L0 — Wire & transport](/dist/docs/3.2.8/building/by-layer/L0)** — MCP and A2A integration, schema validation, type generation.
* **[L2 — Auth & registry](/dist/docs/3.2.8/building/by-layer/L2)** — authentication, multi-tenant account state, principal scoping.
* **[L3 — Protocol semantics](/dist/docs/3.2.8/building/by-layer/L3)** — task lifecycle, async operations, webhooks, error handling, conformance test surface.
* **[Talk to Addie](/dist/docs/3.2.8/learning/overview)** — stuck on a concept? Addie is the AdCP teaching agent. She walks the protocol with you in conversation, and runs the certification path when you're ready to make it stick.
## Audience
AdCP implementers in any language — building an agent, building a caller, authoring an SDK, or evaluating one. **Python and TypeScript are the first-class languages** (TypeScript GA on `@adcp/sdk` 6.x; Python GA on `adcp` 3.x with 4.x in beta); **Go** has L0 and partial L1 in active development; community-maintained ports for other languages are welcome — see the [Builders Working Group](/dist/docs/3.2.8/community/working-group).
# Operating an Agent
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/operating/operating-an-agent
What sits behind a protocol-compliant agent — products, activation, hosting, and whether to partner, self-host, or build.
The 2–8 minute [Build an Agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent) path gets you a protocol-compliant agent. This page is what comes after — the business infrastructure behind each tool call, and how to decide who runs it.
The worked example here is a **sales agent**, since that's the most infrastructure-heavy case. Short callouts mark where the operational concerns diverge for signals, creative, and retail-media agents.
## What the SDK already handles
Before listing what's missing, it helps to be explicit about what a storyboard-validated agent already gives you:
* AdCP tool schemas and typed registration
* Request/response shapes that pass compliance
* Error formats and version negotiation
* A starting point with example products you can swap for real ones
Everything below is what sits behind those tool handlers.
## Partner, self-host, or build
There are three paths to a live agent. They differ in how much you own, not whether you own anything at all — in every case you still own products, pricing, and the activation into your ad server.
**Partner with a managed sales agent platform.** The platform runs the agent endpoint, holds state, and exposes admin UIs for your ad ops team to manage products, pricing, and approvals. You connect your ad server; the platform handles the protocol and the operations around it. Fastest to live, least control.
**Self-host a prebuilt agent.** Deploy an existing open-source agent — today this usually means the [Prebid Sales Agent](https://github.com/prebid/salesagent), a community full-stack seller agent with GAM integration — on your own infrastructure, and connect it to your systems. You skip writing the protocol layer and admin UI, but you own hosting, upgrades, database, and the ad-server wiring. Middle ground: more control than partnering, less work than building.
**Build your own.** Use the SDK and skill files to write a custom agent. You get full control over business logic, pricing models, and activation paths, at the cost of owning the code alongside everything else. Right answer when no prebuilt agent fits your stack or pricing model.
The SDKs and storyboards cover protocol compliance across all three paths. Everything in the table below is what's outside that line, regardless of which path you take.
## What you'll still need to build or provision
| Component | What it does | Example approaches |
| - | - | - |
| **Product & pricing management** | Lets ad ops define products, rate cards, packaging, and availability without code changes. The skill files hardcode example products; a real agent needs these dynamic and editable. | A partner platform's product catalog, a prebuilt agent's admin UI (e.g. Prebid Sales Agent), or a custom admin UI backed by a database. |
| **Persistent storage** | Stores products, pricing, media buys, creative assignments, and delivery state across requests. | PostgreSQL, MySQL, or any datastore your team is comfortable operating. |
| **Creative review & policy** | Applies brand-safety, legal, and format checks to creatives before they go live. The protocol carries the creative; your policy decides whether to accept it. | Human review queue, automated policy engine (IAB categories, brand lists), or a hybrid. Often the first thing ad ops teams underestimate. |
| **Trafficking & fulfillment** | Turns a sold media buy into a live campaign in your ad server. This sits entirely outside AdCP and is usually the hardest piece. | *Manual:* email or Slack alerts that prompt ad ops to set up campaigns in GAM. *Semi-automated:* Google Ad Manager API to create line items and assign creatives. *Full automation:* end-to-end pipeline from buy confirmation to live delivery. |
| **Delivery reporting & performance** | Powers `get_media_buy_delivery` and `provide_performance_feedback` with real numbers. The protocol tools exist; the log ingest, aggregation, and attribution pipeline behind them is yours to build. | Ad server reporting API pulls, log-level ingest into a warehouse, or a managed analytics tool feeding the agent. |
| **Order management** | Tracks buy status, approval workflows, creative deadlines, and pacing beyond what the protocol's task lifecycle covers. | Status fields in your database to start; a dashboard as volume grows. |
| **Hosting** | Keeps your agent live at the URL you declare in operator `brand.json` and publisher `adagents.json`. Downtime or URL drift breaks buyer verification. | Cloud VM, container service (Cloud Run, ECS, Fly.io), or a managed hosting platform. |
| **Discovery and authorization records** | Tells buyer agents who operates the endpoint, where its signing keys live, and which publisher authorizes it for which inventory. Protocol support is declared by `get_adcp_capabilities`. | Publish operator `brand.json` and publisher `adagents.json`. See [Seller setup](/dist/docs/3.2.8/brand-protocol/seller-setup) and [Authorized Properties](/dist/docs/3.2.8/governance/property/authorized-properties). |
## Where the protocol ends and your business begins
AdCP defines the shape of the conversation between agents. It does not define:
* **Pricing strategy** — how you price inventory, how rate cards flex, when discounts apply
* **Approval policy** — which campaigns you accept or reject, and on what grounds
* **Billing and invoicing** — no spec-level billing; you reconcile with buyers out-of-band
* **Identity and consent** — user-level identity, consent capture, and data-subject rights are regulated and implementation-specific
* **SLA monitoring** — uptime, latency, and error budgets for your agent endpoint
* **Ad ops workflow** — how your team monitors pacing, makegoods, and escalations
A partner platform makes default choices for most of these; a self-hosted prebuilt agent gives you its defaults to override; a self-built agent makes you make every call.
## Where this differs by agent type
The components table above assumes a sales agent. Other agent types share most of it but have specific additions:
* **Signals agents** — consent and provenance are load-bearing. You need a defensible data lineage (where a segment came from, what consent covers it) and the ability to honor opt-outs. Activation is less about ad-server trafficking and more about delivering segments to platforms that already ingest them.
* **Creative agents** — asset storage, transcoding, and rendering SLAs replace ad-server trafficking. Creative review becomes policy on what you'll render, not what you'll traffic.
* **Retail-media agents** — catalog freshness is the operational constraint; your products change as SKUs change. Activation often runs through retail-specific ad platforms rather than GAM.
## Operating the agent in production
A protocol-compliant agent is not the same as a well-operated agent. That's two different concerns: **ongoing ad-ops health** (the protocol stuff actually doing its job) and **security** (the protocol stuff staying trustworthy when it does). Treat both with the same seriousness you give your ad-server integration.
### Ad-ops health monitoring — what you actually watch
This is the day-to-day job. Most of it is protocol-aware extensions of the monitoring any ad ops team already runs. The point is not "new concepts to learn" — it's "here are the specific protocol signals you need dashboards for." Addie can help you set these up.
| What to watch | Why it matters | Signals to alert on |
| - | - | - |
| **Open task queue depth** | Async tasks (`create_media_buy` proposals, `sync_creatives` approvals, `si_initiate_session`) stack up when approvers fall behind. Deep queues mean buyers are waiting. | Tasks open > SLA (e.g. creative approvals > 4h), oldest task age trending up, queue growing faster than it drains. |
| **Creative approval throughput** | Creatives need to actually get approved or rejected. A queue that silently stops moving looks identical to "everything's fine" — except buys aren't launching. | Approval/rejection rate vs. submission rate, creatives older than expected review window still `pending`, rejection reason distribution. |
| **Lifecycle transitions firing on time** | The seller MUST transition `pending_start` → `active` when the flight date arrives. Missed transitions leave campaigns never-delivered even though they "created" fine. | Buys still in `pending_start` past flight start, buys in `pending_creatives` past creative arrival, `paused` buys that should have auto-resumed. |
| **Webhook delivery health** | Webhooks are how buyers learn about async state changes. Silent delivery failures mean buyers poll instead — or don't, and miss the event entirely. | Failed delivery rate, retry backlog, dead-letter queue size, time from state change to successful push. |
| **Status correctness for non-launchable buys** | Campaigns that *can't* go live (creative rejected, account suspended, policy denial) MUST be reflected in the status — not silently stuck. Governance depends on this. | Buys that are neither delivering nor showing a terminal/blocked status; mismatch between ad-server state and AdCP state. |
| **Delivery reporting freshness and accuracy** | `get_media_buy_delivery` should return current numbers. Stale reporting means buyers optimize on lies. | Last-updated timestamp trailing, spend deltas that don't reconcile with ad-server logs. |
| **Idempotency-cache behavior** | A retried `create_media_buy` must return the cached response, not create a duplicate. Compliance tests this in a sandbox — production drift is its own signal. | `IDEMPOTENCY_CONFLICT` rate (bug in buyer or attacker probing), `IDEMPOTENCY_EXPIRED` for ongoing work (TTL too short), duplicate media buys created in the ad server (cache failure). |
| **Error-code distribution** | A spike in a specific error code from a specific buyer is usually the first signal of a real problem. | Top-N error codes per buyer per hour, new error codes you haven't seen before. |
This is the monitoring a sales agent needs regardless of who wrote the code. A partner platform should expose dashboards for most of this; a self-hosted prebuilt agent requires you to wire them up; a self-built agent puts every row on your team.
### Security monitoring — what compliance covers vs. what stays with you
**Most AdCP security mechanics are enforced by the [compliance suite](/dist/docs/3.2.8/building/verification/validate-your-agent) — you don't need to hand-verify them.** The storyboard runner verifies authentication, idempotency, schema conformance, error handling, and governance behavior against your agent. If the suite passes, the wire-level behavior is correct. You don't need to learn agent/account scoping internals, JWS verification steps, or canonical JSON — the tests do.
What the compliance suite checks (so you don't have to teach it):
| Storyboard | What it verifies |
| - | - |
| `security_baseline` (universal) | Auth is required on protected operations; invalid keys rejected; at least one of API key or OAuth 2.0 is correctly advertised. |
| `idempotency` (universal) | Mutating requests honor `idempotency_key`: replay returns cached, conflict returns `IDEMPOTENCY_CONFLICT`, missing key returns `INVALID_REQUEST`. |
| `schema-validation`, `error-compliance` | Responses match schemas; errors use the standard taxonomy. |
| Protocol + specialism storyboards | Per-protocol behavior (media buy lifecycle, creative workflow, signals activation) is correct end-to-end. |
| Request-signing test vectors | RFC 9421 signed requests validate correctly across 25+ positive and negative cases. |
**What you still own**, regardless of who wrote the code:
| Concern | What you decide and run |
| - | - |
| **Credential storage and rotation** | Store tokens in a KMS/secret manager. Use short-lived tokens (≤24h for write-capable; consider ≤1h for tokens that can commit spend). Never log in full, never commit. The right rotation cadence depends on the blast radius of a leaked token — justify yours, don't copy a number. |
| **Key ceremony and break-glass** | Have a documented process for generating, transporting, and destroying high-value keys (webhook secrets, governance signing keys). Maintain sealed break-glass credentials for incident recovery — and a procedure for using them that leaves an audit trail. |
| **Idempotency replay TTL** | Declare `capabilities.idempotency.replay_ttl_seconds` — floor 1h, recommended 24h, max 7d — and verify the declared value matches actual cache retention. Prebuilt agents expose this as config; self-built bake it in. |
| **Cross-instance and multi-region failover** | The idempotency cache, session store, and webhook dedup state must survive an instance restart and be shared across horizontally scaled instances. In a multi-region deployment, the cache must be consistent enough that a retry routed to region B replays a buy originally processed in region A. Memory-only state breaks at-most-once guarantees on the first pod restart. |
| **Security signal monitoring** | Watch for `IDEMPOTENCY_CONFLICT` spikes (probing), failed governance verifications (spoofing), SSRF rejections from a single counterparty, 401/403 spikes from one peer. Same dashboard as ops monitoring — just different alerts. |
| **Vendor risk on your counterparties** | Your governance agent, your signals providers, your creative vendors all hold credentials or issue signed tokens that affect your campaigns. Assess them the way you assess any processor: disclosure policy, breach notification commitment, compliance attestations, uptime SLA. |
| **Incident response runbook** | Know how to revoke a compromised credential in under an hour, rotate webhook secrets, notify counterparties, publish a `revoked_kids` entry if you issue governance tokens. Tabletop it before you need it. |
If you're **partnering**, ask the vendor: "Do you pass the AdCP compliance suite on every release? Which version? Can I see the latest run?" That single question covers most of the code-controls surface. Also ask whether they hold SOC 2 Type II, ISO 27001, or the equivalent attestation for your industry — and what their breach-notification commitment is. If you're **self-hosting a prebuilt agent**, run the compliance suite yourself against your deployment. If you're **self-building**, the compliance suite is your regression harness.
> [!NOTE]
>
> **For security and IT leaders:** The [Security Model](/dist/docs/3.2.8/building/concepts/security-model) page is written for you — CISOs, security architects, and third-party risk reviewers at brands, agencies, publishers, and platforms alike. It explains the threat landscape and what AdCP defends against by design, and includes a checklist of questions to ask your engineering team (or your vendor) before going live.
## What's next
* **[Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** — The compliance suite referenced above
* **[Security](/dist/docs/3.2.8/building/by-layer/L1/security)** — The normative reference for HMAC, idempotency, SSRF, and governance verification
* **[How Agents Communicate](/dist/docs/3.2.8/building/concepts/how-agents-communicate)** — Discovery via `adagents.json` and `brand.json`
* **[Seller Integration](/dist/docs/3.2.8/building/operating/seller-integration)** — Patterns for connecting an agent to an ad server
* **[Authorized Properties](/dist/docs/3.2.8/governance/property/authorized-properties)** — Who can sell what, and how that's declared
# Orchestrator Design
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/operating/orchestrator-design
AdCP orchestrator design: state machine patterns, persistent operation tracking, async-first architecture, and reconciliation for multi-vendor campaign workflows.
This guide covers best practices for building AdCP orchestrators that handle asynchronous operations, pending states, and human-in-the-loop workflows.
## Core Design Principles
### 1. Asynchronous First
The AdCP protocol is inherently asynchronous. Operations may take seconds, hours, or even days to complete.
**DO:**
* Design all operations as async/await
* Store operation state persistently
* Handle orchestrator restarts gracefully
* Implement proper timeout handling
**DON'T:**
* Assume immediate completion
* Use synchronous blocking calls
* Store state only in memory
* Retry indefinitely without backoff
### 2. Status-Driven Logic
Operations progress through standardized status values:
```python theme={null}
TASK_STATUSES = {
"submitted", # Long-running (hours to days) - provide webhook or poll
"working", # Processing (< 120 seconds) - poll frequently
"input-required", # Need user input/approval - continue conversation
"completed", # Success - process results
"failed", # Error - handle appropriately
"canceled", # User canceled
"auth-required" # Need authentication
}
```
### 3. State Machine Design
Implement proper state machines aligned with AdCP task statuses:
```python theme={null}
class OperationState(Enum):
# Local orchestrator states
REQUESTED = "requested"
CALLING_ADCP = "calling_adcp"
# AdCP task states (match server responses)
SUBMITTED = "submitted"
WORKING = "working"
INPUT_REQUIRED = "input_required"
COMPLETED = "completed"
FAILED = "failed"
CANCELED = "canceled"
# Valid state transitions
VALID_TRANSITIONS = {
"requested": ["calling_adcp"],
"calling_adcp": ["submitted", "working", "input_required", "completed", "failed"],
"submitted": ["working", "completed", "failed", "canceled"],
"working": ["completed", "failed", "input_required"],
"input_required": ["submitted", "working", "completed", "failed"]
}
```
## Operation Tracking
### Persistent Storage
Store all operations with comprehensive tracking:
```python theme={null}
class OperationTracker:
def __init__(self, db):
self.db = db
async def create_operation(self, operation_type, request_data, webhook_config=None):
operation = {
"id": str(uuid.uuid4()),
"type": operation_type,
"status": "requested",
"request": request_data,
"webhook_config": webhook_config,
"created_at": datetime.now(),
"updated_at": datetime.now(),
"task_id": None,
"context_id": None,
"result": None,
"error": None
}
await self.db.operations.insert_one(operation)
return operation["id"]
async def update_status(self, operation_id, status, **kwargs):
update = {
"status": status,
"updated_at": datetime.now()
}
update.update(kwargs)
await self.db.operations.update_one(
{"id": operation_id},
{"$set": update}
)
async def get_pending_operations(self):
"""Get all operations that need monitoring"""
return await self.db.operations.find({
"status": {"$in": ["submitted", "working", "input_required"]}
}).to_list(length=None)
```
### State Reconciliation
Sync local state with server on startup:
```python theme={null}
async def reconcile_with_server(self, adcp_client):
"""Sync local state with server using AdCP task reconciliation"""
server_tasks = await adcp_client.call('list_tasks', {
'filters': {'statuses': ['submitted', 'working', 'input_required']}
})
server_task_ids = {task['task_id'] for task in server_tasks['tasks']}
local_operations = await self.get_pending_operations()
local_task_ids = {op['task_id'] for op in local_operations if op['task_id']}
return {
'orphaned_on_server': server_task_ids - local_task_ids,
'missing_from_server': local_task_ids - server_task_ids,
'total_pending_server': len(server_tasks['tasks']),
'total_pending_local': len(local_operations)
}
```
## Async Operation Handler
### Response Routing
Handle responses based on status:
```python theme={null}
class AsyncOperationHandler:
def __init__(self, adcp_client, tracker, notifier):
self.adcp = adcp_client
self.tracker = tracker
self.notifier = notifier
self.polling_tasks = {}
async def handle_operation_response(self, operation_id, response):
"""Handle any AdCP response with proper status routing"""
status = response.get("status")
# Update operation with response details
await self.tracker.update_status(
operation_id,
status,
task_id=response.get("task_id"),
context_id=response.get("context_id"),
result=response.get("result") if status == "completed" else None,
error=response.get("error") if status == "failed" else None
)
# Route based on status
if status == "completed":
await self._handle_completed(operation_id, response)
elif status == "failed":
await self._handle_failed(operation_id, response)
elif status == "submitted":
await self._handle_submitted(operation_id, response)
elif status == "working":
await self._handle_working(operation_id, response)
elif status == "input_required":
await self._handle_input_required(operation_id, response)
```
### Submitted Operations
Handle long-running operations:
```python theme={null}
async def _handle_submitted(self, operation_id, response):
"""Handle long-running operations"""
task_id = response["task_id"]
# Check if webhook is configured
operation = await self.tracker.get_operation(operation_id)
webhook_config = operation.get("webhook_config")
if webhook_config:
# Webhook will handle completion notification
await self.notifier.notify_submitted_with_webhook(operation_id, task_id)
else:
# Start polling for completion
polling_task = asyncio.create_task(
self._poll_for_completion(operation_id, task_id, interval=60)
)
self.polling_tasks[task_id] = polling_task
```
### Polling with Backoff
Implement efficient polling:
```python theme={null}
async def _poll_for_completion(self, operation_id, task_id, interval=60):
"""Poll task status until completion"""
max_polls = 1440 if interval == 60 else 24 # 24 hours or 2 minutes
poll_count = 0
while poll_count < max_polls:
try:
await asyncio.sleep(interval)
poll_count += 1
task_response = await self.adcp.call('get_task_status', {
'task_id': task_id,
'include_result': True
})
await self.handle_operation_response(operation_id, task_response)
if task_response["status"] in ["completed", "failed", "canceled"]:
break
except Exception as e:
await self.tracker.update_status(
operation_id,
"failed",
error=f"Polling error: {str(e)}"
)
break
self.polling_tasks.pop(task_id, None)
if poll_count >= max_polls:
await self.tracker.update_status(
operation_id,
"failed",
error="Task polling timeout"
)
```
## Webhook Support
### Reliable Webhook Handler
Implement webhooks with reliability patterns:
```python theme={null}
class WebhookHandler:
def __init__(self, tracker, notifier, secret_key):
self.tracker = tracker
self.notifier = notifier
self.secret_key = secret_key
self.processed_events = {}
def verify_webhook_signature(self, payload: bytes, signature: str) -> bool:
"""Verify webhook authenticity"""
expected_signature = hmac.new(
self.secret_key.encode(),
payload,
hashlib.sha256
).hexdigest()
return signature == f"sha256={expected_signature}"
async def is_replay_attack(self, timestamp: str, event_id: str) -> bool:
"""Prevent replay attacks using timestamp and event ID"""
event_time = datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
now = datetime.now()
if now - event_time > timedelta(minutes=5):
return True
return event_id in self.processed_events
```
### Webhook + Polling Backup
Never rely solely on webhooks:
```python theme={null}
class ReliableWebhookOrchestrator:
def __init__(self):
self.webhook_timeout = timedelta(minutes=10)
self.backup_polling_delay = timedelta(minutes=2)
async def _handle_submitted_with_webhook(self, operation_id, task_id):
"""Handle submitted task with webhook + backup polling"""
async def backup_polling():
await asyncio.sleep(self.backup_polling_delay.total_seconds())
operation = await tracker.get_operation(operation_id)
if operation["status"] not in ["completed", "failed", "canceled"]:
logger.info(f"Starting backup polling for task {task_id}")
await self._poll_for_completion(operation_id, task_id, interval=60)
asyncio.create_task(backup_polling())
```
## Example Orchestrator
Complete orchestrator implementation:
```python theme={null}
class AdCPOrchestrator:
def __init__(self):
self.adcp = AdCPClient()
self.tracker = OperationTracker(db)
self.handler = AsyncOperationHandler(self.adcp, self.tracker, UserNotifier())
self.webhook_base_url = "https://orchestrator.com/webhooks"
async def create_campaign(self, user_id, request, enable_webhook=True):
"""Create a campaign with governance validation and full async handling.
Plans must already be synced via sync_plans before calling this method.
Plan creation happens during the planning phase, not at campaign creation time.
"""
# 1. Run intent check (plan must already exist)
if request.get("governance_context"):
gov_check = await self.adcp.call("check_governance", {
"plan_id": request["governance_context"]["plan_id"],
"caller": request["governance_context"]["caller"],
"tool": "create_media_buy",
"payload": request
})
if gov_check["status"] == "denied":
raise GovernanceDeniedError(gov_check["explanation"])
if gov_check["status"] == "conditions":
raise GovernanceConditionsError(gov_check["conditions"])
# If check_governance needs human review internally, it returns
# async task status (submitted/working) and resolves to
# approved or denied — standard task lifecycle.
# 2. Create the media buy
await self._create_media_buy(user_id, request, enable_webhook)
async def _create_media_buy(self, user_id, request, enable_webhook=True):
"""Create a media buy with full async handling."""
# 1. Prepare webhook configuration
webhook_config = None
if enable_webhook:
webhook_config = {
"webhook_url": f"{self.webhook_base_url}/adcp/{user_id}",
"webhook_auth": {
"type": "bearer",
"credentials": await self.get_webhook_token(user_id)
}
}
# 2. Create operation record
operation_id = await self.tracker.create_operation(
"create_media_buy",
request,
webhook_config=webhook_config
)
try:
# 3. Call AdCP
response = await self.adcp.call("create_media_buy", request, webhook_config)
# 4. Handle response
await self.handler.handle_operation_response(operation_id, response)
# 5. Return appropriate response to user
return self._format_user_response(operation_id, response)
except Exception as e:
await self.tracker.update_status(operation_id, "failed", error=str(e))
raise
async def reconcile_state_on_startup(self):
"""Recover from orchestrator restart"""
reconciliation = await self.tracker.reconcile_with_server(self.adcp)
logger.info(f"State reconciliation: {reconciliation}")
for task_id in reconciliation["orphaned_on_server"]:
# Resume monitoring orphaned tasks
operation_id = await self.tracker.create_operation(
"unknown",
{},
status="submitted"
)
await self.tracker.update_status(operation_id, "submitted", task_id=task_id)
asyncio.create_task(
self.handler._poll_for_completion(operation_id, task_id)
)
```
## Governance in the Campaign Lifecycle
Plan creation ([`sync_plans`](/dist/docs/3.2.8/governance/campaign/tasks/sync_plans)) happens during the planning phase — before any campaigns exist. Governance checks happen during campaign execution. These are separate concerns.
**Planning phase** (once per media plan):
```
sync_plans — orchestrator pushes the plan to the governance agent
```
**Campaign execution** (per media buy):
```
check_governance(tool + payload) → create_media_buy → check_governance(media_buy_id + planned_delivery) → delivery → report_plan_outcome
```
| Phase | Who calls | Task | What happens on failure |
| - | - | - | - |
| Intent check | Orchestrator | [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) (`tool` + `payload`) | Campaign violates buyer's plan — denied or conditioned before any spend. If the governance agent needs human review, the task goes async and resolves to approved or denied. |
| Execution check | Seller | [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) (`media_buy_id` + `planned_delivery`) | Seller's delivery plan doesn't match buyer's expectations — purchase blocked |
| Delivery check | Seller | [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) (`phase: delivery` + `delivery_metrics`) | Drift detected — pacing, geo, or channel distribution deviates from plan |
| Plan outcome | Orchestrator | [`report_plan_outcome`](/dist/docs/3.2.8/governance/campaign/tasks/report_plan_outcome) | No feedback loop — governance agent cannot improve future recommendations |
See the [media buy governance workflow](/dist/docs/3.2.8/media-buy/index#governance) for the complete sequence with code examples, and the [seller integration guide](/dist/docs/3.2.8/building/operating/seller-integration#execution-checks) for the seller's execution check obligations.
## Best Practices
### 1. Persistent Storage
Always use persistent storage for operation state:
* Database (PostgreSQL, MongoDB)
* Message queue (Redis, RabbitMQ)
* Distributed cache (Redis Cluster)
### 2. Idempotency
Make all operations idempotent:
```python theme={null}
async def create_media_buy_idempotent(self, request):
existing = await self.db.operations.find_one({
"type": "create_media_buy",
"request.po_number": request["po_number"],
"status": {"$in": ["created", "active"]}
})
if existing:
return existing["result"]
return await self.create_media_buy(request)
```
### 3. Timeout Handling
Implement reasonable timeouts:
```python theme={null}
OPERATION_TIMEOUTS = {
"create_media_buy": timedelta(hours=24),
"update_media_buy": timedelta(hours=12),
"creative_approval": timedelta(hours=48)
}
```
### 4. Error Recovery
Implement retry logic with circuit breakers:
```python theme={null}
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(min=1, max=60),
retry=retry_if_exception_type(TransientError)
)
async def call_adcp_api(self, tool, params):
try:
return await self.adcp.call(tool, params)
except RateLimitError:
raise TransientError("Rate limited")
except NetworkError:
raise TransientError("Network error")
```
### 5. Monitoring and Alerting
Track key metrics:
* Pending operation count by type
* Average approval time
* Rejection rate
* Task timeout rate
* API error rate
## User Communication
Keep users informed about pending operations:
```python theme={null}
class UserNotifier:
async def notify_pending_approval(self, user_id, operation):
message = {
"type": "pending_approval",
"operation_id": operation["id"],
"message": "Your media buy requires publisher approval",
"estimated_time": "2-4 hours"
}
await self.send_notification(user_id, message)
async def notify_approval(self, user_id, operation):
message = {
"type": "operation_approved",
"operation_id": operation["id"],
"message": "Your media buy has been approved",
"media_buy_id": operation["result"]["media_buy_id"]
}
await self.send_notification(user_id, message)
```
## Summary
Building a robust AdCP orchestrator requires:
1. Asynchronous design throughout
2. Proper state management with persistence
3. Graceful handling of pending states
4. User communication for long-running operations
5. Monitoring and observability
Remember: Pending states are not errors - they're a normal part of the advertising workflow.
## Next Steps
* **Task Lifecycle**: See [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle) for status handling
* **Webhooks**: See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for push notifications
* **Security**: See [Security](/dist/docs/3.2.8/building/by-layer/L1/security) for multi-tenant security
# Making your inventory available to AI agents
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/operating/seller-integration
Seller integration guide for AdCP. How publishers, SSPs, and ad platforms expose inventory to AI buyer agents through standardized product discovery and media buy tasks.
AI agents are starting to buy media. When an agency's AI assistant is evaluating ad inventory across platforms, it needs a way to discover what you sell, understand your pricing and targeting options, and execute a buy — all through a standard interface.
AdCP (Ad Context Protocol) provides that interface. If you're a publisher, SSP, or ad platform, implementing AdCP makes your inventory accessible to any compliant buyer agent without requiring custom integrations for each one.
## Why this matters
Today, every platform requires buyers to learn a proprietary API. That works when humans are doing the buying. But AI agents work across many platforms simultaneously, and they need a shared language for common operations.
Platforms that implement AdCP are discoverable by buyer agents out of the box. Platforms that don't require each buyer to build a custom integration — which limits the pool of agents that can access your inventory.
## What you need to implement
AdCP sell-side integration has four parts:
### Publish publisher authorization
Publish an `adagents.json` file on each publisher domain. This file declares the publisher's properties and the agents authorized to sell or enrich that inventory — similar to how `ads.txt` works for supply chain transparency.
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/adagents.json",
"contact": {
"name": "Example Publisher",
"email": "adops@publisher.example.com",
"domain": "publisher.example.com"
},
"properties": [
{
"property_id": "publisher_home",
"property_type": "website",
"name": "Example Publisher",
"publisher_domain": "publisher.example.com",
"identifiers": [{ "type": "domain", "value": "publisher.example.com" }]
}
],
"authorized_agents": [
{
"authorization_type": "property_ids",
"url": "https://ads.publisher.example.com/mcp",
"authorized_for": "Example Publisher direct inventory",
"property_ids": ["publisher_home"],
"signing_keys": [
{
"kid": "publisher-sales-prod-2026",
"kty": "OKP",
"alg": "EdDSA",
"crv": "Ed25519",
"x": "w8zcY1LZqV4n1oKbfyq3n2q3sL2uV3z7kEw1m9Qjv4A",
"use": "sig"
}
]
}
]
}
```
Buyer agents check `adagents.json` to verify publisher authorization and, for mutating seller authorizations, publisher-pinned signing keys. They discover the agent's protocol coverage from `get_adcp_capabilities`, not from `adagents.json`.
### Publish operator identity
Publish `brand.json` at `https://{your-domain}/.well-known/brand.json` for the organization operating the sales agent. `adagents.json` tells buyers which publisher authorizes a sales agent; `brand.json` tells buyers which operator is claiming the sales path, which properties it represents, and where to find signing keys.
For publisher-owned sales teams, list owned or direct properties. For networks and SSPs, list represented properties with `relationship: "delegated"` or `relationship: "ad_network"` and make sure that value matches the publisher's `authorized_agents[].delegation_type` in `adagents.json`. The two files form the bilateral verification chain: the operator declares "I sell this property", and the publisher confirms "this operator is authorized to sell it". A publisher that delegates sales should still publish `adagents.json`; its own `brand.json` is recommended for publisher identity and portfolio context, but the delegated operator's `brand.json` is the required identity record for the agent buyers call.
For the full sell-side setup pattern, including direct publisher and delegated network examples, see [seller setup](/dist/docs/3.2.8/brand-protocol/seller-setup).
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/brand.json",
"version": "1.0",
"id": "example_publisher",
"url": "https://publisher.example.com",
"names": [{ "en_US": "Example Publisher" }],
"properties": [
{
"type": "website",
"identifier": "publisher.example.com",
"relationship": "owned"
}
],
"agents": [
{
"type": "sales",
"url": "https://ads.publisher.example.com",
"id": "publisher_sales",
"jwks_uri": "https://ads.publisher.example.com/.well-known/jwks.json"
}
]
}
```
The `agents[].jwks_uri` lets buyers resolve your public signing keys. The protocol requires verifiable signatures and discoverable public keys; it does not require a specific KMS vendor. Production agents should back private signing keys with KMS/HSM or a managed secret system. Sellers that send AdCP webhooks should publish an `adcp_use: "request-signing"` JWK in that JWKS so buyers can verify outbound webhook signatures. Deprecated `adcp_use: "webhook-signing"` keys remain accepted on the webhook path for backward compatibility. See [request signing](/dist/docs/3.2.8/building/by-layer/L1/request-signing) for the key-publication and webhook-signing profile.
### Expose your inventory
Implement `get_products` to describe what you sell. Each product represents a buyable unit — a display placement, a video slot, a sponsored listing, a newsletter sponsorship. Buyer agents call this with a `buying_mode` and optional `brief`:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442000",
"buying_mode": "brief",
"brief": "Premium display placements for consumer electronics brand"
}
```
Your response includes structured product objects with pricing, formats, and delivery types:
```json theme={null}
{
"products": [
{
"product_id": "homepage_leaderboard",
"name": "Homepage leaderboard",
"channels": ["display"],
"format_option_refs": [{ "scope": "product", "format_option_id": "display_728x90" }],
"pricing_options": [
{
"pricing_option_id": "cpm_standard",
"pricing_model": "cpm",
"floor_price": 8.00,
"currency": "USD"
}
]
}
]
}
```
The richer the product metadata, the better buyer agents can match your inventory to campaign requirements.
For content-centric inventory like podcasts, CTV, or live events, products reference collections and can offer exclusivity:
```json theme={null}
{
"products": [
{
"product_id": "signal_noise_sponsorship",
"name": "Signal & Noise — Category Sponsorship",
"description": "Category-exclusive sponsorship of the Signal & Noise podcast, including pre-roll and mid-roll host read placements.",
"collections": [{ "publisher_domain": "crestnetwork.example.com", "collection_ids": ["signal_noise"] }],
"publisher_properties": ["crestnetwork_podcast"],
"channels": ["podcast"],
"placements": [
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.crestnetwork.example.com/adcp" }, "placement_id": "pre_roll", "name": "Pre-roll (30s)", "mode": "targetable" },
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.crestnetwork.example.com/adcp" }, "placement_id": "host_read", "name": "Mid-roll host read (60s)", "mode": "targetable" }
],
"delivery_type": "guaranteed",
"exclusivity": "category",
"format_option_refs": [{ "scope": "product", "format_option_id": "audio_30s" }],
"pricing_options": [
{
"pricing_option_id": "flat_monthly",
"pricing_model": "flat_rate",
"fixed_price": 15000,
"currency": "USD"
}
]
}
]
}
```
See [Collections and installments](/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments) for the full content model and [Media products](/dist/docs/3.2.8/media-buy/product-discovery/media-products#exclusivity) for exclusivity patterns.
### Accept and fulfill buys
Implement `create_media_buy` to accept campaign instructions from buyer agents. A media buy includes the product, budget, schedule, and any targeting parameters.
```json theme={null}
{
"account": { "account_id": "acct-56789" },
"brand": { "brand_id": "nova-electronics" },
"proposal_id": "prop-homepage-leaderboard",
"total_budget": { "amount": 10000, "currency": "USD" },
"start_time": "2026-04-01T00:00:00Z",
"end_time": "2026-04-30T23:59:59Z"
}
```
Your platform processes the buy according to your normal workflow — whether that's instant activation, internal review, or an approval queue. AdCP's asynchronous status system (`completed`, `working`, `submitted`, `input-required`) lets you model any workflow.
> [!NOTE]
>
> **Status must be persisted, not computed from flight dates.** Store `status` as an explicit database field, updated only by protocol events — not by comparing `start_time`/`end_time` to the current date. Date arithmetic cannot produce `paused`, `canceled`, or `rejected`; those states are driven by explicit commands. See [seller implementation invariants](/dist/docs/3.2.8/media-buy/media-buys#seller-implementation-invariants) for the full implementation requirement.
## Industry-specific guidance
The core integration steps above apply to all sellers. If you're an **ad network aggregating across multiple platforms**, see the [ad networks deep dive](/dist/docs/3.2.8/sponsored-intelligence/networks) for product modeling, account chains, catalog forwarding, and `adagents.json` for networks.
If you sell inventory for publishers you don't own (as a network or SSP), declare those properties in your [brand.json](/dist/docs/3.2.8/brand-protocol/brand-json#property-relationships) with the appropriate `relationship` value (`delegated` or `ad_network`). This creates bilateral verification — you declare the relationship, and each publisher confirms by authorizing your agent with the matching `delegation_type` in their adagents.json.
For vertical-specific product modeling, pricing patterns, and measurement:
* **AI platforms and AI ad networks**: See the [Sponsored Intelligence guide](/dist/docs/3.2.8/sponsored-intelligence/overview) for sponsored responses, AI search products, generative creative from catalogs, and SI Chat Protocol handoffs.
* **Retail media networks**: See the [commerce media guide](/dist/docs/3.2.8/media-buy/commerce-media) for sponsored product listings, closed-loop attribution, and in-store measurement.
## Accounts and sandbox
Production sales agents should implement the accounts protocol. [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) let buyers establish billing relationships, track spend per advertiser, and manage multiple operators buying on behalf of different brands through a single agent.
The account model depends on your platform:
* **Walled gardens** (social platforms, AI platforms, retail media networks) typically use account-id namespaces — set `require_operator_auth: true` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) so each operator authenticates independently, expose `list_accounts` when the upstream platform owns the namespace, and require buyers to pass discovered `account_id` values.
* **Open platforms** (publishers, SSPs) can use buyer-declared accounts — the agent is trusted and declares accounts via `sync_accounts`.
See [Accounts and Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) for full workflows.
**Sandbox support is strongly recommended.** Declare `account.sandbox: true` in your capabilities so buyers can validate the full integration — product discovery, media buy creation, delivery reporting — before committing real spend. Buyer-declared account sellers provision test accounts through `sync_accounts` with `sandbox: true`; account-id namespace sellers expose pre-existing sandbox accounts through `list_accounts` or out-of-band setup. Without sandbox, buyers must test against live inventory, which slows adoption and increases onboarding friction. See [Sandbox mode](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox) for implementation details.
## Delivery reporting
All Media Buy Protocol sales agents MUST implement [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) and include `reporting_capabilities` on every product. Buyer agents pull performance data — impressions, clicks, spend, conversions — in a standardized format. This is how agents monitor campaigns across platforms without logging into each dashboard individually. See [Required tasks by protocol](/dist/docs/3.2.8/protocol/required-tasks) for the full list of required seller tasks.
Sellers building AdCP into their production stack should consider enrolling in the **[AAO Verified (Live)](/dist/docs/3.2.8/building/verification/aao-verified)** qualifier once they're serving real campaigns. (Live) adds continuous observability of live delivery data on a designated compliance account, distinct from the (Spec) qualifier earned automatically by storyboard passing. Opt-in, no new infrastructure on the seller side — grant the [`attestation_verifier`](/dist/docs/3.2.8/accounts/overview#standard-named-scope-attestation_verifier) scope on one account with live campaigns.
## Product design patterns
Different inventory types use different AdCP features:
| Inventory type | Key features |
| - | - |
| Standard display/video | Canonical `format_options`, `delivery_type: "non_guaranteed"`, auction pricing |
| Podcast sponsorship | `collections`, `placements` (host read), `delivery_type: "guaranteed"`, flat_rate |
| CTV series sponsorship | `collections`, `exclusivity`, `delivery_type: "guaranteed"` |
| Live event | `collections` (cadence: event), `installments` (flexible_end, tentative), `exclusivity` |
| Retail media | `catalog_types`, `catalog_match`, metric optimization |
For content-centric inventory, see [Collections and installments](/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments). For exclusivity and sponsorship patterns, see [Media products](/dist/docs/3.2.8/media-buy/product-discovery/media-products#exclusivity).
## Governance enforcement
Buyer agents increasingly require governance compliance before committing spend. Implementing governance makes your inventory eligible for brand-safe campaigns, reduces post-campaign disputes, and signals to buyer agents that your platform takes brand suitability seriously. Three governance domains are relevant to sellers.
### Property governance via adagents.json
Your `adagents.json` file is the foundation of property governance. It declares which properties you sell, which agents are authorized to sell them, and which governance agents have data about your inventory. Buyer agents use this to verify supply path authorization and discover property intelligence — if your `adagents.json` is missing or incomplete, buyer agents cannot verify that you are authorized to sell what you claim.
Declare `property_features` entries to point buyers toward governance agents that score your properties for quality, sustainability, or brand safety. See the [property governance specification](/dist/docs/3.2.8/governance/property/specification) for the full schema and the [adagents.json tech spec](/dist/docs/3.2.8/governance/property/adagents) for publisher-side setup.
### Content standards enforcement
When a buyer includes a `content_standards_ref` in a `get_products` or `create_media_buy` request, they are asking you to enforce brand suitability rules during delivery. Your responsibilities: fetch the standards from the referenced governance agent, evaluate whether you can enforce them, reject the buy if you cannot, and calibrate your local evaluation model against the governance agent via `calibrate_content`. After delivery, push content artifacts back to the buyer so they can validate compliance independently.
If you cannot meaningfully enforce a buyer's content standards, reject the buy rather than accepting it and failing silently. See the [content standards implementation guide](/dist/docs/3.2.8/governance/content-standards/implementation-guide) for the full sales agent workflow.
### Execution checks
When a request carries `governance_context`, a service declaring `adcp.governance_enforcement` first verifies the signed intent token, including its audience, task, canonical payload hash, and monetary ceiling. A media seller whose task claim includes `online_execution_check` additionally prepares its candidate delivery, calls [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) with the preserved context and `planned_delivery`, and commits only after approval. A `signed_context`-only task commits after the inbound token passes verification. The buyer's plan ID is not part of this service boundary.
```javascript theme={null}
// Before confirming create_media_buy: prepare without external side effects.
const candidate = await prepareMediaBuy(request);
const check = await governanceAgent.checkGovernance({
caller: "https://seller.example.com",
governance_context: request.governance_context, // preserve byte-for-byte after standard-claim verification
phase: "purchase",
planned_delivery: {
media_buy_id: candidate.media_buy_id,
geo: { countries: ["US"] },
channels: ["olv"],
start_time: candidate.start_time,
end_time: candidate.end_time,
total_budget: candidate.total_budget.amount,
currency: candidate.total_budget.currency
}
});
if (check.verdict !== "approved") {
// Execution checks are binary. Do not commit on denied or malformed responses.
return { error: "GOVERNANCE_DENIED", detail: check.explanation };
}
return await commitMediaBuy(candidate); // atomic state transition after approval
```
Execution checks cover three phases of the media buy lifecycle:
| Phase | When to call | What's checked |
| - | - | - |
| `purchase` | Before confirming `create_media_buy` | Budget, geo, channels, flight dates, policies |
| `modification` | Before confirming [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) | Change magnitude, reallocation, new parameters |
| `delivery` | Periodically during delivery | Pacing, spend rate, geo drift, channel distribution |
Agents declare exactly which modes they enforce per task in `adcp.governance_enforcement.tasks`. See [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) for the full specification.
### Campaign governance context
When a buyer includes `governance_context` in the protocol envelope of a `create_media_buy` request, store it alongside the media buy. This is an opaque value — you don't interpret it, you just persist and forward it.
Pass `governance_context` back to the buyer's governance agent on every lifecycle event for that media buy:
| Lifecycle event | How governance_context flows |
| - | - |
| **Create** | Received in `create_media_buy` envelope. Store it. If calling `check_governance`, include it. |
| **Activate** | Include stored `governance_context` when calling `check_governance` with the seller's `planned_delivery`. |
| **Update** | Include on `check_governance` for modifications. The governance agent uses it to track cumulative changes. |
| **Pause / Resume** | Include if calling `check_governance`. The governance agent updates pacing state. |
| **Cancel / Complete** | Include so the governance agent can close out budget tracking and produce final audit. |
| **Delivery webhooks** | Include in webhook payloads so the governance agent can correlate delivery data. |
The governance agent uses `governance_context` to reconnect each event to the original plan, campaign, and budget state. Without it, the governance agent has no way to track the media buy across its lifecycle.
If `governance_context` is not present in the original request, skip governance calls — the buyer is not using campaign governance for this media buy.
### Creative governance
Buyer agents may require creative evaluation before delivery — security scanning, content categorization, or quality scoring. As a seller, you participate by submitting creative manifests to governance agents via `get_creative_features` and honoring the feature requirements the buyer sets (for example, blocking creatives flagged for `auto_redirect` or `credential_harvest`). You do not need to implement the evaluation yourself; specialist governance agents handle that.
See the [creative governance overview](/dist/docs/3.2.8/governance/creative/index) for the feature-based evaluation model and multi-agent collaboration pattern.
### For Sponsored Intelligence sellers: generation-time enforcement
Traditional sellers apply governance as a post-delivery filter — classify content, then block what fails. Sponsored Intelligence platforms generate creative at serve time, which means governance rules can be enforced during generation rather than after the fact. When a buyer pushes content standards, apply them as constraints on your generation pipeline so unsuitable content is never produced. This gives brands a fundamentally stronger guarantee: suitability is built into the output, not bolted on as a check afterward. See the [Sponsored Intelligence guide](/dist/docs/3.2.8/sponsored-intelligence/overview) for how content standards integrate with catalog-driven creative generation.
## How it connects to your existing stack
AdCP sits alongside your existing APIs and dashboards. It doesn't replace your self-serve platform or your internal campaign management system. It adds a standard interface that AI agents can use.
| Your existing system | How AdCP relates |
| - | - |
| Self-serve dashboard | AdCP serves a different audience (AI agents, not humans) |
| Management API | AdCP provides a standard subset; your API provides the full feature set |
| Ad server (GAM, custom) | AdCP sends campaign instructions; your ad server handles delivery |
| OpenRTB integration | AdCP handles campaign setup; OpenRTB handles impression-level auctions |
## Getting started
> [card] [adagents.json builder](https://agenticadvertising.org/adagents/builder)
>
> Create and validate your adagents.json file using the interactive builder.
> [card] [Media buy specification](/dist/docs/3.2.8/media-buy/specification)
>
> Full reference for sell-side task implementations: products, media buys, and delivery reporting.
> [card] [Building with AdCP](/dist/docs/3.2.8/building)
>
> Implementation guides, SDKs, and integration patterns.
> [card] [Operating an agent](/dist/docs/3.2.8/building/operating/operating-an-agent)
>
> What sits behind protocol compliance — activation, storage, hosting, and build-vs-buy.
> [card] [Ask Addie](https://adcontextprotocol.org/chat)
>
> Ask questions about implementing AdCP for your platform — no code required.
> [card] [Sponsored Intelligence guide](/dist/docs/3.2.8/sponsored-intelligence/overview)
>
> Product modeling and workflows for AI platforms and ad networks.
> [card] [Commerce media guide](/dist/docs/3.2.8/media-buy/commerce-media)
>
> Product modeling and workflows for retail media networks.
# Storyboard troubleshooting
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/operating/storyboard-troubleshooting
Common failure patterns when running AdCP compliance storyboards — missing fixtures, signature challenges, envelope drift, context echo, capability mismatches, and state-machine error codes.
When a compliance storyboard fails against your agent, the runner reports a step name and error text. This page maps the most common error patterns to their root causes and fixes, so you can resolve each class of failure without spelunking through SDK source or runner internals.
Each section shows the error you'll see, what it means, and what to change in your agent.
## Unknown fixture errors
```
× (unknown step): PRODUCT_NOT_FOUND: Package 0: Product not found: test-product
```
The storyboard's `sample_request` references a hardcoded ID (`test-product`, `test-pricing`, `campaign_hero_video`, `gov_acme_q2_2027`, etc.). The runner expects the agent to have that ID in its catalog before the mutating step runs.
**Fix:** On the dev or staging endpoint registered for Verified (Spec), implement `comply_test_controller` and honor the seed scenarios declared in the storyboard's `fixtures:` block. Do not expose the controller on the production endpoint used for Verified (Sandbox). When `prerequisites.controller_seeding: true` is set, the runner auto-injects a fixtures phase that calls `seed_product`, `seed_pricing_option`, `seed_creative`, `seed_plan`, or `seed_media_buy` in foreign-key order before the main phases execute.
Implement only the scenarios your selected specialisms require. For example, `sales-non-guaranteed` needs `seed_product` and `seed_pricing_option`; it does not require the full controller surface unless another selected storyboard declares additional fixtures.
See [Compliance test controller — Scenarios](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#scenarios) for the full seed contract. Agents that return `UNKNOWN_SCENARIO` on a seed call grade the storyboard `not_applicable` — they are not penalized for missing sandbox surface, but they cannot pass storyboards that depend on pre-seeded state.
## Ambiguous sandbox account discovery
```
× Discover sandbox accounts for media buy: list_accounts returned multiple matching accounts (acct-a, acct-b); provide media_buy_account_id/account_id to disambiguate
```
The runner is resolving an account-id namespace (`account.require_operator_auth: true`) and the credential can see more than one plausible sandbox account. It cannot safely choose an `account_id` for later media-buy calls.
**Fix:** Prefer a dedicated compliance credential bound to one sandbox account. If the credential must expose a roster, return enough brand data for exactly one active sandbox row to match the selected test kit's `brand.house.domain`. Do not set `require_operator_auth: false` as a workaround unless the seller genuinely uses buyer-declared natural keys (`brand` + `operator`); that flag is a buyer-facing account-model promise, not a runner hint.
When a valid `account` capability block is present, merely exposing `list_accounts` does not opt a buyer-declared seller into account-ID discovery. Leave `require_operator_auth` false or absent, and support `sync_accounts` with `sandbox: true`, when the buyer declares accounts. If the whole `account` block is absent or could not be read, the runner may retain its legacy `list_accounts` discovery heuristic. See [Get test-ready — Pick your sandbox bootstrap path](/dist/docs/3.2.8/building/verification/get-test-ready).
## Signature challenge missing on 401
```
× (unknown step): expected error="request_signature_required", got error="(none)"
```
The storyboard sent an unsigned request to an operation declared in `get_adcp_capabilities.request_signing.required_for`. Your agent rejected with 401 but did not include a `WWW-Authenticate: Signature ...` challenge header, so the runner could not resolve the error code from the transport binding.
**Fix:** Emit the RFC 9421 challenge header on every 401 caused by missing or invalid signatures. The runner resolves the error code via the transport binding order — if the `WWW-Authenticate` header is absent, the error classification falls back to "(none)" even when the JSON body carries a useful message.
The reference SDK constructs these errors via `RequestSignatureError` from `@adcp/sdk/signing` with `.code: RequestSignatureErrorCode`. The full taxonomy (`request_signature_required`, `request_signature_header_malformed`, `request_signature_tag_invalid`, `request_signature_window_invalid`, `request_signature_key_unknown`, etc.) is enumerated in that module. Your agent SHOULD surface the same code on the challenge so SDK-speaking callers can recover automatically.
See [Signed Requests (Transport Layer)](/dist/docs/3.2.8/building/by-layer/L1/security#signed-requests-transport-layer) for the challenge-header format and the [transport-error binding order](/dist/docs/3.2.8/building/operating/transport-errors).
## Response envelope drift
```
× (unknown step): Response contains errors array
```
The vector used `check: error_code` but your response surfaces the error on a shape the runner's client-detection order didn't expect. In practice, this means your agent returned `errors[]` when the transport layer already carried `adcp_error`, or vice versa — the storyboard asserted a single error code and the runner resolved it from a different layer than you emitted on.
**Fix:** Pick one error surface per response and stick to it per the [envelope vs. payload two-layer model](/dist/docs/3.2.8/building/by-layer/L3/error-handling#envelope-vs-payload-errors-the-two-layer-model). On MCP: `adcp_error` for structured content; `errors[]` for task-payload errors. On A2A: the same layers apply — transport error in the envelope, application error in the task artifact's DataPart.
The runner's `check: error_code` is shape-agnostic — it resolves from either layer — but if your agent emits both simultaneously they can disagree, and the runner grades the resolved code against the vector's expectation. Choosing one surface and being consistent avoids the divergence.
## Context echo failures
```
× (unknown step): expected field "context.correlation_id" = "xyz", got (missing)
```
Your agent returned a response that does not include the `context:` object from the request. Every storyboard step that sends `context: { correlation_id: ... }` asserts that `context.correlation_id` echoes unchanged in the response.
**Fix:** Preserve the same `context:` JSON value on every response, including errors. The echo contract is normative — buyers use `correlation_id` to stitch multi-agent flows, and the runner grades every context-carrying step on it. See [Context and sessions — Normative echo contract](/dist/docs/3.2.8/building/by-layer/L2/context-sessions#normative-echo-contract).
Captures use the same contract in reverse: storyboards that pass `"$context."` through `context_outputs:` rely on the capture populating after the producer step's validations pass. A downstream step reading `$context.foo` when the producer failed or omitted `context:` grades as `unresolved_substitution`.
## Capability-vector mismatch (runner declared, agent doesn't support)
```
× (unknown step): capability X asserted but not declared in get_adcp_capabilities
```
The storyboard dispatched a step that requires a capability your agent does not advertise in its `get_adcp_capabilities` response. The runner should auto-skip these steps; if you're seeing them graded as failures instead, either the capability is declared at the wrong key or the runner is missing the auto-skip path.
**Fix:** Double-check your `get_adcp_capabilities.tools` list and any required-for fields (`request_signing.required_for`, `idempotency.supported_tools`, etc.). For vectors that apply only to specialized agents, the storyboard author can use `skipVectors` to flag the opt-out explicitly; as an implementer, the fix is almost always on the capability declaration rather than the vector.
## Required-for composition
```
× (unknown step): missing auth — step requires authenticated or signed
```
The runner encountered a mutating step that expected either authenticated credentials or a signed request, and the transport carried neither. Typically this means the test kit didn't declare `auth.api_key` or `auth.basic` AND the agent doesn't advertise request-signing support — leaving the runner with no way to authenticate the call.
**Fix:** Either (a) declare `auth.api_key` or `auth.basic` in the test kit so the runner uses a static Authorization-header credential, or (b) advertise request-signing via `get_adcp_capabilities.request_signing` so the runner signs the request instead. The runner's `requireAuthenticatedOrSigned` gate accepts either path — it fails only when both are absent.
## Static-credential agent: no auth mechanism contributed (assert_mechanism)
```json theme={null}
{
"check": "assertion",
"passed": false,
"description": "Probe validations failed.",
"expected": ["auth_mechanism_verified"],
"actual": []
}
```
The `mechanism_required` phase found no contribution to `auth_mechanism_verified` from any optional auth phase. This is the most common failure for static-credential-only agents (Bearer API key or HTTP Basic), and it is not a real auth problem — it is a test-kit configuration gap.
**What happened:** The `api_key_path` phase has `skip_if: "!test_kit.auth.api_key"` and the `basic_path` phase has `skip_if: "!test_kit.auth.basic"` — each is skipped unless the test kit declares the matching credential. The `oauth_discovery` phase 404s on `/.well-known/oauth-protected-resource/...` (expected for static-credential-only agents; those failures are silently ignored by the runner). With all optional auth phases contributing nothing, `assert_mechanism` sees `actual: []`.
**The `--auth TOKEN` distinction:** The `--auth TOKEN` flag you pass to the runner is the runner's own session credential — it authorizes the runner's own requests to your agent. It is entirely separate from `test_kit.auth.api_key` or `test_kit.auth.basic`, which are the specific credentials the static-credential phases send during positive and invalid-credential probes. These are not the same token and are not interchangeable.
**`prerequisites.test_kit` is a loading directive, not decoration:** when a storyboard declares `prerequisites.test_kit` (for example `comply_controller_mode_gate` declares `test-kits/acme-outdoor-live.yaml`), the runner loads that kit from the active compliance cache and its credentials flow into the storyboard's `from_test_kit` and `$test_kit.*` references without any CLI flag. An explicitly supplied kit (`options.test_kit` / hosted-run configuration) still wins. A step whose `auth.from_test_kit` resolves no credential fails with an explicit configuration error rather than sending an unauthenticated probe — a probe with no credential cannot test a credential-keyed contract.
**Fix for Bearer API key agents:** Every default AdCP brand test kit declares its probe API key under `auth.api_key` using the `demo--v1` naming convention. The default test kit (`acme-outdoor`) uses `demo-acme-outdoor-v1`. Configure your agent to accept the kit's probe key as a valid compliance-testing credential alongside your production key. The `demo--` prefix is the AdCP conformance handle — accept any Bearer token matching the prefix for the kits you run against (the suffix can rotate across spec versions, the prefix stays stable):
```typescript theme={null}
serve({
authenticate: verifyApiKey({
keys: {
[PRODUCTION_TOKEN]: { principal: 'my-principal' },
// Accept the default compliance kit's probe key (and any future suffix rotation)
'demo-acme-outdoor-v1': { principal: 'compliance-runner' },
}
})
})
```
**Fix for HTTP Basic agents:** Use a test kit that declares `auth.basic` with either `username`/`password` or a single `credentials` value containing the unencoded `username:password` pair. Configure your agent to accept that Basic credential as a valid compliance-testing credential alongside your production Basic credential. The `basic_path` phase then sends the valid Basic credential and a random-invalid Basic credential, and contributes `auth_mechanism_verified` only when the agent accepts the valid credential and rejects the invalid one.
Agents that only accept their own production credential skip the matching static path (no test-kit credential matches), fail `oauth_discovery` (no PRM), and land at `actual: []` in `assert_mechanism`. Adding the test-kit credential to your allowed-credentials set is sufficient — you do not need a PRM endpoint or an OAuth issuer.
Do not serve a fake `/.well-known/oauth-protected-resource/...` pointing at a non-existent issuer to "pass" the OAuth phase. That triggers the advertised-but-unserved failure mode the storyboard was designed to catch.
See [Known spec ambiguities — PRM required for non-OAuth agents](/dist/docs/3.2.8/building/cross-cutting/known-ambiguities#prm-required-for-non-oauth-agents) for background on why the carve-out exists and how the static-credential / `oauth_discovery` phase semantics were designed.
## `INVALID_STATE` vs `INVALID_TRANSITION`
Two codes that are easy to confuse:
* **`INVALID_STATE`** — the canonical AdCP media-buy error code for "the resource is in a state that doesn't allow this action." Used on `create_media_buy`/`update_media_buy`/`pause`/`resume`/`cancel` against a media buy that cannot transition as requested. See `media-buy/specification.mdx` and `media-buy/media-buys/index.mdx` for authoritative usage.
* **`INVALID_TRANSITION`** — specific to the `comply_test_controller` sandbox primitive. Emitted when a runner requests a state-machine transition the seller rejects (e.g., forcing `approved` → `archived` without going through `active`). See [Compliance test controller — Scenarios](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#scenarios).
A storyboard vector that asserts `INVALID_STATE` on a production task but your agent returns `INVALID_TRANSITION` is an error-code vocabulary mismatch — `INVALID_TRANSITION` is not in the canonical enum at `static/schemas/source/enums/error-code.json` and should not appear outside the compliance test controller.
## When none of the above matches
If you hit a failure that doesn't map to anything here, check the [known spec ambiguities](/dist/docs/3.2.8/building/cross-cutting/known-ambiguities) page — some storyboards are blocked on resolved-but-unreleased spec gaps, and the workaround is tracked there.
Still stuck? File an issue at [adcontextprotocol/adcp](https://github.com/adcontextprotocol/adcp/issues) with the storyboard name and the smallest relevant, redacted error excerpt. Remove credentials, agent URLs, account or resource identifiers, and business or personal data; do not attach full request or response payloads. Maintainers can usually narrow the pattern from the error signature.
# Support recovery runbooks
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/operating/support-recovery-runbooks
Operational runbooks for escalation SLA follow-up, certification completion recovery, domain verification, and registry crawl recovery.
# Support recovery runbooks
These runbooks cover support cases that should not sit silently in Addie, certification, or registry queues.
## Escalation SLA follow-up
Addie support requests are visible in the admin escalation dashboard and in the requester's dashboard. The SLA enforcement job runs hourly.
Admin follow-up rules:
* Urgent open requests are re-surfaced to the configured private escalation Slack channel after 4 hours.
* Other open requests are re-surfaced after 24 hours.
* Acknowledged or in-progress requests are re-surfaced after 24 hours without an update.
* Requesters receive a visible dashboard update after 24 hours and can add details or close the request themselves.
Operator checklist:
1. Open `/admin/escalations`.
2. Filter to active requests and look for "Needs pickup" or "Needs update".
3. Acknowledge or move the request to in progress when a human owns it.
4. Add requester-visible notes when the requester needs status.
5. Resolve the request when fixed, and notify the user when appropriate.
If Slack notifications are missing, configure the escalation channel in `/admin/settings`.
## Certification completion recovery
The certification recovery job runs every 6 hours. It looks for passed attempts that did not finish module or credential reconciliation.
Automatic behavior:
* Reconcile the passed attempt to `learner_progress`.
* Re-run credential eligibility and awarding.
* File a deduplicated escalation if automatic repair cannot award the credential.
Manual repair:
1. Open `/admin/certification`.
2. In "Attempts needing attention", click "Reconcile credentials" for passed attempts.
3. If the attempt still has warnings, open the learner detail panel.
4. Use "Admin completion repair" only when there is a teaching checkpoint for the learner, module, and Addie thread.
5. Run "Issue missing badges" when the local credential exists but Certifier badge fields are missing.
6. Record the escalation ID or reason in the note field.
Do not create a duplicate manual credential unless the learner record already proves the module completion. Repair the learner record first, then issue or backfill the credential.
## Domain verification recovery
Use admin domain verification recovery when a member has published the WorkOS DNS TXT record but the self-service verify path is blocked, rate-limited, or the webhook did not update local state.
This is an internal support workflow. Use authenticated admin domain tooling or the private ops runbook; public docs should not expose admin endpoint paths, bearer-token examples, or WorkOS challenge-token handling.
Before closing a registry/domain escalation as resolved, confirm the registry state, not just the AAO UI:
* The target domain has a local `organization_domains` row for the intended org.
* That row is `verified=true`.
* The row is not attached to the member's personal workspace when the support request is for a company org.
* The registry no longer returns `member:null` for the relevant domain.
* The requested agent hostname is covered by a verified domain row on the registering org.
If WorkOS shows a verified domain but the local rows are missing, stale, or attached to another org, run the WorkOS-domain reconciliation action for the intended org. This replays WorkOS as the source of truth, mirrors domains into `organization_domains`, and re-runs brand-registry sync for verified domains. It does not bypass DNS verification; WorkOS still has to know the domain/challenge first.
For personal-workspace/company-org split incidents, run the read-only admin preview first:
* Use the private domain-split preview from the internal ops runbook or admin UI.
* The preview reports WorkOS state, local `organization_domains`, member-profile presence, org membership, and the next safe action.
* Only run the reconciliation action when the preview says WorkOS already verifies the domain for the company org.
* If billing appears attached to the personal workspace, use the separate Stripe customer preview/confirm workflow after human review; do not move billing in the domain repair path.
Outcomes:
* `success: true`: WorkOS confirmed DNS and local `organization_domains` was reconciled.
* `still_pending`: WorkOS still cannot see the TXT record. Ask the member to confirm the record name and token.
* `no_challenge`: issue a new domain challenge from the member domain settings or admin domain tooling.
DNS propagation normally takes minutes, but stale provider caches can last longer. Do not keep retrying every few seconds; fix the DNS record and retry after propagation.
If the request is invalid or suspicious, close it as `wont_do` with notes. Do not mark a registry/domain escalation `resolved` while the local domain row is missing, unverified, or attached to the wrong org.
## Registry and heartbeat recovery
Use these triggers after a member fixes `adagents.json`, `brand.json`, authorization, or endpoint health.
Publisher and brand crawl requests require an authenticated member or admin request and a JSON `domain` body:
```bash theme={null}
curl -X POST "https://agenticadvertising.org/api/registry/crawl-request" \
-H "Content-Type: application/json" \
-b "$SESSION_COOKIE" \
--data '{"domain":"example.publisher"}'
```
Expected accepted response:
```json theme={null}
{
"message": "Crawl request accepted",
"domain": "example.publisher",
"crawl_request_id": "8d127de4-5568-4756-b66c-dd9b0780fd8f"
}
```
Acceptance means the request was committed to the durable PostgreSQL queue; it
does not mean the crawl has completed. Check the request with the same member
or admin session:
```bash theme={null}
CRAWL_REQUEST_ID="8d127de4-5568-4756-b66c-dd9b0780fd8f"
curl "https://agenticadvertising.org/api/registry/crawl-request/$CRAWL_REQUEST_ID" \
-b "$SESSION_COOKIE"
```
The lifecycle is `queued` → `running` → `completed` or `invalid`. Transient
failures move through `retrying`; full-crawl contention produces `deferred`
without consuming an attempt. `failed` is terminal after the bounded retry
budget. Request history is retained for 30 days.
If a worker exits while a request is running, its two-minute lease expires and
another worker reclaims the request. Do not manually change queue rows. For a
terminal `failed` request, correct the reported error category and submit a new
crawl request after the per-domain rate-limit window; the old request remains
as the audit record.
Workers claim at most the configured crawl concurrency per tick. If a periodic
full crawl is active, claimed requests are persisted as `deferred`, their claim
attempt is refunded, and they become eligible again after 30 seconds. This
makes contention visible without spending the retry budget or performing
origin work. On worker startup, the durable queue starts immediately and the
initial full crawl waits a fixed 30 seconds. This gives already-due requests a
bounded opportunity to run after a deploy. After that window, the full crawl
holds an exclusive PostgreSQL intent lock while waiting for active publisher
crawls, including across bounded execution-lock timeouts and retries. New
publisher crawls therefore defer instead of starving the six-hour full crawl.
Each active publisher crawl holds a PostgreSQL shared global execution lock and
an exclusive per-domain lock for the fetch/write lifecycle; the periodic full
crawl holds the exclusive global lock. These session locks use dedicated
connections outside the application pool, so crawl concurrency does not consume
the connections needed by heartbeats, status reads, or mirror transactions. A
lost worker session releases its locks automatically. The locks prevent an
expired or duplicate attempt from
overwriting newer mirror state. The mirror transaction
also verifies the current request lease token before committing. Publisher GET
requests do not acquire these locks and continue to serve the last committed
mirror state while crawling is delayed or unavailable.
Routine dedicated lock-session operations are bounded at 10 seconds. Full-crawl
intent acquisition may wait 10 seconds, with a 10-second socket-operation
margin. The periodic full crawl may wait up to two minutes for the global lock,
plus the same operation margin. A missed keepalive or unlock deadline
invalidates the lock and forcibly closes its dedicated connection so a wedged
socket cannot hold a queue worker or request lease indefinitely.
For the first deployment, use Fly's `immediate` strategy and leave
`PUBLISHER_CRAWL_QUEUE_ENABLED=false`. Immediate replacement prevents an old
image, which does not participate in the new PostgreSQL execution locks, from
overlapping a new worker. After every machine runs the lock-participating image,
set the gate to `true` and restart that image before accepting requests. Keep
that consumer-capable image available for rollback; rolling back to an older
image pauses queued work and removes status lookup until the new image is
restored, but does not delete committed requests. Restore the normal rolling
strategy only after every deployable image participates in these locks.
Admission returns `crawl_queue_at_capacity` with `503` and `Retry-After` when
10,000 active requests are already queued or running. This is backpressure, not
acceptance; retry later rather than inserting or editing queue rows manually.
Operational logs include `crawl_request_id`, attempt count,
`accepted_to_terminal_ms`, queue depth, oldest-due lateness, reclaimed-lease
count, and final-attempt lease expirations. A `Publisher crawl request queue
requires attention` warning means a lease is expired or due work is more than
five minutes late; requests intentionally waiting in retry backoff do not
trigger it. Confirm that the worker process is healthy, then use the status
endpoint to determine whether the request recovered before escalating.
For brand manifests, use the same body shape:
```bash theme={null}
curl -X POST "https://agenticadvertising.org/api/registry/brand-crawl-request" \
-H "Content-Type: application/json" \
-b "$SESSION_COOKIE" \
--data '{"domain":"example.brand"}'
```
Expected accepted response:
```json theme={null}
{ "message": "Brand crawl request accepted", "domain": "example.brand" }
```
Agent refresh and heartbeat requeue use an encoded agent URL. The caller must own the agent or be an AAO admin.
```bash theme={null}
AGENT_URL="https://seller.example/adcp"
ENCODED_URL="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$AGENT_URL")"
curl -X POST "https://agenticadvertising.org/api/registry/agents/$ENCODED_URL/refresh" \
-H "Prefer: respond-async" \
-b "$SESSION_COOKIE"
```
The async form returns `202 Accepted`, a `Location` header, and a body containing
`refresh_operation_id`, `test_session_id`, and `status_url`. Poll `status_url`
with the same authenticated owner or admin session, honoring `Retry-After`,
until the operation is `succeeded` or `failed`. The operation remains available
if the original response is lost, and a same-context retry recovers its handle.
Clients that omit `Prefer: respond-async` retain the compatibility behavior:
the server waits for a terminal result for at most 90 seconds, returning `200`
when it finishes in that window and otherwise returning the same durable `202`
handle. `409`, `429`, `500`, `502`, and `503` identify a conflicting credential
context, rate limit, terminal refresh failure, probe failure, or queue outage.
Queue heartbeat without synchronous probing when the agent should be checked by the normal monitor:
```bash theme={null}
curl -X POST "https://agenticadvertising.org/api/registry/agents/$ENCODED_URL/monitoring/requeue" \
-b "$SESSION_COOKIE"
```
Expected response:
```json theme={null}
{ "requeued": true }
```
Use refresh for a specific agent after endpoint or capability fixes. Use crawl request for publisher authorization changes.
# Transport Error Mapping
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/operating/transport-errors
How AdCP structured errors travel over MCP and A2A transports: extraction paths, JSON-RPC codes, recovery behavior, and client implementation requirements.
AdCP errors are **application-layer** errors. They belong in the tool/task response, not in the transport error channel. This page defines how the [`error.json`](https://adcontextprotocol.org/schemas/3.2.8/core/error.json) schema maps to MCP and A2A response envelopes.
For the error schema itself, standard codes, and recovery strategies, see [Error Handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling).
## Layer Separation
| Layer | Examples | Channel |
| - | - | - |
| Transport | Connection refused, malformed JSON-RPC, internal crash | JSON-RPC `error` / A2A protocol error |
| Application | `RATE_LIMITED`, `BUDGET_TOO_LOW`, `CREATIVE_REJECTED` | Tool/task response body |
Transport errors are handled by protocol libraries. Application errors are handled by business logic. Mixing them loses the structured recovery data that makes AdCP errors useful.
## MCP Binding
### Tool-Level Errors
The standard path for all AdCP error codes. The tool executed, understood the request, and is returning a structured error.
**Today's practical path:** Most MCP hosts (Claude Desktop, Cursor, Windsurf) read `content` text on error responses and do not surface `structuredContent` to LLMs or programmatic consumers. Until `structuredContent` adoption is widespread, the text-fallback path is how most errors will be extracted. Servers SHOULD support both paths:
```json theme={null}
{
"content": [{"type": "text", "text": "{\"adcp_error\":{\"code\":\"RATE_LIMITED\",\"message\":\"Request rate exceeded\",\"retry_after\":5,\"recovery\":\"transient\"}}"}],
"isError": true,
"structuredContent": {
"adcp_error": {
"code": "RATE_LIMITED",
"message": "Request rate exceeded",
"retry_after": 5,
"recovery": "transient"
}
}
}
```
**`content` text** carries the AdCP error as a JSON string for text-based extraction. **`structuredContent.adcp_error`** carries the same error for programmatic clients that support it. Servers that include human-readable text SHOULD add it as a second content item, keeping it terse (one sentence):
```json theme={null}
{
"content": [
{"type": "text", "text": "{\"adcp_error\":{\"code\":\"RATE_LIMITED\",\"message\":\"Request rate exceeded\",\"retry_after\":5,\"recovery\":\"transient\"}}"},
{"type": "text", "text": "Rate limited — retry in 5s."}
],
"isError": true,
"structuredContent": {
"adcp_error": {
"code": "RATE_LIMITED",
"message": "Request rate exceeded",
"retry_after": 5,
"recovery": "transient"
}
}
}
```
**Terse text when `structuredContent` is present.** When `structuredContent` carries the full error, the human-readable text content item SHOULD be a single terse sentence (e.g., "Rate limited — retry in 5s."). The error details are already in `structuredContent` and the JSON text fallback. Repeating the full error in prose wastes LLM context tokens — especially for transient errors that accumulate during retries.
**`adcp_error` key**: Namespacing avoids collisions with success data that may also appear in `structuredContent` (e.g., `products`). A single key simplifies detection.
**`structuredContent`** requires MCP 2025-03-26 or later. Servers on older MCP versions omit `structuredContent` — the JSON string in `content[0].text` is sufficient. Clients parse this via the text-fallback path (see [Client Detection Order](#client-detection-order)).
### Transport-Level Errors
When infrastructure rejects a request *before* tool dispatch (API gateway, rate-limit middleware), the tool never executes. Use a reserved JSON-RPC error code with the AdCP error in `data`:
```json theme={null}
{
"jsonrpc": "2.0",
"id": "req-123",
"error": {
"code": -32029,
"message": "Rate limit exceeded",
"data": {
"adcp_error": {
"code": "RATE_LIMITED",
"retry_after": 5,
"recovery": "transient"
}
}
}
}
```
### Reserved JSON-RPC Codes
| Code | AdCP Error Code | When |
| - | - | - |
| `-32029` | `RATE_LIMITED` | Infrastructure rate limit before tool dispatch |
| `-32028` | `AUTH_MISSING` | No credentials presented; auth rejected by middleware before tool dispatch |
| `-32027` | `SERVICE_UNAVAILABLE` | Infra health check fails, upstream down |
These codes are in the JSON-RPC server-defined range (`-32000` to `-32099`). All other AdCP error codes use the tool-level path exclusively.
> [!NOTE]
>
> **MCP server SDK note:** Throwing `McpError` from inside a tool handler produces a JSON-RPC error response — the SDK does **not** convert it to an `isError: true` tool result. This means `-32029` works the same way whether thrown from middleware or a tool handler. However, application-layer errors (where the tool understood the request and is returning a structured failure) should use the `isError: true` tool-level path above, not JSON-RPC error codes. Reserve `-32029`/`-32028`/`-32027` for infrastructure that rejects requests before tool dispatch.
### MCP Server Implementation
```javascript theme={null}
function adcpErrorResponse(error) {
const adcpError = {
code: error.code,
message: error.message,
recovery: error.recovery,
...(error.buyer_reason != null && { buyer_reason: error.buyer_reason }),
...(error.retry_after != null && { retry_after: error.retry_after }),
...(error.field != null && { field: error.field }),
...(error.suggestion != null && { suggestion: error.suggestion }),
...(error.details != null && { details: error.details }),
};
return {
content: [{ type: "text", text: JSON.stringify({ adcp_error: adcpError }) }],
isError: true,
structuredContent: { adcp_error: adcpError },
};
}
server.tool(
"get_products",
"Search product catalog",
{ query: z.string() },
async ({ query }) => {
try {
const products = await searchProducts(query);
return {
content: [{ type: "text", text: `Found ${products.length} products` }],
structuredContent: { products },
};
} catch (err) {
if (err.code && err.recovery) {
return adcpErrorResponse(err);
}
throw err;
}
}
);
```
## A2A Binding
### Failed Tasks
Use `status: "failed"` with the AdCP error in an artifact `DataPart`, plus a `TextPart` for human/LLM consumption:
```json theme={null}
{
"id": "task_456",
"status": {
"state": "failed",
"timestamp": "2025-01-22T10:30:00Z"
},
"artifacts": [{
"artifactId": "error-result",
"parts": [
{
"kind": "text",
"text": "Rate limit exceeded. Retry in 5 seconds."
},
{
"kind": "data",
"data": {
"adcp_error": {
"code": "RATE_LIMITED",
"message": "Request rate exceeded",
"retry_after": 5,
"recovery": "transient"
}
}
}
]
}]
}
```
This follows the [A2A Response Format](/dist/docs/3.2.8/building/by-layer/L0/a2a-response-format) conventions: final states use `.artifacts` for data.
**Relationship to the "no wrappers" rule.** The `adcp_error` key is an intentional exception for failed tasks. Unlike success responses where `DataPart` contains task-specific data (e.g., `products`), a failed task's `DataPart` contains only the error. The key acts as a type discriminator so clients can distinguish error from success payloads without relying solely on status.
### Error MIME Type (Optional)
A2A agents MAY set `metadata.mimeType` on the error `DataPart`:
```json theme={null}
{
"kind": "data",
"data": { "adcp_error": { "code": "RATE_LIMITED", "recovery": "transient" } },
"metadata": { "mimeType": "application/vnd.adcp.error+json" }
}
```
Clients MUST NOT require the MIME type. The `adcp_error` key is the authoritative signal.
## Envelope vs. payload errors
AdCP exposes errors in two distinct places. This page covers the **transport envelope** (`adcp_error`); the **payload errors array** (`errors[]`) is covered in [Error Handling — Envelope vs. payload errors](/dist/docs/3.2.8/building/by-layer/L3/error-handling#envelope-vs-payload-errors-the-two-layer-model).
| Layer | Key | When to populate | Readers |
| - | - | - | - |
| **Transport envelope** (this page) | `adcp_error` (MCP `structuredContent`, A2A `DataPart`, JSON-RPC `error.data`) | The task failed; transport needs a typed, extractable error signal | MCP hosts, A2A clients, `@adcp/sdk` |
| **Task payload** | `payload.errors[]` (or top-level `errors[]`) | The task ran; payload reports one or more issues (fatal or non-fatal warnings) | Business-logic consumers |
A fatal task failure SHOULD populate **both** layers — see the canonical `protocol-envelope.json` examples and the `error-handling.mdx` reference for the normative SHOULD.
## Client Detection Order
Clients MUST check for AdCP errors in this order:
1. **`structuredContent.adcp_error`** (with `isError: true`) — MCP tool-level error
2. **`artifacts[].parts[].data.adcp_error`** — A2A task-level error (artifacts)
3. **`status.message.parts[].data.adcp_error`** — A2A task-level error (status message)
4. **`error.data.adcp_error`** — JSON-RPC transport-level error
5. **JSON-parsed `content[].text` with `adcp_error` key** — Text fallback for older MCP servers (only for `isError` responses)
6. **`payload.errors[0]`** (or top-level `errors[0]`) — payload-layer fallback. Used when the transport envelope does not surface `adcp_error` but the payload carries an `errors[]` array. Reading from the payload is legitimate for non-fatal cases where only the payload layer is populated (e.g., `input-required` tasks reporting warnings), but a fatal task that surfaces errors only via the payload is a conformance gap on the agent side.
7. **No structured error found** — fall back to generic error handling.
Clients MUST validate that extracted errors have a `code` field of type `string`. If validation fails, treat as no structured error found.
### Storyboard `check: error_code` contract
Storyboard validators use `check: error_code` rather than path-specific assertions because the error may surface on either layer. The runner contract:
* `check: error_code` resolves the error code by running the [client detection order](#client-detection-order) above — preference in order: `adcp_error.code` (transport) → `errors[0].code` (payload).
* If neither layer carries a `code`, the validation fails with `error_code_not_resolvable`.
* Storyboard authors SHOULD NOT pin assertions to a specific path (e.g., `check: field_present, path: "errors"`) — that couples the test to one layer and fails against agents that surface errors on the other. See [Storyboard authoring — Asserting on errors](/dist/docs/3.2.8/contributing/storyboard-authoring#asserting-on-errors).
**Extraction vs. action.** The detection order above is the *extraction* layer — it returns the raw `adcp_error` object with field values preserved as-is (including out-of-range `retry_after`). Clamping, retry logic, and other behavioral requirements apply at the *action* layer (see [Recovery Behavior](#recovery-behavior)).
In practice, implementations branch on transport type first and only check the relevant paths:
```javascript MCP Client theme={null}
function extractAdcpErrorFromMcp(response) {
if (!response.isError) return null;
// 1. structuredContent (preferred)
if (response.structuredContent?.adcp_error) {
return validate(response.structuredContent.adcp_error);
}
// 2. Text fallback
if (response.content) {
for (const item of response.content) {
if (item.type === 'text' && item.text) {
try {
const parsed = JSON.parse(item.text);
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)
&& parsed.adcp_error) {
return validate(parsed.adcp_error);
}
} catch { /* not JSON */ }
}
}
}
return null;
}
// Reject malformed or oversized payloads
function validate(error) {
if (!error || typeof error !== 'object' || Array.isArray(error)) return null;
if (typeof error.code !== 'string') return null;
if (error.code.length === 0 || error.code.length > 64) return null;
if (JSON.stringify(error).length > 4096) return null;
return error;
}
// For JSON-RPC errors (caught as McpError)
function extractAdcpErrorFromMcpError(error) {
return validate(error.data?.adcp_error);
}
```
```javascript A2A Client theme={null}
function extractAdcpErrorFromA2a(task) {
// 1. Artifacts (preferred — final state data)
if (task.artifacts) {
for (const artifact of task.artifacts) {
const dataParts = (artifact.parts || []).filter(p => p.kind === 'data');
for (const part of dataParts) {
if (part.data?.adcp_error) {
return validate(part.data.adcp_error);
}
}
}
}
// 2. status.message.parts (some A2A implementations)
const parts = task.status?.message?.parts;
if (Array.isArray(parts)) {
for (const part of parts) {
if (part.kind === 'data' && part.data?.adcp_error) {
return validate(part.data.adcp_error);
}
}
}
return null;
}
```
## Recovery Behavior
Once extracted, apply recovery based on the `recovery` field:
| Recovery | Client Behavior |
| - | - |
| `transient` | Retry after `retry_after` seconds. When `retry_after` is absent or non-finite, use exponential backoff starting at the client's configured initial delay. |
| `correctable` | Surface `suggestion` and `field` to caller, do not auto-retry |
| `terminal` | Surface error to human operator, do not retry |
**`retry_after` bounds and migration:** AdCP 3.2 sellers MUST return an integer from 1 through 3600 seconds. A producer converting a computed fractional delay MUST round up before clamping (`ceil(delay)`, then clamp to `[1, 3600]`) so migration never schedules a retry earlier than intended. The 3.x schema continues to accept finite fractional values for backward compatibility with earlier producers; clients that encounter one MUST apply the same ceiling-then-clamp rule. Non-finite values (`NaN`, `Infinity`) MUST be treated as absent. This prevents both aggressive retry loops and pathologically long stalls from misconfigured servers.
**Retry ceiling:** Buyer agents MUST enforce a bounded retry budget per operation, such as a maximum count of 3 retries and a maximum cumulative retry duration of 300 seconds. Every scheduled retry consumes that budget. Transient errors that persist beyond it are surfaced to the caller or operator without another automatic retry. Without a ceiling, a malicious or misconfigured seller returning `retry_after: 3600` on every request can stall an agent indefinitely.
**When `recovery` is absent:** Fall back to code-based classification using the standard error code table. This allows legacy [Level 1](/dist/docs/3.2.8/building/by-layer/L3/error-handling#compliance-levels) servers (which return `code` + `message` only) to still get correct recovery behavior from capable clients. If the code is also unknown, use the bounded `transient` fallback.
For unknown `recovery` values (forward compatibility), treat as `terminal`.
```javascript theme={null}
// Standard code → recovery mapping for when recovery field is absent
const CODE_RECOVERY = {
RATE_LIMITED: 'transient',
SERVICE_UNAVAILABLE: 'transient',
CONFLICT: 'transient',
INVALID_REQUEST: 'correctable',
AUTH_MISSING: 'correctable',
AUTH_INVALID: 'terminal',
AUTH_REQUIRED: 'correctable', // deprecated alias for AUTH_MISSING
POLICY_VIOLATION: 'correctable',
PRODUCT_NOT_FOUND: 'correctable',
PRODUCT_UNAVAILABLE: 'correctable',
PROPOSAL_EXPIRED: 'correctable',
PROPOSAL_NOT_FOUND: 'correctable',
MULTI_FINALIZE_UNSUPPORTED: 'correctable',
REQUOTE_REQUIRED: 'correctable',
BUDGET_TOO_LOW: 'correctable',
CREATIVE_REJECTED: 'correctable',
UNSUPPORTED_FEATURE: 'correctable',
AUDIENCE_TOO_SMALL: 'correctable',
ACCOUNT_MOVED: 'correctable',
ACCOUNT_IDENTITY_CONFLICT: 'correctable',
ACCOUNT_SETUP_REQUIRED: 'correctable',
ACCOUNT_AMBIGUOUS: 'correctable',
COMPLIANCE_UNSATISFIED: 'correctable',
GOVERNANCE_DENIED: 'correctable',
MEDIA_BUY_NOT_FOUND: 'correctable',
PACKAGE_NOT_FOUND: 'correctable',
CREATIVE_NOT_FOUND: 'correctable',
SIGNAL_NOT_FOUND: 'correctable',
SESSION_NOT_FOUND: 'correctable',
SESSION_TERMINATED: 'correctable',
REFERENCE_NOT_FOUND: 'correctable',
VALIDATION_ERROR: 'correctable',
ACCOUNT_NOT_FOUND: 'terminal',
ACCOUNT_PAYMENT_REQUIRED: 'terminal',
ACCOUNT_SUSPENDED: 'terminal',
BUDGET_EXHAUSTED: 'terminal',
CONFIGURATION_ERROR: 'terminal',
};
function getRecovery(adcpError) {
if (adcpError.recovery !== undefined) return adcpError.recovery;
return CODE_RECOVERY[adcpError.code] || 'transient';
}
function handleAdcpError(adcpError, retryState) {
switch (getRecovery(adcpError)) {
case 'transient': {
if (retryState.retriesAttempted >= retryState.maxRetries) {
return { action: 'stop_retrying' };
}
const raw = adcpError.retry_after;
const delay = Number.isFinite(raw) ? Math.max(1, Math.min(3600, Math.ceil(raw))) : null;
return {
action: 'retry',
delaySeconds: delay,
nextRetryState: {
...retryState,
retriesAttempted: retryState.retriesAttempted + 1,
},
};
}
case 'correctable':
return {
action: 'fix_request',
field: adcpError.field,
suggestion: adcpError.suggestion,
};
case 'terminal':
return { action: 'escalate', message: adcpError.message };
default:
// Unknown recovery value: treat as terminal
return { action: 'escalate', message: adcpError.message };
}
}
```
## Recommended `details` Shapes
The `details` field is an open object. To prevent interoperability divergence, sellers SHOULD use these standard keys when populating `details` for common error codes:
### `RATE_LIMITED`
```json theme={null}
{
"code": "RATE_LIMITED",
"retry_after": 5,
"recovery": "transient",
"details": {
"limit": 100,
"remaining": 0,
"window_seconds": 60,
"scope": "account"
}
}
```
| Key | Type | Description |
| - | - | - |
| `limit` | number | Maximum requests allowed in the window |
| `remaining` | number | Requests remaining in the current window |
| `window_seconds` | number | Duration of the rate-limit window |
| `scope` | string | What the limit applies to: `account`, `tool`, or `global` |
### `BUDGET_TOO_LOW`
```json theme={null}
{
"code": "BUDGET_TOO_LOW",
"recovery": "correctable",
"details": {
"minimum_budget": 500,
"currency": "USD"
}
}
```
| Key | Type | Description |
| - | - | - |
| `minimum_budget` | number | Seller's minimum budget for this product |
| `currency` | string | ISO 4217 currency code |
### `AUDIENCE_TOO_SMALL`
```json theme={null}
{
"code": "AUDIENCE_TOO_SMALL",
"recovery": "correctable",
"details": {
"minimum_size": 10000,
"current_size": 2500
}
}
```
| Key | Type | Description |
| - | - | - |
| `minimum_size` | number | Minimum audience size required |
| `current_size` | number | Current audience size |
### `ACCOUNT_SETUP_REQUIRED`
```json theme={null}
{
"code": "ACCOUNT_SETUP_REQUIRED",
"recovery": "correctable",
"details": {
"setup_url": "https://seller.example.com/setup/acct_123",
"setup_steps": ["Accept terms of service", "Add payment method"]
}
}
```
| Key | Type | Description |
| - | - | - |
| `setup_url` | string | URL where account setup can be completed |
| `setup_steps` | string\[] | Steps remaining before the account is ready |
### `CREATIVE_REJECTED`
This code covers content-policy, brand-safety, and accessibility-review
failures. Policy failures may use the legacy policy detail keys below.
Accessibility failures SHOULD instead use the bounded experimental
[`accessibility-violation.json`](https://adcontextprotocol.org/schemas/3.2.1/error-details/accessibility-violation.json)
shape.
```json theme={null}
{
"code": "CREATIVE_REJECTED",
"recovery": "correctable",
"suggestion": "Revise creative to comply with alcohol advertising policy",
"details": {
"policy_id": "alcohol-advertising-v2",
"policy_url": "https://seller.example.com/policies/alcohol-advertising",
"reasons": ["Contains health claims not permitted for alcohol products"]
}
}
```
| Key | Type | Description |
| - | - | - |
| `policy_id` | string | Identifier for the violated policy |
| `policy_url` | string | URL where the full policy can be reviewed |
| `reasons` | string\[] | Specific reasons the creative was rejected |
Structured accessibility details are diagnostic data, not recovery commands.
Clients select the recovery class from `code` and `recovery` only. After schema
validation, they may resolve a violation pointer against an immutable copy of
the original request for UI highlighting or controlled repair, but only when it
targets an allowlisted creative asset location. They MUST NOT execute the
pointer as a dynamic mutation path, treat `/creative_id` as a nested asset path,
or pass raw remediation text to an LLM as instructions.
### `POLICY_VIOLATION`
```json theme={null}
{
"code": "POLICY_VIOLATION",
"recovery": "correctable",
"details": {
"policy_id": "targeting-restrictions-v3",
"policy_url": "https://seller.example.com/policies/targeting",
"violated_rules": ["No age-based targeting for financial products"]
}
}
```
| Key | Type | Description |
| - | - | - |
| `policy_id` | string | Identifier for the violated policy |
| `policy_url` | string | URL where the full policy can be reviewed |
| `violated_rules` | string\[] | Specific rules that were violated |
### `CONFLICT`
```json theme={null}
{
"code": "CONFLICT",
"recovery": "transient",
"message": "Resource was modified since last read",
"details": {
"resource_id": "mb_12345",
"expected_version": 3,
"current_version": 5
}
}
```
| Key | Type | Description |
| - | - | - |
| `resource_id` | string | Identifier of the conflicting resource |
| `expected_version` | number \| string | Version or ETag the client was operating against |
| `current_version` | number \| string | Current version or ETag on the server |
### Size Guidance
Sellers SHOULD keep `details` compact. Error responses flow through LLM context windows where every token has a cost — and transient errors that trigger retries can accumulate multiple error responses in a single conversation. As a guideline, keep `details` under 500 serialized JSON bytes (use `JSON.stringify(details).length` in UTF-8 — this matters for non-ASCII content).
### `details` Schemas
JSON Schemas for all recommended `details` shapes are published alongside the error code enum:
* [`/schemas/3.2.8/error-details/rate-limited.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/rate-limited.json)
* [`/schemas/3.2.8/error-details/budget-too-low.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/budget-too-low.json)
* [`/schemas/3.2.8/error-details/audience-too-small.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/audience-too-small.json)
* [`/schemas/3.2.1/error-details/account-moved.json`](https://adcontextprotocol.org/schemas/3.2.1/error-details/account-moved.json)
* [`/schemas/3.2.8/error-details/account-setup-required.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/account-setup-required.json)
* [`/schemas/3.2.8/error-details/creative-rejected.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/creative-rejected.json)
* [`/schemas/3.2.1/error-details/accessibility-violation.json`](https://adcontextprotocol.org/schemas/3.2.1/error-details/accessibility-violation.json) (experimental `CREATIVE_REJECTED` details)
* [`/schemas/3.2.8/error-details/policy-violation.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/policy-violation.json)
* [`/schemas/3.2.8/error-details/conflict.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/conflict.json)
* [`/schemas/3.2.8/error-details/execution-requirement-unmet.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/execution-requirement-unmet.json) (experimental `VALIDATION_ERROR` details for unmet product execution requirements)
Accessibility violation pointers follow the same request-rooted convention as
core error pointers: `/creative_manifest/assets/hero_image` for
`build_creative`, or `/creatives/0/assets/hero_image` for a batched
`sync_creatives` request. They are never relative to the nested manifest.
When a stored manifest is addressed only by `creative_id`, use `/creative_id`;
the request contains no valid nested asset path.
These schemas are recommended unless the code's canonical definition explicitly requires a repair field. `ACCOUNT_MOVED`, for example, requires `details.current_account`; without it the caller cannot repair a tombstoned natural-key reference safely. For codes without such a requirement, sellers that omit `details` entirely are conformant and agents fall back to `code`, `message`, and `recovery` when details are absent or unexpected.
## Seller-Specific Error Codes
Sellers MAY use error codes not in the [standard vocabulary](https://adcontextprotocol.org/schemas/3.2.8/enums/error-code.json). To distinguish seller-specific codes from standard codes and avoid collisions between sellers:
* Seller-specific codes MUST use the format `X_{VENDOR}_{CODE}` (e.g., `X_STREAMHAUS_FLOOR_NOT_MET`)
* `{VENDOR}` MUST be an uppercase alphanumeric identifier (matching `/^[A-Z][A-Z0-9]{1,19}$/`) registered in the vendor error code registry
* `{CODE}` MUST be uppercase alphanumeric with underscores (matching `/^[A-Z][A-Z0-9_]{1,39}$/`)
* Agents MUST handle unknown codes by falling back to the `recovery` classification
* If `recovery` is absent on an unknown code, use the bounded `transient` fallback
* Sellers SHOULD register their vendor prefix and codes in the [vendor error code registry](https://adcontextprotocol.org/schemas/3.2.8/error-details/vendor-error-codes.json) by submitting a PR
```javascript theme={null}
function handleError(error) {
if (isStandardErrorCode(error.code)) {
// Handle per standard code semantics
return handleStandardError(error);
}
// Unknown/vendor code: fall back to recovery classification
return handleByRecovery(error);
}
```
## Client Library Requirements
Client libraries (like `@adcp/sdk`) that implement this spec MUST:
1. **Extract structured errors automatically.** Consumers should receive a typed error object with `code`, `recovery`, `retryAfter`, `field`, `suggestion`, and `details` — not a generic error with a message string.
2. **Implement the detection order.** Check all paths in order: `structuredContent`, artifacts, `status.message.parts`, `error.data`, text fallback.
3. **Validate extracted errors.** Verify that `code` is a non-empty string (max 64 characters) and that the total serialized payload does not exceed 4096 bytes. Discard payloads that fail validation.
4. **Guard text fallback with `isError`.** Only attempt JSON-based text extraction on MCP responses where `isError` is `true`. A successful response with JSON content MUST NOT be interpreted as an error.
5. **Expose recovery metadata.** The extracted error MUST expose the effective recovery classification: preserve wire `recovery` when present, otherwise use the registered class for a known code or bounded `transient` for an unknown code. Preserve `retry_after` when present so callers can schedule an eligible retry without re-parsing.
6. **Handle unknown recovery values.** Treat unknown `recovery` values as `terminal`.
7. **Clamp `retry_after`.** Values below 1 become 1, values above 3600 become 3600. Non-finite values (`NaN`, `Infinity`) MUST be treated as absent.
8. **Support text fallback.** Attempt `JSON.parse` on `content[].text` for MCP `isError` responses without `structuredContent`. This will be the primary extraction path until `structuredContent` adoption is widespread.
Client libraries MAY additionally:
* Auto-retry `transient` errors with exponential backoff when `retry_after` is present
* Expose a `retryPolicy` option for consumers to configure retry behavior
* Map standard error codes to typed error subclasses using the `STANDARD_ERROR_CODES` table
## Test Vectors
Machine-readable test vectors are available at [`/static/test-vectors/transport-error-mapping.json`](https://adcontextprotocol.org/test-vectors/transport-error-mapping.json). Each vector contains:
* `transport`: `mcp` or `a2a`
* `path`: extraction path (`structuredContent`, `jsonrpc_error`, `text_fallback`, `artifact`)
* `response`: the transport-specific response envelope
* `expected_error`: the AdCP error that should be extracted (or `null` for legacy servers)
* `expected_action`: `retry`, `surface_to_caller`, `escalate_to_human`, or `generic_error`
Client libraries SHOULD validate their extraction logic against these vectors.
## Error Translation in Agent Chains
When a seller agent calls upstream services (APIs, databases, other agents), upstream failures must be translated before returning to the caller.
**Rule 1: Translate upstream errors into AdCP error codes.** Do not pass through raw upstream errors. An HTTP 429 from a seller's internal API becomes `RATE_LIMITED`. A database connection timeout becomes `SERVICE_UNAVAILABLE`. The buyer should never see error formats from systems it has no relationship with.
**Rule 2: Classify recovery from the caller's perspective.** If the seller can fix the upstream issue without buyer action, the error is `transient` or `terminal` — not `correctable`. A `correctable` error means the *buyer* needs to change something. For example: if the seller's upstream creative review API rejects an ad, that is `correctable` (the buyer can revise the creative). But if the seller's internal billing system is down, that is `transient` (the buyer should retry) even though the upstream error might be a 500.
**Rule 3: Intermediaries preserve or translate, never drop.** An orchestrator sitting between buyer and seller (e.g., an agency agent routing to multiple sellers) MUST either:
* **Pass through** the AdCP error unchanged if the upstream is already AdCP-conformant, or
* **Translate** the error into a valid AdCP error if the upstream uses a different format
Intermediaries MUST NOT strip `buyer_reason`, `recovery`, `retry_after`, or `details` from errors they pass through. An intermediary MAY aggregate errors from multiple upstream sellers into an `errors` array, with each error preserving its original `code`, `buyer_reason`, and `recovery`.
```javascript theme={null}
// Seller-side: translate upstream errors for the buyer
function translateUpstreamError(upstreamError) {
if (upstreamError.status === 429) {
return {
code: 'RATE_LIMITED',
message: 'Request rate exceeded',
recovery: 'transient',
retry_after: upstreamError.headers?.['retry-after'] || 10,
};
}
if (upstreamError.status >= 500) {
return {
code: 'SERVICE_UNAVAILABLE',
message: 'Service temporarily unavailable',
recovery: 'transient',
};
}
// Never expose upstream details to the buyer
return {
code: 'SERVICE_UNAVAILABLE',
message: 'An internal error occurred',
recovery: 'transient',
};
}
```
## Security Considerations
Error responses flow through LLM context. Every field is client-facing.
### Seller Requirements
**Implementations MUST NOT include:**
* Internal service names, hostnames, or IP addresses
* Database error text, SQL fragments, or query plans
* Stack traces or file paths
* Upstream API responses from internal services
* Credentials, tokens, or session identifiers
**`suggestion` boundaries:** Provide generic correction guidance (e.g., "Increase budget to meet minimum") rather than revealing specific thresholds, valid identifiers, or resource existence.
**`retry_after` consistency:** Return consistent values reflecting the caller's rate-limit state, not the target resource's properties, to avoid timing side channels.
**Transport-level code granularity:** The reserved JSON-RPC codes (`-32029`, `-32028`, `-32027`) enable infrastructure error classification. Implementations that prefer to minimize endpoint fingerprinting MAY collapse these into a single code.
### Buyer Agent Requirements
**Prompt injection via error fields.** The `message`, `suggestion`, `field`, `details`, and all string values within them are seller-controlled content that enters buyer agent LLM context. A malicious or compromised seller can craft values containing instructions aimed at manipulating the buyer agent.
Buyer agents MUST:
* **Route all recovery decisions through `code` and `recovery` only.** Never parse `message`, `suggestion`, or `details` values for actionable instructions. The `handleAdcpError` function above demonstrates this pattern — it switches on `recovery`, not on message content.
* **Use data boundaries for seller-provided strings.** When including error field values in LLM context, place them inside explicit data delimiters (e.g., structured tool response fields, XML-style tags) that the system prompt designates as untrusted seller data. Do not interpolate seller-provided strings into prose or instructions.
* **Enforce length limits** before including seller strings in LLM context: `message` (256 bytes), `suggestion` (512 bytes). Truncate silently.
* **Strip non-printable characters** from all string fields: control characters (U+0000–U+001F), zero-width characters (U+200B–U+200F), and bidirectional override characters (U+202A–U+202E).
* **Enforce a maximum payload size.** Clients MUST discard extracted `adcp_error` objects where `JSON.stringify(error).length` exceeds 4096 bytes. This prevents context window exhaustion from oversized `details` objects.
* **Never use `field` as a dynamic property path** in object mutation operations (e.g., `lodash.set`, bracket notation chains). The `field` value is for display and field-level UI highlighting only.
* **Never merge extracted error objects into application state** via `Object.assign`, spread operators, or shallow copy without filtering keys. Seller-controlled keys like `__proto__` or `constructor` can trigger prototype pollution in some runtimes.
* **Never include raw `details` objects** in system prompts or tool descriptions.
**URL validation.** `details.setup_url` (in `ACCOUNT_SETUP_REQUIRED` errors) is a seller-provided URL that users or agents may follow to complete account setup. Clients MUST validate that `setup_url` uses the `https` scheme, contains no userinfo component (e.g., `https://user:pass@evil.com`), and that the domain matches the seller's known domain. Clients MUST reject URLs that fail any of these checks.
`details.policy_url` (in `CREATIVE_REJECTED` and `POLICY_VIOLATION` errors) is informational. Clients SHOULD apply the same validation. All seller-provided URLs MUST be rejected if they use non-`https` schemes (`http`, `javascript`, `data`, `file`).
## See Also
* [Error Handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling) — error schema, standard codes, recovery strategies
* [MCP Guide](/dist/docs/3.2.8/building/by-layer/L0/mcp-guide) — MCP transport integration
* [A2A Guide](/dist/docs/3.2.8/building/by-layer/L0/a2a-guide) — A2A transport integration
* [A2A Response Format](/dist/docs/3.2.8/building/by-layer/L0/a2a-response-format) — canonical A2A response structure
# Schemas & SDKs
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/schemas-and-sdks
Quick-start reference for AdCP schemas and client SDKs: installation, schema URLs, version discovery, and where to go next.
This page orients you to the two foundational resources for building with AdCP: the JSON schemas that define every request and response, and the SDKs that turn those schemas into typed code.
## SDKs
AdCP ships official SDKs for TypeScript, Python, and Go. Each SDK absorbs the protocol layers (wire format, signing, auth, lifecycle semantics) so you write business logic only.
> [card] [TypeScript](https://www.npmjs.com/package/@adcp/sdk)
>
> `npm install @adcp/sdk`
> [card] [Python](https://pypi.org/project/adcp/)
>
> `pip install adcp`
> [card] [Go](https://github.com/adcontextprotocol/adcp-go)
>
> `go get github.com/adcontextprotocol/adcp-go`
For the full coverage matrix (which layers each SDK ships today), version pinning guidance, and package export details, see [Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk).
For the layered model behind the SDKs — what L0 through L4 each contain and why SDKs matter more in AdCP than in simpler protocols — see the [SDK stack reference](/dist/docs/3.2.8/building/cross-cutting/sdk-stack).
## Schema URLs
AdCP schemas are published at `https://adcontextprotocol.org/schemas/` under the current major-version alias:
| Pattern | Example | Use |
| - | - | - |
| **Current major** | `https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-request.json` | Pin validators to the AdCP 3.x schema family |
Schemas cover every task's request and response, shared enums, governance objects, creative formats, and signal definitions. Use the current major-version URL in production and CI so links stay stable across major releases.
For how wire-level `adcp_protocol_version` relates to schema bundle versions, and why those are different things, see [Versioning & governance](/dist/docs/3.2.8/reference/versioning).
## Authorization in adagents.json
Publishers declare their agent endpoints and authorization scopes in `adagents.json`. The schema supports six authorization types — `property_ids`, `property_tags`, `inline_properties`, `publisher_properties`, `signal_ids`, and `signal_tags` — each scoping which inventory the agent is authorized to act on.
For the full authorization type reference and worked examples, see [Authorization Patterns](/dist/docs/3.2.8/governance/property/adagents#authorization-patterns) in the governance docs.
## Validate an unreleased schema in both SDKs
Schema-changing pull requests build a deterministic protocol bundle and run both the TypeScript and Python generators against it. The check records three machine-readable values in `latest.tgz.provenance.json`: the protocol commit, the bundle SHA-256, and the published-version label. A passing SDK job therefore identifies the exact protocol input it consumed.
For same-repository pull requests, the workflow also publishes an immutable tuple keyed by the full head commit:
```text theme={null}
https://adcontextprotocol.org/protocol/pr//latest.tgz
https://adcontextprotocol.org/protocol/pr//latest.tgz.sha256
https://adcontextprotocol.org/protocol/pr//latest.tgz.provenance.json
```
These bundles are unsigned development artifacts. Verify the checksum and provenance before using one, and never use a PR bundle in production.
Preview bundles are retained for 90 days by default and removed by a daily cleanup job. Maintainers can change the window with the `SCHEMA_PR_BUNDLE_RETENTION_DAYS` repository variable. Rerun the protocol validation workflow to recreate an expired bundle for a still-current commit.
To reproduce the artifact locally after committing the protocol inputs, run:
```bash theme={null}
scripts/build-schema-pr-bundle.sh
```
The script derives both the source commit and deterministic timestamp from `HEAD`, refuses uncommitted bundle inputs, and writes the same three files under `dist/protocol/`.
When creating a dependent SDK pull request:
1. Copy the three artifact URLs from the protocol workflow summary.
2. Regenerate with the SDK repository's supported local-bundle input and commit its provenance metadata with the generated output.
3. Put the full protocol commit and bundle SHA-256 in the dependent pull request body.
4. After every protocol force-push or rebase, use the new head-SHA URL, regenerate, and confirm the old commit no longer appears in generated metadata or the pull request description.
The preview workflow is intentionally triggered only by changes under `static/schemas/source/**`. Once triggered, its TypeScript and Python jobs validate the complete bundle rather than only the changed schema files. Changes limited to compliance sources, the OpenAPI registry, or build tooling remain covered by their normal CI checks but do not publish a schema preview bundle.
## Where to go next
> [card] [Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk)
>
> Coverage matrix, install commands, and version pinning for each language.
> [card] [Build an agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent)
>
> Skill files and step-by-step guide for building a seller agent.
> [card] [Build a caller](/dist/docs/3.2.8/building/by-layer/L4/build-a-caller)
>
> Buyer-side reference for discovering capabilities and handling responses.
> [card] [Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent)
>
> Run the compliance suite to verify your implementation.
# AAO Verified
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/aao-verified
The public trust mark for AdCP agents: what evidence was observed, which grading policy evaluated it, and how to verify the result.
**Status**: Owner-selectable grading rollout
**Last Updated**: September 16, 2026
**AAO Verified** is AgenticAdvertising.org's public trust mark for AdCP agents.
Each badge applies to one exact `(agent URL, role, AdCP version)` and answers two
separate questions:
1. **What evidence did AgenticAdvertising.org observe?** The badge's
`verification_modes` answer this question.
2. **Which grading policy evaluated that evidence?** The badge's
`grading_profile` answers this question.
Do not infer the grading profile from a verification mode. In particular,
`spec` can appear in both fields with different meanings.
## Evidence modes
Evidence modes describe what was exercised or observed. They are not grading
levels.
| Mode | Meaning |
| - | - |
| **Spec** (`"spec"`) | AdCP storyboards exercised the agent's declared protocol behavior. |
| **Live** (`"live"`) | AgenticAdvertising.org observed qualifying production traffic. |
An active badge always has at least one evidence mode. A badge may show
`(Spec)`, `(Live)`, or `(Spec + Live)`. `sandbox` is not a
`verification_modes` value.
## Grading profiles
The grading profile is the policy used to decide whether the collected evidence
supports the public badge.
| Profile | Public status | Meaning |
| - | - | - |
| **Legacy grading** (`"legacy"`) | Available and owner-selectable | The established grading policy. Historical badges and older tokens without a `grading_profile` claim are treated as Legacy. |
| **Strict Spec grading** (`"spec"`) | Available and owner-selectable | A stricter evaluation of the same evidence, including required storyboard, completeness, and skip-reason rules. |
| **Sandbox grading preview** | Preview only | A diagnostic comparison. It cannot be selected and cannot issue or relabel a public badge. |
Sandbox grading remains preview-only until causal bundle data is available and a
public, versioned exception catalog has shipped. Its presence in an owner
dashboard is not a promise that Sandbox grading will become selectable on a
particular date.
> [!NOTE]
>
> **Evidence mode and grading profile are orthogonal.** A badge can, for example,
> show `(Spec) · Legacy grading` or `(Spec) · Strict Spec grading`. The first
> `Spec` says which evidence was collected; the second says which policy judged
> it.
## Reading a badge
The visible SVG includes the role, AdCP version, evidence mode, and grading
profile:
| Display | Meaning |
| - | - |
| `AAO Verified Media Buy Agent 3.1 (Spec) · Legacy grading` | Spec storyboard evidence supports the 3.1 media-buy badge under Legacy grading. |
| `AAO Verified Media Buy Agent 3.1 (Spec) · Strict Spec grading` | The same evidence category supports that exact badge under Strict Spec grading. |
| `AAO Verified — Not Verified` | No active badge exists for that exact role and version. |
The profile suffix is part of the public meaning. Do not remove it from copied
alt text or replace it with the evidence qualifier.
## Declare specialisms
```json theme={null}
// agent declares its claims in get_adcp_capabilities
{
"supported_protocols": ["media_buy", "creative"],
"specialisms": [
"sales-broadcast-tv",
"sales-guaranteed",
"creative-ad-server"
]
}
```
`specialisms` routes evidence to role-specific badges. Omitting it does not stop
universal and protocol-baseline storyboards from running, but the verification
engine has no narrow specialism claim from which to issue a public badge.
Badge issuance also requires an active AgenticAdvertising.org membership at an
API-access tier.
## Selecting a grading profile
An organization owner or administrator can select Legacy or Strict Spec grading
from the agent dashboard when a current comparison is available.
Selection is deliberately narrow:
* It changes one exact `(agent URL, role, AdCP version)` only.
* It uses a current immutable assessment from one source run.
* It does not contact or re-run the agent.
* A stale, incomplete, missing, or superseded assessment cannot be selected.
* Sandbox grading preview cannot be selected.
Before confirmation, the dashboard shows the server-computed public effect and,
when relevant, the grace deadline. Depending on the current evidence and badge
state, selection can leave the badge unchanged, issue it, restore it, regrade it
without changing lifecycle status, degrade it, or revoke it. A degrade or revoke
effect requires explicit acknowledgement.
### Roll back to Legacy grading
Legacy remains an owner-selectable production profile. An owner can revert one
exact role and version from Strict Spec to Legacy when the dashboard offers a
current Legacy assessment. Rollback uses the same authorization, freshness,
revision, audit, and public-impact checks as selection in the other direction.
It is not an agent-wide reset.
The dashboard and registry are authoritative after a selection. If refreshed
offline tokens are still being generated, the selection succeeds and the
dashboard reports that token refresh is pending.
## Decentralized verification
Each active badge is backed by a signed JWT (EdDSA / Ed25519).
AgenticAdvertising.org publishes its public keys at `/.well-known/jwks.json`.
```json theme={null}
{
"iss": "https://aao.org",
"sub": "https://your-agent.example.com/mcp",
"aud": "aao-verification",
"jti": "",
"iat": 1789516800,
"exp": 1792108800,
"role": "media-buy",
"adcp_version": "3.1",
"verified_specialisms": ["sales-broadcast-tv", "sales-guaranteed"],
"verification_modes": ["spec"],
"grading_profile": "spec",
"protocol_version": "3.1.0"
}
```
Verifiers must check all of the claims relevant to their decision:
* `sub`, `role`, and `adcp_version` identify the exact badge.
* `verification_modes` says which evidence was observed.
* `grading_profile` says whether Legacy or Strict Spec grading produced it.
* `exp`, signature, issuer, and audience establish token validity.
Tokens issued before grading profiles were added may omit `grading_profile`.
Interpret a missing claim as `legacy`; never reinterpret an old token as Strict
Spec grading.
The registry API is authoritative for real-time status. A JWT is an offline,
cacheable proof that can remain valid for up to 30 days and cannot learn about a
later profile selection, degradation, revocation, membership lapse, or opt-out.
Applications that need current status must check the registry.
## Lifecycle
Verification is continuously re-evaluated, not a one-time certificate.
* **Issued** — qualifying evidence and all non-evidence eligibility checks pass.
* **Active** — the selected profile continues to pass on current evidence.
* **Degraded** — a qualifying regression starts the existing 48-hour grace
period; the registry exposes the state and deadline.
* **Revoked** — the badge no longer qualifies after the applicable grace or an
immediate-revocation event.
* **Recovered** — later passing evidence can restore or issue the badge.
A membership lapse or compliance opt-out revokes the public badge regardless of
grading profile. Re-enabling monitoring requires fresh qualifying evidence;
partial reruns do not silently restore an earlier badge.
## Legacy grading sunset
Legacy is not automatically deprecated or relabeled by this rollout.
* The working group will review Legacy no earlier than six months after
owner-selectable grading launches.
* Legacy cannot retire earlier than 12 months after that launch.
* Any proposed retirement requires at least 90 days' public notice.
* Existing Legacy selections and claim-less historical tokens are never
automatically relabeled as Strict Spec.
* Retirement timing and migration behavior require a future working-group
decision; there is no automatic retirement deadline today.
Until those conditions are met and a later decision is published, Legacy is an
honest production profile and remains available for rollback.
## Per-version badges
Each badge is identified by `(agent URL, role, AdCP version)`. An agent can hold
parallel badges across AdCP releases and can select a different grading profile
for each exact role/version pair. A 3.0 selection or regression does not change
the 3.1 badge.
The version is embedded in the visible label, for example:
`Media Buy Agent 3.1 (Spec) · Strict Spec grading`.
## Display and embedding
Two SVG URL shapes are available:
```text theme={null}
# Auto-upgrades to the highest active version for the role
https://agenticadvertising.org/api/registry/agents/{url-encoded-agent-url}/badge/{role}.svg
# Pins one exact AdCP release
https://agenticadvertising.org/api/registry/agents/{url-encoded-agent-url}/badge/{role}/{adcp-version}.svg
```
Use the version-pinned URL when your claim is about a specific AdCP version.
The unversioned URL can change to a newer active badge without the embed URL
changing. Both SVG forms revalidate using ETags.
Unknown agents, opted-out agents, and revoked or never-earned exact badges
return a grey `Not Verified` SVG. To decide whether to render a badge at all,
query the exact versioned embed endpoint during server-side rendering or a
static-site build:
```javascript test=true integration=true theme={null}
const agentUrl = "https://seller.example.com/mcp";
const role = "media-buy";
const version = "3.1";
const encodedUrl = encodeURIComponent(agentUrl);
const endpoint = `https://agenticadvertising.org/api/registry/agents/${encodedUrl}/badge/${role}/${version}/embed`;
const response = await fetch(endpoint);
if (!response.ok) throw new Error("Could not check AgenticAdvertising.org verification");
const embed = await response.json();
const badgeHtml = embed.verified ? embed.html : "";
export { badgeHtml };
```
For bulk decisions, query
`/api/registry/agents/{url-encoded-agent-url}/verification` and match both `role`
and `adcp_version` in `badges[]`. Read `verification_modes` and
`grading_profile` independently.
## What AAO Verified is not
* **Not a Sandbox grading badge.** Sandbox is diagnostic preview only until its
data and catalog gates ship.
* **Not a regulatory, security, or financial audit.** Frameworks such as SOC 2,
ISO 27001, and ISAE 3402 address different controls.
* **Not an SLA.** The mark does not guarantee uptime, latency, inventory, or
commercial outcomes.
* **Not a substitute for due diligence.** Buyers should still assess contracts,
billing, governance, security, and incident response.
## Related documentation
* [Conformance Specification](/dist/docs/3.2.8/building/verification/conformance)
* [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog)
* [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities)
* [Maintaining your agent](/dist/docs/3.2.8/registry/maintaining-your-agent)
# Pair-program with Addie (Socket Mode)
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/addie-socket-mode
Connect your dev/staging AdCP agent to Addie via outbound WebSocket so she can run storyboards against it conversationally. No public DNS, no ngrok, no inbound exposure.
**Status**: Available in preview behind `CONFORMANCE_SOCKET_ENABLED`
**Last updated**: May 4, 2026
When you're building an AdCP agent, the most useful loop is: run a storyboard against your in-progress server, see what fails, fix it, run again. Until now that meant standing up a public sandbox endpoint with TLS, DNS, auth, and firewall config — a real lift before you've written meaningful code, and a non-trivial security review at larger orgs.
**Pair-programming with Addie via Socket Mode** collapses that to: install one library, paste a token, connect outbound. Addie sees your dev agent like any other AdCP server — no inbound exposure, no public surface — and can run any compliance storyboard against it in chat.
## When to use Socket Mode (and when not to)
| Use Socket Mode when… | Use the public-endpoint path when… |
| - | - |
| You're building or refactoring an agent and want fast feedback | You're ready for AAO's [(Spec) heartbeat](/dist/docs/3.2.8/building/verification/aao-verified) on a stable test endpoint |
| Your dev agent runs on `localhost`, a Codespace, or behind a firewall | Your platform exposes a public test endpoint anyway |
| You want Addie to run multiple storyboards interactively in chat | You want unattended, scheduled compliance runs |
| You're a small team without infra to expose a sandbox endpoint | You operate at scale and prefer batch CI |
Socket Mode is **not** a replacement for AAO Verified. Once your agent is stable, expose a real test endpoint and let the AAO heartbeat run continuously — that's what earns the public **AAO Verified (Spec)** badge. Socket Mode is the dev-loop channel before you get there (and after, when you're iterating on changes).
> [!NOTE]
>
> **Dev/staging only by design.** Socket Mode is gated to non-production deployments, the same constraint as [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) per [adcp#3986](https://github.com/adcontextprotocol/adcp/issues/3986). Production agents do not expose this channel and AAO never enrolls production deployments via Socket Mode.
## What you need
1. **An AdCP MCP server you're actively developing.** It can be incomplete — that's the point. The simplest case is a JS/TS process running on your laptop with the MCP SDK installed.
2. **An AAO account.** The conformance channel is bound to your WorkOS organization, so you need to be signed in to a member or trial org. Anonymous chat with Addie cannot use Socket Mode.
3. **`@adcp/sdk` ≥ 6.9** in your dev project. The `ConformanceClient` primitive ships from `@adcp/sdk/server`.
4. **Network egress to `addie.agenticadvertising.org` over WebSockets (port 443).** No inbound rules needed.
That's it. No public DNS, no firewall changes, no ngrok, no certificate provisioning.
## The five-minute setup
### Step 1 — Ask Addie for a token
In your Addie chat session, ask:
> Give me a fresh conformance token
Addie returns shell exports plus a copy-paste integration snippet:
```
**Conformance token issued.** Bound to your organization, expires in 1h.
Paste these into your dev environment and start the conformance client:
export ADCP_CONFORMANCE_URL=wss://addie.agenticadvertising.org/conformance/connect
export ADCP_CONFORMANCE_TOKEN=eyJ…
Three-line integration with @adcp/sdk ≥ 6.9: …
```
Tokens expire in one hour. When yours runs out, just ask Addie for a new one — there's no refresh endpoint by design.
### Step 2 — Wire `ConformanceClient` into your dev server
Three lines added to your existing AdCP server bootstrap:
```ts theme={null}
import { ConformanceClient } from '@adcp/sdk/server';
import { mcpServer } from './my-mcp-server';
const conformance = new ConformanceClient({
url: process.env.ADCP_CONFORMANCE_URL!,
token: process.env.ADCP_CONFORMANCE_TOKEN!,
server: mcpServer,
});
await conformance.start();
```
`mcpServer` is the same `Server` instance you'd connect to `StreamableHTTPServerTransport` for normal traffic — no separate setup, no parallel server. `ConformanceClient` exposes it bidirectionally over the outbound WebSocket; Addie sees a normal MCP server on the other end.
If you don't have an AdCP server yet, fork the [`hello_seller_adapter_social` example](https://github.com/adcontextprotocol/adcp-client/blob/main/examples/hello_seller_adapter_social.ts) — it's a worked starting point with the SDK's `createAdcpServerFromPlatform` helper.
### Step 3 — Confirm the connection
Run your dev server with the token and URL exported. You should see a status line:
```
[conformance] status=connecting
[conformance] status=connected
```
Once `status=connected` lands, Addie has a live MCP client pointed at your dev server. The session stays open until you stop the process or your token expires.
### Step 4 — Run a storyboard from chat
Back in Addie chat:
> Run [`media_buy_state_machine`](/compliance/latest/protocols/media-buy/state-machine.yaml) against my agent
Addie dispatches the storyboard through the open socket and renders the result as a markdown report in chat:
```
### Conformance result — Media buy state machine lifecycle (media_buy_state_machine)
**Overall:** ✅ PASSED
**Steps passed/failed/skipped:** 8 / 0 / 1
**Duration:** 1240 ms
#### ✓ Capability discovery
- ✓ passed — Check agent capabilities
#### ✓ Create a media buy
- ✓ passed — Discover products for media buy
- ✓ passed — Create the test media buy
#### ✓ Valid state transitions
- ✓ passed — Pause the media buy
- ✓ passed — Resume the media buy
- ✓ passed — Cancel the media buy
…
```
Failing steps include trimmed error text so you can fix in place and re-run without leaving the chat. Iterate until green.
You can run any storyboard in the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) this way — sales, creative, signals, governance, signed requests, etc. Ask Addie what's available if you're not sure: *"What conformance storyboards apply to a sales agent?"*
## What Addie can do once you're connected
Beyond storyboard runs, the live MCP channel lets Addie:
* **Diagnose failing steps interactively** — when a step fails, ask "why?" and Addie can re-call the same tool with different inputs to narrow the root cause
* **Validate capability declarations** — *"Does my [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) claim what I actually implement?"*
* **Walk lifecycle states** — if you've wired [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller), Addie can drive deterministic state transitions and observe the results
* **Suggest fixes against your real wire output** — *"Your `error_code` field is missing on this rejection — here's the fix"* — based on bytes she just saw, not generic advice
## Privacy & safety
The Socket Mode channel is built to keep the surface narrow:
* **Dev/staging only.** Production deployments must not expose this channel — same deployment-scoped rule as [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) ([adcp#3986](https://github.com/adcontextprotocol/adcp/issues/3986)).
* **Outbound from you.** Your dev box opens the connection to Addie. Addie has no way to reach into your network.
* **Session-scoped.** You start the client; it runs until you stop the process. No persistent tunnel, no daemon.
* **Org-scoped.** The token's WorkOS org claim is the only tenant boundary. Other orgs cannot reach your agent over the channel.
* **Disconnect anytime.** Kill the client process and the socket closes; Addie's session for your org evicts immediately.
* **What Addie sees stays in your Addie context.** Same data-handling posture as anything else you tell her in chat.
If you'd prefer to inspect the channel yourself, the wire format is plain JSON-RPC 2.0 frames (the same shape MCP already uses) over `wss://`. Run `wscat` against the URL with your token and you'll see exactly what Addie sees.
## Troubleshooting
### Addie says "you're not mapped to an organization"
You're chatting with Addie anonymously or your account isn't bound to a WorkOS org yet. Sign in to your member or trial org and try again.
### `status=error` on connect; the server logs `401 Unauthorized`
Token expired (1h TTL) or wrong token. Ask Addie for a fresh one. If a new token also 401s, your AAO membership may not have the conformance entitlement enabled — check your org's plan.
### Storyboard report shows step 1 failed with `unknown tool get_adcp_capabilities`
Your dev MCP server doesn't yet implement [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). That's the discovery tool every AdCP agent must expose. Implement it before running any storyboard — see [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) for the response shape.
### Addie says "no conformance connection is live for your org"
The socket isn't open. Either you haven't started the client yet, or it disconnected. Restart `ConformanceClient` and confirm `status=connected` before asking Addie to run anything.
### Socket connects but every storyboard step skips
Your `get_adcp_capabilities` response declares specialisms you haven't implemented. The runner skips steps that don't match the declared surface. Either implement the tools or trim the declaration.
### How do I know what Addie is doing on the channel?
The `onStatus` callback exposes every state transition (`connecting`, `connected`, `disconnected`, `error`). Pipe it to your dev logs:
```ts theme={null}
new ConformanceClient({
url, token, server: mcpServer,
onStatus: (status, detail) => {
console.log(`[conformance] status=${status}`,
detail?.attempt ? `attempt=${detail.attempt}` : '',
detail?.error ? `error=${detail.error.message}` : '');
},
});
```
For tool-level visibility, log inside your `setRequestHandler` callbacks — Addie's calls land there exactly like normal MCP traffic.
## Reference
* [`@adcp/sdk/server` `ConformanceClient`](https://github.com/adcontextprotocol/adcp-client/blob/main/src/lib/server/socket-mode/conformance-client.ts) — adopter-side primitive
* [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) — the discovery tool every storyboard starts with
* [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) — full list of available storyboards
* [Get Test-Ready](/dist/docs/3.2.8/building/verification/get-test-ready) — what your agent needs in place before any storyboard can pass
* [AAO Verified](/dist/docs/3.2.8/building/verification/aao-verified) — the public trust mark you graduate to once your agent is stable
* Channel design: [adcp#3991](https://github.com/adcontextprotocol/adcp/issues/3991)
* Deployment-scoped controller rule: [adcp#3986](https://github.com/adcontextprotocol/adcp/issues/3986)
# Compliance Catalog
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/compliance-catalog
Full index of AdCP protocols and specialisms an agent can claim — what each one means, which compliance storyboards run, and where to find the source YAML.
Every AdCP agent declares its `supported_protocols` and `specialisms` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). Each declaration maps to a compliance bundle at `/compliance/{version}/` that the storyboard runner executes to verify the claim.
> [!NOTE]
>
> **`supported_protocols` is not exhaustive.** The `accounts` surface ([`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts), [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts), [`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance)) is a foundation implicit in every `media_buy`, `creative`, and `signals` agent and is intentionally not a `supported_protocols` value. See [Accounts tasks](/dist/docs/3.2.8/accounts/tasks/sync_accounts) for the full account surface.
This page is the human-readable index of that taxonomy. The machine-readable equivalent is `/compliance/{version}/index.json`.
## Universal storyboards
Every agent runs every graded storyboard in `/compliance/{version}/universal/` regardless of which protocols or specialisms it claims. A few are *capability-gated* — they only run when the agent advertises the relevant capability — but the storyboard is still universal in scope: any agent claiming the capability is graded by it. Failing a universal storyboard fails overall compliance. Non-executable schemas and support fixtures shipped in the universal bundle are not runner scenarios and do not appear in this table.
| Graded storyboard | Purpose | Source |
| - | - | - |
| `account-identity-reconciliation` | Deprecated in 3.3 with account.identity_updates. Validates revision-guarded operator identity rekeying, collision safety, and former-key redirects for sellers that advertise identity updates. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/account-identity-reconciliation.yaml) |
| `account-requests` | Opens a fresh sandbox account with request_account, reads the request back through list_accounts, checks the change rules (revision guards, fields that never change, unreachable accounts), and drives the change outcomes: updated, a separate account only with allow_separate_account and its distinct refusal code, matched to an account the caller holds, a buyer sign-up action, reduced and revoked grants, and a seller review that resolves on the sandbox clock. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/account-requests.yaml) |
| `agent-notification-configs` | Validates the 3.2 agent-level capabilities.changed registration surface: advertised revision fencing, NO_AUTH rejection, and dry-run clear semantics. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/agent-notification-configs.yaml) |
| `billing-gate-dispatch` | Validates that account.supported_billing is declared and honored by sync_accounts, including out-of-set BILLING_NOT_SUPPORTED rejection, recovery-value consistency, and the distinct per-buyer-agent BILLING_NOT_PERMITTED_FOR_AGENT gate. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/billing-gate-dispatch.yaml) |
| `canonical-format-validate-input` | Validates 3.1 canonical-format dry-run semantics: structural pass/fail across canonical slots and unvalidatable_nondeterministic for seeded products. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/canonical-format-validate-input.yaml) |
| `capability-discovery` | Buyer calls get_adcp_capabilities to discover what an agent supports before making any buying or creative decisions. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/capability-discovery.yaml) |
| `collection-lists-pagination-integrity` | Validates the cursor↔has_more invariant by walking a paginated list_collection_lists response from a continuation page to a terminal page. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/collection-lists-pagination-integrity.yaml) |
| `comply-controller-mode-gate` | Verifies that a seller exposing comply_test_controller refuses calls from live-mode (non-sandbox) accounts with FORBIDDEN. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/comply-controller-mode-gate.yaml) |
| `content-standards-pagination-integrity` | Validates the cursor↔has_more invariant by walking a paginated list_content_standards response from a continuation page to a terminal page. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/content-standards-pagination-integrity.yaml) |
| `ctv-experience-validate-input` | Validates AdCP 3.2 ctv_ad_experience matrix pairings, duration/interactivity constraint profiles, the menu focus/video pairing, and non-blocking activation-copy warnings via validate_input against seeded CTV products. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/ctv-experience-validate-input.yaml) |
| `deterministic-testing` | Uses comply_test_controller to force state transitions and simulate delivery/budget, verifying state machines and reporting. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/deterministic-testing.yaml) |
| `error-compliance` | Validates that agents return properly structured AdCP errors with correct codes, recovery hints, and transport bindings. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/error-compliance.yaml) |
| `error-compliance-signals` | Checks discovery error codes, context echo, and protocol versions for owned and marketplace signals agents. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/error-compliance-signals.yaml) |
| `get-media-buys-pagination-integrity` | Validates that get_media_buys responses carry a well-formed pagination envelope honoring the cursor↔has_more invariant. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/get-media-buys-pagination-integrity.yaml) |
| `get-products-pagination-integrity` | Validates get_products wholesale-mode pagination by walking a seeded product feed from continuation to terminal, while documenting that brief/refine pagination caps returned products in curated results. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/get-products-pagination-integrity.yaml) |
| `get-signals-pagination-integrity` | Validates the cursor↔has_more invariant on a paginated get_signals response by walking from a continuation page to the next page under a broad query. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/get-signals-pagination-integrity.yaml) |
| `idempotency` | Validates that mutating requests enforce idempotency_key — replays return cached responses even after resource purge, key reuse with a different payload returns IDEMPOTENCY_CONFLICT, fresh keys create new resources, and concurrent retries with the same key produce exactly one resource (first-insert-wins under rule 9). | [YAML](https://adcontextprotocol.org/compliance/latest/universal/idempotency.yaml) |
| `notification-config-event-scope` | Validates that sync_accounts.accounts\[].notification_configs\[] rejects media-buy-anchored notification types. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/notification-config-event-scope.yaml) |
| `notification-config-lifecycle` | Validates account-level notification_configs\[] lifecycle behavior on sync_accounts: paused registration, durable echo, subscriber-keyed replacement, and clear. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/notification-config-lifecycle.yaml) |
| `notification-config-rejections` | Validates account-level notification_configs\[] semantic rejection for duplicate subscriber keys. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/notification-config-rejections.yaml) |
| `oauth-setup` | Capability-gated evaluation of an agent's RFC 9728 protected-resource metadata and the complete RFC 8414 authorization-server graph it advertises. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/oauth-setup.yaml) |
| `pagination-integrity` | Validates the cursor↔has_more invariant by walking a paginated list_creatives response from a continuation page to a terminal page. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/pagination-integrity.yaml) |
| `pagination-integrity-creative-formats` | When an agent still exposes deprecated list_creative_formats compatibility, validates its cursor↔has_more invariant by seeding two formats and walking pages with max_results=1. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/pagination-integrity-creative-formats.yaml) |
| `pagination-integrity-list-accounts` | Validates list_accounts pagination by seeding sandbox accounts, requesting a small first page, and following its cursor once. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/pagination-integrity-list-accounts.yaml) |
| `premium-display-canonical-validation` | Validates AdCP 3.2 seller_rendered_stateful_display supply-mode contracts (components, rendered_canvases, layered_source), single-state reveal shape, policy floors, and coordinated_placements sequence/serving_policy, alongside transition/canvas coverage and shared-slot resolution. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/premium-display-canonical-validation.yaml) |
| `principal` | Validates the experimental stable-principal-scoped configuration surface: capability discovery, pre-configuration identity readback, NO_AUTH rejection, dry-run setup, applied lifecycle with readback, idempotent replay, and section clearing. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/principal.yaml) |
| `property-list-reference-resolution` | An independent receiver resolves an issued list over the task transport using only its read-only bearer token and follows pagination. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/property-list-reference-resolution.yaml) |
| `property-lists-pagination-integrity` | Validates the cursor↔has_more invariant by walking a paginated list_property_lists response from a continuation page to a terminal page. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/property-lists-pagination-integrity.yaml) |
| `read-tool-idempotency` | Validates that read-only AdCP tasks and the 3.x get_products compatibility facade tolerate an optional idempotency_key without claiming read-response replay. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/read-tool-idempotency.yaml) |
| `reliable-reporting-managed-delivery` | Validates the Managed Delivery tier's explicit capability, atomic managed offering, resource retention, and authorization-revocation contract. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/reliable-reporting-managed-delivery.yaml) |
| `reliable-reporting-reconciled-billing` | Validates the Reconciled Billing tier's canonical evidence and authenticated receipt path for official revisions and later adjustments. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/reliable-reporting-reconciled-billing.yaml) |
| `reporting-consumer-status` | Validates opt-in buyer-to-seller reporting status, missing-obligation identity, caller-scoped mismatch, content-mismatch contract facts, counted silence, escalation, and immutable supersession. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/reporting-consumer-status.yaml) |
| `reporting-core` | Validates reporting.core obligation-before-report behavior, clock-derived health, and explicit zero-row reporting. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/reporting-core.yaml) |
| `reporting-core-declaration` | Validates the proper-name Reliable Reporting 1.0 declaration and its required Core tier without requiring optional tiers or a sandbox controller. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/reporting-core-declaration.yaml) |
| `schema-validation` | Validates that agent responses conform to AdCP schemas and that temporal constraints are enforced. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/schema-validation.yaml) |
| `schema-validation-signals` | Validates that signals agent responses conform to AdCP schemas with all required fields present and correctly typed. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/schema-validation-signals.yaml) |
| `security` | Every AdCP agent MUST require authentication on protected operations. At least one of static credentials or OAuth MUST be implemented and correctly advertised. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/security.yaml) |
| `signed-requests` | Agent verifies RFC 9421 HTTP Signatures on incoming AdCP requests per the 3.1-compatible transport-layer profile. Universal capability-gated storyboard — runs for any agent advertising `request_signing.supported: true` regardless of `supported_protocols`. Graded against the legacy wire suite covering every 3.1 checklist step and canonicalization-edge rule; a verifier advertising `covers_content_digest: "required"` (every 3.2+ verifier) is graded against the `profile-3.2/` mirror, which carries a counterpart of every legacy vector (positive `001` and `002` collapse into `positive/001-post-with-content-digest`) except `negative/018` (`forbidden` is illegal in 3.2). | [YAML](https://adcontextprotocol.org/compliance/latest/universal/signed-requests.yaml) |
| `stale-response-advisory` | Validates that STALE_RESPONSE rides in errors\[] on a populated success response with transport success preserved, and that STALE_RESPONSE is absent on healthy upstream responses. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/stale-response-advisory.yaml) |
| `trusted-match-publisher-authentication` | Verifies that a TMP router deployment rejects schema-valid Context Match and Identity Match requests with absent or invalid publisher authentication using HTTP 401 and a WWW-Authenticate challenge. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/trusted-match-publisher-authentication.yaml) |
| `v3-envelope-integrity` | v3 protocol envelopes MUST NOT carry task_status or response_status — v2 legacy field names that have no semantics in v3. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/v3-envelope-integrity.yaml) |
| `version-negotiation` | Sellers advertise supported releases on capabilities and echo the served release on every response. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/version-negotiation.yaml) |
| `webhook-emission` | Any agent that emits webhooks MUST echo the caller-supplied operation_id in every payload, carry a stable idempotency_key across retries, avoid duplicate webhook side effects on request replay, and — when the buyer has not opted into the deprecated HMAC fallback — MUST sign deliveries under the RFC 9421 webhook profile. Sellers MUST NOT emit task webhooks for inline terminal responses; any future sync-completion notification mode would be explicit and capability-advertised. Graded by a runner hosting a webhook receiver during storyboard execution. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/webhook-emission.yaml) |
| `webhook-receiver-envelope` | Buyer webhook receivers MUST accept full MCP webhook envelopes, reject bare delivery-result payloads, preserve raw-body signature verification, and dedupe retries by a stable idempotency_key. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/webhook-receiver-envelope.yaml) |
| `wholesale-feed-bulk-webhooks` | Validates account-level notification_configs\[] registration for agents that advertise wholesale_feed.bulk_change webhook events. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/wholesale-feed-bulk-webhooks.yaml) |
| `wholesale-feed-product-webhooks` | Validates account-level notification_configs\[] registration for agents that advertise product wholesale feed webhook events. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/wholesale-feed-product-webhooks.yaml) |
| `wholesale-feed-products` | Validates get_products wholesale feed versioning: bootstrap responses carry wholesale_feed_version/cache_scope and matching if_wholesale_feed_version probes return unchanged without product rows. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/wholesale-feed-products.yaml) |
| `wholesale-feed-products-scope-isolation` | Validates that get_products conditional-fetch is keyed by cache_scope: a wholesale_feed_version minted under one cache_scope must not short-circuit (unchanged: true) a request the seller resolves to a different cache_scope. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/wholesale-feed-products-scope-isolation.yaml) |
| `wholesale-feed-signal-webhooks` | Validates account-level notification_configs\[] registration for agents that advertise signal wholesale feed webhook events. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/wholesale-feed-signal-webhooks.yaml) |
| `wholesale-feed-signals` | Validates get_signals wholesale feed versioning: bootstrap responses carry wholesale_feed_version/cache_scope and matching if_wholesale_feed_version probes return unchanged without signal rows. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/wholesale-feed-signals.yaml) |
| `wholesale-feed-signals-scope-isolation` | Validates that get_signals conditional-fetch is keyed by cache_scope: a wholesale_feed_version minted under one cache_scope must not short-circuit (unchanged: true) a request the agent resolves to a different cache_scope. | [YAML](https://adcontextprotocol.org/compliance/latest/universal/wholesale-feed-signals-scope-isolation.yaml) |
Capability-gated rows (`deterministic-testing`, `oauth-setup`, `signed-requests`) are skipped when the corresponding capability is absent or advertises `supported: false`; they cannot be claimed and partially implemented. Declaring `supported: true` and failing the storyboard is non-conformant — omit the capability or declare `false` rather than ship a partial implementation. The `billing-gate-dispatch` and `comply-controller-mode-gate` rows are precondition-gated rather than ordinary capability-gated rows: each phase grades `not_applicable` when its precondition is not met. Sellers wanting full coverage of the per-agent billing gate SHOULD ship a test kit with `commercial_relationship: passthrough_only` declared so the per-agent phases run.
## Standard error codes
The compliance suite verifies that standard errors use the recovery classifications and remediation guidance defined by the canonical [`error-code.json`](https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/source/enums/error-code.json) source taxonomy. The vocabulary remains open: agents must also handle unknown codes using the response's `recovery` value.
| Code | Recovery | Suggested action |
| - | - | - |
| `ACCOUNT_AMBIGUOUS` | correctable | pass the account_id of the intended account from error.details.candidates or list_accounts |
| `ACCOUNT_CHANGE_REQUIRES_NEW_ACCOUNT` | correctable | open a separate account for the change (request_account, or a sync_accounts provisioning entry), or resend the change with allow_separate_account: true; the named account is unchanged |
| `ACCOUNT_IDENTITY_CONFLICT` | correctable | choose a different operator or operator_unit identity, or retain the account's current identity; do not retry the same desired identity unchanged |
| `ACCOUNT_MOVED` | correctable | replace the stale reference with error.details.current_account, refresh through list_accounts, and retry with a fresh idempotency key |
| `ACCOUNT_NOT_FOUND` | terminal | for a natural key, provision through sync_accounts or omit account for public discovery; for an account_id, verify via list_accounts or contact seller |
| `ACCOUNT_PAYMENT_REQUIRED` | terminal | buyer must resolve billing |
| `ACCOUNT_REQUIRED` | correctable | pass account, or reference an existing resource whose owning account the service can resolve |
| `ACCOUNT_SETUP_REQUIRED` | correctable | check details.setup for URL or instructions |
| `ACCOUNT_SUSPENDED` | terminal | contact seller to resolve suspension |
| `ACTION_NOT_ALLOWED` | correctable | branch on error.details.reason: for wrong_status, wait for or transition to a status listed under the action's allowed_statuses; for mode_mismatch, this is a flow switch (not a retry against update_media_buy) — follow the mode named in available_actions\[\].mode; for condition_unresolved, wait until the seller advertises the action after resolving its opaque condition; for not_supported_on_product or not_supported_on_buy, do not retry — the action is unavailable on this buy and buyer must select a different product or renegotiate, using error.details.decline_reason when present to inform that renegotiation |
| `AGENT_BLOCKED` | terminal | surface to a human at the buyer — the relationship is permanently denied and is reinstated only through offline operator action with the seller, not via any seller-callable AdCP task |
| `AGENT_SUSPENDED` | terminal | surface to a human at the buyer — the agent cannot unilaterally lift a suspension; re-onboarding with the seller offline may resolve |
| `AMBIGUOUS_BIDDING_POLICY` | correctable | remove either the canonical bidding block or all legacy bidding fields from the effective package |
| `AUDIENCE_TOO_SMALL` | correctable | broaden targeting or upload more audience members |
| `AUTHORIZATION_REQUIRED` | correctable | complete or restore the required downstream platform connection, identity, creator, or post authorization; use error.details.missing_connections, authorization_url, authorization_instructions, or reference_authorization when present |
| `AUTH_INVALID` | terminal | do NOT auto-retry — credentials were rejected; rotate keys, refresh OAuth tokens once if applicable, otherwise escalate to a human |
| `AUTH_MISSING` | correctable | provide credentials via the auth header and retry |
| `AUTH_REQUIRED` | correctable | provide credentials when missing; do NOT auto-retry rejected credentials — escalate for rotation |
| `BIDDING_PLACEMENT_CONFLICT` | correctable | align media-buy and package bidding scopes with the provider's supported placement, or choose a compatible budget mode/product combination |
| `BILLING_NOT_PERMITTED_FOR_AGENT` | correctable | retry with error.details.suggested_billing (typically 'operator') when present; when absent, surface to a human at the buyer — the agent cannot unilaterally extend its commercial relationship and MUST NOT auto-retry |
| `BILLING_NOT_SUPPORTED` | correctable | check get_adcp_capabilities for supported_billing and resubmit with a supported value, or omit billing to accept the seller's default |
| `BILLING_OUT_OF_BAND` | terminal | do not retry — billing for this account runs through a non-AdCP channel. Pre-filter via capabilities.creative.bills_through_adcp before sending report_usage; flag the account in the buyer's routing table and fall back to the ad server's native billing export for cost reconciliation |
| `BRAND_REQUIRED` | correctable | include brand (domain plus optional brand_id) on the request |
| `BUDGET_CAP_REACHED` | correctable | raise max_spend, or reduce max_creatives/max_variants, to produce the remaining items |
| `BUDGET_EXCEEDED` | correctable | reduce requested amount or increase budget allocation |
| `BUDGET_EXHAUSTED` | terminal | buyer must add funds or increase budget cap |
| `BUDGET_TOO_LOW` | correctable | inspect the budget floor details; reconcile the constrained budget, then adjust that budget or its contributing bid within existing authorization |
| `CAMPAIGN_SUSPENDED` | transient | wait for the escalation to resolve; contact the plan operator if the suspension persists |
| `CATALOG_LIMIT_EXCEEDED` | correctable | remove unused catalogs, or contact the seller to raise the limit |
| `COMMITTED_RESOURCE_PURGED` | terminal | do not automatically retry with the same or a fresh idempotency_key; reconcile through the resource read task and seller audit or operator records before deciding whether to initiate a new operation |
| `COMPLIANCE_UNSATISFIED` | correctable | choose a format that supports the required disclosure positions and persistence modes, remove the disclosure requirement, or revise the refinement instruction |
| `CONFIGURATION_ERROR` | terminal | surface to a human at the seller — the buyer cannot resolve a seller-side deployment misconfiguration and MUST NOT auto-retry |
| `CONFLICT` | transient | re-read the resource and retry with current state |
| `CONFLICTING_SELECTORS` | correctable | emit one canonical format selector route, or make every required legacy 3.x compatibility projection select the same product format contract under the canonical v2-narrows-v1 comparison |
| `CREATIVE_DEADLINE_EXCEEDED` | correctable | check creative_deadline via get_media_buys before submitting changes, or negotiate a deadline extension with the seller |
| `CREATIVE_INACCESSIBLE` | correctable | verify the asset URLs in creative_manifest are reachable without agent-side credentials, then re-submit |
| `CREATIVE_LIVE_UPDATE_UNSUPPORTED` | correctable | sync the change as a new creative_id and swap it in on each live package with an assignment_operations replace, which every seller declaring creative.live_updates lists in creative.assignment_operations; send the change with dry_run to see the exact outcome without applying it |
| `CREATIVE_LOCALE_NOT_ACCEPTED` | correctable | supply or assign a creative variant matching every in-scope format option's accepted_language_ranges, narrow placement scope, choose a compatible format option, or change an ineligible serve_default |
| `CREATIVE_MERGE_REJECTED` | correctable | confirm the pairing via list_creatives, or, when the seller lists replace in creative.assignment_operations, use a replace assignment operation to traffic creative_id as a new serving object |
| `CREATIVE_MISSING_CLICK_URL` | correctable | add the required destination URL and resubmit the creative |
| `CREATIVE_NOT_FOUND` | correctable | verify creative_id via list_creatives, or sync_creatives to register it |
| `CREATIVE_REJECTED` | correctable | revise the creative according to the applicable advertising policy or validated accessibility criteria |
| `CREATIVE_REPRESENTATION_UNRESOLVED` | correctable | inspect every error.details.representation_rejections entry, then choose a compatible format option or supply a compatible representation |
| `CREATIVE_REVISION_CONTENT_MISMATCH` | correctable | resend the exact content previously bound to this revision_id, or mint a new revision_id for changed content |
| `CREATIVE_SIZE_MISMATCH` | correctable | resize or replace the creative with a size accepted by every selected package that may serve it |
| `CREATIVE_VALIDATION_FAILED_GENERIC` | correctable | correct the buyer-visible validation problem and resubmit the creative |
| `CREATIVE_VALUE_NOT_ALLOWED` | correctable | pick a value from error.details.allowed_values (or re-fetch the format) and resubmit |
| `CREDENTIAL_IN_ARGS` | terminal | do NOT auto-retry — auto-retry re-logs the credential on each attempt. Move authentication material or caller-supplied trust material out of request args (top-level, `context`, `ext`, any nested location) onto the relevant transport authentication/trust channel or account provisioning path (Authorization: Bearer, RFC 9421 signature/JWKS, mTLS, MCP/A2A authentication framing); rotate any leaked credential, then resubmit |
| `CURSOR_EXPIRED` | correctable | obtain a latest checkpoint, rebuild authoritative account snapshots, then drain changes after the checkpoint |
| `EVALUATOR_AGENT_NOT_ACCEPTED` | correctable | replace the evaluator agent_url (evaluator.feature_agent.agent_url or the evaluator agent-form agent_url) with one from the seller's published accepted_verifiers, or drop the evaluator agent pointer to fall back to seller-default ranking |
| `FEED_FETCH_FAILED` | correctable | check URL accessibility, authentication, and that content matches the declared feed_format |
| `FIELD_NOT_PERMITTED` | correctable | drop the disallowed field(s) and retry |
| `FORMAT_DECLARATION_DIVERGENT` | correctable | advisory — seller-side fix needed: producer is emitting disagreeing format_ids and format_options for the same product. Buyer SDK SHOULD prefer format_options and surface the divergent product to operators; do not auto-retry |
| `FORMAT_DECLARATION_V1_AMBIGUOUS` | correctable | advisory — seller-side fix needed: the v2 declaration's canonical has only family-level structural registry entries (no invertible literal). Seller MUST author v1_format_ref on the v2 declaration to disambiguate; SDKs MUST NOT synthesize. Do not auto-retry |
| `FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE` | correctable | advisory — emitted alongside the partial v1 emission, NOT in place of it: the v2 declaration carries `params.sizes[]` with N entries but only M v1_format_ref entries (M \< N), so v1 buyers see partial size coverage on the product. Seller-side fix: add v1_format_ref entries for the missing sizes. SDK MAY (non-normative) fan out automatically by catalog lookup. Non-fatal — do not auto-retry |
| `FORMAT_NOT_SUPPORTED` | correctable | refresh get_adcp_capabilities creative.supported_formats\[] and retry with a capability_id whose operations contains the intended build, preview, or validate operation |
| `FORMAT_OPTION_UNRESOLVED` | correctable | advisory — publisher-side fix needed: a placement's `format_options[].format_option_id` references a `format_option_id` that does not exist in this file's top-level `formats[]`. Buyer SDK MUST fail closed for that placement (drop the format from the placement's accepted set) and surface this code. Publisher fix: either declare the missing format option in `formats[]` or remove the reference from the placement. Do not auto-retry |
| `FORMAT_PROJECTION_FAILED` | correctable | advisory — seller-side fix needed: ask the seller to add an explicit `canonical` field on the legacy format declaration, or contribute a registry entry (format_id_glob or structural match) to v1-canonical-mapping.json. Do not auto-retry; the product is still valid on the legacy named-format path |
| `FORMAT_SHAPE_PROMOTED` | correctable | advisory — migrate the legacy custom format_shape to error.details.promoted_to before error.details.transition_end; dual emission is allowed during the transition window. Do not auto-retry |
| `GOVERNANCE_AGENT_NOT_ACCEPTED` | correctable | select a governance agent matching `error.details.accepted_governance_agents`, then retry `sync_governance` with a fresh idempotency key |
| `GOVERNANCE_DENIED` | correctable | restructure the buy, escalate to human spending authority, or contact the governance agent for details |
| `GOVERNANCE_UNAVAILABLE` | transient | retry with backoff; if the agent remains unreachable, the buyer MUST contact the plan's governance operator |
| `IDEMPOTENCY_CONFLICT` | correctable | use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response |
| `IDEMPOTENCY_EXPIRED` | correctable | perform a natural-key check to determine whether the original request succeeded; if no evidence of success, generate a fresh idempotency_key for a new attempt |
| `IDEMPOTENCY_IN_FLIGHT` | transient | wait top-level error.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race) |
| `INVALID_FEED_FORMAT` | correctable | verify the feed content matches the declared format |
| `INVALID_PRICING_OPTION` | correctable | verify pricing_option_id against the product's pricing_options from get_products or the vendor's discovery response, then resubmit with a valid ID |
| `INVALID_REQUEST` | correctable | check request parameters and fix |
| `INVALID_STATE` | correctable | check current status via get_media_buys and adjust request |
| `INVALID_USAGE_DATA` | correctable | check required fields for the vendor type (vendor_cost, currency, account at minimum), fix invalid values, and resubmit |
| `IO_REQUIRED` | correctable | review the proposal's insertion_order, accept terms, and include io_acceptance on accept_proposal; use create_media_buy only for 3.x compatibility |
| `ITEM_VALIDATION_FAILED` | correctable | check item_issues for per-item rejection reasons and fix the offending items |
| `MACRO_RESOLUTION_FAILED` | correctable | inspect error.details.macro_resolution_results and route to a resolver that supports the declared dialect, semantic, owner, and encoding depth |
| `MEDIA_BUY_NOT_FOUND` | correctable | verify media_buy_id; for legacy correlation use get_media_buys plus context, such as context.internal_campaign_id |
| `MULTI_FINALIZE_UNSUPPORTED` | correctable | sequence single-proposal finalize calls — one finalize entry per get_products refine\[] call or per refine_proposals refinements\[] call |
| `NOT_CANCELLABLE` | correctable | check the seller's cancellation policy or contact the seller |
| `PACKAGE_NOT_FOUND` | correctable | verify package_id; for legacy package correlation use get_media_buys plus package context, such as context.buyer_ref |
| `PAYMENT_TERMS_NOT_SUPPORTED` | correctable | omit payment_terms to accept the seller's default, retry with a different supported value, or negotiate offline |
| `PERMISSION_DENIED` | correctable | call check_governance to mint a valid token, or contact the seller to resolve the underlying permission; when error.details.scope is 'agent' (reason 'sandbox_only' or 'grant_absent') the rejection is terminal-pending-onboarding — surface to a human rather than auto-retrying. For suspended/blocked agent relationships, sellers emit AGENT_SUSPENDED / AGENT_BLOCKED instead (those codes carry recovery: terminal directly). |
| `PIXEL_TRACKER_LOSSY_DOWNGRADE` | correctable | advisory — emitted alongside the v1 downgrade emission: SDK collapsed a pixel_tracker asset to v1 `{asset_type: url, url_type: tracker_pixel}` for a seller that doesn't support pixel_tracker natively. The URL still fires; what's lost is in `error.details.lost_fields` (event variant, method:js execution context, or custom event timing). Buyer decision: accept the loss (most counter pixels survive), or fail the buy and route to a 3.1-capable seller. Non-fatal — do not auto-retry |
| `PIXEL_TRACKER_UPGRADE_INFERRED` | correctable | advisory — emitted when a 3.1 SDK upgrades a v1 url+tracker_pixel asset to pixel_tracker by inferring event and method from asset_id conventions. The inference may not match the buyer's original intent; check `error.details.inferred_event` / `inferred_method` and re-prompt the seller for explicit values if precise measurement matters. Non-fatal — do not auto-retry |
| `PLACE_TARGET_UNAVAILABLE` | correctable | resolve the pinned value against the current catalog, review any replacement, and submit an intentional package targeting update |
| `PLAN_NOT_FOUND` | correctable | verify plan_id via sync_plans, or register the plan first |
| `POLICY_VIOLATION` | correctable | review policy requirements in the error details |
| `PRIVATE_FIELD_IN_PUBLIC_PLACEMENT` | correctable | seller-side fix needed: remove private operational fields (`visibility`, `source`, `origin`, `delivery_mappings`, or similar) from public placement objects. Consumers MUST fail closed for the affected placement and alert operators; do not echo private field values in logs or error details |
| `PRODUCT_EXPIRED` | correctable | re-discover with get_products to find current inventory |
| `PRODUCT_NOT_FOUND` | correctable | remove invalid IDs and retry, or re-discover with get_products |
| `PRODUCT_UNAVAILABLE` | correctable | choose a different product |
| `PROPOSAL_EXPIRED` | correctable | call request_proposals and finalize a fresh proposal, or re-discover and finalize through legacy get_products |
| `PROPOSAL_NOT_COMMITTED` | correctable | finalize the draft through refine_proposals, or through the legacy get_products refine action |
| `PROPOSAL_NOT_FOUND` | correctable | request and finalize a fresh proposal, then retry |
| `PROVENANCE_CLAIM_CONTRADICTED` | correctable | revise the provenance claim to match the verifier's observation or replace the creative; auto-retry without correction will not pass |
| `PROVENANCE_DIGITAL_SOURCE_TYPE_MISSING` | correctable | set provenance.digital_source_type to a value from the digital-source-type enum and resubmit |
| `PROVENANCE_DISCLOSURE_MISSING` | correctable | set provenance.disclosure.required and, when true, populate disclosure.jurisdictions |
| `PROVENANCE_EMBEDDED_MISSING` | correctable | attach at least one embedded_provenance entry from a supported provider and resubmit |
| `PROVENANCE_REQUIRED` | correctable | attach a provenance object - at minimum digital_source_type - and resubmit |
| `PROVENANCE_SYNTHETIC_DEPICTION_MISSING` | correctable | assess the creative, set provenance.synthetic_depiction to true or false, and resubmit |
| `PROVENANCE_VERIFIER_NOT_ACCEPTED` | correctable | replace verify_agent.agent_url with one from the seller's published accepted_verifiers, drop verify_agent if the embedding is self-verifiable, or re-embed with a verifier the seller accepts |
| `RATE_LIMITED` | transient | wait top-level error.retry_after seconds when present, then retry |
| `READ_ONLY_SCOPE` | correctable | use a non-mutating alternative, or surface to the operator to request a scope that permits mutation |
| `REFERENCE_NOT_FOUND` | correctable | verify the referenced identifier exists and is accessible to the caller |
| `REQUOTE_REQUIRED` | correctable | use error.details.decline_reason when present to inform recovery, then refine accepted_proposal_id and apply the amendment through accept_proposal, or keep control_media_buy inside the accepted envelope; some policies require a free-text ask or human negotiation, and 3.1 compatibility callers must adjust or rediscover |
| `RIGHTS_CHANNEL_VIOLATION` | correctable | advisory — inspect error.details.rights_id and the requested channel against rights\[].channels / excluded_channels; target a capability on a permitted channel, confirm the rights entry applies to this output, or have the holder grant the channel (a human or holder action) |
| `SCOPE_INSUFFICIENT` | correctable | the agent cannot broaden its own scope - surface to the operator rather than auto-retry |
| `SERVICE_UNAVAILABLE` | transient | retry with exponential backoff |
| `SESSION_NOT_FOUND` | correctable | initiate a new session via si_initiate_session |
| `SESSION_TERMINATED` | correctable | initiate a new session via si_initiate_session |
| `SIGNAL_NOT_FOUND` | correctable | verify signal_id via get_signals, or confirm the signal is available from this agent |
| `SIGNAL_TARGETING_INCOMPATIBLE` | correctable | assign the creative to a package whose signal targeting matches the creative's signal_condition, or rebuild the creative for the package's condition; match on shared signal_ref identity (compare signal_agent_segment_id exactly when both carry it, else categorical signal_ref + value) |
| `SIGNED_RESPONSE_ENVELOPE_EXPIRED` | transient | re-invoke the designated task (verify_brand_claim or verify_brand_claims) to obtain a freshly signed response with a current exp window |
| `SIGNED_RESPONSE_REQUEST_HASH_MISMATCH` | correctable | re-invoke the designated task with the intended request parameters — the signed response's request_hash does not match the verifier's recomputed hash of the actual request; if the mismatch persists across retries, investigate JCS request-binding canonicalization between caller and responder |
| `SIGNED_RESPONSE_TENANT_MISMATCH` | correctable | verify the request targeted the correct brand domain and agent_url, then re-invoke; if the mismatch persists, the responding agent's server-side tenant resolution may be misconfigured |
| `SOURCE_ACCESS_FAILED` | correctable | error.field source.locator/source.segment_ref: fix the reference; error.field source: grant the seller's declared consumer identity and retry; no error.field: vendor outage, retry with backoff |
| `STALE_RESPONSE` | transient | advisory — emitted alongside a populated payload that was served from cache past the seller's freshness target because an upstream or sub-agent was unreachable. The response is usable; treat as non-fatal. Inspect `error.details.cache_age_seconds` to decide whether to immediately retry for fresh data or accept the cached value; the seller's own service is healthy, so retry is safe (it does not amplify the upstream failure) |
| `TERMS_REJECTED` | correctable | adjust the proposed terms and retry, or omit measurement_terms to accept the product's defaults |
| `UNPRICEABLE_OUTPUT` | correctable | target an output format the transformer prices, or have the seller add a pricing option covering it |
| `UNRECOGNIZED_TERMS` | correctable | remove the member the seller cannot interpret, or send it only to sellers that interpret it |
| `UNSUPPORTED_FEATURE` | correctable | check get_adcp_capabilities (or the product's overlay_support for a rejected targeting dimension), remove unsupported fields, and use details.replacement_dimension when present |
| `UNSUPPORTED_GRANULARITY` | correctable | pick a granularity from the product's reporting_capabilities.windowed_pull_granularities (via get_adcp_capabilities) and resubmit, or omit time_granularity to fall back to cumulative date-range pulls |
| `UNSUPPORTED_PROVISIONING` | correctable | re-issue with the entry shape the seller supports — `account: {account_id: ...}` for settings-update sellers with account-id namespaces, or `brand+operator+billing` for provisioning sellers; check seller documentation or capability declaration for which modes are implemented |
| `VALIDATION_ERROR` | correctable | review error details and fix field values |
| `VAST_PARSE_FAILED` | correctable | inspect error.details.reason (not_xml, no_vast_root, no_ad, no_media_file), fix the VAST document, and resubmit |
| `VAST_VERSION_MISMATCH` | correctable | inspect error.details.mismatch_reason and the corresponding acceptance-set or observed-document fields; select a compatible source representation or correct the offending VAST document |
| `VAST_WRAPPER_DEPTH_EXCEEDED` | correctable | inspect error.details.reason (depth, loop, timeout); flatten the wrapper chain, reduce redirects below the format's max_wrapper_depth, or fix the failing hop |
| `VERSION_UNSUPPORTED` | correctable | re-pin to a release in supported_versions and retry, or call get_adcp_capabilities without a version pin to discover supported_versions |
### Full descriptions
> [accordion] ACCOUNT_AMBIGUOUS — correctable
>
> **Suggested action:** pass the account_id of the intended account from error.details.candidates or list_accounts
>
> A natural-key reference matches more than one of the caller's accounts. error.details MAY list candidates\[] (account_id, name), conforming to error-details/account-ambiguous.json, limited to accounts the caller is already granted. Recovery: correctable (pass the intended account_id).
> [accordion] ACCOUNT_CHANGE_REQUIRES_NEW_ACCOUNT — correctable
>
> **Suggested action:** open a separate account for the change (request_account, or a sync_accounts provisioning entry), or resend the change with allow_separate_account: true; the named account is unchanged
>
> The seller would accept a requested account change only as a separate account, for example because the new market needs its own contract, legal entity, invoicing entity, or currency, and the caller did not allow that. Returned for a request_account change request whose allow_separate_account is absent or false, and for a sync_accounts settings update, which has no such option. The named account is unchanged. error.details.reason MAY say what the separate account needs. Distinct from a plain refusal: the change is acceptable on a new account. Recovery: correctable (open a separate account with request_account or a sync_accounts provisioning entry, or resend the change with allow_separate_account: true, or keep the account as it is).
> [accordion] ACCOUNT_IDENTITY_CONFLICT — correctable
>
> **Suggested action:** choose a different operator or operator_unit identity, or retain the account's current identity; do not retry the same desired identity unchanged
>
> **Deprecated in 3.3**, planned for removal in 4.0: an attribute update never changes identity, so it cannot collide. Sellers that still support the deprecated operator_identity rekey return it during 3.x. The complete operator_identity requested through sync_accounts would rekey the account onto a natural key already owned by another account. The seller MUST reject the change atomically, MUST NOT merge the accounts, and MUST preserve both accounts and every account-scoped resource unchanged. Distinct from CONFLICT, which reports a transient stale revision or concurrent write. Recovery: correctable (choose a different operator or operator_unit identity, or retain the account's current identity; do not retry the same desired identity unchanged).
> [accordion] ACCOUNT_MOVED — correctable
>
> **Suggested action:** replace the stale reference with error.details.current_account, refresh through list_accounts, and retry with a fresh idempotency key
>
> **Deprecated in 3.3**, planned for removal in 4.0: account_id never changes, so no former reference exists. Sellers that still support the deprecated operator_identity rekey return it during 3.x. An authorized caller used a former natural key that was tombstoned after the same account was rekeyed through sync_accounts. The seller MUST return the current canonical reference in error.details.current_account, conforming to error-details/account-moved.json, and MUST NOT provision or resolve a second account from the former key. Sellers retain the tombstone while the account or any account-scoped historical resources are retained. To avoid a cross-tenant existence oracle, sellers return ACCOUNT_MOVED only when the caller is authorized to resolve the current account; otherwise they return ACCOUNT_NOT_FOUND. Recovery: correctable (replace the stale account reference with details.current_account, refresh through list_accounts, and retry with a fresh idempotency key).
> [accordion] ACCOUNT_NOT_FOUND — terminal
>
> **Suggested action:** for a natural key, provision through sync_accounts or omit account for public discovery; for an account_id, verify via list_accounts or contact seller
>
> The account reference could not be resolved: an account_id that does not exist, a buyer-declared natural key the seller has not provisioned, or an account outside the caller's authorized set. Sellers return it on tasks where account is optional too, rather than ignoring the reference, unless a lazy-provisioning seller answers a discovery task for the account it would create. Recovery: terminal (for a natural key, provision through sync_accounts or omit account for public discovery; for an account_id, verify via list_accounts or contact seller).
> [accordion] ACCOUNT_PAYMENT_REQUIRED — terminal
>
> **Suggested action:** buyer must resolve billing
>
> Account has an outstanding balance requiring payment before new buys. Recovery: terminal (buyer must resolve billing).
> [accordion] ACCOUNT_REQUIRED — correctable
>
> **Suggested action:** pass account, or reference an existing resource whose owning account the service can resolve
>
> The service must resolve the commercial account before it can determine governance applicability, but the request and referenced resource do not identify one. Recovery: correctable (pass account, or use a resource bound to an account).
> [accordion] ACCOUNT_SETUP_REQUIRED — correctable
>
> **Suggested action:** check details.setup for URL or instructions
>
> The account reference resolved but the account needs setup before use. Recovery: correctable (check details.setup for URL or instructions).
> [accordion] ACCOUNT_SUSPENDED — terminal
>
> **Suggested action:** contact seller to resolve suspension
>
> Account has been suspended. Recovery: terminal (contact seller to resolve suspension).
> [accordion] ACTION_NOT_ALLOWED — correctable
>
> **Suggested action:** branch on error.details.reason: for wrong_status, wait for or transition to a status listed under the action's allowed_statuses; for mode_mismatch, this is a flow switch (not a retry against update_media_buy) — follow the mode named in available_actions\[\].mode; for condition_unresolved, wait until the seller advertises the action after resolving its opaque condition; for not_supported_on_product or not_supported_on_buy, do not retry — the action is unavailable on this buy and buyer must select a different product or renegotiate, using error.details.decline_reason when present to inform that renegotiation
>
> The requested mutation maps to an action that is not currently available on this media buy. Sellers MUST populate `error.details` with `attempted_action` (the structured available-action identifier the request maps to), `reason` (an `action-not-allowed-reason` value: `wrong_status`, `not_supported_on_product`, `not_supported_on_buy`, `mode_mismatch`, or `condition_unresolved`), and `currently_available_actions` (echo of the buy's resolved `available_actions[]` so the buyer SDK can offer recovery without a separate get_media_buys round-trip). For `not_supported_on_buy`, sellers SHOULD also populate `decline_reason` from `seller-policy-decline-reason` when they have a structured reason and disclosure does not expose private thresholds or enforcement controls. `decline_reason` SHOULD be omitted for structural reasons. All producer-authored explanatory text, including message, suggestion, and extension detail values, MUST remain buyer-safe and MUST NOT contain vendor identifiers, internal object names, internal IDs, stack traces, or other producer-private implementation details. Recovery: correctable when `reason` is `wrong_status` (wait for or transition to an allowed status), `mode_mismatch` (re-issue through the appropriate flow), or `condition_unresolved` (wait until the seller can resolve the condition and advertises the action). Terminal-for-this-buy when `reason` is `not_supported_on_product` or `not_supported_on_buy` — buyers select a different product or renegotiate buy terms.
> [accordion] AGENT_BLOCKED — terminal
>
> **Suggested action:** surface to a human at the buyer — the relationship is permanently denied and is reinstated only through offline operator action with the seller, not via any seller-callable AdCP task
>
> The calling buyer agent's commercial relationship with the seller is permanently denied — the agent is blocked. Sibling to `AGENT_SUSPENDED` on the agent-relationship axis but with no recovery path (a suspension may lift via re-onboarding; a block does not). The code itself is the discriminator — same posture as `AGENT_SUSPENDED`: no `error.details` payload, no per-agent commercial state, cross-tenant onboarding oracle clamp + channel-coverage requirements normative in error-handling.mdx Per-Agent Authorization Gate. Recovery: terminal (no autonomous recovery — the agent MUST surface to a human at the buyer; relationships are reinstated only through offline operator action with the seller, not via any seller-callable AdCP task).
> [accordion] AGENT_SUSPENDED — terminal
>
> **Suggested action:** surface to a human at the buyer — the agent cannot unilaterally lift a suspension; re-onboarding with the seller offline may resolve
>
> The calling buyer agent's commercial relationship with the seller is temporarily paused — the agent is onboarded but currently suspended. Sibling to `ACCOUNT_SUSPENDED` (account-wide) and `CAMPAIGN_SUSPENDED` (per-plan) but scoped to the agent-relationship axis (orthogonal to any specific account on that agent). The code itself is the discriminator — it does NOT carry an `error.details` payload (mirroring `BILLING_NOT_PERMITTED_FOR_AGENT`'s discriminator-by-code pattern), and MUST NOT carry per-agent commercial state (rate cards, payment terms, credit limit, billing entity, contact channels) since full disclosure of per-agent state in a single probe is a per-agent oracle. Cross-tenant onboarding oracle clamp + channel-coverage requirements (response shape, HTTP/A2A/MCP status, headers, side effects, observability, latency parity, retry-counter side channel) are normative in error-handling.mdx Per-Agent Authorization Gate; this description does not restate them to avoid drift. Recovery: terminal (re-onboarding may resolve the suspension; the agent MUST surface to a human at the buyer rather than auto-retrying — the agent cannot unilaterally lift a suspension, and re-attempts only reinforce the gate).
> [accordion] AMBIGUOUS_BIDDING_POLICY — correctable
>
> **Suggested action:** remove either the canonical bidding block or all legacy bidding fields from the effective package
>
> The same effective package combines the canonical bidding block with legacy bid_price or monetary optimization-goal target fields, so two bidding interpretations are present. Sellers MUST reject rather than choosing a winner. Recovery: correctable (emit only the 3.2 bidding block or only one legacy representation).
> [accordion] AUDIENCE_TOO_SMALL — correctable
>
> **Suggested action:** broaden targeting or upload more audience members
>
> Audience segment is below the minimum required size for targeting. Recovery: correctable (broaden targeting or upload more audience members).
> [accordion] AUTHORIZATION_REQUIRED — correctable
>
> **Suggested action:** complete or restore the required downstream platform connection, identity, creator, or post authorization; use error.details.missing_connections, authorization_url, authorization_instructions, or reference_authorization when present
>
> The caller is authenticated, but the referenced object requires an additional downstream platform connection, identity, creator, or post authorization before the seller can complete the requested action. Typical use: `sync_creatives` with a `published_post` reference where the seller can resolve the post but the owning identity has not authorized paid serving, or authorization has expired/revoked and can be restored. Distinct from `AUTH_MISSING` / `AUTH_INVALID` (caller credentials) and from `PERMISSION_DENIED` (seller policy denies the caller). Sellers SHOULD include recovery details conforming to `error-details/authorization-required.json`, especially `error.details.missing_connections[]` when the caller needs to complete one of several platform connections. Legacy recovery hints such as `authorization_url`, `authorization_instructions`, or `reference_authorization` remain valid when safe to disclose. Recovery: correctable (complete or restore the required authorization, then retry).
> [accordion] AUTH_INVALID — terminal
>
> **Suggested action:** do NOT auto-retry — credentials were rejected; rotate keys, refresh OAuth tokens once if applicable, otherwise escalate to a human
>
> Credentials were presented but rejected — revoked, malformed signature, or a key no longer in the seller's keystore. Sellers MUST return this code when an `Authorization` header was present but verification failed. Recovery: terminal. Exception: agents with a valid OAuth 2.1 refresh grant MAY treat this as correctable when the rejection reason is token expiry — silently refresh and retry once; if the refresh fails or the seller explicitly signals revocation, escalate to human.
> [accordion] AUTH_MISSING — correctable
>
> **Suggested action:** provide credentials via the auth header and retry
>
> No credentials were presented. Sellers MUST return this code when no `Authorization` header was included in the request. Recovery: correctable (provide credentials via the auth header and retry).
> [accordion] AUTH_REQUIRED — correctable
>
> **Suggested action:** provide credentials when missing; do NOT auto-retry rejected credentials — escalate for rotation
>
> **Deprecated** — use `AUTH_MISSING` (no credentials presented) or `AUTH_INVALID` (credentials presented and rejected). Retained as a backward-compatible alias during the 3.x deprecation window. Recovery: correctable.
> [accordion] BIDDING_PLACEMENT_CONFLICT — correctable
>
> **Suggested action:** align media-buy and package bidding scopes with the provider's supported placement, or choose a compatible budget mode/product combination
>
> The authored media-buy/package bidding scopes cannot be represented by the provider's native campaign, package, or shared-strategy placement rules. Sellers MUST detect this before any provider mutation and SHOULD identify the conflicting scopes and provider constraint in error.details. Recovery: correctable (remove or align package overrides, move the policy to the supported scope, or choose a compatible budget mode/product combination).
> [accordion] BILLING_NOT_PERMITTED_FOR_AGENT — correctable
>
> **Suggested action:** retry with error.details.suggested_billing (typically 'operator') when present; when absent, surface to a human at the buyer — the agent cannot unilaterally extend its commercial relationship and MUST NOT auto-retry
>
> The seller's `supported_billing` capability accepts the requested model, but the calling buyer agent's commercial relationship with the seller does not — e.g., the agent is onboarded as passthrough-only (no payments relationship — only the operator can be invoiced) and `billing: 'agent'` or `billing: 'advertiser'` is rejected even though the seller supports both at the capability level. Distinct from `BILLING_NOT_SUPPORTED` (seller-wide capability) by being narrowly per-buyer-agent: the gate is the seller's onboarding record for this caller, not the seller's global wire capability. Sellers MUST emit this code only after agent identity has been established via signed-request derivation or a credential-to-agent mapping in the seller's onboarding record; callers without established identity MUST receive `BILLING_NOT_SUPPORTED` instead, to prevent the distinct code from acting as an onboarding oracle. The recovery shape is deliberately minimal — `error.details` MUST conform to `error-details/billing-not-permitted-for-agent.json` (`rejected_billing` plus an optional single `suggested_billing` retry value, typically `operator`) and MUST NOT carry the agent's full permitted-billing subset, rate cards, payment terms, credit limit, billing entity, or any other per-agent commercial state. Recovery: correctable (retry with `error.details.suggested_billing` when present; when absent, surface to a human at the buyer — the agent cannot unilaterally extend its commercial relationship and MUST NOT auto-retry, since payments-relationship onboarding with the seller is offline).
> [accordion] BILLING_NOT_SUPPORTED — correctable
>
> **Suggested action:** check get_adcp_capabilities for supported_billing and resubmit with a supported value, or omit billing to accept the seller's default
>
> The seller declines the requested `billing` value either at the seller-wide capability level (`supported_billing` does not include the value) or at the per-account-relationship level (e.g., the seller accepts `operator` billing in general but has no direct billing relationship with the operator on this specific account). The default reject code for billing-value mismatches; `error.details` SHOULD conform to `error-details/billing-not-supported.json` (`scope` ∈ `{"capability", "account"}` plus optional `supported_billing` echo for the `"capability"` scope) so callers can dispatch without parsing prose. Distinct from `BILLING_NOT_PERMITTED_FOR_AGENT`, which is narrowly scoped to the calling buyer agent's commercial relationship with the seller (passthrough-only vs agent-billable) rather than to the seller's capability or per-account state. Sellers MUST emit `BILLING_NOT_PERMITTED_FOR_AGENT` only when agent identity has been established via signed-request derivation or a credential-to-agent mapping in the seller's onboarding record; in all other cases (unauthenticated callers and bearer credentials not mapped to a specific agent record) sellers MUST return `BILLING_NOT_SUPPORTED` and MUST omit `error.details.scope` — emitting the per-agent code or the `"account"`-scope hint without established identity is a cross-tenant onboarding oracle (same uniform-response shape required by the `*_NOT_FOUND` family). Recovery: correctable (check `get_adcp_capabilities` for `supported_billing` and resubmit with a value the seller supports, or omit `billing` to accept the seller's default).
> [accordion] BILLING_OUT_OF_BAND — terminal
>
> **Suggested action:** do not retry — billing for this account runs through a non-AdCP channel. Pre-filter via capabilities.creative.bills_through_adcp before sending report_usage; flag the account in the buyer's routing table and fall back to the ad server's native billing export for cost reconciliation
>
> A creative-agent billing-loop operation (`report_usage` is the canonical case) received a well-formed record that the agent will not bill on because this account bills via a non-AdCP channel — flat license, SaaS contract, bundled enterprise agreement, or any other out-of-band arrangement. The agent returns `accepted: 0` with the offending record(s) listed in `errors[]` carrying this code; the request itself is valid and silent acceptance would break buyer-side reconciliation. Distinct from `BILLING_NOT_SUPPORTED` (the seller declines a specific `billing` value on a media-buy account where AdCP billing is otherwise in scope) and `BILLING_NOT_PERMITTED_FOR_AGENT` (per-buyer-agent commercial gate on an otherwise-billable surface) by signaling that the entire billing surface is offline for this account, not that a specific value or caller is rejected. Buyers SHOULD pre-filter by reading `capabilities.creative.bills_through_adcp` from `get_adcp_capabilities` before issuing `report_usage`; agents that have not yet declared the capability remain in the probe-to-discover mode. The error is returned per-record (in the `report_usage` response `errors[]` array with `field` pointing at `usage[N]` or a specific record subpath), not at the envelope level. The code itself is the discriminator; no `error.details` shape is defined for this code (mirroring `CONFIGURATION_ERROR`'s discriminator-by-code pattern). Recovery: terminal — auto-retry will not change the outcome; the buyer SHOULD flag the account in its routing table so reconciliation falls back to the ad server's native billing export (or whatever offline channel the agent uses) rather than expecting AdCP-side cost truth.
> [accordion] BRAND_REQUIRED — correctable
>
> **Suggested action:** include brand (domain plus optional brand_id) on the request
>
> A billable operation was attempted without a brand reference. Every billable operation requires either a seller-assigned `account_id` or a natural key including `brand`. Recovery: correctable (include `brand` — `domain` plus optional `brand_id` — on the request).
> [accordion] BUDGET_CAP_REACHED — correctable
>
> **Suggested action:** raise max_spend, or reduce max_creatives/max_variants, to produce the remaining items
>
> build_creative stopped producing early because the next leaf would exceed the request's max_spend ceiling. Normally a SUCCESSFUL partial build (BuildCreativeVariantSuccess with budget_status: 'capped' and an advisory BUDGET_CAP_REACHED entry — every returned leaf is real and billed); returned as a terminal error only when even the first leaf would exceed the cap (no partial possible). Distinct from BUDGET_EXCEEDED (would exceed a media-buy/package allocation — a rejection) and BUDGET_EXHAUSTED (already spent). Recovery: correctable (raise max_spend, or reduce max_creatives/max_variants).
> [accordion] BUDGET_EXCEEDED — correctable
>
> **Suggested action:** reduce requested amount or increase budget allocation
>
> Operation would exceed the allocated budget for the media buy or package. Distinct from BUDGET_EXHAUSTED (already spent) and BUDGET_TOO_LOW (below minimum). Recovery: correctable (reduce requested amount or increase budget allocation).
> [accordion] BUDGET_EXHAUSTED — terminal
>
> **Suggested action:** buyer must add funds or increase budget cap
>
> Account or campaign budget has been fully spent. Distinct from BUDGET_TOO_LOW (rejected at submission). Recovery: terminal (buyer must add funds or increase budget cap).
> [accordion] BUDGET_TOO_LOW — correctable
>
> **Suggested action:** inspect the budget floor details; reconcile the constrained budget, then adjust that budget or its contributing bid within existing authorization
>
> Budget is below the seller's minimum. Optional recovery details follow error-details/budget-too-low\.json: minimum_budget and currency describe the floor; basis distinguishes daily and lifetime budgets, constraint identifies its cause, budget_field identifies the constrained budget when error.field instead names a contributing bid, and related_field can identify that bid. error.field retains its existing consistency with issues\[0].pointer. Without an unambiguous budget locator, the amount is diagnostic; reconcile current state before choosing a change. Recovery: correctable (adjust the constrained budget or contributing bid within the buyer's authorization).
> [accordion] CAMPAIGN_SUSPENDED — transient
>
> **Suggested action:** wait for the escalation to resolve; contact the plan operator if the suspension persists
>
> Campaign governance has been suspended pending human review; the governance agent MUST reject `check_governance` and `report_plan_outcome` calls on the affected plan until the escalation is resolved. Distinct from `ACCOUNT_SUSPENDED` (account-wide) — this is scoped to a single plan/campaign. Recovery: transient (wait for the escalation to resolve; contact the plan operator if the suspension persists).
> [accordion] CATALOG_LIMIT_EXCEEDED — correctable
>
> **Suggested action:** remove unused catalogs, or contact the seller to raise the limit
>
> The account has reached its maximum catalog count. Recovery: correctable (remove unused catalogs, or contact the seller to raise the limit).
> [accordion] COMMITTED_RESOURCE_PURGED — terminal
>
> **Suggested action:** do not automatically retry with the same or a fresh idempotency_key; reconcile through the resource read task and seller audit or operator records before deciding whether to initiate a new operation
>
> The requested mutation committed, but the affected resource was independently deleted or purged for a reason outside that requested mutation before the seller could durably record the canonical success response. The write stands even though the resource no longer exists, so sellers SHOULD set error.mutation_outcome to applied and MUST NOT set not_applied; this code does not describe the successful outcome of a requested delete operation. Sellers MUST retain the idempotency key record and canonical request hash independently of the resource until at least committed_at + replay_ttl_seconds, and exact replays MUST return this terminal outcome with replayed: true without re-executing the mutation. If the canonical success response was already durably recorded, sellers return that historical response under the normal replay rule instead. Distinct from CONFLICT (a transient concurrent modification before a stable result) and MEDIA_BUY_NOT_FOUND (a request targeting a resource that was already absent). Recovery: terminal (do not automatically retry with the same or a fresh idempotency_key; first reconcile through the resource read task and seller audit or operator records, then initiate a new operation only when reconciliation confirms that is intended).
> [accordion] COMPLIANCE_UNSATISFIED — correctable
>
> **Suggested action:** choose a format that supports the required disclosure positions and persistence modes, remove the disclosure requirement, or revise the refinement instruction
>
> A required disclosure from the brief's compliance section cannot be satisfied — either the target format's disclosure_capabilities do not include the required position or persistence mode, or (on a refinement) the request's message or config instructs removal or contradiction of a required disclosure or the use of a prohibited claim. Recovery: correctable (choose a format that supports the required disclosure positions and persistence modes, remove the disclosure requirement, or revise the refinement instruction).
> [accordion] CONFIGURATION_ERROR — terminal
>
> **Suggested action:** surface to a human at the seller — the buyer cannot resolve a seller-side deployment misconfiguration and MUST NOT auto-retry
>
> The seller's deployment is misconfigured in a way that prevents handling the request — the buyer cannot fix it, retrying will not help, and reporting to the seller's operator is the only remediation. Examples: account declared with `mode: 'mock'` but no `mock_upstream_url` populated; platform declared with `mode: 'live'` or `mode: 'sandbox'` but no `upstream_url` declared; required environment variable unset on the seller process. Distinct from `INVALID_REQUEST` (buyer-fixable; the request itself is malformed), `SERVICE_UNAVAILABLE` (transient; retry-with-backoff may succeed), `UNSUPPORTED_FEATURE` (capability mismatch — the seller does not implement the requested specialism), `ACCOUNT_SETUP_REQUIRED` (buyer-side onboarding incomplete; this code is seller-side deployment incomplete), and `GOVERNANCE_UNAVAILABLE` (governance-agent-scoped; transient). Wire placement. The deployment cannot produce a success artifact, so sellers MUST flip transport-level failure markers (HTTP 5xx, MCP `isError: true`, A2A `failed`) and populate both layers per the two-layer model in `error-handling.mdx#envelope-vs-payload-errors-the-two-layer-model`. The code itself is the discriminator; no `error.details` shape is defined for this code (mirroring the minimal-disclosure precedent of `AGENT_SUSPENDED` / `AGENT_BLOCKED`). Sellers SHOULD populate `error.message` with operator-actionable detail (which metadata key is missing, which env var is unset) and MUST NOT include credentials, connection strings, or stack traces — the message is wire-visible to the buyer. Recovery: terminal — the buyer MUST surface to the seller's operator and MUST NOT auto-retry (retries cannot resolve a misconfigured deployment until the operator intervenes).
> [accordion] CONFLICT — transient
>
> **Suggested action:** re-read the resource and retry with current state
>
> Concurrent modification detected. The resource was modified by another request between read and write. This code does not cover a resource that was committed and then independently deleted or purged before the seller could durably record the canonical success response; use COMMITTED_RESOURCE_PURGED for that terminal outcome. Recovery: transient (re-read the resource and retry with current state).
> [accordion] CONFLICTING_SELECTORS — correctable
>
> **Suggested action:** emit one canonical format selector route, or make every required legacy 3.x compatibility projection select the same product format contract under the canonical v2-narrows-v1 comparison
>
> A 3.x package request carries multiple resolvable format selector routes that select different canonical product format declaration sets. Sellers MUST first resolve every present route independently (`format_option_refs`, direct `format_kind` plus `params`, and deprecated `format_ids`) without applying precedence. An unresolved option reference or an unprojectable legacy ID is rejected with `UNSUPPORTED_FEATURE`, not this code. Once all routes resolve, sellers derive the product `format_options[]` entries selected by each route using directional product satisfaction and require those sets to match. Legacy parameter compatibility uses the asymmetric v2-narrows-v1 relation defined by canonical formats, not raw object equality. For fixed-size image selectors, both width and height participate in compatibility. Sellers MUST reject different format shapes, selected option sets, or incompatible dimensions rather than silently choosing the canonical route. `error.field` SHOULD point at the conflicting package, and `error.details` SHOULD identify the supplied selector routes and their normalized canonical summaries. Recovery: correctable (emit one canonical selector route, or make a required legacy 3.x compatibility projection select the same product format contract).
> [accordion] CREATIVE_DEADLINE_EXCEEDED — correctable
>
> **Suggested action:** check creative_deadline via get_media_buys before submitting changes, or negotiate a deadline extension with the seller
>
> Creative change submitted after the package's creative_deadline. Distinct from CREATIVE_REJECTED (content-policy, brand-safety, or accessibility-review failure). Recovery: correctable (check creative_deadline via get_media_buys before submitting changes, or negotiate a deadline extension with the seller).
> [accordion] CREATIVE_INACCESSIBLE — correctable
>
> **Suggested action:** verify the asset URLs in creative_manifest are reachable without agent-side credentials, then re-submit
>
> A creative governance agent (get_creative_features) could not retrieve the submitted creative_manifest assets for evaluation — an asset URL was unreachable, returned an error, or required credentials the agent does not hold. Distinct from CREATIVE_NOT_FOUND (a creative_id absent from the agent's library, not an asset-fetch failure) and CREATIVE_REJECTED (assets retrieved but failed creative review). Recovery: correctable (verify the asset URLs are reachable without agent-side credentials, then re-submit).
> [accordion] CREATIVE_LIVE_UPDATE_UNSUPPORTED — correctable
>
> **Suggested action:** sync the change as a new creative_id and swap it in on each live package with an assignment_operations replace, which every seller declaring creative.live_updates lists in creative.assignment_operations; send the change with dry_run to see the exact outcome without applying it
>
> A sync_creatives item changed a live creative in a way the seller does not apply in place under the same creative_id. A creative is live when its status is approved and it has at least one assignment on a package that is not canceled, whose flight has not ended, and whose media buy is not in a terminal state; a paused package still counts. Returned only by sellers that declare creative.live_updates (others keep returning INVALID_STATE). The seller MUST fail only that item, MUST leave the creative, its review state, and its serving unchanged, SHOULD set error.field to the item, and SHOULD return details conforming to error-details/creative-live-update-unsupported.json naming the refused change kinds and the live packages. A dry_run returns the same refusal. Recovery: correctable (sync the change as a new creative_id, then swap it in on each live package with an assignment_operations replace, which every seller declaring creative.live_updates lists in creative.assignment_operations).
> [accordion] CREATIVE_LOCALE_NOT_ACCEPTED — correctable
>
> **Suggested action:** supply or assign a creative variant matching every in-scope format option's accepted_language_ranges, narrow placement scope, choose a compatible format option, or change an ineligible serve_default
>
> A creative bound to a locale-constrained product format has no materialized variant matching locale_policy.accepted_language_ranges, lacks protocol-declared locale topology, or uses serve_default with a seller-ineligible default variant. Seller ranges use RFC 4647 Basic Filtering and are applied independently for every placement where the assignment may serve, before buyer Lookup, locale_fallbacks, or default selection. Distinct from CREATIVE_REJECTED because this is a mechanically discoverable assignment-eligibility mismatch, not subjective content review. error.field SHOULD point to the offending creative or assignment; error.details SHOULD include format_option_id when present, accepted_language_ranges, available_variant_locales, and placement identity when applicable. Recovery: correctable (supply or assign a matching materialized locale variant, narrow placement scope, choose a compatible format option, or change an ineligible serve_default).
> [accordion] CREATIVE_MERGE_REJECTED — correctable
>
> **Suggested action:** confirm the pairing via list_creatives, or, when the seller lists replace in creative.assignment_operations, use a replace assignment operation to traffic creative_id as a new serving object
>
> One or more sync_creatives merge assignment operations failed seller verification. The seller evaluates every merge in the request, MUST leave every assignment unchanged (assignment operations are atomic), SHOULD set error.field to the first rejected assignment_operations entry, and SHOULD return details conforming to error-details/creative-merge-rejected.json listing each rejected merge with a reason: content_mismatch (the seller judges the copy is a different creative), format_mismatch (the buyer's creative cannot take over the copy's serving object), not_on_package (merged_creative_id is not a seller-assigned creative assigned to the package in this account, reported uniformly for unknown IDs), or not_supported (the seller cannot merge this pairing on this package). A seller that does not list merge in creative.assignment_operations returns UNSUPPORTED_FEATURE instead. Recovery: correctable (drop or fix the rejected merges and resubmit; where the seller lists replace in creative.assignment_operations, use replace to traffic creative_id as a new serving object).
> [accordion] CREATIVE_MISSING_CLICK_URL — correctable
>
> **Suggested action:** add the required destination URL and resubmit the creative
>
> A submitted creative that requires a destination URL does not provide one. Sellers SHOULD identify the missing buyer-visible field in error.field and MUST NOT expose downstream ad-server names or internal object identifiers in the buyer-facing message. Recovery: correctable (add the required destination URL and resubmit the creative).
> [accordion] CREATIVE_NOT_FOUND — correctable
>
> **Suggested action:** verify creative_id via list_creatives, or sync_creatives to register it
>
> Referenced creative does not exist in the agent's creative library. Recovery: correctable (verify creative_id via list_creatives, or sync_creatives to register it). Sellers MUST return this code uniformly for any creative_id not owned by the calling account — never distinguish 'exists in another tenant' from 'does not exist', which would enable cross-tenant enumeration.
> [accordion] CREATIVE_REJECTED — correctable
>
> **Suggested action:** revise the creative according to the applicable advertising policy or validated accessibility criteria
>
> Creative failed content-policy, brand-safety, or accessibility review. For deadline violations, see CREATIVE_DEADLINE_EXCEEDED. Accessibility failures SHOULD use structured details conforming to error-details/accessibility-violation.json. Recovery: correctable (revise the creative according to the applicable policy or validated accessibility criteria).
> [accordion] CREATIVE_REPRESENTATION_UNRESOLVED — correctable
>
> **Suggested action:** inspect every error.details.representation_rejections entry, then choose a compatible format option or supply a compatible representation
>
> No representation in a CreativeRepresentationSet is compatible with the selected target capability or product format option. The resolver MUST retain the complete representation set and MUST include one `error.details.representation_rejections[]` entry per candidate, conforming to `error-details/creative-representation-unresolved.json`; silent seller guessing is forbidden. Recovery: correctable (choose a compatible product/format option, add a compatible representation under a new revision, or fix the rejected asset contract).
> [accordion] CREATIVE_REVISION_CONTENT_MISMATCH — correctable
>
> **Suggested action:** resend the exact content previously bound to this revision_id, or mint a new revision_id for changed content
>
> A sync_creatives item reused a revision_id for different canonical revision content under the same creative_id. Revision identity is scoped to the parent creative and immutable after first acceptance. Sellers MUST evaluate the buyer input before transcoding or normalization, MUST leave the prior creative state unchanged, and SHOULD return details conforming to error-details/creative-revision-content-mismatch.json. Distinct from IDEMPOTENCY_CONFLICT: idempotency_key protects one request replay window, while revision identity protects creative content across requests and retention. Recovery: correctable (resend the exact content previously bound to this revision_id, or mint a new revision_id for the changed content).
> [accordion] CREATIVE_SIZE_MISMATCH — correctable
>
> **Suggested action:** resize or replace the creative with a size accepted by every selected package that may serve it
>
> The submitted creative dimensions do not match any size accepted by the selected packages. Sellers SHOULD identify the offending creative in error.field and MAY include the submitted and accepted dimensions in buyer-safe error.details. Recovery: correctable (resize or replace the creative with a size accepted by every selected package that may serve it).
> [accordion] CREATIVE_VALIDATION_FAILED_GENERIC — correctable
>
> **Suggested action:** correct the buyer-visible validation problem and resubmit the creative
>
> The creative failed buyer-correctable validation, but the producer cannot classify the failure with a more specific standard code. Producers SHOULD prefer a specific creative code whenever one applies and MUST keep buyer-facing messages free of vendor identifiers, internal object names, internal IDs, and stack traces. Recovery: correctable (correct the buyer-visible validation problem and resubmit the creative).
> [accordion] CREATIVE_VALUE_NOT_ALLOWED — correctable
>
> **Suggested action:** pick a value from error.details.allowed_values (or re-fetch the format) and resubmit
>
> A submitted text-asset value is not in the closed set the targeted format option declares: its `allowed_values` list, or a canonical closed-set parameter such as native_in_feed `cta_values`. Sellers MUST NOT return this code for a slot whose option declares no such set; that slot takes free text. Distinct from `CREATIVE_REJECTED` (generic creative-review failure) by being a closed-set constraint violation that the buyer can resolve mechanically without policy interpretation — the seller has published the complete list of acceptable values on the format, and any value outside that list is rejected by definition. The seller MUST set `error.field` to the offending asset's path within the manifest (e.g., `creatives[0].creative_manifest.assets[0].value` or the field name declared by the format) and SHOULD include the format's `allowed_values` array in `error.details.allowed_values` so the buyer agent can re-prompt its LLM with constrained sampling. Recovery: correctable (select a value from `allowed_values` and resubmit).
> [accordion] CREDENTIAL_IN_ARGS — terminal
>
> **Suggested action:** do NOT auto-retry — auto-retry re-logs the credential on each attempt. Move authentication material or caller-supplied trust material out of request args (top-level, `context`, `ext`, any nested location) onto the relevant transport authentication/trust channel or account provisioning path (Authorization: Bearer, RFC 9421 signature/JWKS, mTLS, MCP/A2A authentication framing); rotate any leaked credential, then resubmit
>
> The seller detected authentication material or caller-supplied trust material placed in request args (top-level, in `context`, in `ext`, or any other nested location in the task payload) instead of arriving on the relevant transport authentication or trust channel. This includes buyer-principal credentials that should arrive on the inbound transport (`Authorization: Bearer` per RFC 6750 §2 for HTTP, RFC 9421 signature headers for signed requests, MCP/A2A authentication framing per RFC 9728 §3), and evaluator-call credentials or JWK/JWKS/JWKS-URI trust material smuggled into evaluator-related payload fields instead of being established through the creative agent's outbound transport authentication to the evaluator. Distinct from `AUTH_REQUIRED` (no credentials presented or presented credentials rejected on the transport channel) and `PERMISSION_DENIED` (authenticated caller not authorized for the action). Distinct from the receiver-side credentials carried in `push_notification_config.authentication.credentials`, which configure the seller's webhook callback authentication and are not buyer-principal or evaluator-call credentials — those are an explicit carve-out and MUST NOT trigger this code. Sellers SHOULD reject credential-in-args under AdCP 3.1; the requirement upgrades to MUST 90 days after the 3.1 publication date. Recovery: terminal — the agent MUST NOT auto-retry. Auto-retry against this code re-logs the credential on each attempt across the seller's request logs, observability stack, and any LLM-context surfaces in the buyer-side recovery loop, exactly the prompt-injection exfiltration surface that motivated the rule. Wire placement. Sellers MUST flip transport-level failure markers (HTTP 4xx, MCP `isError: true`, A2A `failed`) and populate both layers per the two-layer model in `error-handling.mdx#envelope-vs-payload-errors-the-two-layer-model`. The code itself is the discriminator; no `error.details` shape is defined, and `error.field` MUST NOT echo the offending credential value or any prefix of it (e.g., `"Bearer ey..."`). `error.message` MUST be generic and MUST NOT contain credential material. Sellers MUST drop the smuggled credential from logs, audit rows, and observability spans before persisting the rejection — the rejection itself is otherwise an exfiltration surface.
> [accordion] CURSOR_EXPIRED — correctable
>
> **Suggested action:** obtain a latest checkpoint, rebuild authoritative account snapshots, then drain changes after the checkpoint
>
> The list_account_changes cursor (experimental, account.change_feed) is no longer within the seller's retained account change window. The seller MUST NOT silently restart from the retention boundary. Recovery: correctable (obtain a new starting_position: latest checkpoint, rebuild every authoritative account snapshot, then drain changes after that checkpoint). error.details SHOULD include available_since and MAY include a replacement starting-position hint, without disclosing inaccessible history.
> [accordion] EVALUATOR_AGENT_NOT_ACCEPTED — correctable
>
> **Suggested action:** replace the evaluator agent_url (evaluator.feature_agent.agent_url or the evaluator agent-form agent_url) with one from the seller's published accepted_verifiers, or drop the evaluator agent pointer to fall back to seller-default ranking
>
> Buyer attached an evaluator agent pointer on `build_creative` — `evaluator.feature_agent.agent_url` or the `evaluator` agent-form `agent_url` — that does not match (canonicalized per /docs/reference/url-canonicalization: lowercase scheme and host, strip default port, normalize path dot-segments) any entry in the seller's `creative_policy.accepted_verifiers[].agent_url`. The producing agent does not call buyer-asserted endpoints outside its allowlist; this mirrors `PROVENANCE_VERIFIER_NOT_ACCEPTED` for the gate/rank evaluator path — the buyer represents which on-list agent it used, the seller is the agent-of-record and calls only allowlisted agents. `error.field` MUST point at the offending `agent_url` path; `error.details` SHOULD include a reference to the product whose `creative_policy.accepted_verifiers` the buyer should consult. Recovery: correctable (replace the agent_url with one from the seller's published `accepted_verifiers`, or drop the evaluator agent pointer to fall back to seller-default ranking).
> [accordion] FEED_FETCH_FAILED — correctable
>
> **Suggested action:** check URL accessibility, authentication, and that content matches the declared feed_format
>
> Platform could not fetch the catalog feed URL during sync_catalogs. Recovery: correctable (check URL accessibility, authentication, and that the content matches the declared feed_format).
> [accordion] FIELD_NOT_PERMITTED — correctable
>
> **Suggested action:** drop the disallowed field(s) and retry
>
> A request field is not in the caller's `field_scopes` allowlist for this task. Sellers declaring `field_scopes` on the account's `authorization` object MUST reject any request that sets a non-allowlisted field with this code. Distinct from `VALIDATION_ERROR` (schema/business-rule violation) - the field is valid, just not writable by this caller. `error.field` MUST identify the exact offending field path (e.g., `packages[0].budget`); when multiple fields are disallowed, sellers SHOULD return one error per field, or MAY enumerate them in `error.details.fields`. Recovery: correctable and agent-autonomous - agent may drop the disallowed field(s) and retry.
> [accordion] FORMAT_DECLARATION_DIVERGENT — correctable
>
> **Suggested action:** advisory — seller-side fix needed: producer is emitting disagreeing format_ids and format_options for the same product. Buyer SDK SHOULD prefer format_options and surface the divergent product to operators; do not auto-retry
>
> Non-fatal advisory raised when a product carries BOTH `format_ids` (v1) AND `format_options` (v2) and the two disagree (different canonical, different dimensions, different orientation) after projection. The producer's contract is that both shapes MUST refer to the same underlying declaration; divergence is a producer bug.
>
> Either side MAY emit this code: a SELLER may self-detect on emit (own producer bug; rare), or more commonly a consumer-SDK detects on consumption. SDKs MUST prefer `format_options` (the richer surface) when both are present and MUST surface the divergent product so it's observable rather than silently picked-one-and-dropped-other. Hard-failing the entire `get_products` response is discouraged — it punishes downstream buyers for the producer bug.
>
> **Surface placement (normative).** Same single-surface mandate as `FORMAT_PROJECTION_FAILED`: SDKs that detect this on consumption MUST augment the response's `errors[]` array with an entry carrying `source: "sdk"`, `sdk_id: "@"`, `code: "FORMAT_DECLARATION_DIVERGENT"`, and the field+details described below. Logger-only is insufficient; lint-output channels are NOT acceptable as the surface (the multi-hop agent network needs warnings to propagate across SDK boundaries via the wire response).
>
> `error.field` MUST point at the offending product; `error.details` SHOULD carry `{ product_id, format_ids, format_options_summary, divergence_reason }` so buyer SDKs can flag the producer for follow-up.
>
> **Multi-hop deduplication.** Each hop that detects the same divergence SHOULD deduplicate by `(code, field)` rather than re-emit; the existing entry's `sdk_id` identifies which earlier processor saw it first.
>
> Recovery: correctable but seller-side — buyer can't fix divergent declarations, only flag them.
> [accordion] FORMAT_DECLARATION_V1_AMBIGUOUS — correctable
>
> **Suggested action:** advisory — seller-side fix needed: the v2 declaration's canonical has only family-level structural registry entries (no invertible literal). Seller MUST author v1_format_ref on the v2 declaration to disambiguate; SDKs MUST NOT synthesize. Do not auto-retry
>
> Non-fatal advisory raised when an SDK detects that a product's v2 declaration cannot be unambiguously projected back to a single v1 named format because the v1-canonical-mapping registry has only family-level structural entries for this canonical (no invertible `format_id_glob` literal). The family is known (e.g., 'this is a video_vast'); the specific v1 named format isn't pickable mechanically. Distinct from `FORMAT_PROJECTION_FAILED` (registry-coverage gap, correctable by adding a registry entry) — ambiguity is structural: the family is defined but a specific format can't be picked without seller assertion.
>
> Surface placement: same single-mandate as `FORMAT_PROJECTION_FAILED` and `FORMAT_DECLARATION_DIVERGENT` — SDKs MUST augment the response's `errors[]` array with an entry carrying `source: "sdk"`, `sdk_id`, `code: "FORMAT_DECLARATION_V1_AMBIGUOUS"`, `field` pointing at the offending declaration, and `error.details` SHOULD carry `{ format_kind, registry_matches: [], product_id }` so adopters can see why the inversion was ambiguous.
>
> **SDKs MUST NOT synthesize a v1_format_ref** in this case (or any other case). v1↔v2 explicit pairing is seller-asserted only — SDKs encountering family-only registry matches MUST treat the v2 declaration as v1-unreachable and surface this code rather than invent a plausible v1 format_id. The seller's path: author `v1_format_ref` on the v2 declaration to disambiguate (the authoritative pairing per `v1-canonical-mapping.json` resolution step 1), or accept that v1-only buyers won't see this product. Recovery: correctable but seller-side — buyer can't disambiguate without the seller's assertion.
> [accordion] FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE — correctable
>
> **Suggested action:** advisory — emitted alongside the partial v1 emission, NOT in place of it: the v2 declaration carries `params.sizes[]` with N entries but only M v1_format_ref entries (M \< N), so v1 buyers see partial size coverage on the product. Seller-side fix: add v1_format_ref entries for the missing sizes. SDK MAY (non-normative) fan out automatically by catalog lookup. Non-fatal — do not auto-retry
>
> Non-fatal advisory raised when a v2 declaration carries `params.sizes[]` with N entries but only M v1_format_ref entries (M \< N). The seller has asserted some v1 named formats but not enough to cover all declared sizes — v1-only buyers see partial coverage on the product. Emitted **alongside** the partial v1 emission (NOT in place of it): the product still appears on the v1 wire under the M sizes the seller covered; this code tells v1-aware downstream agents that N-M sizes were dropped from the projection.
>
> Surface placement: SDKs that detect on emission OR consumption MUST augment the response's `errors[]` with `source: "sdk"` (or `"producer"` if the seller self-detects on emit), `sdk_id`, `code: "FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE"`, `field` pointing at the offending declaration, and `error.details` SHOULD carry `{ product_id, declared_sizes: [{w,h}, …], covered_sizes: [{w,h}, …], dropped_sizes: [{w,h}, …] }` so buyer agents see which sizes were lost.
>
> **SDKs MAY (non-normative) fan out automatically** by catalog lookup — for each entry in `sizes[]` lacking a corresponding `v1_format_ref`, the SDK consults the AAO catalog for the per-size v1 named format (e.g., for `{width: 728, height: 90}` look up `display_728x90_image`) and emits it under `format_ids[]`. This is opt-in (requires catalog access); when SDKs fan out, they SHOULD still emit this code as a transparency advisory so downstream consumers know the v1 emit was synthesized rather than seller-asserted.
>
> Recovery: correctable — non-fatal advisory, do not auto-retry. Seller fix: add `v1_format_ref[]` entries for the missing sizes.
> [accordion] FORMAT_NOT_SUPPORTED — correctable
>
> **Suggested action:** refresh get_adcp_capabilities creative.supported_formats\[] and retry with a capability_id whose operations contains the intended build, preview, or validate operation
>
> A requested creative operation route is not supported by this creative agent. On the canonical 3.2 path, returned when build_creative.target_capability_id(s), preview_creative.target_capability_id, or validate_input targets\[] kind capability does not match an advertised creative.supported_formats\[].capability_id carrying the requested operation. Also returned when preview renderer inference has zero or multiple compatible matches. Sellers SHOULD attribute the error to the selector field and MAY include supported capability IDs in error.details.supported_capability_ids when safe. Deprecated target_format_id(s) and preview format_id retain legacy named-format error attribution during the 3.x compatibility window. Recovery: correctable (read get_adcp_capabilities creative.supported_formats\[] and retry with a capability_id whose operations contains the intended operation).
> [accordion] FORMAT_OPTION_UNRESOLVED — correctable
>
> **Suggested action:** advisory — publisher-side fix needed: a placement's `format_options[].format_option_id` references a `format_option_id` that does not exist in this file's top-level `formats[]`. Buyer SDK MUST fail closed for that placement (drop the format from the placement's accepted set) and surface this code. Publisher fix: either declare the missing format option in `formats[]` or remove the reference from the placement. Do not auto-retry
>
> Non-fatal advisory raised when a placement in `adagents.json` (or any consumer of `placement-definition.json`) carries `format_options[].format_option_id` referencing a `format_option_id` that does NOT exist in the file's top-level `formats[]`. The reference is broken — the publisher's catalog claims the placement accepts a format option that isn't declared.
>
> **Resolution scope is same-file only.** Cross-file `format_option_id` lookup is not supported by design (closes off format_option_id squatting across publisher boundaries — a malicious file cannot reference another publisher's format_option_id and claim its narrowing). Buyer SDKs MUST fail closed for the placement (drop the format from the placement's accepted format set) and MUST surface this code rather than silently dropping or guessing what the publisher meant.
>
> Surface placement: same single-mandate as the other FORMAT\_\* codes — SDKs that detect on consumption MUST augment the response's `errors[]` with `source: "sdk"`, `sdk_id`, `code: "FORMAT_OPTION_UNRESOLVED"`, `field` pointing at the offending placement (e.g., `placements[2].format_options[1].format_option_id`), and `error.details` SHOULD carry `{ placement_id, format_option_id, declared_format_options: [] }` so the publisher can fix.
>
> Recovery: correctable but publisher-side — buyer can't fix; publisher either declares the missing format option in `formats[]` or removes the reference from the placement.
> [accordion] FORMAT_PROJECTION_FAILED — correctable
>
> **Suggested action:** advisory — seller-side fix needed: ask the seller to add an explicit `canonical` field on the legacy format declaration, or contribute a registry entry (format_id_glob or structural match) to v1-canonical-mapping.json. Do not auto-retry; the product is still valid on the legacy named-format path
>
> Non-fatal advisory raised when a legacy named format on a product cannot be projected to a canonical-formats `ProductFormatDeclaration` via the resolution order in `v1-canonical-mapping.json` (explicit `canonical` field → format_id_glob → structural match → fail-closed). The product is still valid on the legacy named-format path; only the 3.1+ `format_options` projection failed. Primarily a **consumer-SDK concern** — the seller didn't fail; the consumer-side SDK couldn't project on their behalf. `error.field` MUST point at the offending product (e.g., `products[3].format_ids[0]`); `error.details` SHOULD carry `{ format_id, product_id, resolution_failure: "no_explicit_canonical" | "no_registry_match" | "no_structural_match" }` so buyer SDKs can route remediation (suggest the seller add an explicit `canonical` field, or file a registry PR).
>
> **Surface placement (normative).** SDKs that detect this on consumption MUST augment the response's `errors[]` array with an entry carrying `source: "sdk"`, `sdk_id: "@"`, `code: "FORMAT_PROJECTION_FAILED"`, and the field+details described above. This is the single mandated surface — logger-only is insufficient and a separate lint-output channel is NOT acceptable (AdCP is a multi-hop agent network; warnings need to propagate across hops or each hop has to re-detect locally). Sellers MAY emit this code on their own response when they self-detect a non-projectable format on emit; producer-emitted entries omit `source` (or set `source: "producer"`). The response stays 200/success regardless of who emits; this is non-fatal.
>
> **Multi-hop deduplication.** Each hop that detects the same condition SHOULD deduplicate by `(code, field)` rather than re-emit. The existing entry's `sdk_id` identifies which earlier processor saw it first; downstream SDKs SHOULD NOT add a second entry for the same `(code, field)` pair unless they have materially different `error.details` (e.g., a different `resolution_failure` reason from a different registry version).
>
> Recovery: correctable (seller-side action — add explicit `canonical` field on the legacy format file, contribute a v1-canonical-mapping registry entry, or author a 3.1+ `ProductFormatDeclaration` with `v1_format_ref` linking back). See canonical-formats.mdx 'Dual emission and v2↔v1 projection' for the full rules.
> [accordion] FORMAT_SHAPE_PROMOTED — correctable
>
> **Suggested action:** advisory — migrate the legacy custom format_shape to error.details.promoted_to before error.details.transition_end; dual emission is allowed during the transition window. Do not auto-retry
>
> Non-fatal deprecation advisory raised when a 3.2-aware SDK encounters `format_kind: custom` with a `format_shape` that has been promoted to a first-class canonical. SDKs MUST preserve the declaration during its transition window and SHOULD augment the containing response's `errors[]` with `source: sdk`, `sdk_id`, this code, and `details: { format_shape, promoted_to, promotion_release, transition_end }`. Producers that self-detect their own legacy declaration MAY emit the same advisory with `source: producer`. Recovery is seller-side: dual-emit during the published transition window, migrate consumers, then replace the custom declaration with the promoted canonical.
> [accordion] GOVERNANCE_AGENT_NOT_ACCEPTED — correctable
>
> **Suggested action:** select a governance agent matching `error.details.accepted_governance_agents`, then retry `sync_governance` with a fresh idempotency key
>
> The governance agent proposed in `sync_governance` does not satisfy the seller's authoritative per-account acceptance criteria. The failed binding MUST NOT be persisted or contacted, and credentials supplied for it MUST NOT be echoed in responses or logs. `error.details` SHOULD conform to `error-details/governance-agent-not-accepted.json`. Distinct from `GOVERNANCE_UNAVAILABLE`, which means a verification criterion or registry could not be resolved and is retryable. Recovery: correctable (select an agent satisfying the returned criteria or resolve the account-specific requirement with the seller).
> [accordion] GOVERNANCE_DENIED — correctable
>
> **Suggested action:** restructure the buy, escalate to human spending authority, or contact the governance agent for details
>
> A registered governance agent denied the transaction. Sellers MUST place the denial in the operation's structured rejection arm when one exists (e.g., `acquire_rights` → `AcquireRightsRejected`, or an `approval_webhook` delivery → `CreativeRejected`); otherwise in `errors[]` + `adcp_error`. Buyers MUST dispatch on the response's discriminated `status` first and fall back to `errors[].code` / `adcp_error.code` only when no rejection arm exists for that operation. The buyer may restructure the buy (e.g., reduce budget, split into smaller transactions), escalate to human spending authority, or contact the governance agent for details. Recovery: correctable.
>
> Wire placement (full guidance). Governance denial is a structured business outcome, not a system error — the governance call SUCCEEDED and the agent returned a denial verdict. Two cases:
>
> 1. Operation or webhook payload defines a structured rejection arm. The arm IS the canonical denial shape. The seller populates `reason` (human-readable, propagating governance findings) and `suggestions` (optional) and does NOT additionally emit `GOVERNANCE_DENIED` in `errors[]` or `adcp_error`. The rejection arms enforce this at the schema layer: e.g., `AcquireRightsRejected` and `CreativeRejected` both declare `not: { required: [errors] }`, so dual-emission is already a schema violation. The code does not appear on the wire when the rejection arm is used. Transport-level success markers MUST NOT be flipped (HTTP 200, MCP `isError: false`, A2A `succeeded`) — the operation completed successfully and produced a structured response.
>
> 2. Operation response has no rejection arm (e.g., `create_media_buy` returns Success / Error / Submitted arms only). The seller populates `errors[].code: GOVERNANCE_DENIED` in the payload AND `adcp_error.code: GOVERNANCE_DENIED` on the envelope per the two-layer model in `error-handling.mdx#envelope-vs-payload-errors-the-two-layer-model`. Transport-level failure markers DO flip in this case (HTTP 4xx, MCP `isError: true`, A2A `failed`) — the task could not produce a success artifact.
>
> The rule generalizes to any current or future operation or webhook payload whose response defines a discriminated rejection arm. In either placement, sellers SHOULD propagate governance findings verbatim — buyers' recovery decisions depend on what specifically was rejected. `GOVERNANCE_DENIED` is reserved for verdicts received from a reachable governance agent; if the governance call itself failed (timeout, network, config error), use `GOVERNANCE_UNAVAILABLE` instead.
> [accordion] GOVERNANCE_UNAVAILABLE — transient
>
> **Suggested action:** retry with backoff; if the agent remains unreachable, the buyer MUST contact the plan's governance operator
>
> A registered governance agent is unreachable. Sellers MUST place this code in `errors[]` + `adcp_error` (never a structured rejection arm) and flip transport-level failure markers (HTTP 5xx, MCP `isError: true`, A2A `failed`). Distinct from `GOVERNANCE_DENIED` (agent reachable and explicitly denied — see that code's wire-placement guidance). Recovery: transient (retry with backoff; if the agent remains unreachable, the buyer MUST contact the plan's governance operator — the seller MUST NOT proceed with the media buy without a valid decision).
>
> Wire placement (full guidance). Governance unavailability is a system error — the governance call FAILED (timeout, network, config error) and the seller could not get a verdict at all. Always populate both layers per the two-layer model in `error-handling.mdx#envelope-vs-payload-errors-the-two-layer-model`. Do NOT use a structured rejection arm for unavailability even when the task offers one — the buyer's recovery semantics differ (retry-with-backoff for unavailability vs. restructure-or-escalate for denial), and conflating them masks the system-error signal.
> [accordion] IDEMPOTENCY_CONFLICT — correctable
>
> **Suggested action:** use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response
>
> An earlier request with the same idempotency_key was processed with a different canonical payload within the seller's replay window. Distinct from CONFLICT (concurrent write) — this indicates the client reused a key across semantically different requests. Recovery: correctable (use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response).
> [accordion] IDEMPOTENCY_EXPIRED — correctable
>
> **Suggested action:** perform a natural-key check to determine whether the original request succeeded; if no evidence of success, generate a fresh idempotency_key for a new attempt
>
> The idempotency_key was seen previously but its cached response has been evicted because it is past the seller's declared replay_ttl_seconds. Distinct from IDEMPOTENCY_CONFLICT (different payload within window) — this indicates the retry arrived too late for at-most-once guarantees. Recovery: correctable (perform a natural-key reconciliation — e.g., call get_media_buys for the relevant account/status scope and match returned media_buys\[].context.internal_campaign_id — to determine whether the original request succeeded, then either accept that result or generate a fresh idempotency_key for a new attempt). If the buyer has any evidence the prior call succeeded (partial response received before crash, entry in the buyer's own DB, a webhook fired), the buyer MUST do the natural-key reconciliation BEFORE minting a new key — minting a new key in that situation is exactly how double-creation happens.
> [accordion] IDEMPOTENCY_IN_FLIGHT — transient
>
> **Suggested action:** wait top-level error.retry_after seconds and retry with the SAME idempotency_key — MUST NOT mint a fresh key (turns a safe retry into a double-execution race)
>
> A prior request with the same `idempotency_key` is either actively executing or has an unresolved outcome under fail-closed reconciliation, and has not yet produced a cached response or committed-outcome tombstone. Sellers MAY return this code instead of blocking the second caller while active execution or reconciliation finishes — useful when the first call invokes a slow or ambiguously responding downstream system (SSP, ad server, payment provider). Distinct from IDEMPOTENCY_CONFLICT (different canonical payload — a client bug) and from CONFLICT (concurrent modification of a different resource) — IDEMPOTENCY_IN_FLIGHT tells the buyer that its retry is correct but the prior attempt's outcome is not yet available. Sellers SHOULD populate top-level `error.retry_after` with an integer-second wait hint based on expected execution or reconciliation progress. Buyers MUST treat this as transient and MUST NOT mint a fresh `idempotency_key` — minting a new key turns a safe retry into a double-execution race. Recovery: transient (wait `error.retry_after` seconds and retry with the same `idempotency_key`; the next attempt will replay the resolved outcome, continue reconciliation, or return IDEMPOTENCY_IN_FLIGHT again).
> [accordion] INVALID_FEED_FORMAT — correctable
>
> **Suggested action:** verify the feed content matches the declared format
>
> Catalog feed content does not match the declared feed_format. Recovery: correctable (verify the feed content matches the declared format, e.g. XML for google_merchant_center).
> [accordion] INVALID_PRICING_OPTION — correctable
>
> **Suggested action:** verify pricing_option_id against the product's pricing_options from get_products or the vendor's discovery response, then resubmit with a valid ID
>
> A `pricing_option_id` referenced in the request does not exist on the target account or product. Returned per-record in `report_usage` responses and at the request level for `create_media_buy` when the submitted pricing option cannot be resolved. `error.field` SHOULD point at the offending record path (e.g., `usage[1].pricing_option_id` or `packages[0].pricing_option_id`). Distinct from `PRODUCT_NOT_FOUND` (the product itself is unknown) by being narrowly about a pricing option within a known product or account. Recovery: correctable (verify `pricing_option_id` against the product's `pricing_options` from `get_products` or the vendor's discovery response, then resubmit with a valid ID).
> [accordion] INVALID_REQUEST — correctable
>
> **Suggested action:** check request parameters and fix
>
> Request is malformed, missing required fields, or violates schema constraints. Recovery: correctable (check request parameters and fix).
> [accordion] INVALID_STATE — correctable
>
> **Suggested action:** check current status via get_media_buys and adjust request
>
> Operation is not permitted for the resource's current status (e.g., updating a completed or canceled media buy, or modifying a canceled package). Recovery: correctable (check current status via get_media_buys and adjust request).
> [accordion] INVALID_USAGE_DATA — correctable
>
> **Suggested action:** check required fields for the vendor type (vendor_cost, currency, account at minimum), fix invalid values, and resubmit
>
> A usage record in `report_usage` has missing or invalid fields — required fields absent, values out of range, or type mismatches. Returned per-record in the `report_usage` response `errors[]` array. `error.field` SHOULD point at the offending field path (e.g., `usage[0].vendor_cost`, `usage[0].currency`). Distinct from `INVALID_REQUEST` (top-level request malformed) by being scoped to individual usage records within an otherwise well-formed request. Recovery: correctable (check required fields for the vendor type — at minimum `vendor_cost`, `currency`, and `account` — fix the offending values, and resubmit).
> [accordion] IO_REQUIRED — correctable
>
> **Suggested action:** review the proposal's insertion_order, accept terms, and include io_acceptance on accept_proposal; use create_media_buy only for 3.x compatibility
>
> The committed proposal requires a signed insertion order but no io_acceptance was provided. Recovery: correctable (review the proposal's insertion_order, accept terms, and include io_acceptance on accept_proposal; 3.x compatibility callers use create_media_buy).
> [accordion] ITEM_VALIDATION_FAILED — correctable
>
> **Suggested action:** check item_issues for per-item rejection reasons and fix the offending items
>
> One or more catalog items failed schema validation during sync_catalogs. Recovery: correctable (check item_issues for per-item rejection reasons and fix the offending items).
> [accordion] MACRO_RESOLUTION_FAILED — correctable
>
> **Suggested action:** inspect error.details.macro_resolution_results and route to a resolver that supports the declared dialect, semantic, owner, and encoding depth
>
> One or more declared creative macro tokens cannot be resolved or safely preserved under the selected product and seller capability intersection. Sellers MUST include per-token `error.details.macro_resolution_results`, conforming to `error-details/macro-resolution-failed.json`; unknown or ambiguous tokens remain byte-preserved and MUST NOT receive guessed values. Recovery: correctable (route to a compatible execution path, correct the verified declaration, or assign the proper downstream resolver).
> [accordion] MEDIA_BUY_NOT_FOUND — correctable
>
> **Suggested action:** verify media_buy_id; for legacy correlation use get_media_buys plus context, such as context.internal_campaign_id
>
> Referenced media buy does not exist or is not accessible to the requesting agent. Recovery: correctable (verify media_buy_id; when recovering across legacy sellers or missing echoed IDs, reconcile via get_media_buys and the opaque request/response context correlation handle, such as context.internal_campaign_id, rather than deprecated top-level buyer_ref).
> [accordion] MULTI_FINALIZE_UNSUPPORTED — correctable
>
> **Suggested action:** sequence single-proposal finalize calls — one finalize entry per get_products refine\[] call or per refine_proposals refinements\[] call
>
> Returned by sellers that cannot guarantee atomic commit across multiple proposals in a single finalize batch. Two call sites where this applies: (1) a `get_products` call with multiple `action: 'finalize'` entries in `refine[]` targeting different `proposal_id` values; (2) a `refine_proposals` call with multiple `action: 'finalize'` entries in `refinements[]` targeting different `proposal_id` values. The buyer's intent — atomic multi-proposal finalize — is structurally well-formed and per spec atomic on both surfaces, but this seller's downstream stack cannot satisfy the atomicity guarantee (e.g., the proposals route to two different ad servers with no 2PC). More specific than `INVALID_REQUEST` so buyers can distinguish 'this seller doesn't support multi-finalize' from 'the request itself is malformed'. Recovery: correctable (sequence the finalize calls one-`proposal_id`-per-call on whichever task surface the buyer is using; there is no capability flag for multi-finalize support, so a successful first-attempt is the only positive discovery signal). See [refinement guide § Finalize is exclusive](/docs/media-buy/product-discovery/refinement#finalize-is-exclusive-within-refine).
> [accordion] NOT_CANCELLABLE — correctable
>
> **Suggested action:** check the seller's cancellation policy or contact the seller
>
> The media buy or package cannot be canceled in its current state. The seller may have contractual or operational constraints that prevent cancellation. Recovery: correctable (check the seller's cancellation policy or contact the seller).
> [accordion] PACKAGE_NOT_FOUND — correctable
>
> **Suggested action:** verify package_id; for legacy package correlation use get_media_buys plus package context, such as context.buyer_ref
>
> Referenced package does not exist within the specified media buy. Recovery: correctable (verify package_id within the media buy; when recovering across legacy sellers or missing echoed product_id, reconcile via get_media_buys and the package-level context correlation handle, such as context.buyer_ref, rather than deprecated top-level buyer_ref).
> [accordion] PAYMENT_TERMS_NOT_SUPPORTED — correctable
>
> **Suggested action:** omit payment_terms to accept the seller's default, retry with a different supported value, or negotiate offline
>
> The seller does not accept the requested `payment_terms` value for this account. Payment terms are never silently remapped — sellers either accept or reject. Distinct from `BILLING_NOT_SUPPORTED` (the `billing` enum) by being narrowly about the `payment_terms` enum on the same account. Recovery: correctable (omit `payment_terms` to accept the seller's default, retry with a different value the seller supports, or negotiate offline).
> [accordion] PERMISSION_DENIED — correctable
>
> **Suggested action:** call check_governance to mint a valid token, or contact the seller to resolve the underlying permission; when error.details.scope is 'agent' (reason 'sandbox_only' or 'grant_absent') the rejection is terminal-pending-onboarding — surface to a human rather than auto-retrying. For suspended/blocked agent relationships, sellers emit AGENT_SUSPENDED / AGENT_BLOCKED instead (those codes carry recovery: terminal directly).
>
> The authenticated caller is not authorized for the requested action, or a required signed credential (e.g., a `governance_context` token on a spend-commit) is missing, fails verification, or was issued for a different plan, seller, or phase. Seller content or advertising policy denials use `POLICY_VIOLATION`; media-buy change-right and current-availability denials use `ACTION_NOT_ALLOWED`. Distinct from `AUTH_MISSING` (no credentials presented), `AUTH_INVALID` (credentials presented but rejected), `GOVERNANCE_DENIED` (governance agent denied), `AGENT_SUSPENDED` (agent's relationship temporarily paused), and `AGENT_BLOCKED` (agent's relationship permanently denied). When the gate that fired is specifically a non-status per-agent gate — a provisioning constraint (e.g., the agent is provisioned for sandbox traffic only and the request was against a non-sandbox account) or a missing demand-side grant — `error.details` SHOULD conform to `error-details/agent-permission-denied.json` (`scope: "agent"` plus `reason: "sandbox_only"`, or `reason: "grant_absent"` when no demand-side grant authorizes the agent to act for the account's brand) so callers can dispatch without parsing prose. Sellers MUST emit `scope: "agent"` only when buyer-agent identity has been established via signed-request derivation or a credential-to-agent mapping in the seller's onboarding record; in all other cases (including bearer credentials not mapped to a specific agent record) sellers MUST return `PERMISSION_DENIED` and MUST omit `error.details.scope` — emitting the per-agent scope without established identity is a cross-tenant onboarding oracle, and the omit MUST be enforced across every observable channel (response shape, HTTP/A2A/MCP status, headers, side effects, observability, latency parity) per the channel-coverage rules in error-handling.mdx Per-Agent Authorization Gate, mirroring the `*_NOT_FOUND` uniform-response rule and `BILLING_NOT_PERMITTED_FOR_AGENT`. The `suspended` and `blocked` per-agent states are NOT carried on this code — sellers MUST emit `AGENT_SUSPENDED` / `AGENT_BLOCKED` instead, each of which is its own discriminator. Recovery: correctable (call `check_governance` to mint a valid token, or contact the seller to resolve the underlying permission); when `details.reason` is present the rejection is terminal-pending-onboarding — the agent MUST surface to a human at the buyer rather than auto-retrying, since the agent cannot satisfy the gate itself.
> [accordion] PIXEL_TRACKER_LOSSY_DOWNGRADE — correctable
>
> **Suggested action:** advisory — emitted alongside the v1 downgrade emission: SDK collapsed a pixel_tracker asset to v1 `{asset_type: url, url_type: tracker_pixel}` for a seller that doesn't support pixel_tracker natively. The URL still fires; what's lost is in `error.details.lost_fields` (event variant, method:js execution context, or custom event timing). Buyer decision: accept the loss (most counter pixels survive), or fail the buy and route to a 3.1-capable seller. Non-fatal — do not auto-retry
>
> Non-fatal advisory raised when a 3.1 buyer SDK downgrades a `pixel_tracker` asset to the v1 `{asset_type: url, url_type: tracker_pixel}` shape for a 3.0.x seller that doesn't recognize the new asset type. The URL is still emitted on the wire and the seller will fire it as a tracker pixel; what's lost is the event/method discrimination. The one exception is the playback events (`start`, quartiles, `complete`), which are dropped rather than emitted.
>
> Downgrade rules (normative):
>
> * `event: impression` + `method: img` → no loss; emit as `{asset_type: url, url_type: tracker_pixel, url, asset_id: impression_tracker}`
> * `event: viewable_mrc_50` / `viewable_mrc_100` / `viewable_video_50` / `audible_video_complete` → emit with `asset_id: viewability_tracker`; advisory `lost_event: ` (specific viewability variant collapses to a single v1 slot)
> * `event: start` / `first_quartile` / `midpoint` / `third_quartile` / `complete` → **drop** the tracker (no v1 emission); advisory `lost_event: ` and `lost_fields` covering the whole tracker. `event: custom` with `custom_event_name` equal to one of those five names (the 3.2 interim form) is dropped the same way, and this rule takes precedence over the `custom` and `method: js` rules; set `downgrade_target: "dropped"` and `lost_fields: ["event", "url"]`. Never emit these as `impression_tracker`: a playback URL fired at impression time would count every impression as a quartile view
> * `event: click` → emit with `asset_id: click_tracker`; no meaningful loss
> * `event: custom, custom_event_name: X` → emit with `asset_id: impression_tracker` (default tracker_pixel fires on impression); advisory `lost_event: "custom"`, `lost_custom_event_name: X` (custom event timing collapses to impression timing)
> * `method: js` → emit unchanged shape (url, url_type:tracker_pixel); advisory `lost_method: "js"` (v1 seller will fire as HTTP GET; the URL is hit and any counter-based measurement increments, but the response body won't execute as JS — measurement that depends on JS execution, e.g., OMID-style verification, viewability observers, cross-domain cookie setters, won't work. Simple counter pixels still work.)
>
> Surface: SDK that performs the downgrade MUST augment the response's `errors[]` with `source: "sdk"`, `sdk_id`, `code: "PIXEL_TRACKER_LOSSY_DOWNGRADE"`, `field` pointing at the affected manifest asset path, and `error.details` SHOULD carry `{ asset_id, original_event, original_method, original_custom_event_name (if present), downgrade_target: "url+tracker_pixel", lost_fields: [] }`. One advisory per downgraded asset; SDKs SHOULD NOT collapse multiple downgrades into a single advisory entry — per-asset details let the buyer's measurement-plan owner decide whether each loss is tolerable.
>
> Recovery: correctable — non-fatal advisory, do not auto-retry. Buyer-side decision: accept the loss (most simple counter pixels survive; dropped playback trackers do not), or fail the buy and route to a 3.1-capable seller. Seller-side fix: upgrade to 3.1 and accept `pixel_tracker` natively.
> [accordion] PIXEL_TRACKER_UPGRADE_INFERRED — correctable
>
> **Suggested action:** advisory — emitted when a 3.1 SDK upgrades a v1 url+tracker_pixel asset to pixel_tracker by inferring event and method from asset_id conventions. The inference may not match the buyer's original intent; check `error.details.inferred_event` / `inferred_method` and re-prompt the seller for explicit values if precise measurement matters. Non-fatal — do not auto-retry
>
> Non-fatal advisory raised when a 3.1 buyer SDK upgrades a v1 `{asset_type: url, url_type: tracker_pixel}` to a `pixel_tracker` asset by INFERRING the event and method from the v1 asset_id and conventional defaults. The inference is structural — the SDK doesn't have explicit event/method values, only the v1 asset_id hint and `url_type: tracker_pixel` (which implies `method: img` by default).
>
> Inference rules (normative):
>
> * `asset_id: impression_tracker` → `event: impression, method: img`
> * `asset_id: viewability_tracker` → `event: viewable_mrc_50, method: img` (50% is the most common default; specific viewability variant cannot be recovered from v1 shape)
> * `asset_id: click_tracker` → `event: click, method: img`
> * `asset_id: ` → `event: custom, custom_event_name: , method: img`
>
> Surface: SDK MUST augment the response's `errors[]` with `code: "PIXEL_TRACKER_UPGRADE_INFERRED"`, `field` pointing at the upgraded asset path, and `error.details` SHOULD carry `{ asset_id, inferred_event, inferred_method, inference_basis: "asset_id_convention" | "default" }`. Buyer agents reading the response can re-prompt the seller for explicit values if precise measurement matters.
>
> Recovery: correctable — non-fatal advisory, do not auto-retry. Seller-side: upgrade emit path to ship pixel_tracker shape directly when 3.1-capable; until then, conventional asset_id values give the SDK enough signal to upgrade without losing critical semantics.
> [accordion] PLACE_TARGET_UNAVAILABLE — correctable
>
> **Suggested action:** resolve the pinned value against the current catalog, review any replacement, and submit an intentional package targeting update
>
> A place identifier previously accepted and pinned on a package can no longer be executed. This is a nonfatal resource-state error returned in get_media_buys.errors\[] alongside the affected buy. error.field MUST point to the exact media_buys\[N].packages\[M].targeting_overlay.geo_places\[\_exclude]\[A].values\[V] response path. error.details MUST include media_buy_id, package_id, system, system_version, country, place_type, and value. The seller MUST preserve and echo the pinned target rather than silently changing geography. Recovery: correctable (look up the value through the declared resolver at the current catalog version and submit an intentional targeting update).
> [accordion] PLAN_NOT_FOUND — correctable
>
> **Suggested action:** verify plan_id via sync_plans, or register the plan first
>
> Referenced governance plan does not exist or is not accessible to the requesting agent. Recovery: correctable (verify plan_id via sync_plans, or register the plan first). Sellers MUST return this code uniformly for any plan_id not accessible to the calling account — never distinguish 'exists but unauthorized' from 'does not exist', which would enable cross-tenant enumeration of governance plans.
> [accordion] POLICY_VIOLATION — correctable
>
> **Suggested action:** review policy requirements in the error details
>
> Request violates the seller's content or advertising policies. Recovery: correctable (review policy requirements in the error details).
> [accordion] PRIVATE_FIELD_IN_PUBLIC_PLACEMENT — correctable
>
> **Suggested action:** seller-side fix needed: remove private operational fields (`visibility`, `source`, `origin`, `delivery_mappings`, or similar) from public placement objects. Consumers MUST fail closed for the affected placement and alert operators; do not echo private field values in logs or error details
>
> Fatal producer-side error raised when a public placement object (`Product.placements[]` in `get_products` or `placements[]` in adagents.json) exposes seller-private operational fields such as `visibility`, `source`, `origin`, or `delivery_mappings`. This is a private-data leak, not an ordinary syntactic mismatch. Consumers that detect it MUST fail closed for that placement and surface this code so monitoring can alarm on the leak specifically instead of burying it under generic schema validation. `error.field` SHOULD point at the offending placement path and `error.details` SHOULD carry `{ placement_id, leaked_fields: [] }` without echoing private field values. Recovery: correctable but seller-side — remove private operational fields from the public placement surface and keep delivery mappings in seller-internal systems.
> [accordion] PRODUCT_EXPIRED — correctable
>
> **Suggested action:** re-discover with get_products to find current inventory
>
> The seller still recognizes one or more configured product IDs as issued to the authenticated account and referenced discovery/refinement lineage, and they have passed their expires_at timestamps. Sellers are not required to retain expiry tombstones indefinitely; an ID that is no longer resolvable, or is inaccessible to this caller because it belongs to another account or lineage, uses PRODUCT_NOT_FOUND. This distinction MUST NOT become a cross-tenant existence oracle. Recovery: correctable (re-discover through list_products, request_proposals, or the get_products compatibility facade to find current inventory).
> [accordion] PRODUCT_NOT_FOUND — correctable
>
> **Suggested action:** remove invalid IDs and retry, or re-discover with get_products
>
> One or more referenced product IDs are unknown or are not resolvable within the authenticated account and configured-offer lineage. A caller-authorized configured ID that is still recognized as expired uses PRODUCT_EXPIRED; once no expiry tombstone remains, or whenever the ID belongs to another account or lineage, PRODUCT_NOT_FOUND applies. Sellers MUST NOT reveal cross-tenant product existence through error choice. Recovery: correctable (remove invalid IDs and retry, or re-discover with get_products).
> [accordion] PRODUCT_UNAVAILABLE — correctable
>
> **Suggested action:** choose a different product
>
> The requested product is sold out or no longer available. On accept_proposal for an experimental ranked hold behind first position (media_buy.hold_ranking), it means a hold ahead still stands: the committed proposal stays acceptable until expires_at and a later acceptance may succeed. Recovery: correctable (choose a different product).
> [accordion] PROPOSAL_EXPIRED — correctable
>
> **Suggested action:** call request_proposals and finalize a fresh proposal, or re-discover and finalize through legacy get_products
>
> A referenced proposal ID has passed its expires_at timestamp. For a committed proposal, the inventory hold has lapsed (or, under terms_only hold semantics, the acceptance window has closed). Recovery: correctable (call request_proposals and finalize a fresh proposal, or re-discover and finalize through the legacy get_products facade).
> [accordion] PROPOSAL_NOT_COMMITTED — correctable
>
> **Suggested action:** finalize the draft through refine_proposals, or through the legacy get_products refine action
>
> The referenced proposal has proposal_status 'draft' and cannot be accepted into a media buy. Recovery: correctable (finalize it through refine_proposals, or through the legacy get_products refine action).
> [accordion] PROPOSAL_NOT_FOUND — correctable
>
> **Suggested action:** request and finalize a fresh proposal, then retry
>
> The referenced proposal_id is not recognized by the seller — it belongs to a different tenant, was never issued, or was evicted from the seller's session cache before consumption. Distinct from `PROPOSAL_EXPIRED` (a known proposal whose `expires_at` window has passed) and `PROPOSAL_NOT_COMMITTED` (a known proposal still in `draft`). Recovery: correctable (request a fresh proposal, finalize it, then retry accept_proposal; 3.x compatibility callers retry create_media_buy).
> [accordion] PROVENANCE_CLAIM_CONTRADICTED — correctable
>
> **Suggested action:** revise the provenance claim to match the verifier's observation or replace the creative; auto-retry without correction will not pass
>
> Seller invoked a governance agent from `creative_policy.accepted_verifiers` via `get_creative_features` and the verifier's result contradicts the buyer's provenance claim - e.g., buyer claims `digital_source_type: digital_capture` but the AI-detection feature returns `ai_generated: true` above the seller's confidence threshold. Distinct from the `PROVENANCE_*_MISSING` family (structural absence) by being an active refutation. `error.details` SHOULD be limited to the audit-safe allowlist `{ agent_url, feature_id, claimed_value, observed_value, confidence }`; sellers MUST NOT forward arbitrary verifier extension fields, `detail_url`, or any verifier response shape that may carry cross-tenant or PII data. When the seller calls a different on-list agent than the buyer nominated (the seller is the verifier-of-record), `error.details.agent_url` is the agent the seller actually called and `error.details.substituted_for` SHOULD carry the buyer's nominated `agent_url` so the buyer can reconcile. Recovery: correctable - buyer revises the provenance claim to match reality (or replaces the creative); auto-retry without correction will not pass.
> [accordion] PROVENANCE_DIGITAL_SOURCE_TYPE_MISSING — correctable
>
> **Suggested action:** set provenance.digital_source_type to a value from the digital-source-type enum and resubmit
>
> Seller's `creative_policy.provenance_requirements.require_digital_source_type` is true and the submitted creative's resolved provenance (after inheritance) has no `digital_source_type` value, or has it set to null. Distinct from `PROVENANCE_REQUIRED` (no provenance object at all) - provenance is present, just missing this specific field. Recovery: correctable (set `provenance.digital_source_type` to a value from the `digital-source-type` enum and resubmit). `error.field` MUST point at the resolved provenance path that was inspected (e.g., `creatives[0].creative_manifest.provenance.digital_source_type`).
> [accordion] PROVENANCE_DISCLOSURE_MISSING — correctable
>
> **Suggested action:** set provenance.disclosure.required and, when true, populate disclosure.jurisdictions
>
> Seller's `creative_policy.provenance_requirements.require_disclosure_metadata` is true and the submitted creative's resolved provenance has no `disclosure.required` boolean, or `disclosure.required` is true with no `disclosure.jurisdictions` entries. Recovery: correctable (set `provenance.disclosure.required` and, when true, populate `disclosure.jurisdictions`). `error.field` MUST point at `provenance.disclosure` (e.g., `creatives[0].creative_manifest.provenance.disclosure`).
> [accordion] PROVENANCE_EMBEDDED_MISSING — correctable
>
> **Suggested action:** attach at least one embedded_provenance entry from a supported provider and resubmit
>
> Seller's `creative_policy.provenance_requirements.require_embedded_provenance` is true and the submitted creative's resolved provenance has no `embedded_provenance` array, or has it as an empty array. Used in pipelines where sidecar `c2pa.manifest_url` is stripped by intermediaries and the seller requires content-stream-resilient provenance. Recovery: correctable (attach at least one `embedded_provenance` entry from a supported provider and resubmit, optionally with a `verify_agent` pointer matching one of the seller's `creative_policy.accepted_verifiers`). `error.field` MUST point at `provenance.embedded_provenance` on the resolved manifest.
> [accordion] PROVENANCE_REQUIRED — correctable
>
> **Suggested action:** attach a provenance object - at minimum digital_source_type - and resubmit
>
> Seller's `creative_policy.provenance_required` is true and the submitted creative has no `provenance` object on the manifest, on the creative-asset, or on any individual asset. Distinct from `CREATIVE_REJECTED` (generic creative-review failure) by being narrowly about provenance presence. Recovery: correctable (attach a provenance object - at minimum `digital_source_type` - and resubmit). `error.field` MUST point at the path where provenance was expected (e.g., `creatives[0].creative_manifest`).
> [accordion] PROVENANCE_SYNTHETIC_DEPICTION_MISSING — correctable
>
> **Suggested action:** assess the creative, set provenance.synthetic_depiction to true or false, and resubmit
>
> Seller's `creative_policy.provenance_requirements.require_synthetic_depiction` is true and the submitted creative's resolved provenance (after inheritance) has no `synthetic_depiction` boolean. Both `true` and `false` satisfy the requirement; absence means unassessed. Distinct from `PROVENANCE_REQUIRED` (no provenance object at all) and from `PROVENANCE_CLAIM_CONTRADICTED` (an independent verifier actively refuted a declared value). Recovery: correctable (assess the creative, set `provenance.synthetic_depiction` to true or false, and resubmit). `error.field` MUST point at the resolved `provenance.synthetic_depiction` path. The declaration does not establish consent, legality, or verification.
> [accordion] PROVENANCE_VERIFIER_NOT_ACCEPTED — correctable
>
> **Suggested action:** replace verify_agent.agent_url with one from the seller's published accepted_verifiers, drop verify_agent if the embedding is self-verifiable, or re-embed with a verifier the seller accepts
>
> Buyer attached a `verify_agent.agent_url` on `embedded_provenance[]` or `watermarks[]` that does not match (canonicalized per /docs/reference/url-canonicalization: lowercase scheme and host, strip default port, normalize path dot-segments) any entry in the seller's `creative_policy.accepted_verifiers[].agent_url`. The seller does not call buyer-asserted endpoints outside its allowlist; this is the cross-check that closes the buyer-controlled-URL trust gap. `error.field` MUST point at the offending `verify_agent.agent_url` path; `error.details` SHOULD include a reference to the product whose `creative_policy.accepted_verifiers` the buyer should consult (the buyer already has this from `get_products`). Recovery: correctable (replace `verify_agent.agent_url` with one from the seller's published `accepted_verifiers`, drop the `verify_agent` entirely if the embedding is self-verifiable, or re-embed evidence using a verifier the seller accepts).
> [accordion] RATE_LIMITED — transient
>
> **Suggested action:** wait top-level error.retry_after seconds when present, then retry
>
> Request rate exceeded. Sellers SHOULD populate top-level `error.retry_after` with the integer number of seconds to wait. Recovery: transient (wait `error.retry_after` seconds when present, then retry).
> [accordion] READ_ONLY_SCOPE — correctable
>
> **Suggested action:** use a non-mutating alternative, or surface to the operator to request a scope that permits mutation
>
> The caller's scope is read-only; the invoked task would mutate state and was rejected. Distinct from `SCOPE_INSUFFICIENT` (task not in scope at all) — the task is in some scopes this seller supports, just not this caller's. Recovery: correctable but not agent-autonomous — use a non-mutating alternative, or surface to the operator to request a scope that permits mutation.
> [accordion] REFERENCE_NOT_FOUND — correctable
>
> **Suggested action:** verify the referenced identifier exists and is accessible to the caller
>
> Generic fallback for a referenced identifier, grant, session, or other resource that does not exist or is not accessible by the caller. Use when no resource-specific not-found code applies (e.g., property lists, content standards, rights grants, SI offerings, proposals, catalogs, event sources, collection lists, brands, individual properties). Typed parameters that lack a dedicated standard code MUST also use REFERENCE_NOT_FOUND rather than minting a custom \*\_NOT_FOUND code. See 'Uniform response for inaccessible references' in error-handling.mdx for the full MUST list. Recovery: correctable. Summary of the uniform-response MUST: sellers MUST return the same response for 'exists but the caller lacks access' as for 'does not exist' across every observable channel — error.code/message/field/details (message MUST be generic; error.field MUST be identical across both cases on typed parameters); HTTP status, A2A task.status.state, and MCP isError; response headers (ETag, Cache-Control, per-type rate-limit buckets, CDN tags); side effects (webhook/audit writes, background-job enqueues, per-type quota counters, DB-shard routing); and observability (logs, APM spans, third-party error telemetry like Sentry/Datadog). Sellers MUST perform the same resolution-and-authorization work on both paths (resolve-then-authorize; on true-miss still run an authorization decision of equivalent shape against an empty principal set so authorizer latency is not a side channel). Cache population MUST NOT be gated on authorization. Polymorphism is evaluated against the tool-schema's declared parameter shape before any lookup, and a tool's declared shape MUST be identical across all callers.
> [accordion] REQUOTE_REQUIRED — correctable
>
> **Suggested action:** use error.details.decline_reason when present to inform recovery, then refine accepted_proposal_id and apply the amendment through accept_proposal, or keep control_media_buy inside the accepted envelope; some policies require a free-text ask or human negotiation, and 3.1 compatibility callers must adjust or rediscover
>
> A control_media_buy request, or the 3.x update_media_buy facade, would exceed the accepted commercial envelope. The seller is declining the requested shape at the current terms. Distinct from TERMS_REJECTED (measurement) and POLICY_VIOLATION (content). Error details SHOULD conform to error-details/requote-required.json: populate envelope_field with the field path(s) that breached the envelope, change_term_id when an accepted change term governed the request, and decline_reason when a structured seller-policy reason is available and safe to disclose. All producer-authored explanatory text, including message, suggestion, and extension detail values, MUST remain buyer-safe and MUST NOT contain vendor identifiers, internal object names, internal IDs, stack traces, or other producer-private implementation details. AdCP 3.2 callers refine the MediaBuy's accepted_proposal_id to obtain a typed amendment; legacy 3.1 callers adjust the update, rediscover terms, or create a separate buy.
> [accordion] RIGHTS_CHANNEL_VIOLATION — correctable
>
> **Suggested action:** advisory — inspect error.details.rights_id and the requested channel against rights\[].channels / excluded_channels; target a capability on a permitted channel, confirm the rights entry applies to this output, or have the holder grant the channel (a human or holder action)
>
> Advisory. A creative's rights\[] channels / excluded_channels restriction (core/rights-constraint.json) does not permit the media channel of the requested output, so building it would produce a derivative the rights grant does not allow to run there. Creative agents SHOULD check rights\[].channels against the channel each requested target capability serves (for example its applies_to_channels, where declared) before generating, and SHOULD surface this code rather than silently building; the restriction is advisory in 3.3, so a creative agent MAY proceed and attach this code as a non-terminal entry in errors\[] on an otherwise-successful build, or MAY decline the affected output with a terminal error. error.field SHOULD point at the offending rights entry (e.g. creative_manifest.rights\[0].excluded_channels, or creative_manifests\[N].rights\[i].channels for a multi-capability build) and error.details SHOULD include rights_id, the requested channel, and capability_id when the build named one. Distinct from CREATIVE_REJECTED (content-policy or brand-safety review) and from the governance plan channel check, which is a hard check by the governance agent. Recovery: correctable (target a capability whose channel the grant permits, confirm the rights entry applies to this output, or have the holder grant the channel; the last is a human or holder action, not an autonomous retry). Advisory in 3.3 and may tighten while the surface is experimental.
> [accordion] SCOPE_INSUFFICIENT — correctable
>
> **Suggested action:** the agent cannot broaden its own scope - surface to the operator rather than auto-retry
>
> The authenticated caller is not authorized for the invoked task — the task is not in the caller's `allowed_tasks` for this account (discoverable via the `authorization` object on sync_accounts / list_accounts responses). Distinct from `PERMISSION_DENIED` (generic authz failure, often credential-shaped) by being narrowly about task-level scope. Sellers SHOULD populate `error.details.introspection_hint` pointing at where the caller can re-read its scope (strawman: `{ task: 'list_accounts', account: {...} }`). Recovery: correctable in the sense that the request can be re-sent after the scope is broadened, but the agent cannot broaden its own scope — this requires operator intervention, and agents SHOULD surface rather than auto-retry.
> [accordion] SERVICE_UNAVAILABLE — transient
>
> **Suggested action:** retry with exponential backoff
>
> Seller service is temporarily unavailable. Retry with exponential backoff. Recovery: transient.
> [accordion] SESSION_NOT_FOUND — correctable
>
> **Suggested action:** initiate a new session via si_initiate_session
>
> SI session ID is invalid, expired, or does not exist. Recovery: correctable (initiate a new session via si_initiate_session).
> [accordion] SESSION_TERMINATED — correctable
>
> **Suggested action:** initiate a new session via si_initiate_session
>
> SI session has already been terminated and cannot accept further messages. Recovery: correctable (initiate a new session via si_initiate_session).
> [accordion] SIGNAL_NOT_FOUND — correctable
>
> **Suggested action:** verify signal_id via get_signals, or confirm the signal is available from this agent
>
> Referenced signal does not exist in the agent's catalog. Recovery: correctable (verify signal_ref via get_signals, or confirm the signal is available from this agent). Sellers MUST return this code uniformly for any signal_ref not accessible to the calling account — never distinguish 'exists but unauthorized' from 'does not exist', which would enable cross-tenant enumeration.
> [accordion] SIGNAL_TARGETING_INCOMPATIBLE — correctable
>
> **Suggested action:** assign the creative to a package whose signal targeting matches the creative's signal_condition, or rebuild the creative for the package's condition; match on shared signal_ref identity (compare signal_agent_segment_id exactly when both carry it, else categorical signal_ref + value)
>
> A creative carrying a signal_condition (from build_creative signal_conditions fan-out, #5240) was assigned to a package whose signal targeting is incompatible — e.g. a sun creative routed to a rain-targeted package. The trafficking-compatibility invariant: a creative built FOR one signal condition MUST NOT serve into a package targeting an incompatible condition. Enforced reject-at-trafficking on the sales side (create_media_buy / sync_creatives), NOT at build_creative (per #5280, signal pointers are advisory at the build layer; enforcement lives at the trafficking boundary). Compatibility is matched on shared signal_ref identity: when both sides carry signal_agent_segment_id, compare the opaque handle exactly; when both carry only categorical \{signal_id,value}, compare signal_ref + value-set semantics; equal categorical labels from DIFFERENT providers are NOT compatible absent an explicit equivalence mechanism; when one side has a segment handle and the other only a categorical value, the seller MAY accept only if it can resolve both to the same provider-issued segment, else reject/warn. For value_type:numeric the comparison is range-overlap (WG-open: range-overlap vs exact-match — see RFC #5240 open decisions). error.field SHOULD point at the offending assignment path (e.g. packages\[N].creative_assignments\[M] or creatives\[N]); error.details SHOULD carry the creative's signal_condition and the package's incompatible signal targeting so the buyer can re-route. Distinct from SIGNAL_NOT_FOUND (signal unknown/inaccessible) by being a compatibility mismatch between a known creative condition and a known package condition. Recovery: correctable (assign the creative to a package whose signal targeting matches its signal_condition, or rebuild for the package's condition).
> [accordion] SIGNED_RESPONSE_ENVELOPE_EXPIRED — transient
>
> **Suggested action:** re-invoke the designated task (verify_brand_claim or verify_brand_claims) to obtain a freshly signed response with a current exp window
>
> The `signed_response.payload.exp` timestamp is at or past the current time after applying the verifier's clock-skew tolerance. The signed envelope was valid when issued but the verification window has closed. Raised by verifiers consuming a designated-task signed response (`verify_brand_claim` / `verify_brand_claims`) during step 7 of the [response-signing verifier checklist](/docs/building/by-layer/L1/security#verifier-checklist-responses). Online verifiers MUST reject expired envelopes; audit verifiers MAY verify after `exp` as historical evidence that the brand-agent signed the payload during the stated `iat`/`exp` window, but MUST NOT treat the result as current truth. Distinct from `STALE_RESPONSE` (cache-staleness advisory on a populated success payload) by being a cryptographic freshness failure on a signed response envelope. Recovery: transient (re-invoke the designated task to obtain a freshly signed response with a current `exp` window).
> [accordion] SIGNED_RESPONSE_REQUEST_HASH_MISMATCH — correctable
>
> **Suggested action:** re-invoke the designated task with the intended request parameters — the signed response's request_hash does not match the verifier's recomputed hash of the actual request; if the mismatch persists across retries, investigate JCS request-binding canonicalization between caller and responder
>
> The `signed_response.payload.request_hash` does not match the verifier's recomputed SHA-256 hash of the canonical request-binding object `{ task, brand_domain, agent_url, caller_identity, request }` for the actual request sent. Raised during step 8 of the [response-signing verifier checklist](/docs/building/by-layer/L1/security#verifier-checklist-responses). This indicates either a replay of a signed response from a different request, a JCS request-binding canonicalization divergence between signer and verifier, or payload tampering. Verifiers MUST reject the envelope when the recomputed hash does not byte-match the signed `request_hash`. `error.details` SHOULD carry `expected_request_hash` (the verifier's recomputed value) when safe to disclose — the hash binds the response to the exact request that produced it, and divergence is the signal that the binding has been broken. Recovery: correctable (re-invoke the designated task with the intended request parameters; if the mismatch persists across retries, investigate JCS request-binding canonicalization between the caller and the responding agent).
> [accordion] SIGNED_RESPONSE_TENANT_MISMATCH — correctable
>
> **Suggested action:** verify the request targeted the correct brand domain and agent_url, then re-invoke; if the mismatch persists, the responding agent's server-side tenant resolution may be misconfigured
>
> The `signed_response.payload.brand_domain` does not match the verifier's resolved or expected brand tenant for this verification call. Raised during step 9 of the [response-signing verifier checklist](/docs/building/by-layer/L1/security#verifier-checklist-responses). The responding brand agent derives `brand_domain` from server-side tenant resolution, not from caller-supplied request fields (per the response-signing profile in security.mdx), so a mismatch indicates cross-tenant replay, a multi-brand agent routing error, or a mismatch between the verifier's tenant resolution and the responder's. Distinct from `SIGNED_RESPONSE_REQUEST_HASH_MISMATCH` (request-binding divergence) by being narrowly about the tenant identity — `brand_domain` is a field inside the signed payload that the responder derives independently, not an echo of any caller-supplied value. Recovery: correctable (verify that the request targeted the correct brand domain and agent; re-invoke with the correct brand reference if the request was mis-routed; if the mismatch persists, the responding agent's server-side tenant resolution may be misconfigured).
> [accordion] SOURCE_ACCESS_FAILED — correctable
>
> **Suggested action:** error.field source.locator/source.segment_ref: fix the reference; error.field source: grant the seller's declared consumer identity and retry; no error.field: vendor outage, retry with backoff
>
> Seller could not read an external audience source on sync_audiences (experimental, media_buy.audience_activation). Per-audience: surfaces as action: failed with this code in the audience's errors array. The seller cannot reliably distinguish a revoked grant from an expired one from a transient vendor outage — all three observables are a failed read — so error.field distinguishes what the buyer can act on: 'source.locator' or 'source.segment_ref' means the reference does not resolve (changed request needed); 'source' means access denied (establish or re-grant access to the seller's declared consumer identity, then retry); absence of error.field indicates a vendor-side failure (retry with backoff, no buyer action). On an already-ready audience a failed re-read MUST NOT change audience status — membership stays frozen at the last successful read and source.access_status reports 'unavailable'. Recovery: correctable (fix the reference or grant per error.field; vendor outages without error.field are transient and retry with backoff).
> [accordion] STALE_RESPONSE — transient
>
> **Suggested action:** advisory — emitted alongside a populated payload that was served from cache past the seller's freshness target because an upstream or sub-agent was unreachable. The response is usable; treat as non-fatal. Inspect `error.details.cache_age_seconds` to decide whether to immediately retry for fresh data or accept the cached value; the seller's own service is healthy, so retry is safe (it does not amplify the upstream failure)
>
> Non-fatal advisory raised when the seller's live fetch to an upstream or sub-agent failed (timeout, connection error, downstream 5xx) and the response payload was satisfied from a cached prior result that is past the seller's freshness target for this surface. Emitted **alongside** a populated success payload — the caller's request still completes from a usable cache hit; this code tells downstream consumers that the data is older than the seller would normally serve.
>
> Distinct from `SERVICE_UNAVAILABLE` (seller's own service is down, no payload — transient, retry-with-backoff) by signalling **graceful degradation**: the seller's own service is fine, but one of its dependencies is currently unreachable and the seller chose to honor the request from cache rather than return empty. Sellers MUST emit `STALE_RESPONSE` ONLY when the response payload is non-empty AND derived from a cache entry whose `cache_age_seconds` exceeds the surface's freshness target. When no cached entry exists (or the cache hit is within freshness target), sellers MUST NOT emit this code — return the empty-or-fresh response with whatever upstream-failure code applies (e.g., `SERVICE_UNAVAILABLE`).
>
> **Wire placement (normative).** Transport-level success markers stay flipped to success (HTTP 200, MCP `isError: false`, A2A `succeeded`) — the task ran successfully and produced a response, even if from cache. The advisory rides in `errors[]` on the payload and MUST NOT be promoted to `adcp_error` on the envelope (envelope-level errors are reserved for the empty-payload failure case per the two-layer model in `error-handling.mdx#envelope-vs-payload-errors-the-two-layer-model`). `error.field` SHOULD point at the affected payload path (e.g., `formats` for `list_creative_formats`, `products` for `get_products`). `error.details` SHOULD conform to `error-details/stale-response.json` — `served_from_cache` (required, always `true`), `cache_age_seconds` (required), and optionally `freshness_target_seconds`, `upstream` (the dependency that failed), and `original_error` (the underlying failure code/message).
>
> **Multiple stale upstreams.** When N sub-agents are stale (e.g., a `list_creative_formats` registry aggregating from multiple creative agents), the seller SHOULD emit **one `STALE_RESPONSE` entry per affected upstream** rather than aggregating — the per-upstream shape mirrors the existing precedent set by `PIXEL_TRACKER_LOSSY_DOWNGRADE` (one advisory per downgraded asset) and lets buyer agents reason about which sub-population of the payload is stale. Each entry's `error.field` SHOULD narrow to the affected slice (e.g., `formats` for formats sourced from the stale upstream).
>
> Recovery: transient — buyers MUST treat as non-fatal (the response is usable), MAY immediately retry later for fresh data, and SHOULD surface staleness to operators or end users when relevant. `cache_age_seconds` is the informational knob for the buyer's own "is this stale enough to bother retrying" policy.
> [accordion] TERMS_REJECTED — correctable
>
> **Suggested action:** adjust the proposed terms and retry, or omit measurement_terms to accept the product's defaults
>
> Buyer-proposed measurement_terms were rejected by the seller. The error details SHOULD identify which specific term was rejected and the seller's acceptable range or supported vendors. Recovery: correctable (adjust the proposed terms and retry, or omit measurement_terms to accept the product's defaults).
> [accordion] UNPRICEABLE_OUTPUT — correctable
>
> **Suggested action:** target an output format the transformer prices, or have the seller add a pricing option covering it
>
> A creative transformer build targets an output capability that no pricing option covers — no transformer.pricing_options entry has a matching applies_to_output_capability_ids and none is unscoped. The build is rejected rather than billed at a guessed rate. Recovery: correctable.
> [accordion] UNRECOGNIZED_TERMS — correctable
>
> **Suggested action:** remove the member the seller cannot interpret, or send it only to sellers that interpret it
>
> The request carries commercial terms the seller would record and be bound by, such as a buy_products purchase, and at least one member of them, at any depth and including ext, is one the seller cannot interpret. Accepting signed terms binds the accepting party to every member, so the seller MUST reject the request instead of accepting it, dropping the member, or carrying it without interpreting it. A member whose schema defines it as opaque, such as context, is interpreted by that definition. The seller SHOULD set error.field to the path of the first such member. Distinct from UNSUPPORTED_FEATURE (a field the seller recognizes but does not support) and INVALID_REQUEST (a request that fails the schema). Recovery: correctable (remove the member, or send it only to sellers that interpret it).
> [accordion] UNSUPPORTED_FEATURE — correctable
>
> **Suggested action:** check get_adcp_capabilities (or the product's overlay_support for a rejected targeting dimension), remove unsupported fields, and use details.replacement_dimension when present
>
> A requested feature or field is not supported by this seller. When rejecting a `refine_proposals` request that uses a typed dimension omitted from an explicit `proposal_refinement.supported_dimensions` declaration, the error details SHOULD follow `error-details/unsupported-refinement-dimension.json` — `unsupported_dimension` names the offending dimension and `supported_dimensions` echoes the seller's declaration so the buyer can remove or translate the field without another capability round trip. When rejecting a targeting dimension that is unsupported for the product or seller, or has been removed, the error details SHOULD follow `error-details/unsupported-targeting-dimension.json` (`unsupported_dimension`, optional `supported_dimensions`, `deprecated`, `replacement_dimension`) and `error.field` SHOULD point at the targeting path. When rejecting a `sync_creatives` assignment operation the agent does not list in `creative.assignment_operations`, `error.field` SHOULD point at that operation's `operation`. Recovery: correctable (check get_adcp_capabilities (or the product's overlay_support for a rejected targeting dimension), remove unsupported fields, and use details.replacement_dimension when present).
> [accordion] UNSUPPORTED_GRANULARITY — correctable
>
> **Suggested action:** pick a granularity from the product's reporting_capabilities.windowed_pull_granularities (via get_adcp_capabilities) and resubmit, or omit time_granularity to fall back to cumulative date-range pulls
>
> The requested `time_granularity` on `get_media_buy_delivery` is not in the product's declared `reporting_capabilities.windowed_pull_granularities`. Distinct from `UNSUPPORTED_FEATURE` (generic capability mismatch) by being narrowly about reporting-window granularity — the buyer asked for hourly pull-recovery on a product that only honors daily pulls, for example. Sellers MAY echo the declared set in `error.details.supported_granularities` when the caller is authorized to read the product's reporting capabilities — the same set is already available via `get_adcp_capabilities`, so the echo is a convenience, not load-bearing. Sellers MUST NOT echo a granularity set the caller could not otherwise read (per-product capability views vary by buyer entitlement). The `error.field` SHOULD point at `time_granularity`. Buyers that need higher-frequency recovery than the seller's pull set supports MUST rely on the webhook channel as primary at that frequency — the seller's `available_reporting_frequencies` may legitimately exceed `windowed_pull_granularities` (e.g., a stream-tap webhook on Kafka with warehouse pulls only at daily). Recovery: correctable (re-issue at a granularity in the declared set, or omit `time_granularity` to fall back to cumulative date-range pulls).
> [accordion] UNSUPPORTED_PROVISIONING — correctable
>
> **Suggested action:** re-issue with the entry shape the seller supports — `account: {account_id: ...}` for settings-update sellers with account-id namespaces, or `brand+operator+billing` for provisioning sellers; check seller documentation or capability declaration for which modes are implemented
>
> The seller does not support the `sync_accounts` mode the entry requested. Returned per-entry in the `sync_accounts` response when (a) an entry keyed by the natural-key trio (`brand` + `operator` + `billing`) is sent to a seller that does not provision accounts via AdCP — typical for account-id namespaces where accounts are pre-provisioned out of band or discovered via `list_accounts`; or (b) an entry keyed by `account` (AccountRef) is sent to an account-id-namespace seller that does not expose settings updates. A seller that opens buyer-declared accounts through `sync_accounts` accepts settings-update entries and declines an attribute change it cannot make with `UNSUPPORTED_FEATURE`. Distinct from `UNSUPPORTED_FEATURE` (generic capability mismatch) by being narrowly about which of the two `sync_accounts` modes the seller implements. The two modes are mutually exclusive per-entry — the seller MUST NOT silently downgrade or upgrade between them. Sellers MAY declare which modes they implement via `get_adcp_capabilities` (forward-looking — capability declaration shape is open). Recovery: correctable (re-issue with the entry shape the seller supports; for account-id namespaces that expose settings updates, that means `account: {account_id: ...}` entries; for sellers that only provision via natural key that means the flat `brand+operator+billing` shape). The `error.field` SHOULD point at the entry index where the unsupported shape was found.
> [accordion] VALIDATION_ERROR — correctable
>
> **Suggested action:** review error details and fix field values
>
> Request contains invalid field values or violates business rules beyond schema validation. Recovery: correctable (review error details and fix field values).
> [accordion] VAST_PARSE_FAILED — correctable
>
> **Suggested action:** inspect error.details.reason (not_xml, no_vast_root, no_ad, no_media_file), fix the VAST document, and resubmit
>
> A submitted `vast` asset failed document-level validation: the inline `content` (or the document fetched from `url`) is not well-formed XML, has no `` root element, contains no `` element, or an `` linear creative carries no ``. Returned by sellers that declare `creative_specs.vast_validation` of `document` or `wrapper`; sellers at the default `structural` level do not inspect the VAST document and MUST NOT return this code. Distinct from `VALIDATION_ERROR` (manifest-level format validation): the manifest was structurally valid, the VAST document inside it was not. Sellers SHOULD set `error.field` to the offending asset path and SHOULD populate `error.details.reason` with one of `not_xml`, `no_vast_root`, `no_ad`, `no_media_file`. Unresolved ad-server macros in URLs (`[MACRO]`, `${MACRO}`, `{UNIVERSAL_MACRO}`) are opaque tokens, not parse failures. Recovery: correctable (fix the VAST document and resubmit).
> [accordion] VAST_VERSION_MISMATCH — correctable
>
> **Suggested action:** inspect error.details.mismatch_reason and the corresponding acceptance-set or observed-document fields; select a compatible source representation or correct the offending VAST document
>
> A submitted `vast` asset is version-incompatible when its exact `vast_version` is absent from the intersection of the selected product format option's `params.vast_versions` and the seller's `execution.creative_specs.vast_versions`, or when an inspected document violates its applicable VAST version rule. Modern `error.details` MUST conform to `error-details/vast-version-mismatch.json`: acceptance failures carry `mismatch_reason: asset_outside_acceptance`, `asset_vast_version`, `product_vast_versions`, and `seller_vast_versions`, plus `format_option_ref` only when the selected option is addressable; inspected-document failures carry `mismatch_reason: document_version_mismatch`, `asset_vast_version`, `observed_document_vast_version`, and `document_role`. Only the submitted document is compared for equality with the asset declaration; wrapper and terminal documents are checked against the acceptance intersection. The deprecated `supported_versions` field remains accepted for older 3.x peers. Distinct from `VERSION_UNSUPPORTED`, which concerns AdCP protocol negotiation. Recovery: correctable (select a source VAST representation in the compatibility intersection or correct the offending document; never relabel the asset).
> [accordion] VAST_WRAPPER_DEPTH_EXCEEDED — correctable
>
> **Suggested action:** inspect error.details.reason (depth, loop, timeout); flatten the wrapper chain, reduce redirects below the format's max_wrapper_depth, or fix the failing hop
>
> Resolving a `vast` asset's wrapper chain failed: the chain exceeded the format's declared `max_wrapper_depth`, revisited a `VASTAdTagURI` already seen in the chain (a loop), or a hop did not resolve within the seller's per-hop timeout. Returned by sellers that declare `creative_specs.vast_validation: "wrapper"`. Sellers SHOULD set `error.field` to the offending asset path and SHOULD populate `error.details.reason` with one of `depth`, `loop`, `timeout`, plus `error.details.depth` with the depth reached. Recovery: correctable (flatten the chain, reduce redirects below the format's `max_wrapper_depth`, or fix the failing hop).
> [accordion] VERSION_UNSUPPORTED — correctable
>
> **Suggested action:** re-pin to a release in supported_versions and retry, or call get_adcp_capabilities without a version pin to discover supported_versions
>
> The declared adcp_version (release-precision) or adcp_major_version (deprecated) is not supported by this seller. The error details SHOULD follow `error-details/version-unsupported.json` — `supported_versions` (release-precision strings) is authoritative for retry; `supported_majors` is deprecated. Recovery: correctable (re-pin to a release in supported_versions and retry; or call get_adcp_capabilities without a version pin to discover supported_versions).
## Protocols
Top-level agent capability claims. An agent claims a protocol by listing it in `supported_protocols` and must pass the protocol's baseline storyboard plus every [universal](/dist/docs/3.2.8/building/verification/validate-your-agent#storyboard-taxonomy) storyboard.
`supported_protocols` uses snake_case; compliance paths and specialism IDs use kebab-case. See [Naming conventions](#naming-conventions) below for the full mapping.
| `supported_protocols` value | Compliance path | Purpose |
| - | - | - |
| `media_buy` | `protocols/media-buy/` | Campaign creation, package management, delivery optimization, conversion tracking |
| `creative` | `protocols/creative/` | Creative asset management, format discovery, rendering |
| `signals` | `protocols/signals/` | Audience signal discovery and activation |
| `governance` | `protocols/governance/` | Property governance, brand standards, compliance |
| `brand` | `protocols/brand/` | Brand identity, rights discovery, rights acquisition *— small protocol today, growing with rights licensing work; see `brand-rights` specialism.* |
| `sponsored_intelligence` | `protocols/sponsored-intelligence/` | AI-mediated commerce and conversational sponsored experiences |
| `measurement` | Preview / no stable baseline | Experimental 3.1 metric-catalog discovery. Agents implementing it must list `measurement.core` in `experimental_features`. |
> [!NOTE]
>
> Support for the [compliance test controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) is declared via the `capabilities.compliance_testing` block on [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities), not via `supported_protocols`. Compliance testing is an RPC surface for the test harness, not a functional protocol.
> [!TIP]
>
> An agent can claim multiple protocols — a full-stack media-buy platform might list `media_buy`, `creative`, and `signals`. The runner executes all matching baselines.
## Specialisms
Specific capability claims. Each specialism lives under exactly one protocol. An agent claiming a specialism must pass the specialism's storyboard in addition to the parent protocol's baseline — e.g. claiming `sales-guaranteed` requires `media_buy` in `supported_protocols`.
Specialisms carry a `status`:
* **`stable`** — fully specified storyboard. Compliance runner executes every phase; `AAO Verified` means the agent demonstrably passed.
* **`preview`** — ID and scope are reserved; the storyboard is a placeholder while the underlying protocol surface stabilizes. Agents may claim these; the runner emits a result of `{ status: "preview", passed: null, reason: "storyboard not yet defined" }` instead of a verified pass/fail. AAO badges render preview specialisms with a distinct indicator.
* **`deprecated`** — retained for backward compatibility but scheduled for removal in a future major. Runner emits `{ status: "deprecated", passed: , reason: "..." }` — still executes the storyboard if one exists, but warns the claim should be migrated.
Status is declared per-specialism in the YAML frontmatter and surfaced in `/compliance/{version}/index.json`.
Specialisms are grouped below by parent protocol.
> [!NOTE]
>
> **What changed in 3.0.** `sponsored_intelligence` was promoted from a specialism to a full protocol (declare it in `supported_protocols`, not `specialisms`). `audience-sync` moved from `governance` to `media-buy` to match its tool family. `broadcast-platform` was renamed to `sales-broadcast-tv` and `social-platform` to `sales-social`. `property-governance` and `collection-governance` split into sibling `property-lists` and `collection-lists` specialisms.
### media-buy
| Specialism | Status | Purpose |
| - | - | - |
| `sales-guaranteed` | stable | Guaranteed media buys with human IO approval |
| `sales-non-guaranteed` | stable | Non-guaranteed auction-based media buys |
| `sales-proposal-mode` | deprecated | **Deprecated in 3.1.** Drop this claim and replace with `sales-guaranteed` + `media_buy.supports_proposals: true`. See [#3823](https://github.com/adcontextprotocol/adcp/issues/3823). |
| `sales-catalog-driven` | stable | Catalog-driven commerce with conversion tracking |
| `sales-broadcast-tv` | stable | Broadcast linear TV with guaranteed inventory and FCC cancellation rules |
| `sales-dooh` | stable | Digital out-of-home, non-guaranteed venue and screen inventory |
| `sales-social` | stable | Social media advertising platform with self-service flows |
| `governance-aware-seller` | stable | Seller composes with the buyer's campaign-governance agent after baseline registration — calls [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) and propagates approvals, conditions, and denials unchanged. Optional claim for the full governance-check loop. |
| `audience-sync` | stable | Syncs buyer-provided audience segments into a platform for activation (uses [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences), [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts)) |
| `buyer-discovery` | preview | Buyer agent that discovers seller inventory, interprets product capabilities, and assembles a candidate shortlist from a brief |
| `buyer-activation` | preview | Buyer agent that creates media buys with correct idempotency keys, handles transient failures with retry, and coordinates creative assignment |
| `buyer-negotiation` | preview | Buyer agent that requests proposals, refines terms, handles TERMS_REJECTED, and accepts or declines offers |
| `buyer-monitoring` | preview | Buyer agent that monitors delivery via webhooks and polling, detects pacing variance, and flags under-delivery |
| `buyer-recovery` | preview | Buyer agent that handles seller offline, auth expiry, idempotency collisions, and rate limiting with graceful degradation |
| `orchestrator-multi-agent` | preview | Orchestrator agent that coordinates across multiple sellers, handles partial failures, and reconciles cross-agent budget and state |
| `sales-retail-media` | preview | Retail media network seller — onsite sponsored search, sponsored display, and offsite extensions tied to SKU-level catalog feeds, keyword targeting, and deterministic purchase attribution |
| `sales-streaming-tv` | preview | Connected TV and streaming seller — SSAI-delivered video inventory, audience-based buying, household-level frequency capping, and VAST creative delivery across CTV apps |
| `sales-exchange` | preview | Programmatic exchange or SSP — multi-publisher auction inventory with floor prices, bid guidance, audience targeting, and auction-level delivery transparency |
> [!NOTE]
>
> `audience-sync` moved from the `governance` protocol to `media-buy` to match its tool family. If your agent claims `audience-sync` but only declares `governance` in `supported_protocols`, add `media_buy` to `supported_protocols` — the runner now expects the media-buy baseline to run alongside the audience-sync storyboard.
### creative
| Specialism | Status | Purpose |
| - | - | - |
| `creative-ad-server` | stable | Creative ad server with tag-based delivery |
| `creative-generative` | stable | Generative creative agent producing assets on demand |
| `creative-template` | stable | Creative template and transformation agent |
### signals
| Specialism | Status | Purpose |
| - | - | - |
| `signal-owned` | stable | Owned signal agent exposing first-party segments through [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals); activation is not required for this claim |
| `signal-marketplace` | stable | Marketplace signal agent reselling third-party data; requires `get_signals` and [`activate_signal`](/dist/docs/3.2.8/signals/tasks/activate_signal) |
### governance
| Specialism | Status | Purpose |
| - | - | - |
| `content-standards` | stable | Content standards enforcement (brand safety, policy compliance) |
| `property-lists` | stable | Property list governance — curated inclusion and exclusion lists for targeting and delivery compliance |
| `collection-lists` | stable | Collection list governance — curated inclusion and exclusion lists of content programs (shows, series, podcasts) for program-level brand safety |
| `governance-delivery-monitor` | stable | Campaign delivery monitoring with drift detection |
| `governance-spend-authority` | stable | Conditional spend approval and human-in-the-loop governance |
> [!NOTE]
>
> **Experimental in 3.1.** Measurement metric-catalog discovery is available through the experimental `measurement` capability block and `measurement.core` experimental feature. A stable `measurement-verification` specialism and baseline storyboard are deferred until the measurement task surface is frozen.
### brand
| Specialism | Status | Purpose |
| - | - | - |
| `brand-rights` | stable | Brand identity and rights licensing (talent, music, stock media) |
## Choosing a sales specialism
The `sales-*` specialisms are not mutually exclusive — a hybrid platform with both a guaranteed direct desk and an auction floor should claim both `sales-guaranteed` and `sales-non-guaranteed`. Follow the steps below to resolve your claim.
> [!WARNING]
>
> **`sales-proposal-mode` is deprecated in 3.1.** Do not claim it for new agents. Existing agents that declare it must drop it entirely and replace it with `sales-guaranteed` + `media_buy.supports_proposals: true` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). See [#3823](https://github.com/adcontextprotocol/adcp/issues/3823).
**1. Is your inventory channel-specific?**
Four specialisms apply to specific delivery channels and have their own storyboards. If you only sell one of these channel types, claim only the matching specialism. If you also sell general display or video inventory outside these channels, continue to Step 2.
| If you operate… | Claim |
| - | - |
| Broadcast linear TV with FCC cancellation rules | `sales-broadcast-tv` |
| Catalog-driven dynamic ads (product listings, restaurant menus, hotel listings, local commerce) | `sales-catalog-driven` |
| Non-guaranteed digital out-of-home venue and screen inventory | `sales-dooh` |
| Guaranteed-only digital out-of-home inventory | `sales-guaranteed` |
| Social platform with platform-managed creative | `sales-social` |
`sales-dooh` is the non-guaranteed DOOH profile. Guaranteed-only DOOH sellers still route `dooh` briefs through their portfolio declaration, but claim `sales-guaranteed` until a dedicated guaranteed DOOH profile exists.
**2. What purchase model do you support?**
| If you sell… | Claim |
| - | - |
| Guaranteed media (IO approval, fixed pricing) | `sales-guaranteed` → see Step 3 |
| Auction / PMP non-guaranteed | `sales-non-guaranteed` |
| Both guaranteed and non-guaranteed | `sales-guaranteed` + `sales-non-guaranteed` |
**3. Set media_buy.supports_proposals (sales-guaranteed only)**
`media_buy.supports_proposals` is a boolean in the `media_buy` capabilities block of your `get_adcp_capabilities` response. It gates whether the `proposal_finalize` compliance scenario runs. It is a conformance declaration, not the buyer's per-proposal routing signal: buyers decide whether a returned proposal can be bought from `proposal_status`.
| If you… | Set |
| - | - |
| Accept RFPs, generate proposals, and finalize draft proposals to committed status before create | `media_buy.supports_proposals: true` |
| Sell direct-buy guaranteed only (auction PG, retail SKU, quoted-rate — no RFP flow) | `media_buy.supports_proposals: false` (or omit — default is `false`) |
```jsonc theme={null}
// Full-service guaranteed seller — proposal lifecycle graded
{
"supported_protocols": ["media_buy"],
"specialisms": ["sales-guaranteed"],
"media_buy": {
"supports_proposals": true
}
}
```
```jsonc theme={null}
// Direct-buy guaranteed seller — proposal scenario skipped as capability_unsupported
{
"supported_protocols": ["media_buy"],
"specialisms": ["sales-guaranteed"],
"media_buy": {
"supports_proposals": false
}
}
```
### creative
| Specialism | Status | Purpose |
| - | - | - |
| `creative-ad-server` | stable | Creative ad server with tag-based delivery |
| `creative-generative` | stable | Generative creative agent producing assets on demand |
| `creative-template` | stable | Creative template and transformation agent |
### signals
| Specialism | Status | Purpose |
| - | - | - |
| `signal-owned` | stable | Owned signal agent exposing first-party segments through [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals); activation is not required for this claim |
| `signal-marketplace` | stable | Marketplace signal agent reselling third-party data; requires `get_signals` and [`activate_signal`](/dist/docs/3.2.8/signals/tasks/activate_signal) |
### governance
| Specialism | Status | Purpose |
| - | - | - |
| `content-standards` | stable | Content standards enforcement (brand safety, policy compliance) |
| `property-lists` | stable | Property list governance — curated inclusion and exclusion lists for targeting and delivery compliance |
| `collection-lists` | stable | Collection list governance — curated inclusion and exclusion lists of content programs (shows, series, podcasts) for program-level brand safety |
| `governance-delivery-monitor` | stable | Campaign delivery monitoring with drift detection |
| `governance-spend-authority` | stable | Conditional spend approval and human-in-the-loop governance |
> [!NOTE]
>
> **Experimental in 3.1.** Measurement metric-catalog discovery is available through the experimental `measurement` capability block and `measurement.core` experimental feature. A stable `measurement-verification` specialism and baseline storyboard are deferred until the measurement task surface is frozen.
### brand
| Specialism | Status | Purpose |
| - | - | - |
| `brand-rights` | stable | Brand identity and rights licensing (talent, music, stock media) |
### sponsored-intelligence
| Specialism | Status | Purpose |
| - | - | - |
| `sponsored-intelligence` | preview | Agent claim for SDKs that dispatch on specialism ID. The graded storyboard is the `sponsored-intelligence` protocol baseline; this specialism reserves the wire ID and promotes to `stable` when the SI tools graduate from `x-status: experimental`. |
## Cross-resource invariants
In addition to per-step validations, specialisms declare cross-step and cross-resource **invariants** the runner observes across the full storyboard run. These catch state inconsistencies that no single response shape would surface.
| Invariant | Scope | Specialisms |
| - | - | - |
| `status.monotonic` | Single-resource — rejects status transitions observed across steps that aren't on the spec lifecycle graph. | All specialisms with a stateful resource lifecycle. |
| `impairment.coherence` | Cross-resource — verifies that `media_buy.impairments[]` stays in sync with referenced resources. **Forward**: every entry references a currently-offline resource. **Inverse**: any offline resource referenced by a non-terminal buy appears in `impairments[]`. **Health-iff**: on a non-terminal buy, `health == "impaired"` iff `impairments[]` is non-empty (strict iff — stale drift fails). Out of scope: all three rules relax on terminal-status buys (sellers MAY leave `impairments[]` and `health` in whatever state held at the terminal transition); materiality is schema-enforced via `package_ids: minItems: 1`. | `audience-sync`, `creative-ad-server`, `creative-template`, `creative-generative`, `sales-catalog-driven`. Driven by the [`media_buy_seller/dependency_impairment`](/compliance/latest/protocols/media-buy/scenarios/dependency_impairment.yaml) scenario (creative-track via `force_creative_status`); audience-track and catalog-track follow once the compliance test controller adds `force_audience_status` / `force_catalog_item_status`. Grades `not_applicable` on storyboards that don't observe both a resource transition and a media-buy snapshot read. |
Invariants are declared in the specialism YAML's `invariants:` array and documented inline with the rule they enforce. See [media-buy lifecycle § Compliance](/dist/docs/3.2.8/media-buy/media-buys/lifecycle#compliance) for the full `impairment.coherence` contract.
## How to claim
Declare your protocols and specialisms in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities):
```json theme={null}
{
"supported_protocols": ["media_buy", "creative"],
"specialisms": ["sales-guaranteed", "creative-template"]
}
```
The storyboard runner:
1. Runs every storyboard in `/compliance/{version}/universal/`
2. For each protocol in `supported_protocols`, runs the baseline at `/compliance/{version}/protocols/{protocol}/` (snake_case → kebab-case)
3. Runs each claimed specialism's storyboard at `/compliance/{version}/specialisms/{id}/`
4. For `preview` specialisms, emits a warning instead of a pass/fail verdict — AAO Verified badges render preview specialisms with a distinct indicator
> [!WARNING]
>
> **Implement the tools AND claim the specialism.** An agent that wires all of a specialism's required tools but omits the kebab-case ID from `capabilities.specialisms[]` will be graded **"No applicable tracks found"** by the runner — `tracks_passed = 0, tracks_failed = 0, tracks_skipped = 1`. This is a silent pass at the step level and a silent fail at the track level. The fix is to add the specialism ID (e.g., `"creative-generative"`) to your `get_adcp_capabilities` response.
If any `stable` storyboard fails, your agent is not compliant for that claim. See [Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent) for how to run the suite locally. For a detailed walkthrough of how the runner resolves specialism manifests into graded scenarios — including how capability flags like `media_buy.supports_proposals` gate individual scenarios — see [How grading works](/dist/docs/3.2.8/building/verification/how-grading-works).
## Naming conventions
Four casings coexist in the taxonomy. Which one applies depends on where the identifier is read:
| Casing | Layer | Example | Where it appears |
| - | - | - | - |
| `snake_case` | Wire enums (`supported_protocols`, `delivery_type`, channel IDs, `signal_type`) | `media_buy`, `non_guaranteed`, `ctv`, `custom` | [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) response, JSON payloads, generated schemas |
| `kebab-case` | Specialism IDs and compliance URLs | `sales-broadcast-tv`, `property-lists`, `audience-sync` | `get_adcp_capabilities.specialisms`, `/compliance/.../specialisms/{id}/` paths |
| `snake_case` | Storyboard `id:` and `category:` fields | `sales_broadcast_tv`, `audience_sync` | Compliance YAML frontmatter, runner output, test reports |
| Prose / hyphenated | Titles and narrative | "Streaming TV", "non-guaranteed" | Catalog pages, narrative copy |
The kebab↔snake swap between wire specialism IDs and storyboard categories is mechanical identity — hyphens become underscores, nothing more. Variant scenarios within a specialism use `{category}/{variant}` path form.
| Specialism ID (wire) | Channel / tool family | Storyboard category | Variant scenarios |
| - | - | - | - |
| `sales-broadcast-tv` | `channels: ['linear_tv']` | [`sales_broadcast_tv`](/compliance/latest/specialisms/sales-broadcast-tv/index.yaml) | — |
| `sales-dooh` | `channels: ['dooh']` | [`sales_dooh`](/compliance/latest/specialisms/sales-dooh/index.yaml) | — |
| `sales-social` | `channels: ['social']` | [`sales_social`](/compliance/latest/specialisms/sales-social/index.yaml) | — |
| `audience-sync` | [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) tool | [`audience_sync`](/compliance/latest/specialisms/audience-sync/index.yaml) | — |
| `property-lists` | `property_list` tools | [`property_lists`](/compliance/latest/specialisms/property-lists/index.yaml) | — |
| `collection-lists` | `collection_list` tools | [`collection_lists`](/compliance/latest/specialisms/collection-lists/index.yaml) | — |
| `governance-spend-authority` | [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance), [`sync_plans`](/dist/docs/3.2.8/governance/campaign/tasks/sync_plans) | [`governance_spend_authority`](/compliance/latest/specialisms/governance-spend-authority/index.yaml) | [`governance_spend_authority/denied`](/compliance/latest/specialisms/governance-spend-authority/denied.yaml) |
| `creative-generative` | [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) | [`creative_generative`](/compliance/latest/specialisms/creative-generative/index.yaml) | [`creative_generative/seller`](/compliance/latest/specialisms/creative-generative/generative-seller.yaml) |
| `brand-rights` | [`get_brand_identity`](/dist/docs/3.2.8/brand-protocol/tasks/get_brand_identity), [`acquire_rights`](/dist/docs/3.2.8/brand-protocol/tasks/acquire_rights) | [`brand_rights`](/compliance/latest/specialisms/brand-rights/index.yaml) | [`brand_rights/governance_denied`](/compliance/latest/specialisms/brand-rights/scenarios/governance_denied.yaml) |
The case split is deliberate: `supported_protocols` is a pre-existing 3.0 field already shipped to production agents, while specialism IDs are new and URL-first (each is a directory name under `/compliance/.../specialisms/{id}/`). The runner handles the mapping transparently.
### Specialism ↔ tool family mapping
The protocol an agent claims does not always match the tool family name a specialism uses:
* `audience-sync` lives under the `media-buy` protocol because `sync_audiences` is a media-buy tool.
* `property-lists` (specialism ID, kebab-case) maps to the `property_list` tool family ([`create_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#create_property_list), [`validate_property_delivery`](/dist/docs/3.2.8/governance/property/tasks/validate_property_delivery)) and storyboard category `property_lists`.
* `sales-broadcast-tv` declares `channels: ['linear_tv']` — "Broadcast TV" is the prose name; `linear_tv` is the wire value.
`/compliance/{version}/index.json` surfaces each specialism's `required_tools` so agents can discover the tool families without reading the full storyboard YAML.
### Wire enum vs prose
Wire enum values are always `snake_case` (`non_guaranteed`, `pmax_platform`, `ctv`). Prose renders the same concept with hyphens or spaces ("non-guaranteed auction inventory", "Connected TV"). When populating a payload, always use the wire form — hyphenated or spaced spellings are editorial only and will fail schema validation.
### `signal_type` values
The `signal_type` enum in signal responses has three values:
* `marketplace` — the signal agent is reselling segments published by a third-party data provider (Experian, Peer39, etc.). Buyers can verify authorization via the provider's `/.well-known/adagents.json`.
* `owned` — the signal agent exposes its own first-party segments derived from directly owned data (retailer purchase data, publisher behavioral data, telco location data).
* `custom` — the signal source builds the segment on demand from models, composites, or buyer-supplied inputs. Use this when no `adagents.json` authorization chain applies — the segment is source-native, not attributable to a standing upstream provider.
## Source of truth
The machine index is published alongside schemas:
| Path | Contents |
| - | - |
| `/compliance/{version}/index.json` | Enumerated protocols + specialisms + universal storyboards + per-specialism `status` |
| `/schemas/{version}/enums/specialism.json` | Specialism enum used by `get_adcp_capabilities.specialisms` |
| `/schemas/{version}/enums/adcp-protocol.json` | Task-classification enum referenced by `tasks-list-request` and webhook payloads. Same axis as `supported_protocols` (kebab-case here, snake_case on the wire). |
The build pipeline verifies the specialism filesystem ↔ enum parity and that every specialism's parent protocol exists in the compliance tree. Drift fails the build.
> [!NOTE]
>
> The catalog on this page is maintained by hand to give human context. The authoritative enumeration is always `/compliance/{version}/index.json`.
> [!TIP]
>
> **Building an agent that wraps an upstream platform?** Storyboards in this catalog grade the AdCP wire contract; they cannot detect adapters that return shape-valid responses without integrating with the upstream. See **[Validate adapter agents with mock upstream fixtures](/dist/docs/3.2.8/building/verification/validate-with-mock-fixtures)** for the complementary pre-staging gate.
# Conformance Specification
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/conformance
What 'AdCP-conformant' means, defined by the storyboards that verify it. Conformance is what the spec requires; verified is what the suite attests.
**Status**: Request for Comments
**Last Updated**: April 19, 2026
## Two words, not three
AdCP conformance has two load-bearing terms. A third (one you'll hear in the wild) is a trap.
* **Conformant** — the agent meets the normative rules. Defined by the storyboards this document indexes.
* **Verified** — AAO has tested the agent recently and issued a signed attestation. Gated on active membership and a live heartbeat. The [AAO Verified badge](/dist/docs/3.2.8/building/verification/aao-verified) carries one of two qualifiers: **(Spec)** for storyboard-conformance against a test deployment or dev endpoint, **(Sandbox)** for storyboard-conformance against the seller's real production endpoint under `account.sandbox: true` flagging. An agent can earn either or both.
* **"Compliant"** — self-attested, unverified, no external check. Don't claim it; don't design for it. This document uses *conformant* and *verified* exclusively.
Put differently:
* Conformance is a property of the agent's wire behavior.
* Verification is a time-bounded third-party attestation. **(Spec)** attests wire-format conformance against any registered endpoint; **(Sandbox)** attests the same storyboard suite passes against the seller's real production endpoint under sandbox-flagged traffic. Same storyboards, different attestation surface.
* The two axes are independent: a seller without a separate test deployment can earn **(Sandbox)** directly on production; a test agent that can never serve real impressions earns **(Spec)** as a complete claim.
## Storyboard conformance vs. AAO Verified
This page indexes **storyboard conformance** — the property an agent's wire behavior has when it matches the spec, verified by storyboards running against seeded test data. Storyboard passing earns the **AAO Verified (Spec)** or **AAO Verified (Sandbox)** qualifier (or both) on an agent's badge, depending on where the runner targeted.
A second axis — **AAO Verified (Sandbox)** — verifies the seller's real production endpoint correctly handles the full storyboard suite under `account.sandbox: true` flagging. (Sandbox) is the stronger claim: a seller can pass (Spec) on a test deployment while their production stack has a broken sandbox gate (real-world side effects under flagged traffic, missing account-mode verification, etc.) — (Sandbox) closes that gap.
The two qualifiers share one brand mark — **AAO Verified** — and an agent can earn either or both. **(Spec) and (Sandbox) are independent**: each independently demonstrates conformance through different evidence. (Spec) attests wire-format conformance against any registered endpoint; (Sandbox) attests the production code path correctly tolerates sandbox-flagged traffic. See [AAO Verified](/dist/docs/3.2.8/building/verification/aao-verified) for the qualifier model and the [Sandbox framing verdict](https://github.com/adcontextprotocol/adcp/issues/4379); the rest of this page indexes the storyboards that back both qualifiers.
## Test surfaces and the storyboard loop
Every seller exposes a *test surface* — the mechanism that lets a storyboard runner exercise the seller's tools deterministically without triggering real-world side effects. The test surface is what (Spec) is graded against. How a seller stands up that surface depends on where their state-of-record lives; the implementation differs, the goal does not:
| Where state-of-record lives | How the test loop closes |
| - | - |
| Local DB only (typically SSPs, creative agents) | The storyboard runner writes fixtures via `comply_test_controller.seed_*`; the seller's read handlers consume the same store. The seed → read loop closes naturally. |
| Upstream system the seller does not control (DSPs proxying to platforms, retail-media networks reading retailer catalogs, signals brokers) | Seeded writes are dead to the read handler. The TypeScript SDK ships a `TestControllerBridge` that runs the real adapter call first (so a broken upstream call still fails the gate), then merges seeded fixtures into the response. |
| Platform catalog with seller-issued or derived identifiers | For storyboards that declare `fixture_resolution`, the runner discovers qualifying entities through the seller's normal AdCP read surface, pins the seller-issued IDs to run-scoped fixture handles, and exercises the normal booking path. Requirements the sandbox catalog cannot satisfy remain visible as `fixture_unsatisfied` coverage gaps. |
| Mixed (some tools local, some upstream) | Both, per tool. |
All three paths can earn `(Spec)` — each proves the seller's wire behavior against the storyboards, and the run report identifies which fixture strategy supplied the evidence. The bridge is **one implementation** of the test-surface pattern, not a separate seller category. Discovery is not a blanket opt-out from controlled setup: a seller still needs the `force_*` and `simulate_*` scenarios required to prove lifecycle behavior, and an unsatisfied catalog requirement reduces reported coverage rather than passing the test. Neither category is what `(Sandbox)` attests; `(Sandbox)` is the separate axis covering whether the seller's production stack honors `account.sandbox: true` without real-world side effects.
### Fixture handles and catalog resolution
In AdCP 3.2, fixture IDs are run-scoped handles. Existing storyboards and
sellers retain literal `seed_*` injection by default. A storyboard opts a
fixture into catalog resolution through explicit `fixture_resolution` match
rules; the runner never guesses that an arbitrary fixture object is a generic
subset predicate.
For product discovery, the runner reads the fully paginated wholesale catalog
for the resolved sandbox account, validates the response normally, selects a
qualifying entity deterministically, and binds the authored handle to the
seller's `product_id`. Product pricing options bind as the scoped pair
`(product_id, pricing_option_id)`. The binding stays fixed for the run and is
substituted only into request fields carrying the corresponding `x-entity`
annotation.
The grading boundary is important:
* No qualifying entity after every declared strategy is
`fixture_unsatisfied`: an explicit, reported coverage gap.
* A rejected, malformed, incomplete, or transport-failed discovery call is a
conformance failure.
* Once a supported setup operation begins, its failure is a conformance
failure; the runner cannot fall back to another strategy to conceal it.
The normative authoring and output contracts live in
[`storyboard-schema.yaml`](https://adcontextprotocol.org/compliance/latest/universal/storyboard-schema)
and
[`runner-output-contract.yaml`](https://adcontextprotocol.org/compliance/latest/universal/runner-output-contract).
### Distinguishing fixture-merged from upstream-derived responses
When a response passes through the SDK's `TestControllerBridge`, the SDK stamps a `_bridge: { callback, tool, merged_count }` marker on the response. Marker presence on a step means the response content was merged from a seeded fixture after the seller's handler returned; marker absence means the response came from the seller's adapter end-to-end (or from a local DB the runner seeded directly). The marker is advisory metadata for runners and downstream leaderboards — it is **not** part of the wire contract. Sellers MUST NOT emit it, and conformance checks ignore it. The leading underscore marks the field as SDK/runner-stamped metadata reserved for testing tooling; future fields with the same prefix follow the same rule.
Marker design: [`adcp-client#1775`](https://github.com/adcontextprotocol/adcp-client/issues/1775). Shipped: [`adcp-client#1786`](https://github.com/adcontextprotocol/adcp-client/pull/1786). Leaderboard policy that consumes the marker: [`adcp-client#1782`](https://github.com/adcontextprotocol/adcp-client/issues/1782).
### Three signals — don't conflate them
Adopters often read these three controls as the same thing. They answer different questions:
| Signal | Question it answers |
| - | - |
| Test controller availability ([`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) in `tools/list`) | "Has the seller exposed deterministic-mode forces?" |
| Sandbox flag (`account.sandbox` on requests) | "Is the targeted account a sandbox account, with no real-world side effects?" |
| Bridge participation (`_bridge` marker on a response) | "Did this response come from the adapter's upstream call, or from a fixture the SDK merged in?" |
These are **runtime controls** on individual storyboard steps — distinct from the `(Spec)` and `(Sandbox)` verification qualifiers, which describe what a storyboard pass *attests* over time. A storyboard pass can carry any combination of the three signals.
## Storyboards are the truth
Rather than restate every MUST in prose — which would inevitably drift from the executable suite — **the storyboards ARE the conformance specification.** This document is a navigational index to them, grouped by the declaration that obligates the storyboard to run.
Every normative rule in the suite has exactly one home: the storyboard YAML at [`/compliance/latest/`](https://adcontextprotocol.org/compliance/latest/). Changes to what "conformant" means happen there, in a versioned release, tested against real agents. If a rule isn't in a storyboard, it's not part of conformance.
This is deliberate. A separate prose spec that restates storyboard rules creates two sources of truth. Two sources of truth drift. We pick one: the suite.
> [!NOTE]
>
> The `@adcp/sdk` package also ships TypeScript files under `testing/scenarios/` that pre-date storyboard-driven `comply()`. They are **not** the conformance spec — see [Storyboards vs. scenarios](/dist/docs/3.2.8/building/verification/storyboards-vs-scenarios) for which is which.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the referenced storyboards and prose sections below are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
## Conformance is layered
Every agent satisfies the universal layer. Each `supported_protocols` claim adds a protocol baseline. Each `specialisms` claim adds a specialism baseline.
| Layer | Obligation | Path |
| - | - | - |
| **Universal** | Every AdCP agent | [`/compliance/latest/universal/`](https://adcontextprotocol.org/compliance/latest/universal/) |
| **Protocol** | Agent claiming a `supported_protocols` value | [`/compliance/latest/protocols/{protocol}/`](https://adcontextprotocol.org/compliance/latest/protocols/) |
| **Specialism** | Agent claiming a `specialisms` value | [`/compliance/latest/specialisms/{id}/`](https://adcontextprotocol.org/compliance/latest/specialisms/) |
Agents MUST NOT declare a capability whose storyboards they do not pass. See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for the full taxonomy and [Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent) for how to run the suite locally.
The non-executable [cross-role governance index](/compliance/latest/universal/governance.yaml)
maps the shared governance contract to capability-gated media-buy, signals,
rights, and creative proofs. It is discoverability metadata, not an additional
universal storyboard; only an agent's exact
`adcp.governance_enforcement.tasks[]` claims select those role-specific tests.
## Universal conformance
Every agent MUST pass every storyboard below.
| Storyboard | What it verifies |
| - | - |
| [`capability_discovery`](/compliance/latest/universal/capability-discovery.yaml) | [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) shape, protocol/specialism declarations, version advertising |
| [`comply_controller_mode_gate`](/compliance/latest/universal/comply-controller-mode-gate.yaml) | Sandbox/live isolation for sellers that expose [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) on a shared endpoint — live-mode principals must be refused before scenario dispatch |
| [`schema_validation`](/compliance/latest/universal/schema-validation.yaml) | Request and response schema conformance, ISO 8601 timestamps, temporal invariants |
| [`schema_validation_signals`](/compliance/latest/universal/schema-validation-signals.yaml) | Response schema compliance for signals — required fields on every signal; gated on [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) |
| [`version_negotiation`](/compliance/latest/universal/version-negotiation.yaml) | Release-precision `adcp.supported_versions` advertisement and response-envelope `adcp_version` echo; advisory in 3.1, promoted in later cuts |
| [`v3_envelope_integrity`](/compliance/latest/universal/v3-envelope-integrity.yaml) | v3 protocol envelopes MUST NOT carry the v2 legacy `task_status` or `response_status` fields — `status` is the single canonical lifecycle field in v3 |
| [`error_compliance`](/compliance/latest/universal/error-compliance.yaml) | Structured error shape, published error codes, transport binding, no existence leaks across tenants |
| [`error_compliance_signals`](/compliance/latest/universal/error-compliance-signals.yaml) | Error handling for signals protocol — nonexistent signal IDs, missing fields, VERSION_UNSUPPORTED, transport binding; discovery phases are gated on `get_signals`; activation phases run only for agents that claim activation support such as `signal-marketplace` |
| [`stale_response_advisory`](/compliance/latest/universal/stale-response-advisory.yaml) | [`STALE_RESPONSE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-stale-response) wire placement — advisory rides in `errors[]` on a populated success response with transport success preserved; stale-cache forcing steps gated on `comply_test_controller` with `force_upstream_unavailable` |
| [`idempotency`](/compliance/latest/universal/idempotency.yaml) | `idempotency_key` scoping, replay semantics, [`IDEMPOTENCY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-conflict), `replayed: true`, declared TTL |
| [`read_tool_idempotency`](/compliance/latest/universal/read-tool-idempotency.yaml) | Read-only task wrappers and the 3.x [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) compatibility facade tolerate an optional `idempotency_key` without implying read replay; verifies the keyless capabilities bootstrap |
| [`reporting_core_declaration`](/compliance/latest/universal/reporting-core-declaration.yaml) | The proper-name Reliable Reporting 1.0 declaration and required Core boundary for [`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status), graded without requiring an optional test controller |
| [`reporting_core`](/compliance/latest/universal/reporting-core.yaml) | Controller-backed Reliable Reporting Core obligation-before-report lifecycle, deadline health, and explicit zero-row reporting |
| [`reporting_consumer_status`](/compliance/latest/universal/reporting-consumer-status.yaml) | Capability-gated buyer-to-seller status sync, missing-obligation identity, caller-scoped mismatch, and immutable supersession |
| [`reliable_reporting_managed_delivery`](/compliance/latest/universal/reliable-reporting-managed-delivery.yaml) | Capability-gated Managed Delivery declaration, including an atomic managed offering plus resource-retention and authorization-revocation guarantees |
| [`reliable_reporting_reconciled_billing`](/compliance/latest/universal/reliable-reporting-reconciled-billing.yaml) | Capability-gated Reconciled Billing declaration, including canonical evidence and authenticated revision/adjustment receipts |
| [`canonical_format_validate_input`](/compliance/latest/universal/canonical-format-validate-input.yaml) | Canonical-format [`validate_input`](https://adcontextprotocol.org/schemas/3.2.8/creative/validate-input-request.json) result semantics: structural pass/fail across required slots and `unvalidatable_nondeterministic` for seeded product declarations. Gated on agents that advertise `validate_input`; the seeded-product branch also requires `comply_test_controller` seeding support. |
| [`ctv_experience_validate_input`](/compliance/latest/universal/ctv-experience-validate-input.yaml) | [CTV experience profile](/dist/docs/3.2.8/creative/ctv-experiences) `validate_input` semantics: the six `ctv_ad_experience` values against their permitted canonicals, the `overlay`/`squeezeback` duration floor, `in_scene`'s no-interactivity rule, the menu focus/video slot pairing, and non-blocking activation-copy warnings. Gated on agents that advertise `validate_input` and `comply_test_controller` seeding support. |
| [`premium_display_canonical_validation`](/compliance/latest/universal/premium-display-canonical-validation.yaml) | AdCP 3.2 premium-display conformance: bounded state transitions, exact state/breakpoint canvas coverage, coordinated placement/component resolution, namespaced asset coverage, and shared-slot references. |
| [`security_baseline`](/compliance/latest/universal/security.yaml) | Unauth rejection, static-credential enforcement (Bearer API key or HTTP Basic), OAuth discovery + RFC 9728 audience binding |
| [`oauth_setup`](/compliance/latest/universal/oauth-setup.yaml) | Complete RFC 9728/RFC 8414 discovery graph, issuer/resource consistency, and passive endpoint reachability — skipped unless `oauth.supported: true` |
| [`trusted_match_publisher_authentication`](/compliance/latest/universal/trusted-match-publisher-authentication.yaml) | TMP router deployment authentication — selected only for agents declaring `trusted_match.core` in `experimental_features`; a credential-profile-neutral runner sends schema-valid Context Match and Identity Match requests with absent and invalid credentials and requires HTTP `401` with `WWW-Authenticate`; a selected deployment with unavailable probe configuration produces `requirement_unmet` |
| [`webhook_emission`](/compliance/latest/universal/webhook-emission.yaml) | Outbound webhook conformance — stable `idempotency_key` across retries, RFC 9421 webhook signing (or opt-in HMAC fallback) on every delivery. Runs for any agent accepting `push_notification_config`. |
| [`webhook_receiver_envelope`](/compliance/latest/universal/webhook-receiver-envelope.yaml) | Buyer receiver replay conformance: accepts full MCP webhook envelopes, rejects bare delivery-result payloads, verifies signatures over raw body bytes, and dedupes retries by `idempotency_key`. |
| [`agent_notification_configs`](/compliance/latest/universal/agent-notification-configs.yaml) | Agent-level `capabilities.changed` registration: revision-fenced capability declaration, NO_AUTH rejection, and dry-run clear semantics for [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) |
| [`principal`](/compliance/latest/universal/principal.yaml) | Stable-principal connection configuration for [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) and [`get_principal`](/dist/docs/3.2.8/protocol/get_principal): experimental capability declaration, NO_AUTH rejection, dry-run validation, applied lifecycle with readback, idempotent replay, and section clearing |
| [`notification_config_event_scope`](/compliance/latest/universal/notification-config-event-scope.yaml) | `sync_accounts.accounts[].notification_configs[]` semantic validation — account-level subscribers reject media-buy-anchored notification types even though those values are valid in the shared enum |
| [`account_identity_reconciliation`](/compliance/latest/universal/account-identity-reconciliation.yaml) | Capability-gated account identity lifecycle: mandatory revision fences, stale-write atomicity, in-place operator-unit rekeying, collision rollback, preserved account IDs, and authorized former-key [`ACCOUNT_MOVED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-moved) recovery |
| [`notification_config_lifecycle`](/compliance/latest/universal/notification-config-lifecycle.yaml) | Account-level `notification_configs[]` lifecycle on [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts): paused registration, durable [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) echo, subscriber-keyed replacement, and clear-all semantics |
| [`notification_config_rejections`](/compliance/latest/universal/notification-config-rejections.yaml) | Semantic `notification_configs[]` request rejection path for duplicate `subscriber_id` values |
| [`wholesale_feed_products`](/compliance/latest/universal/wholesale-feed-products.yaml) | Product wholesale feed versioning: bootstrap responses carry `wholesale_feed_version`/`cache_scope`, and matching `if_wholesale_feed_version` probes return `unchanged` without product rows |
| [`wholesale_feed_signals`](/compliance/latest/universal/wholesale-feed-signals.yaml) | Signals wholesale feed versioning: bootstrap responses carry `wholesale_feed_version`/`cache_scope`, and matching `if_wholesale_feed_version` probes return `unchanged` without signal rows |
| [`wholesale_feed_products_scope_isolation`](/compliance/latest/universal/wholesale-feed-products-scope-isolation.yaml) | Product wholesale feed cache-scope isolation: a `wholesale_feed_version` minted under one `cache_scope` must not short-circuit (`unchanged: true`) a request the seller resolves to a different `cache_scope` |
| [`wholesale_feed_signals_scope_isolation`](/compliance/latest/universal/wholesale-feed-signals-scope-isolation.yaml) | Signals wholesale feed cache-scope isolation: a `wholesale_feed_version` minted under one `cache_scope` must not short-circuit (`unchanged: true`) a request the agent resolves to a different `cache_scope` |
| [`wholesale_feed_product_webhooks`](/compliance/latest/universal/wholesale-feed-product-webhooks.yaml) | Account-level `notification_configs[]` registration for agents that advertise product wholesale feed webhook events |
| [`wholesale_feed_signal_webhooks`](/compliance/latest/universal/wholesale-feed-signal-webhooks.yaml) | Account-level `notification_configs[]` registration for agents that advertise signal wholesale feed webhook events |
| [`wholesale_feed_bulk_webhooks`](/compliance/latest/universal/wholesale-feed-bulk-webhooks.yaml) | Account-level `notification_configs[]` registration for agents that advertise `wholesale_feed.bulk_change` |
| [`pagination_integrity`](/compliance/latest/universal/pagination-integrity.yaml) | `cursor` ↔ `has_more` invariant on paginated [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) responses, walked from a continuation page through to a terminal page |
| [`get_products_pagination_integrity`](/compliance/latest/universal/get-products-pagination-integrity.yaml) | [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) wholesale pagination semantics: walks a seeded product feed from continuation to terminal while preserving brief/refine as capped curated/refined answers, not feed enumeration |
| [`get_signals_pagination_integrity`](/compliance/latest/universal/get-signals-pagination-integrity.yaml) | `cursor` ↔ `has_more` invariant on paginated `get_signals` responses under a broad query, with first-page non-terminal assertion against any non-trivial signal set |
| [`pagination_integrity_list_accounts`](/compliance/latest/universal/pagination-integrity-list-accounts.yaml) | Continuation-side pagination integrity on `list_accounts` responses; storyboard bootstraps three sandbox accounts via `sync_accounts`, requires `has_more=true` with a usable cursor on the first page, and follows that cursor once |
| [`pagination_integrity_creative_formats`](/compliance/latest/universal/pagination-integrity-creative-formats.yaml) | Deprecated named-format compatibility check: `cursor` ↔ `has_more` invariant when an agent still exposes [`list_creative_formats`](/dist/docs/3.2.8/creative/task-reference/list_creative_formats) |
| [`get_media_buys_pagination_integrity`](/compliance/latest/universal/get-media-buys-pagination-integrity.yaml) | `cursor` ↔ `has_more` invariant on paginated [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) responses; storyboard seeds three media buys via `seed_media_buy` and walks from a continuation page to a terminal page |
| [`pagination_integrity_content_standards`](/compliance/latest/universal/content-standards-pagination-integrity.yaml) | `cursor` ↔ `has_more` invariant on paginated [`list_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/list_content_standards) responses; storyboard bootstraps three content standards configurations via [`create_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/create_content_standards) and walks from a continuation page to a terminal page |
| [`pagination_integrity_collection_lists`](/compliance/latest/universal/collection-lists-pagination-integrity.yaml) | `cursor` ↔ `has_more` invariant on paginated [`list_collection_lists`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#list_collection_lists) responses; storyboard bootstraps three collection lists via [`create_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#create_collection_list) and walks from a continuation page to a terminal page |
| [`pagination_integrity_property_lists`](/compliance/latest/universal/property-lists-pagination-integrity.yaml) | `cursor` ↔ `has_more` invariant on paginated [`list_property_lists`](/dist/docs/3.2.8/governance/property/tasks/property_lists#list_property_lists) responses; storyboard bootstraps three property lists via [`create_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#create_property_list) and walks from a continuation page to a terminal page |
| [`deterministic_testing`](/compliance/latest/universal/deterministic-testing.yaml) | `comply_test_controller` state machine — skipped if `capabilities.compliance_testing.supported: false` |
| [`signed_requests`](/compliance/latest/universal/signed-requests.yaml) | RFC 9421 transport-layer request-signing verification — skipped if `request_signing.supported: false`. |
| [`billing_gate_dispatch`](/compliance/latest/universal/billing-gate-dispatch.yaml) | Two-gate dispatch on `sync_accounts.billing` rejection: seller-wide capability gate ([`BILLING_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-supported) with `error.details.scope`) vs per-buyer-agent commercial-relationship gate ([`BILLING_NOT_PERMITTED_FOR_AGENT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-permitted-for-agent) with the clamped `rejected_billing` + optional `suggested_billing` shape). Capability phase skipped when the seller supports all three `billing` values; per-agent phases skipped when the test kit does not declare `commercial_relationship: passthrough_only`. |
Agents that declare `capabilities.compliance_testing.supported: true` MUST implement the full [test controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller); a partial controller is non-conformant, so declare `false` rather than ship one.
Agents that declare `request_signing.supported: true` MUST implement the full RFC 9421 verifier per the [request-signing profile](/dist/docs/3.2.8/building/by-layer/L1/security#signed-requests-transport-layer); a partial verifier is non-conformant, so declare `false` rather than ship one.
Agents that declare `oauth.supported: true` MUST serve a consistent public OAuth discovery graph. The baseline grade is passive: it does not register a client, issue credentials, or perform an authorization flow.
## Protocol conformance
A `supported_protocols` claim obligates the protocol's baseline storyboard.
| `supported_protocols` | Storyboard |
| - | - |
| `media_buy` | [`media_buy_seller`](/compliance/latest/protocols/media-buy/index.yaml) + [`media_buy_state_machine`](/compliance/latest/protocols/media-buy/state-machine.yaml) |
| `creative` | [`creative_lifecycle`](/compliance/latest/protocols/creative/index.yaml) |
| `signals` | [`signals_baseline`](/compliance/latest/protocols/signals/index.yaml) |
| `governance` | [`media_buy_governance_escalation`](/compliance/latest/protocols/governance/index.yaml) |
| `brand` | [`brand_baseline`](/compliance/latest/protocols/brand/index.yaml) |
| `sponsored_intelligence` | [`si_baseline`](/compliance/latest/protocols/sponsored-intelligence/index.yaml) |
## Specialism conformance
A `specialisms` claim obligates the specialism's storyboard in addition to its parent protocol baseline. The catalog lives at [`/compliance/latest/index.json`](https://adcontextprotocol.org/compliance/latest/index.json); the human-readable index is the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog).
Specialisms carry a `status` — `stable` (verified pass/fail), `preview` (storyboard not yet defined; runner emits `passed: null`), `deprecated` (scheduled for removal). Agents MAY claim preview specialisms, but preview claims do not yield a pass/fail verdict.
## Outside the wire
Some requirements can't be verified by a storyboard because they're operator-level, not wire-level. They remain part of running a conformant agent, but the suite can't attest to them. Operators MUST self-assess against these; third-party frameworks (SOC 2, ISO 27001) are the usual attestation path.
* **Secret storage** — credentials SHOULD live in a KMS or equivalent. The wire shows only whether auth succeeds, not where the key was stored.
* **Credential rotation and revocation** — the operator MUST have a documented path to revoke a compromised credential in under an hour. The wire can't observe the runbook.
* **Personnel and physical security** — who can touch production, break-glass custody, employee offboarding. Entirely outside the protocol.
* **Governance agent due diligence** — when the operator relies on a third-party governance agent, the buyer SHOULD treat it as a processor with multi-customer blast radius and assess its posture. The storyboards verify correct JWS handling by the seller but cannot vouch for the governance agent itself.
* **LLM subprocessor posture** — if the agent uses an LLM provider, the DPA with that provider governs whether prompts, brand assets, or creative metadata may be retained. The protocol can't see upstream DPA terms.
* **Incident response** — AdCP emits the signals worth watching ([`IDEMPOTENCY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-conflict) spikes, failed governance verifications, SSRF rejections); detection, alert routing, and response are operator concerns.
* **Data residency configuration** — whether and how EU / UK data is kept in-region is typically declared in the agent's capabilities or contract; the wire records the declaration, not the underlying infrastructure.
Full operator checklist: [Security Model § What to verify before going live](/dist/docs/3.2.8/building/concepts/security-model#what-to-verify-before-going-live).
## Conformance vs external assurance
Conformance is wire-level correctness. SOC 2, ISO 27001, and NIST CSF are operational assurance. They answer different questions and neither substitutes for the other.
| External control area | Storyboard evidence | Gap to external assurance |
| - | - | - |
| Access control (SOC 2 CC6, ISO 27001 A.5.15) | [`security_baseline`](/compliance/latest/universal/security.yaml) (identity) + isolation checks in protocol storyboards | Personnel access reviews, least-privilege admin, offboarding |
| Change management (SOC 2 CC8) | [`idempotency`](/compliance/latest/universal/idempotency.yaml) proves duplicate state changes are prevented on the wire | Deployment approvals, release gates, rollback procedures |
| System monitoring (SOC 2 CC7, ISO 27001 A.8.16) | Error taxonomy produces a monitorable surface | Detection engineering, alert routing, on-call runbooks |
| Cryptography (ISO 27001 A.8.24) | TLS, RFC 9421 signing, JWS governance tokens | KMS selection, rotation cadence, cert lifecycle |
| Audit logging (SOC 2 CC7) | Governance storyboards verify signed-record issuance | Log retention, legal hold, integrity monitoring |
| Data handling (SOC 2 Privacy, GDPR, ISO 27701) | TMP two-call separation, audience hashing, signal access control | Data subject rights, DPA management, cross-border transfer |
| Vendor and subprocessor risk (SOC 2 CC9) | `adagents.json` / brand.json discovery, JWKS publication | Third-party risk assessment, LLM provider review |
| Incident response (SOC 2 CC7, NIST CSF RS) | Signals observable; response not mandated | Runbooks, tabletop exercises, breach notification |
| Business continuity (ISO 27001 A.5.30) | Cross-instance state storyboard checks | RPO/RTO targets, DR testing |
Two practical consequences:
1. Storyboard pass evidence MAY support specific external control objectives. It is not a substitute for an audit.
2. External certification does not imply AdCP conformance. SOC 2 Type II says nothing about whether [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) responses validate.
## How to claim conformance
1. Declare `supported_protocols` and `specialisms` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities).
2. Pass every storyboard the declaration obligates — universal + protocol baselines + specialism baselines — at a specific AdCP major version.
3. Keep declaration and behavior in sync. An undeclared capability the suite happens to test is separate from a declared capability that fails. Both are non-conformant.
Conformance is per-version; the suite is per-version. A 3.0-conformant agent is not thereby 3.1-conformant.
**For third-party attestation**, run the heartbeat against AAO and earn an [AAO Verified badge](/dist/docs/3.2.8/building/verification/compliance-catalog). The badge is a signed claim that AAO tested the agent recently and the pass still holds. Buyers filtering on *verified* get a smaller set than *conformant* — fewer agents, fresher attestation, a named party on the hook.
## What this document does not do
* **Define individual MUSTs.** The storyboards do. If a rule isn't in a storyboard, it isn't part of conformance.
* **Grant or revoke certification.** The [AgenticAdvertising.org certification program](/dist/docs/3.2.8/learning/overview) runs on top of this; conformance is necessary but not sufficient.
* **Duplicate schemas and storyboards as per-task vectors.** The [Reference Test Vectors index](/dist/docs/3.2.8/reference/test-vectors) catalogs byte-sensitive and library-level fixtures. Per-task shapes remain owned by JSON Schema, while task behavior remains owned by storyboards; a parallel frozen request/response corpus would create a third authority. SDK authors can derive local fixtures from the versioned storyboard when they need isolated unit tests.
## When a storyboard fails
When a failure surfaces a disagreement between the spec, the mock, and an SDK, the section below gives the triage order. For symptom-to-cause lookup, see the links at the end of this section.
### Mock-server authority and failure triage
The `adcp mock-server` is the reference wire implementation for stable surfaces. Use this triage order when a storyboard failure implicates the mock or an SDK:
**Triage order: spec → mock → SDK.** The storyboards (and the schemas they reference) are canonical. The mock interprets the storyboards. The SDK consumes the protocol via the mock.
| Condition | Default verdict | Next step |
| - | - | - |
| SDK wire shape **differs** from the mock's | SDK is wrong | File a bug against the SDK |
| SDK wire shape **matches** the mock's, but a storyboard still fails | Mock is wrong | File an issue against `adcontextprotocol/adcp` to fix the mock |
| Storyboard assertion conflicts with an otherwise-passing wire shape | Storyboard is wrong | File an issue against `adcontextprotocol/adcp` to fix the storyboard |
| Spec text (storyboard prose or schema) explicitly contradicts the mock | Spec wins; mock is the bug | File an issue against `adcontextprotocol/adcp` to fix the mock |
**Scope.** This triage order applies to stable surfaces only. Experimental surfaces (see [Experimental Status](/dist/docs/3.2.8/reference/experimental-status)) are under active revision; mock behavior there is not yet authoritative.
**Spec ambiguity vs. spec silence.** When spec text exists but is ambiguous, the mock's behavior pins the authoritative interpretation — that pinning is normative even if the prose has not yet been tightened. When the spec is entirely silent on a point and the mock has no behavior for it, the chain breaks; open a [known-ambiguities issue](/dist/docs/3.2.8/building/cross-cutting/known-ambiguities) instead of treating the mock as authoritative.
* **[Storyboard troubleshooting](/dist/docs/3.2.8/building/operating/storyboard-troubleshooting)** — Error pattern → root cause → fix for the most common storyboard failures
* **[Known spec ambiguities](/dist/docs/3.2.8/building/cross-cutting/known-ambiguities)** — Open spec gaps with workarounds and issue links; entries are removed as underlying issues close
## Further reading
* **[AAO Verified](/dist/docs/3.2.8/building/verification/aao-verified)** — Continuous-observability verification of the seller's live ad-server integration
* **[Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog)** — Full taxonomy of protocols and specialisms with storyboard IDs
* **[Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** — How to run the suite
* **[Security Model](/dist/docs/3.2.8/building/concepts/security-model)** — Strategic framing for the five defense layers that the security storyboards enforce
* **[Security (implementation reference)](/dist/docs/3.2.8/building/by-layer/L1/security)** — Normative rules cited by the storyboards
* **[Versioning](/dist/docs/3.2.8/reference/versioning)** — Major-version support windows
* **[Known Limitations](/dist/docs/3.2.8/reference/known-limitations)** — Visible edges of the specification
# Get Test-Ready
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/get-test-ready
What a sales agent operator must have in place before running storyboards — capabilities, sandbox accounts, and the compliance test controller.
Storyboards are the versioned buyer-simulation suite that decides whether your agent is published as **conformant**. Buyer agents filter on that status — overclaiming or failing storyboards is a public, permanent signal, not a CI warning. This page is the checklist between "I built an agent" and "I can run `npx @adcp/sdk@latest storyboard run`."
## The three surfaces the runner needs
The runner drives your agent through the same public tools a buyer would call, plus one sandbox-only tool for fixture setup. Three surfaces must be in place:
| Surface | What it tells the runner | Where it lives |
| - | - | - |
| [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) | Which protocols and specialisms you claim, and that you support sandbox | Your agent's capability response |
| [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) (or [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts)) | How to obtain a sandbox account to run tests against | Your agent's account tool |
| [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) | How to force seller-side transitions deterministically and, when supported, inject fixtures | Your agent, sandbox-only |
You ship these three surfaces. The runner owns storyboard selection, fixture ordering, and response comparison.
## Step 1 — Declare capabilities honestly
[`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) is how the runner picks which storyboards apply to you. It is also the [conformance](/dist/docs/3.2.8/building/verification/conformance) contract: you are promising to pass every storyboard that matches what you declare.
The example below is for a full-service guaranteed seller (proposal lifecycle enabled). A direct-buy guaranteed seller would set `media_buy.supports_proposals: false` (or omit it). A broadcast-TV seller would claim `sales-broadcast-tv`; a creative-only agent would claim the `creative` protocol with `creative-ad-server` or `creative-generative` specialisms; a signals provider would claim `signals`. The pattern is the same: declare only what you actually implement.
```json theme={null}
{
"supported_protocols": ["media_buy", "creative"],
"specialisms": ["sales-guaranteed"],
"media_buy": {
"supports_proposals": true
},
"account": {
"sandbox": true,
"require_operator_auth": false
}
}
```
* **`supported_protocols`** — Pulls in the matching protocol storyboards from `/compliance/{version}/protocols/`.
* **`specialisms`** — Pulls in opt-in specialism storyboards (see the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for the full enumeration).
* **`account.sandbox: true`** — Signals that you honor sandbox semantics (no real spend, no production side effects).
* **`account.require_operator_auth`** — Determines your sandbox bootstrap path (step 2).
> [!WARNING]
>
> Claiming `sales-guaranteed` when you only run RTB ships you into storyboards you will fail on record. Conformance status is part of the [Verified](/dist/docs/3.2.8/building/verification/conformance) badge buyer agents use to filter sellers — overclaim once, lose inclusion everywhere.
## Step 2 — Pick your sandbox bootstrap path
The runner must obtain a sandbox account before it can do anything. Your `require_operator_auth` flag chooses the path:
**Buyer-declared accounts (`require_operator_auth: false`).** Your agent accepts [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) from any authenticated buyer. The runner calls `sync_accounts` with `sandbox: true` to mint a test account on demand. Most new sales agents start here.
**Account-id namespaces (`require_operator_auth: true`).** Accounts must be pre-provisioned by a human on your side or by an upstream platform. The runner calls [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) with a sandbox filter to discover pre-existing test accounts. If your credential is bound to exactly one sandbox account, return that singleton. Publish a short note telling operators how to request one — include the contact, the expected turnaround, and what credentials they'll receive.
> [!NOTE]
>
> When your response includes the `account` capability block, its `require_operator_auth` flag — not the presence of `list_accounts` — selects the account model. Keep the flag `false` (or omit the flag, since `false` is its schema default) for buyer-declared natural-key accounts even if your agent also exposes `list_accounts`. Do not omit the entire `account` block: without account capability data, runners may retain a legacy `list_accounts` discovery heuristic. Set the flag to `true` only when callers must use seller-assigned account IDs. In that mode, the sandbox credential must expose one unambiguous account for the storyboard brand; if it exposes a roster, make sure exactly one row matches the test kit's `brand.house.domain`. Do not advertise `false` merely to bypass an ambiguous roster — that tells buyers the wrong account model.
Full details and examples: [Sandbox mode](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox).
## Step 3 — Implement the compliance test controller
Without a compliance test controller, the runner tests only buyer-initiated flows (**observational mode**) — schema conformance, auth rejection, happy-path buyer calls. That is enough for early integration work and production-path sandbox smoke tests, but it produces **partial coverage** whenever controller-seeded or controller-forced scenarios are in scope. [Conformance](/dist/docs/3.2.8/building/verification/conformance) treats **deterministic mode** — full lifecycle walks enabled by the controller — as the bar for complete specialism coverage.
In practice, sellers usually run both:
| Run | Endpoint | Expected result |
| - | - | - |
| Observational sandbox run | Production endpoint with sandbox accounts, no controller exposed | `steps_failed = 0`; live-only probes appear as not selected, and selected controller-dependent scenarios may make the summary `partial` with `requirement_unmet` (`controller`) or `missing_test_controller` skips |
| Deterministic run | Dev/staging or sandbox-only endpoint with [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) | `steps_failed = 0` and no controller-dependent coverage skips |
The first run answers "does the production buyer-visible path tolerate sandbox traffic?" The second answers "can the runner prove every lifecycle path for the declared specialisms?" Do not collapse those into one signal. A zero-failure partial run is useful, but buyers need the skip list to know exactly which lifecycle assertions were not graded.
`comply_test_controller` is a single sandbox-only tool with a `scenario` parameter covering three families:
| Scenario family | What it does | When you need it |
| - | - | - |
| `seed_*` | Create fixtures (products, pricing options, creatives, plans, media buys) with caller-supplied IDs | Seed-only storyboards and fixture-store sellers; 3.2 storyboards may instead resolve explicitly declared requirements through normal discovery or construction |
| `force_*` | Drive entities through state transitions that are normally seller-initiated | Any storyboard that tests a state machine (creative approval, account suspension, etc.) |
| `simulate_*` | Inject delivery data or budget spend | Reporting and budgeting storyboards |
See the [Compliance test controller reference](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) for scenario-by-scenario parameters and response shapes, and the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for which scenarios each specialism requires.
If your products come from a publisher-owned catalog and use seller-issued or
derived IDs, do not add a test-only alias layer merely to accept storyboard
literals. For storyboards that publish `fixture_resolution` rules, provision
representative inventory through your normal platform path and let the runner
discover and bind it. The run will report any requirement your sandbox catalog
cannot satisfy as `fixture_unsatisfied`. Storyboards that have not yet migrated
remain seed-only, so inspect the coverage report rather than assuming discovery
applies suite-wide.
### Wiring the SDK scaffold
`@adcp/sdk` (6.x is the production GA on AdCP 3.0) ships `createComplyController` so you wire your data layer to the controller without reimplementing tool registration, param validation, error envelopes, or re-seed idempotency.
```bash theme={null}
npm install @adcp/sdk
```
> [!NOTE]
>
> The scaffold is TypeScript/JavaScript. Python, Go, and Java sellers implement the tool directly against the [schema](https://adcontextprotocol.org/schemas/3.2.8/compliance/comply-test-controller-request.json) — the contract below (adapters, error codes, idempotency semantics) applies the same way. SDKs for other languages are tracked in [Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk).
```ts theme={null}
import { createComplyController, TestControllerError } from '@adcp/sdk/testing';
// `server` is your AdcpServer or MCP server instance — see `createAdcpServer` in
// `@adcp/sdk/server` if you need a reference setup.
const controller = createComplyController({
seed: {
product: async ({ product_id, fixture }) => {
await productRepo.upsert(product_id, fixture);
},
creative: async ({ creative_id, fixture }) => {
await creativeRepo.upsert(creative_id, fixture);
},
// Add pricing_option, plan, media_buy as your claimed storyboards require.
},
force: {
creative_status: async ({ creative_id, status, rejection_reason }) => {
const previous = await creativeRepo.getStatus(creative_id);
if (previous == null) {
throw new TestControllerError('NOT_FOUND', `creative ${creative_id} not found`);
}
const result = await creativeRepo.transition(creative_id, status, rejection_reason);
if (result.kind === 'invalid_transition') {
throw new TestControllerError('INVALID_TRANSITION', result.message, previous);
}
return { success: true, previous_state: previous, current_state: result.status };
},
// Add account_status, media_buy_status, session_status as needed.
},
// simulate: { delivery, budget_spend } — add if you claim reporting/budget specialisms.
});
// Primary gate: register the tool only in sandbox deployments, so it never
// appears in production `tools/list`.
if (process.env.ADCP_SANDBOX === '1') {
controller.register(server);
}
```
What the scaffold handles for you:
* **Tool registration and schema.** `controller.toolDefinition` stays in sync with the published spec version.
* **Dispatch and [`UNKNOWN_SCENARIO`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes).** Scenarios you do not register return `UNKNOWN_SCENARIO` automatically — never a schema error.
* **Param validation.** Invalid params produce [`INVALID_PARAMS`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) with a readable `error_detail` without reaching your adapter.
* **Seed idempotency.** Calling `seed_product` twice with the same `product_id` and an equivalent `fixture` returns `previous_state: "existing"`; a divergent `fixture` returns `INVALID_PARAMS`. Your adapter is only invoked on the first seed.
* **Typed error envelopes.** Throw `TestControllerError(code, message, currentState?)` with `code` from the controller error-code table. Common adapter codes are `'INVALID_TRANSITION' | 'NOT_FOUND' | 'FORBIDDEN' | 'INVALID_PARAMS'`; digest-mode `query_upstream_traffic` implementations may also return [`JCS_NON_FINITE_NUMBER`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) when RFC 8785/JCS canonicalization encounters a non-finite numeric value.
The scaffold does **not** own the state machine. Transition rules live in your adapters, so compliance testing and production share one source of truth — the mechanic the [anti-teach-to-test section](#avoiding-the-teach-to-test-trap) depends on.
### Two layers of sandbox gating
The scaffold supports two gates. Ship both in any deployment that serves both sandbox and production traffic from the same process:
1. **Registration gate (primary).** Wrap `controller.register(server)` in an environment check. This is what keeps `comply_test_controller` out of production `tools/list` entirely. Without it, a leaked sandbox credential on a production endpoint exposes seller-side state-forcing.
2. **Per-request gate (defense-in-depth).** Pass a `sandboxGate: (input) => boolean` to `createComplyController`. The scaffold calls it on every request and returns [`FORBIDDEN`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) when it returns `false`. Use this on shared-process deployments where the tool IS registered but some requests might still reference a production account.
`sandboxGate` receives the raw tool input (`Record`). The SDK does not plumb auth context onto it — you decide what to inspect. A typical pattern is to pull the referenced entity ID out of `params` and verify it belongs to a sandbox account in your own data layer:
```ts theme={null}
sandboxGate: async (input) => {
const params = input.params as { account_id?: string; media_buy_id?: string } | undefined;
const accountRef = params?.account_id
?? (params?.media_buy_id && await mediaBuyRepo.getAccountId(params.media_buy_id));
return typeof accountRef === 'string' && await accountRepo.isSandbox(accountRef);
}
```
> [!NOTE]
>
> For custom MCP wrappers — AsyncLocalStorage for per-request auth, transport-level sandbox gating, session-backed stores — compose the lower-level `handleTestControllerRequest`, `toMcpResponse`, and `TOOL_INPUT_SHAPE` from `@adcp/sdk/server` directly.
## Step 4 — Run the storyboard runner
Once the three surfaces are in place, the runner takes over:
```bash theme={null}
npx @adcp/sdk@latest --save-auth my-agent http://localhost:3001/mcp
npx @adcp/sdk@latest storyboard run my-agent
```
The runner discovers your capabilities, obtains a sandbox account, seeds fixtures via the controller, and walks each matching storyboard. See [Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent) for the full CLI, debug flags, and Addie workflows.
## Avoiding the teach-to-test trap
Storyboards hardcode fixture IDs — `"test-product"`, `"campaign_hero_video"`, `"acmeoutdoor.example"`. A controller that special-cases those strings passes the suite while silently failing on every real buyer. That is the exact industry cost conformance is trying to prevent: every post-conformance integration failure burns seller reputation, inflates buyer agent skepticism, and slows protocol adoption.
The SDK scaffold already points you in the right direction: adapters receive `product_id`, `creative_id`, etc. as values, not as conditions. If your adapter contains a switch on `product_id === "test-product"`, you have regressed.
Two rules of thumb:
1. **Implement seed scenarios generically.** `seed_product` accepts any `product_id` and persists a product with that ID in your sandbox data layer. Your adapter is a thin wrapper over a real upsert against your sandbox store.
2. **The `fixture` object is the contract, the ID is not.** Storyboard authors set `fixture` to the minimum shape the test needs. Everything beyond that — discovery, filtering, authorization — is your normal code path, exercised on fixture-seeded data the same way it runs on production data.
To check: swap a storyboard's fixture IDs for random UUIDs and rerun. If the run still passes, your controller is correct. If it breaks, you have hardcoded behavior to fix.
## Debug a failed storyboard
Start with the first failing step; later failures are often consequences of lost state. Check these recurring classes before changing protocol behavior:
| Failure | What to inspect |
| - | - |
| Capability storyboard skips or selects the wrong tracks | `get_adcp_capabilities.supported_protocols` and `specialisms[]` must describe only the surface actually implemented |
| Version-negotiation failure | Keep legacy `adcp.major_versions`, add release-precision `adcp.supported_versions`, and echo the served release as envelope-level `adcp_version` |
| Missing status or malformed response | Put `status` and `adcp_version` on the protocol envelope, not inside the task payload; validate the raw wire response against the referenced response schema |
| A later step cannot resolve an ID | Preserve the prior step's captured entity and account scope; do not replace storyboard-generated IDs with fixture literals |
| Error-path context mismatch | Echo request `context` on success and error branches so correlation survives validation, authorization, and state errors |
| Authenticated steps return 401 while discovery works | [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) is public, but the reverse proxy must forward the `Authorization` header unchanged on authenticated task calls |
Run the single failed storyboard with debug output before rerunning the full suite. The step's `schema_ref`, `response_schema_ref`, validation path, and raw response identify whether the defect is transport, envelope shape, state continuity, or capability declaration.
## Readiness checklist
Before your first full storyboard sweep:
* [ ] [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) returns only protocols and specialisms you actually implement
* [ ] Capabilities include both `adcp.major_versions` and release-precision `adcp.supported_versions`; responses echo the served `adcp_version` at envelope level
* [ ] Success and error responses preserve request `context`, including `correlation_id`
* [ ] Your ingress/proxy preserves `Authorization` on authenticated task calls
* [ ] `account.sandbox: true` is declared and honored — sandbox requests produce no real spend, no production platform calls, no persisted production state
* [ ] [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) (implicit) or [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) (explicit) handles sandbox requests per step 2
* [ ] [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) is absent from `tools/list` on any production endpoint
* [ ] Requests that reference a non-sandbox account are rejected with [`FORBIDDEN`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes)
* [ ] Every seed scenario your claimed storyboards depend on persists fixtures generically, with no ID special-cases
* [ ] Every force scenario uses the same state-transition rules as production, returning typed errors on invalid transitions
* [ ] A full storyboard sweep still passes when fixture IDs are swapped for random UUIDs
## What's next
* **[Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** — CLI, Addie workflows, and multi-instance verification
* **[Compliance test controller reference](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller)** — Full scenario-by-scenario spec
* **[Sandbox mode](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox)** — The two account model paths in depth
* **[Conformance](/dist/docs/3.2.8/building/verification/conformance)** — What "conformant" and "verified" mean once your runs pass
# Auth Graders
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/grading
AdCP CLI graders for RFC 9421 request-signing conformance, OAuth handshake diagnosis, and Ed25519/P-256 signing key generation and verification.
`@adcp/sdk` 5.21+ ships CLI graders for authentication conformance. They are separate from the [compliance storyboards](/dist/docs/3.2.8/building/verification/validate-your-agent) — storyboards test protocol behavior end-to-end; these graders test the authentication and signing layer specifically, giving per-vector diagnostics and hypothesis-ranked failure analysis.
> [!TIP]
>
> All commands below use `npx @adcp/sdk@latest`. If you have `@adcp/sdk` installed globally (`npm install -g @adcp/sdk`) you can drop the `npx @adcp/sdk@latest` prefix and use `adcp` directly.
## Request-signing grader
Validates RFC 9421 conformance against your agent end-to-end. Runs every signing vector and reports per-vector results so you can trace exactly which canonicalization rule or header coverage check is failing.
```bash theme={null}
npx @adcp/sdk@latest grade request-signing
```
**What it checks:**
* Signature base canonicalization (method, target-uri, authority, content-type, content-digest)
* Covered-component completeness and ordering
* `alg` and `kid` fields present and valid
* Timestamp window (±60 s) and nonce uniqueness
* Replay detection (if the agent advertises it)
* Negative-vector rejection — each malformed request MUST produce the expected error code
**When to use it:** before flipping any operation to `required_for` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities); when a counterparty reports signature verification failures; when upgrading key algorithms (Ed25519 → P-256 or the reverse).
## OAuth handshake diagnoser
Probes an agent's OAuth discovery documents (RFC 9728 protected-resource metadata, RFC 8414 authorization-server metadata), performs the authorization code + PKCE flow, decodes the resulting JWT, and ranks hypotheses about what is wrong.
```bash theme={null}
npx @adcp/sdk@latest diagnose-auth
```
The `` form uses a saved alias from `~/.adcp/config.json` (set via `npx @adcp/sdk@latest --save-auth `).
**What it probes:**
* `/.well-known/oauth-protected-resource` — presence, `authorization_servers` list, HTTPS enforcement
* `/.well-known/oauth-authorization-server` — issuer match, `token_endpoint`, `code_challenge_methods_supported`
* Token endpoint response — token type, expiry, scope coverage
* JWT claims — `iss`, `sub`, `aud`, `exp`, `iat` presence and validity
* Cross-origin `authorization_servers` issuer pinning (flags if the resource metadata's AS URL doesn't match out-of-band config)
**Output:** ranked hypothesis list, e.g., `1. token_endpoint not reachable (connection refused) — likely cause`, `2. issuer mismatch — AS URL returned by protected-resource does not match adagents.json`. Each hypothesis links to the relevant spec section.
**When to use it:** when [`AUTH_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-required) errors persist after bearer token configuration; when dynamic client registration returns unexpected responses; when a new seller's OAuth setup fails silently.
## Key generation
Generate an Ed25519 or P-256 keypair formatted for publication at your agent's `jwks_uri`.
```bash theme={null}
npx @adcp/sdk@latest signing generate-key
```
Outputs:
* A private key file (PEM, for your agent's signing config)
* A JWK with `"kid"`, `"use": "sig"`, `"key_ops": ["verify"]`, `"adcp_use": "request-signing"`, and `"alg": "EdDSA"` (or `"ES256"` for P-256) ready to paste into your JWKS endpoint
**When to use it:** initial signing setup; key rotation (generate new, publish alongside old, drain in-flight requests, retire old).
## Vector verifier
Verify a single signing vector without running the full grader. Useful for debugging a specific canonicalization case during implementation.
```bash theme={null}
npx @adcp/sdk@latest signing verify-vector \
--vector /path/to/vector.json \
--keys /path/to/keys.json
```
Reads the local vector and key-set JSON files and runs the SDK reference verifier. For a self-contained negative vector, compare the reported rejection code with the fixture's `expected_outcome.error_code`; the CLI does not grade that comparison for you and exits with status 1 for an expected rejection. Shell scripts and CI jobs must therefore compare the output rather than treating every nonzero exit as an unexpected tool failure.
Some negative fixtures declare `test_harness_state` and are not self-contained. For example, `016-replayed-nonce.json` requires the verifier harness to preload a replay-cache entry. A local white-box harness can apply the fixture's declared state; live black-box certification uses the full grader's coordinated repeat-request contract. See the request-signing guide's [downloadable vector example](/dist/docs/3.2.8/building/by-layer/L1/request-signing#conformance-vectors) for a copyable CDN flow.
**When to use it:** while implementing or debugging a verifier to isolate canonicalization and validation rules before testing end-to-end.
## Related
* [Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent) — storyboard-based protocol compliance testing
* [Authentication](/dist/docs/3.2.8/building/by-layer/L2/authentication) — auth model overview, bearer tokens, RFC 9421 introduction
* [Security implementation reference](/dist/docs/3.2.8/building/by-layer/L1/security#signed-requests-transport-layer) — full RFC 9421 profile, verifier checklist, key publication rules
# How grading works
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/how-grading-works
How the AdCP compliance runner translates specialism declarations into a concrete set of graded storyboards — and how capability flags alter that set.
The [Conformance Specification](/dist/docs/3.2.8/building/verification/conformance#conformance-is-layered) defines three obligation layers: Universal, Protocol, and Specialism. This page explains what happens inside the Specialism layer: how a specialism manifest resolves to a set of graded scenarios, and how per-scenario capability gates can narrow or expand that set.
## From declaration to graded scenarios
When your agent declares a specialism in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities), the runner:
1. Fetches the specialism manifest at `/compliance/{version}/specialisms/{id}/`.
2. Reads the manifest's `requires_scenarios` list — an ordered set of scenario IDs the runner must grade.
3. For each scenario, checks whether the scenario declares a `requires_capability` gate.
4. If a gate is present, reads the named path from your `get_adcp_capabilities` response to decide whether to run or skip the scenario.
The manifest drives the full scenario list; capability gates apply per-scenario on top of it.
## Runner evidence vs. verification policy
The storyboard runner does not decide whether an agent earns a badge or satisfies a particular buyer. It produces evidence: executed assertions, failures, selected-but-skipped steps, not-selected steps, skip reasons, and the endpoint/run mode used. A verification policy consumes that evidence and decides which gaps are acceptable for a named outcome.
| Question | Decided by | Evidence used |
| - | - | - |
| "Did this step match the storyboard?" | Storyboard runner | Step validations and response schemas |
| "Does this agent earn **Verified (Spec)**?" | AgenticAdvertising.org verification policy | Runner evidence against the registered spec/test endpoint, plus membership and declaration checks |
| "Does this agent earn **Verified (Sandbox)**?" | AgenticAdvertising.org verification policy | Runner evidence against the production endpoint under `account.sandbox: true`, plus sandbox-isolation checks |
| "Is this good enough for a specific buyer?" | That buyer's requirement profile | Verified mode, declared protocols/specialisms, optional capabilities they require, and any business or integration requirements outside AdCP |
This is why runner classification matters. "Not selected because this is a sandbox-only run" is a suite-selection fact, not a seller capability gap. "Skipped because the seller did not claim an optional feature" may be acceptable for the badge but unacceptable to a buyer that requires that feature. "Skipped because a declared required tool is missing" is a seller implementation problem.
## Requirement profiles
To answer "what do I need to pass?", start with the profile you are trying to satisfy:
| Target | Minimum question the profile answers |
| - | - |
| **Verified (Spec)** | Does the declared AdCP surface pass the required storyboards on the registered spec/test endpoint, with no blocking missing tools or failed assertions? |
| **Verified (Sandbox)** | Does the registered production endpoint pass the sandbox verification profile under `account.sandbox: true`, with sandbox isolation enforced and only Sandbox-acceptable skips present? |
| **Specific buyer requirement** | Which verified modes, protocols, specialisms, optional capabilities, operational behaviors, and skip classes does this buyer require? |
A buyer requirement profile can be stricter than the public badge. For example, the public Sandbox profile can accept a capability-gated proposal storyboard being skipped when `media_buy.supports_proposals: false`; a buyer that requires proposal workflows can treat the same skip as a blocker. Conversely, a production endpoint omitting [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) can be acceptable for the Sandbox badge, while a buyer doing deterministic integration testing may ask for a separate dev/staging endpoint that exposes it.
The storyboard runner should not encode those buyer decisions. It should emit typed evidence that a verification policy or buyer profile can evaluate consistently.
## Specialism manifests
Each specialism's `requires_scenarios` field lists the scenarios the runner will grade. Example — the `sales-guaranteed` manifest declares eight required scenarios:
```yaml theme={null}
# /compliance/{version}/specialisms/sales-guaranteed/ (source: static/compliance/source/specialisms/sales-guaranteed/index.yaml)
id: sales_guaranteed
requires_scenarios:
- media_buy_seller/refine_products
- media_buy_seller/delivery_reporting
- media_buy_seller/measurement_terms_rejected
- media_buy_seller/pending_creatives_to_start
- media_buy_seller/inventory_list_targeting
- media_buy_seller/inventory_list_no_match
- media_buy_seller/invalid_transitions
- media_buy_seller/proposal_finalize # ← capability-gated
```
Seven of these run unconditionally for any `sales-guaranteed` agent. The eighth — `proposal_finalize` — carries a capability gate.
## Capability gates
A scenario or phase can declare a `requires_capability` block. The runner reads the named path from your [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) response and checks it against the expected value. If the check fails (the capability is absent or false), the scenario or phase is skipped — the `skip` block will appear in runner output with `reason: not_applicable` — and does not contribute to `steps_failed`.
```yaml theme={null}
# /compliance/{version}/protocols/media-buy/scenarios/proposal_finalize/ (source: static/compliance/source/protocols/media-buy/scenarios/proposal_finalize.yaml)
id: media_buy_seller/proposal_finalize
requires_capability:
path: media_buy.supports_proposals
equals: true
```
The gate is evaluated against your agent's live `get_adcp_capabilities` response at run time — the same call the runner makes during the universal [`capability_discovery`](/compliance/latest/universal/capability-discovery.yaml) storyboard.
Phase-level gates use the same shape and scope only the phase that declares the block. Universal storyboards use this for protocol-specific phase families, for example deterministic testing skips its SI session phase when an agent does not declare `sponsored_intelligence` while still running media-buy or creative phases the agent does declare.
## Worked example
**Scenario:** Priya's StreamHaus platform claims `sales-guaranteed` and declares `media_buy.supports_proposals: true`.
```json theme={null}
{
"supported_protocols": ["media_buy"],
"specialisms": ["sales-guaranteed"],
"media_buy": {
"supports_proposals": true
}
}
```
**Runner behavior:** all eight `requires_scenarios` run, including `proposal_finalize`. Priya's platform is graded on the full proposal lifecycle — brief with proposals, refine, finalize, and execute via [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy).
***
**Scenario:** StreamHaus Direct is an auction-based PG platform — no proposal abstraction. It claims `sales-guaranteed` and declares `media_buy.supports_proposals: false`.
```json theme={null}
{
"supported_protocols": ["media_buy"],
"specialisms": ["sales-guaranteed"],
"media_buy": {
"supports_proposals": false
}
}
```
**Runner behavior:** seven scenarios run; `proposal_finalize` is skipped. The `skip` block in runner output is the authoritative signal:
```json theme={null}
{
"storyboard_id": "media_buy_seller/proposal_finalize",
"skip": {
"reason": "not_applicable",
"detail": "requires_capability check: media_buy.supports_proposals must equal true — agent declared false"
}
}
```
When the `skip` block is present, the step was not graded and does not count against `steps_failed`. The `skip.detail` string identifies the specific cause (capability gate, missing specialism declaration, or missing tool).
> [!NOTE]
>
> **Absent = false.** The `supports_proposals` field has `"default": false` in the capabilities schema. Omitting it from your response is equivalent to declaring `false` — the runner skips capability-gated proposal scenarios. Declare `true` explicitly to opt in to grading.
>
> This flag is only the grading gate. Buyer agents should not use it to decide whether a specific proposal is executable. If a seller returns a proposal, `proposal_status` is the source of truth: `draft` requires finalization before create, `committed` can be executed before `expires_at`, and absent status is legacy ready-to-buy.
## Grading verdicts at a glance
| Outcome | Output field | Meaning |
| - | - | - |
| Scenario passed | Step result with no `skip`; `passed: true` | All validations passed |
| Scenario failed | Step result with no `skip`; `passed: false` | One or more required validations failed; see `validations[]` for the failing field and `json_pointer` |
| Scenario not selected | `summary.not_selected[].reason`, counted in `summary.steps_not_selected` | The caller's selected suite, run mode, version, or verification profile excluded this scenario before execution |
| Scenario skipped | `skip.reason: not_applicable` | Scenario was selected, but an applicability gate evaluated false, such as an optional capability the seller did not claim |
| Required tool missing | `skip.reason: missing_tool` | Scenario was selected and the agent declared the specialism, but did not expose a tool listed in `required_tools` |
| Raw storyboard assertion failed | `StoryboardResult.assertions[]` entry with `passed: false` | A storyboard invariant failed; a storyboard-scoped failure can fail the storyboard even when every individual step passed |
In a raw `StoryboardResult`, `overall_passed` combines executed-step results with [storyboard invariants](/dist/docs/3.2.8/building/verification/compliance-catalog#cross-resource-invariants). A storyboard-scoped assertion can set `overall_passed: false` even when `failed_count` — and the aggregate `summary.steps_failed` count — is zero. Inspect `assertions[]` for its `assertion_id`, `scope`, optional `step_id`, and `error` or structured `hint`. Step-scoped assertion failures also appear in that step's `validations[]` with `check: "assertion"`.
As of `@adcp/sdk@13.0.0`, the compliance aggregate preserves storyboard-scoped assertion failures as structured error observations and represents the failed invariant as a storyboard-level scenario. The containing track cannot report `pass`, while `summary.steps_failed` remains a truthful step counter and can stay zero when no individual step failed. Consumers should inspect the structured observation or storyboard-level scenario for the failed `assertion_id`; do not fabricate a failed step for an `onEnd`-only invariant.
Skipped steps (`skip` block present) and not-selected items (`summary.not_selected[]` entries) do not contribute to `summary.steps_failed`, but they mean different things. `summary.steps_not_selected` says the runner deliberately excluded those scenarios from this run. `summary.steps_skipped` says the runner selected those scenarios but could not execute them; use `summary.skipped_by_reason` and `skip.detail` to distinguish optional capability choices from missing required surfaces. For ordinary step validation failures, see [Storyboard troubleshooting](/dist/docs/3.2.8/building/operating/storyboard-troubleshooting).
A sandbox-only run should therefore look like this when the only excluded work is outside the selected mode:
```json theme={null}
{
"summary": {
"steps_passed": 84,
"steps_failed": 0,
"steps_skipped": 0,
"steps_not_selected": 80,
"not_selected_by_reason": {
"run_mode_excluded": 80
}
}
}
```
If those 80 items instead appear under `steps_skipped`, they were selected and then skipped; that is a different signal and needs `skipped_by_reason`.
## Pass vs partial coverage
Runner summaries distinguish **failure** from **coverage**:
| Run shape | What it means | Seller action |
| - | - | - |
| `summary.steps_failed > 0` | One or more executed steps failed a required validation, including a step-scoped assertion | Fix the agent before claiming the corresponding protocol or specialism |
| `summary.steps_failed = 0`, no coverage-gap skips, and every raw `StoryboardResult.overall_passed` is `true` | Full pass for the declared scope | The declared protocols, specialisms, and capability flags were graded cleanly |
| `summary.steps_failed = 0` with a failed `StoryboardResult.assertions[]` entry | The raw storyboard failed despite passing step counters; the rc15 aggregate does not preserve this verdict | Fix the invariant failure and treat the run as failed; do not rely on the aggregate status |
| `summary.steps_failed = 0`, with `summary.steps_not_selected > 0` only | The requested suite or run mode intentionally excluded some probes, such as live-only checks during a sandbox-only run | No implementation ask; label the run mode clearly |
| `summary.steps_failed = 0`, with only capability-gate `not_applicable` skips | Narrower declared scope, not a failure | The agent honestly declined an optional capability, such as `media_buy.supports_proposals: false` |
| `summary.steps_failed = 0`, with `missing_test_controller` skips | Deterministic-test-surface coverage gap: the controller was available at load time but became unavailable mid-run, or a step calls it in a storyboard that does not gate on it | Run a dev/staging deterministic pass or publish the skipped lifecycle coverage explicitly |
| `requirement_unmet` skip naming `controller` on controller-seeded storyboards | The seller exposes no [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#who-is-expected-to-implement-the-controller); reference sellers SHOULD implement it, translator and adapter sellers that cannot seed state are not expected to | Reference sellers: implement the controller. Translator and adapter sellers: no ask; publish the skipped coverage list |
| Any `missing_tool`, `unsatisfied_contract`, or other `requirement_unmet` skip (except the `controller` row above) for a declared protocol or specialism | The seller declared a claim the runner could not fully test | Fix the missing surface or narrow the declaration |
This distinction matters for production-path sandbox runs. A seller can run the storyboard suite against the real production endpoint under sandbox-flagged traffic and get **zero failures** while still seeing a `partial` summary because the production endpoint correctly does not expose [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller). After confirming that the raw storyboard results contain no failed storyboard-scoped assertions, that result says: "the buyer-visible sandbox path passed every assertion the runner could grade, but controller-seeded lifecycle scenarios were skipped." It is useful evidence for sandbox readiness, but it is not the same as full deterministic specialism coverage.
For full coverage, run the same declared scope against a dev or staging endpoint that exposes the controller, or pre-seed the required state and configure the runner to assert seeded-state coverage. For a production-only seller, publish the skipped coverage list alongside the zero-failure result so buyers can see exactly what was and was not graded.
## Where each piece lives
| Artifact | URL path | Source |
| - | - | - |
| Specialism manifest | `/compliance/{version}/specialisms/{id}/` | `static/compliance/source/specialisms/{id}/index.yaml` |
| Scenario YAML | `/compliance/{version}/protocols/{protocol}/scenarios/{name}/` | `static/compliance/source/protocols/{protocol}/scenarios/{name}.yaml` |
| Universal storyboards | `/compliance/{version}/universal/` | `static/compliance/source/universal/` |
| Capabilities schema | `/schemas/3.2.8/protocol/get-adcp-capabilities-response.json` | `static/schemas/source/protocol/get-adcp-capabilities-response.json` |
The full specialism-to-scenario index is at [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog). The runner output contract defining every skip reason and verdict shape is at `static/compliance/source/universal/runner-output-contract.yaml`.
## Related
* [Conformance Specification](/dist/docs/3.2.8/building/verification/conformance) — the three-layer obligation model and the normative storyboard index
* [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) — full taxonomy of protocols, specialisms, and universal storyboards
* [Validate Your Agent](/dist/docs/3.2.8/building/verification/validate-your-agent) — running the suite locally with `@adcp/sdk`
# Storyboards vs. scenarios — which is which
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/storyboards-vs-scenarios
Three things in AdCP share the word 'scenarios' and they aren't the same. Here's how to tell them apart.
If you're trying to figure out *how* to test an AdCP agent, three things in this ecosystem share overlapping vocabulary. They are not the same. Confusing them produces wrong conclusions — including the kind that get reported as protocol gaps that aren't actually gaps.
## TL;DR
| | What it is | Where it lives | Normative? |
| - | - | - | - |
| **Storyboards** | YAML files defining a workflow end-to-end + every wire-shape assertion. **The conformance specification.** | `/compliance/{version}/universal/*.yaml`, `protocols/*/*.yaml`, `specialisms/*/index.yaml` | ✅ Yes |
| **[`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) scenarios** | Protocol-level tool operations a seller exposes (`force_*`, `simulate_*`, `seed_*`) so storyboards can drive deterministic state. | The `scenario` parameter of the seller's `comply_test_controller` MCP tool. | ✅ Yes |
| **`@adcp/sdk/testing/scenarios/*.ts`** | Legacy TypeScript test runners predating storyboard-driven `comply()`. | `node_modules/@adcp/sdk/dist/lib/testing/scenarios/*.js` | ❌ **No** |
If you're reading a file at `node_modules/@adcp/sdk/dist/lib/testing/scenarios/media-buy.js` and trying to figure out what AdCP requires — **stop**. That's not the spec. Read [the storyboards](/dist/docs/3.2.8/building/verification/conformance) instead.
## Storyboards (normative)
Storyboards are the conformance specification. Each one defines:
* A workflow (e.g. *sales-guaranteed proposal/refine/finalize lifecycle*)
* The exact tool calls a buyer agent makes
* Every wire-shape assertion the seller's responses must satisfy
* The [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) operations the runner uses to seed deterministic state
[`conformance.mdx`](/dist/docs/3.2.8/building/verification/conformance) calls these *"the truth"* — and means it. These YAML files are the basis for **AgenticAdvertising.org Verified (Spec)**; AgenticAdvertising.org issues that qualifier when its compliance heartbeat runs the applicable storyboards and every assertion passes.
You'll see storyboards at:
* `/compliance/{version}/universal/*.yaml` — every AdCP agent must pass
* `/compliance/{version}/protocols/{protocol}/index.yaml` — anyone claiming the protocol
* `/compliance/{version}/specialisms/{id}/index.yaml` — opt-in claims
Run them via `npx @adcp/sdk@latest storyboard run ` or interactively through [Addie](https://agenticadvertising.org).
### Source authority and rollout
The authored source of truth for storyboards is `static/compliance/source/` in the `adcontextprotocol/adcp` repo. `scripts/build-compliance.cjs` builds `dist/compliance/latest/` during development and stamps `dist/compliance/{version}/` on release, adding only generated distribution artifacts such as `index.json` and the legacy `domains/` alias. SDKs may bundle a snapshot so runners work offline and remain version-pinned, but that snapshot is a distribution copy, not the authority.
During the current migration, `@adcp/sdk` still loads its bundled cache by default. Spec repo CI overlays `static/compliance/source/` onto that cache before running the training-agent storyboards so pull requests are graded against the candidate source without switching runtime authority in the same step. SDK release work should separately prove its bundled cache matches the spec bundle it claims to ship.
Breaking or materially stricter storyboard changes must roll out in this order:
```text theme={null}
spec storyboard change -> reference implementations update -> @adcp/sdk runner release -> downstream consumers update
```
That order prevents the release deadlock where a new runner expects stricter scenarios before repo-owned reference implementations have a tagged implementation that can pass them.
## `comply_test_controller` scenarios (normative — but different)
The word "scenario" also appears in the [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) MCP tool that sellers expose to support deterministic testing. Storyboards call this tool with `scenario: ` to drive seller state without waiting for real time to pass: e.g. `force_task_completion` to finish a pending async media buy, `simulate_delivery` to inject impressions, `seed_product` to install a fixture.
These are **protocol operations**, not test runners. They're documented at [comply_test_controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller). Sellers MUST implement them to be testable; the storyboards MUST use them to stay deterministic.
So when you hear "the seller doesn't support that scenario," it usually means: "the seller's `comply_test_controller` doesn't expose `force_X` yet." Not "no storyboard tests X."
## `@adcp/sdk/testing/scenarios/*.ts` (NON-normative legacy)
The SDK ships TypeScript files under `testing/scenarios/` — `media-buy.ts`, `signals.ts`, `creative.ts`, and a dozen siblings. These predate the storyboard-driven `comply()` engine. They are:
* **Not the conformance spec.** Reading them to learn what AdCP requires will produce wrong answers.
* **Not maintained in lockstep with storyboards.** A scenario file may hard-code parameters that the storyboard equivalent has long since corrected. *Example: `scenarios/media-buy.ts` hard-codes `buying_mode: 'brief'` at four call sites; the YAML storyboard for `sales-guaranteed` exercises `buying_mode: 'refine'` + `action: 'finalize'` via the `proposal_finalize` storyboard. Both are valid `buying_mode` values; the scenario file just doesn't cover the lifecycle.*
* **Callable, but for different purposes.** Internal smoke tests in the SDK, integration-test fixtures for downstream tooling, and some legacy paths still use these. They are not what AgenticAdvertising.org Verified (Spec) runs against.
If you find yourself grepping `testing/scenarios/*.ts` to understand AdCP, you've taken a wrong turn. The right path:
1. Find the storyboard that matches your declared specialism: `npx @adcp/sdk@latest storyboard list`
2. Read the YAML: `npx @adcp/sdk@latest storyboard show `
3. Run it: `npx @adcp/sdk@latest storyboard run --agent-url `
## Three-line decoder
| If you see… | …you're looking at | Trust as spec? |
| - | - | - |
| A `.yaml` under `/compliance/{version}/...` | A storyboard | ✅ Yes |
| A seller responding to [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) with a `scenario` parameter | A protocol-level test-control operation | ✅ Yes (the contract is normative; the seller MAY refuse with [`UNKNOWN_SCENARIO`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes)) |
| A `.ts` or `.js` under `@adcp/sdk/dist/lib/testing/scenarios/` | A legacy SDK test runner | ❌ No |
## Cross-repo
The disambiguation work in the SDK itself — marking the legacy scenarios as `@deprecated`, mirroring the storyboard CLI verbs, or removing the export entirely — lives in [`adcp-client`](https://github.com/adcontextprotocol/adcp-client). The decision on whether `testing/scenarios/*` stays public-but-deprecated or becomes internal-only is tracked in [#4035](https://github.com/adcontextprotocol/adcp/issues/4035).
For now: if you want to test an AdCP agent, the answer is storyboards. The other two things named "scenario" have their place, but they aren't it.
# Validate adapter agents with mock upstream fixtures
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/validate-with-mock-fixtures
Pre-staging gate for AdCP adapter agents — published mock upstreams plus traffic counters surface integration gaps before staging tests.
> [!NOTE]
>
> **Non-normative.** This page describes a complementary harness pattern, not a compliance tier. The recipe builds on top of the storyboard runner ([Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent)) — it does not replace storyboards or staging integration tests, and is not a certification gate. The mock-fixture conventions described here (`/_lookup/`, `/_debug/traffic`) are reference implementations in `@adcp/sdk`; alternative SDK implementations may diverge. Treat as harness convention, not protocol contract.
Most AdCP agents that wrap an external platform (a DSP, SSP, retail data warehouse, creative server, signal marketplace) ship façade bugs that storyboards alone cannot detect: handlers return shape-valid AdCP responses without actually integrating with the upstream. The recipe on this page closes that gap as a **pre-staging gate** — cheap, fast, runs in CI, surfaces façades and contract drift before code reaches a staging tenant.
If your agent does not wrap an upstream — for example, a pure decisioning service that owns its own data — the storyboard runner alone is sufficient. See [Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent).
## The four-step recipe
```bash theme={null}
# 1. Boot a mock upstream for your specialism
npx @adcp/sdk@latest mock-server sales-social --port 4250 &
# 2. Run your AdCP agent, configured to use http://localhost:4250 as its upstream
./your-agent.sh # Python / Go / Rust / TS — language-agnostic
# 3. Grade your agent against the matching storyboard
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp sales_social \
--auth $TOKEN --json > grader.json
# 4. Assert your agent actually called the upstream
curl -s http://localhost:4250/_debug/traffic
# {"traffic": {"POST /oauth/token": 1, "POST /event/track": 6, ...}}
```
Step 3 catches AdCP wire bugs (response shape, error codes, idempotency, missing required fields). Step 4 catches **integration gaps** — agents whose handlers return shape-valid AdCP responses without exercising the upstream's headline endpoints. Both signals matter; one without the other is incomplete.
> [!NOTE]
>
> The mock-server CLI shown above ships in `@adcp/sdk` (TypeScript). If your CI runs in another language, the simplest pattern is to run the TS CLI as a sidecar (e.g. a Docker service container in GitHub Actions, or a separate Node process) — the agent under test stays in its native language, only the mock + storyboard runner are TS. A Python or Go SDK shipping its own mock-server would re-implement the conventions described below; until that lands, the TS CLI is the reference.
## Why traffic counters
Storyboards check the AdCP wire contract: did the response match the schema, did the agent advertise the right tools, did context echo. They do not assert what happened *behind* the wire. The CLAUDE.md guidance for this repo puts it directly: **storyboards are assertions, not ground truth.**
Adapters that look correct under shape-only validation but skip the upstream entirely have shipped to staging more than once. Common shapes:
* Handler short-circuits before the upstream call when the input doesn't match a non-spec branch (e.g. empty `members[]` on [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) → returns shape-valid empty response, never POSTs).
* OAuth client is wired but never invoked from any handler; tree-shaking is defeated with a `void fetchUpstreamToken;` literal.
* Synthetic placeholder data is injected to satisfy the upstream's required-field schema, masking real-data shape mismatches.
A traffic counter on the mock upstream catches the first two cases unconditionally and the third case if the storyboard exercises the relevant payload variety. Position this in your CI as a **pre-staging gate**: cheap, deterministic, complements your existing staging tests rather than replacing them.
## What's available
The reference TS implementation (`@adcp/sdk`) ships four mock-server specialisms covering distinct upstream surface shapes. These are not exhaustive — they exist to exercise representative auth/tenancy/payload patterns, and other specialisms reuse the closest match.
| Specialism | Mimics | Auth | Multi-tenant scope |
| - | - | - | - |
| `signal-marketplace` | LiveRamp / Lotame / data marketplace | Static Bearer | Header (`X-Operator-Id`) |
| `creative-template` | Celtra / Innovid creative-management platform | Static Bearer | Path (`/v3/workspaces/{ws}/…`) |
| `sales-social` | TikTok / Meta-shaped social ads platform | OAuth 2.0 client_credentials with refresh | Path (`/v1.3/advertiser/{advertiser_id}/…`) |
| `sales-guaranteed` | GAM / FreeWheel guaranteed-sales platform | Static Bearer | Header (`X-Network-Code`) |
The auth shapes and tenancy patterns are realistic; the specific account-field names the adapter receives (e.g. `account.advertiser`, `account.operator`) are SDK conventions for binding AdCP requests to upstream tenants, not normative AdCP terms. See the `@adcp/sdk` source for the canonical mapping.
Each mock exposes:
* **The upstream's domain endpoints** — shaped to match the real platform's public contract.
* **`GET /_lookup/?=`** — runtime resolution from AdCP-side identifiers to upstream tenant IDs. *Harness convention.*
* **`GET /_debug/traffic`** — hit counters keyed by ` `, no auth, harness-only. *Harness convention.* Read after the storyboard run; assert each headline route is hit at least once.
OpenAPI specs for each mock ship as part of the SDK package. Reference your adapter against the spec, not against any specific seed data — seeds vary and are not part of the contract.
## CI integration
Reference shape for a GitHub Actions job, language-agnostic:
```yaml theme={null}
jobs:
validate-adapter:
runs-on: ubuntu-latest
services:
mock-upstream:
image: node:20
ports: ['4250:4250']
# Use a bootstrap script that runs `npx @adcp/sdk@latest mock-server `.
steps:
- uses: actions/checkout@v4
- run: ./scripts/start-agent.sh & # Your agent in your language
- run: ./scripts/wait-for-port.sh 3001
- run: |
npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp \
--auth $TOKEN --json > grader.json
- run: |
# Assert each expected upstream route was hit at least once
curl -s http://localhost:4250/_debug/traffic | \
jq -e '.traffic["POST /oauth/token"] >= 1 and .traffic["POST /event/track"] >= 1'
```
**Threshold guidance.** The minimum useful assertion is `≥ 1` per headline route — that proves the handler reached the upstream. Stronger assertions (per-route counts, distinct-payload verification) require encoding storyboard-payload expectations and aren't worth the maintenance burden in a pre-staging gate. If your storyboard exercises 3 audience uploads, expect 3 hits to `custom_audience/upload`; if it doesn't, the storyboard's payload coverage is the lever to pull, not the gate's threshold.
For agents claiming multiple specialisms, run one CI job per specialism in parallel; each gets its own mock-server port pair (agent + upstream). Jobs are independent.
## Iteration loop
Realistically your first run will not pass both gates. Common shapes and how to debug:
* **Storyboard `passing` but traffic gate fails on N endpoints** — classic façade. The handlers for those routes either short-circuited or never got exercised by the storyboard's input.
* **Storyboard `partial` with cascade skips** — an early step ([`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products), [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals)) returned a shape-valid response missing fields that the runner extracts state from. Downstream steps skip with `unresolved context variables`. Fix the early step's response shape and most cascade skips clear.
* **Storyboard `failing` on a single step + traffic gate clean** — usually a one-line shape bug (wrong field name, missing required field, status mismatch). The per-step `details` names the field via JSON pointer.
* **Traffic gate empty (0 hits everywhere) + agent appears to start** — agent boot threw a recoverable error after listening on port. Check the agent's stderr.
Fastest debug loop: use `npx @adcp/sdk@latest storyboard step ` to isolate the failing step. Skips the cascade, runs a single tool call, sub-second feedback. Don't run the full storyboard until the isolated step passes — saves minutes per iteration.
## Limitations
Be honest with your team about what these gates do and don't catch:
### Storyboard limitations
* **Storyboards under-cover payload variety.** A storyboard step may pass shape with an empty input where a real adapter never gets exercised on the variant that matters. Tracked at [adcontextprotocol/adcp#3785](https://github.com/adcontextprotocol/adcp/issues/3785).
### Runner / tooling caveats
* **Storyboard cascade skips silently** when an early step's response is shape-valid but missing fields the runner extracts state from. The error you see is on the *downstream* step, not the early one — investigate "skipped" steps before "failed". Tracked at [adcontextprotocol/adcp#3796](https://github.com/adcontextprotocol/adcp/issues/3796) (runner-side).
* **Mock seed data may not match storyboard fixture inputs.** If you see 404s on `_lookup/`, the storyboard's payloads may reference IDs the mock doesn't seed. Either widen the mock's seed or seed scenario state at runtime via the [compliance test controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller).
### Traffic gate limitations
* **Necessary, not sufficient.** A handler can call upstream with synthetic placeholder data and still satisfy the hit-count assertion. For agents in regulated channels (audience uploads, conversion tracking, signed requests), additional integration tests against the real upstream's payload validation are still required before production.
* **Idempotency replay is not exercised by traffic counters.** A façade that ignores `idempotency_key` and doubles upstream writes will pass the hit-count gate. Use the storyboard's idempotency-replay scenarios + a separate counter check (same `idempotency_key` → same hit count) if your platform has at-most-once semantics.
* **Outbound webhook delivery is not exercised by upstream traffic counters.** Traffic counters live on the upstream the agent calls *into*; agent → buyer webhook signing/delivery is graded by the storyboard runner's `--webhook-receiver` flag, separately. Both gates apply for adapters that emit webhooks.
## What's next
* **[Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** — the broader storyboard-runner-driven validation checklist (fuzz, multi-instance, request-signing, webhook conformance).
* **[Compliance test controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller)** — seed scenario state at runtime when storyboards need fixtures the mock doesn't provide.
* **[Build an agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent)** — the language-agnostic guide to building an AdCP agent.
* **[Compliance catalog](/dist/docs/3.2.8/building/verification/compliance-catalog)** — the full taxonomy of universal / protocol / specialism storyboards.
# Validate your agent using storyboards
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/building/verification/validate-your-agent
Test your AdCP agent with storyboards — from the CLI or through Addie.
Once your agent is running, validate it before going live. Storyboards exercise a specific workflow end-to-end — media buy creation, creative sync, signals discovery. Each storyboard defines the exact tool call sequence a buyer agent makes and validates every response shape.
Storyboards are available from the command line and interactively through [Addie](https://agenticadvertising.org). They are also published alongside schemas at `/compliance/{version}/` and bundled into the per-version protocol tarball at `/protocol/{version}.tgz` — see [Schemas and SDKs](/dist/docs/3.2.8/building/by-layer/L0/schemas#one-shot-protocol-bundle) for how to fetch them offline.
> [!NOTE]
>
> The `@adcp/sdk` package also exports legacy TypeScript test runners under `testing/scenarios/*` (e.g. `media-buy.ts`, `signals.ts`). These predate `comply()` and are **not** the conformance specification. If you find yourself grepping those files to learn what AdCP requires, see [Storyboards vs. scenarios](/dist/docs/3.2.8/building/verification/storyboards-vs-scenarios) for which surface is normative.
> [!NOTE]
>
> **Wrapping an upstream platform** (DSP, SSP, retail data warehouse, creative server, signal marketplace)? Storyboards check your AdCP wire contract; they cannot tell whether the adapter behind the wire actually integrates with the upstream or returns shape-valid responses with synthetic data. See [Validate adapter agents with mock upstream fixtures](/dist/docs/3.2.8/building/verification/validate-with-mock-fixtures) — published mock fixtures plus traffic counters give you façade-resistant compliance for adapters in any language.
## Storyboard taxonomy
Storyboards are organized into three layers so agents declare only what they actually support:
| Layer | Path | Who must pass it |
| - | - | - |
| **Universal** | `/compliance/{version}/universal/` | Every AdCP agent (capability discovery, error handling, schema validation) |
| **Protocol** | `/compliance/{version}/protocols/{protocol}/` | Any agent claiming a protocol (`media-buy`, `creative`, `signals`, `governance`, `brand`) |
| **Specialism** | `/compliance/{version}/specialisms/{id}/` | Opt-in claims (e.g. `sales-guaranteed`, `sales-broadcast-tv`, `creative-generative`) — see the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) |
Declare your `supported_protocols` and `specialisms` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) — the runner picks the matching storyboards automatically. See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for the full taxonomy.
## Setup
Save your agent as a named alias so you can reference it by name:
```bash theme={null}
npx @adcp/sdk@latest --save-auth my-agent http://localhost:3001/mcp
```
This stores the alias in `~/.adcp/config.json`. You only need to do this once. Built-in aliases `test-mcp` and `test-a2a` point to the public test agents — no setup needed.
> [!TIP]
>
> You can also pass a URL directly instead of an alias: `npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp media_buy_seller`
## Run a storyboard
### 1. List available storyboards
```bash theme={null}
npx @adcp/sdk@latest storyboard list
```
Each storyboard targets a specific agent type. The [Build an Agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent) page maps skills to their matching storyboards.
### 2. Preview what a storyboard tests
```bash theme={null}
npx @adcp/sdk@latest storyboard show media_buy_seller
```
This shows the phases, steps, and validations without running anything.
### 3. Run the storyboard
```bash theme={null}
npx @adcp/sdk@latest storyboard run my-agent media_buy_seller
```
Output shows each step with pass/fail:
```
media_buy_seller (9 steps)
✓ get_adcp_capabilities
✓ sync_accounts
✓ get_products
✓ create_media_buy
✓ canonical format declarations
✓ sync_creatives
✓ list_creatives
✓ get_media_buy_delivery
✓ provide_performance_feedback
9/9 passed
```
Pass `--json` for machine-readable results. Pass `--debug` to see full request/response payloads for each step.
### 4. Debug a failing step
If a step fails, run it individually:
```bash theme={null}
npx @adcp/sdk@latest storyboard step my-agent media_buy_seller create_media_buy --json --debug
```
Pass `--context` to provide state from earlier steps (account IDs, product IDs):
```bash theme={null}
npx @adcp/sdk@latest storyboard step my-agent media_buy_seller get_products \
--context '{"account_id":"acct-123"}' --json
```
### 5. Run all storyboards
Run without a storyboard ID to test everything. The CLI discovers your agent's tools via `tools/list` and selects matching storyboards automatically:
```bash theme={null}
npx @adcp/sdk@latest storyboard run my-agent
```
Add `--json` for structured output.
### Select a compliance cache and test kit
`--compliance-version` selects a cache bundled with the SDK. For an extracted cache, pass its versioned directory to `--compliance-dir`; `--test-kit` takes a YAML file from the `test-kits/` directory below that same cache root. After extracting the `@adcp/sdk` 14.0.0 npm tarball in the current directory, use its versioned cache root like this:
```bash theme={null}
npx @adcp/sdk@14.0.0 storyboard run my-agent \
--compliance-dir ./package/compliance/cache/3.2.1 \
--test-kit ./package/compliance/cache/3.2.1/test-kits/acme-outdoor.yaml
```
> [!NOTE]
>
> `@adcp/sdk` 13.0.0 and later infer the compliance line from test-kit metadata and reject mixed or ambiguous `--test-kit`, `--compliance-version`, and `--compliance-dir` selections before contacting the agent. Keep the test kit and storyboard files under the same versioned cache root.
The storyboard runner operates in two modes depending on whether your agent implements the optional [compliance test controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller):
| Mode | When | What it tests |
| - | - | - |
| **Observational** | No test controller | Response schemas and buyer-initiated flows |
| **Deterministic** | Test controller present | Full lifecycle state machines, error codes, operation gates |
### Reading `partial`
`partial` is a coverage result, not automatically a failure. The runner uses it when one or more selected scenarios could not be graded even though no executed assertion failed. The most common cause is intentional: production endpoints MUST NOT expose [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller), so controller-seeded storyboards skip with a storyboard-level `requirement_unmet` naming `controller`, and controller-forced steps that are not gated skip with `missing_test_controller`.
Read `steps_not_selected` separately from `steps_skipped`. Not-selected scenarios were outside the suite or run mode you asked for. Skipped scenarios were inside the selected suite, but the runner could not execute them because of an applicability gate, missing test surface, missing tool, or prerequisite.
Use the summary counters and skip reasons to decide what the result means:
| Summary | Interpretation |
| - | - |
| `0 failed`, `steps_not_selected > 0`, `steps_skipped = 0` | Expected for the selected run mode, such as sandbox-only testing that excludes live-only probes |
| `0 failed`, only capability-gate `not_applicable` skips | Clean pass for the capability scope the seller declared |
| `0 failed`, `requirement_unmet` (`controller`) or `missing_test_controller` skips | Buyer-visible path passed, but deterministic lifecycle coverage was not graded |
| Any `missing_tool` skip for a declared protocol or specialism | The seller overclaimed or forgot to expose a required tool |
| Any failed step | Not conformant for the declared scope until fixed |
For production-path sandbox validation, a result like `84 passed, 0 failed, 0 skipped, 80 not selected` is a clean sandbox-only selection result: the excluded probes were never part of that run. A result like `84 passed, 0 failed, 80 skipped` needs the skip breakdown before it means anything. Skips because an optional capability was not claimed are selected-scope skips. Skips with `missing_test_controller` are deterministic coverage gaps: the suite tested the public sandbox path and reported that controller-seeded lifecycle scenarios were not graded. To get full green on those, run against a dev/staging endpoint that exposes the controller, pre-seed the required state and tell the runner to assert seeded-state coverage, or accept and publish the skipped coverage list as an explicit limitation.
## Validate through Addie
[Addie](https://agenticadvertising.org) provides interactive testing without any CLI setup. Paste your agent URL in any conversation to get started.
### Connectivity check
Ask Addie to check your agent. She'll verify it's online, list its advertised tools, and confirm the transport protocol (MCP or A2A). This is the quickest way to confirm your agent is reachable before running any tests.
### Storyboard coaching
Addie runs the same storyboards as the CLI but walks you through each step interactively. When a step fails, she explains what went wrong, shows the expected vs actual response, and suggests specific code changes. This is the fastest way to iterate when you're building.
### RFP testing
Share a real RFP or campaign brief with Addie. She'll parse it, call your agent's [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) with the buyer's actual requirements, and compare results against what your sales team would normally propose. This tests whether your agent can handle real buyer demand — not just synthetic briefs derived from your own inventory description.
### IO execution testing
Share an insertion order with Addie. She'll extract the line items, match them against your agent's product catalog, and test whether [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) can execute the deal. The output shows line-by-line matching quality (exact, close, weak, unmapped) and rate comparisons so you can see exactly where execution would break down.
### Recommended testing sequence
1. **Connectivity** — Is the agent online?
2. **Storyboards** — Does it pass protocol compliance?
3. **RFP testing** — Can it respond to real buyer demand?
4. **IO execution** — Can it close real deals?
Each step builds confidence. Storyboards prove protocol compliance. RFP and IO testing prove business readiness.
## Sandbox mode
All storyboard runs use sandbox mode by default. For buyer-declared accounts, the runner includes `sandbox: true` in every natural-key account reference. For account-ID namespaces, it first resolves and verifies a sandbox account, then sends `{ "account_id": "..." }` without a sandbox flag. In either model, your agent processes the selected sandbox account without real platform calls or spend.
Your agent should declare sandbox support in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities):
```json theme={null}
{
"account": {
"sandbox": true
}
}
```
When a request references a sandbox account, your agent MUST NOT persist production state or cause real-world side effects — no real orders, no real billing, no real ad platform API calls. Return realistic response shapes with simulated data and include `sandbox: true` in success responses.
See [Sandbox mode](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox) for full implementation details and the natural-key and account-ID paths.
## Verifying cross-instance state
The protocol requires that `(brand, account)`-scoped state [survive across agent process instances](/dist/docs/3.2.8/protocol/architecture#state-persistence-and-horizontal-scaling) — a media buy created on one replica must be readable from any other. Single-instance storyboard success does not by itself prove that invariant. Choose a verification approach that fits your deployment.
**Verify by architecture.** If you run on a managed serverless platform with a shared datastore — Lambda + DynamoDB, Cloudflare Workers + D1, Cloud Run + Firestore, Vercel + Neon — the invariant holds by construction. Storyboards that pass against your deployed endpoint are sufficient. Document your storage pattern so it's discoverable.
**Verify by multi-instance testing.** If you deploy long-running processes (containers, VMs, a classic app server behind a load balancer), put ≥2 replicas behind round-robin routing and run storyboards against the shared endpoint:
```bash theme={null}
npx @adcp/sdk@latest --save-auth my-agent https://my-agent.example/mcp
npx @adcp/sdk@latest storyboard run my-agent
```
The compliance runner rotates requests across replicas for any storyboard that contains a step marked `stateful: true` — the write→read sequences most likely to catch in-process state. Stateless probes (capability discovery, auth rejection, schema validation) are unaffected.
A typical failure looks like:
```
✗ get_media_buy MEDIA_BUY_NOT_FOUND
create_media_buy on replica A returned media_buy_id=mb_abc123 (status: active)
get_media_buy on replica B returned MEDIA_BUY_NOT_FOUND for the same id
→ Brand-scoped state is not shared across replicas.
```
**Verify by your own testing.** Property-based tests against a real datastore, chaos fault injection between replicas, or production observability that correlates writes and reads across instances are all valid. The protocol cares about the invariant, not the methodology.
Insertion-order approval records, governance tokens, signal activations, and sponsored-intelligence sessions all fall under the same rule. Any state you write that a later call can read back must live in a shared store — not a per-process `Map` or module-level variable.
## Preparing to test uniform error responses
The [uniform-response MUST](/dist/docs/3.2.8/building/by-layer/L3/error-handling#standard-error-codes) requires byte-equivalent responses for "the id exists but the caller lacks access" and "the id does not exist" across every observable channel — error body, transport status, headers, side effects, and telemetry. Verifying this needs a paired-probe runner (`adcp fuzz`) that compares two responses per tool. The runner has two modes, and you need to plan tenant setup before you can exercise the strong one.
**Baseline mode — single tenant.** One auth token, two fresh UUIDs probed per tool. Catches id-echo in error bodies, header divergence outside the allowlist, MCP `isError` / A2A `task.status.state` divergence, and gross latency deltas. Cannot catch cross-tenant existence leaks, because neither probe resolves to a real resource.
**Cross-tenant mode — two tenants.** Tenant A seeds a resource (e.g., a property list, content standard, media buy, creative); tenant B probes against the seeded id plus a fresh UUID. Catches the full MUST, because it exercises the `(exists, unauthorized)` vs `(does not exist)` pair that baseline cannot construct.
Both modes exercise spec MUSTs. Only the cross-tenant path verifies the whole invariant.
### Minimum tenant setup
Provision two isolated test accounts against your agent:
* **Tenant A** — can create resources the invariant seeds (property lists, content standards, media buys, creatives). Sandbox-mode accounts are fine.
* **Tenant B** — read-only against shared discovery surfaces. MUST NOT share any per-tenant state with A beyond what your platform makes globally visible (e.g., published product catalogs).
Anything else the two tenants share — audit shards, rate-limit buckets keyed by resource type, cache tags — is a potential side channel the invariant is designed to catch. Share only what you'd share in production.
### Runner invocation
```bash theme={null}
# Cross-tenant (full MUST)
npx @adcp/sdk@latest fuzz my-agent \
--auth-token $TENANT_A_TOKEN \
--auth-token-cross-tenant $TENANT_B_TOKEN
# Baseline (partial coverage)
npx @adcp/sdk@latest fuzz my-agent --auth-token $TOKEN
```
Tokens may also be supplied via `ADCP_AUTH_TOKEN` and `ADCP_AUTH_TOKEN_CROSS_TENANT`. See the [`@adcp/sdk` uniform-error-response invariant guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/VALIDATE-YOUR-AGENT.md#uniform-error-response-invariant-paired-probe) for the full flag list, the header allowlist, and the list of tools currently probed.
### Testing with only one tenant
If you haven't provisioned a second tenant yet, run baseline anyway — it still catches a meaningful class of leaks, and the CLI flags the run as baseline-only so operators can see coverage is partial. Treat single-tenant fuzz as a pre-check, not a conformance signal: a clean baseline run does not prove the MUST holds. Add the cross-tenant leg before you claim uniform-response conformance.
## The build-validate-fix loop
The typical development workflow:
1. **Build** — Point a coding agent at a [skill file](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent) to generate your agent
2. **Run** — Start the agent locally (`npx tsx agent.ts`)
3. **Validate** — Run the matching storyboard (`npx @adcp/sdk@latest storyboard run my-agent media_buy_seller`)
4. **Fix** — Address any failures (missing fields, wrong status values, invalid transitions)
5. **Repeat** — Run the storyboard again until all steps pass
6. **Full check** — Run `npx @adcp/sdk@latest storyboard run my-agent` (no storyboard ID) for a full assessment before going live
> [!NOTE]
>
> For [Practitioner certification](https://agenticadvertising.org/certification), passing storyboard validation is the capstone — it proves your agent handles the complete protocol workflow for your chosen role track.
## CLI reference
| Command | Description |
| - | - |
| `npx @adcp/sdk@latest storyboard list` | List all available storyboards |
| `npx @adcp/sdk@latest storyboard show ` | Preview storyboard structure |
| `npx @adcp/sdk@latest storyboard run [id]` | Run one storyboard, or all matching if no ID given |
| `npx @adcp/sdk@latest storyboard step ` | Run a single step |
| `npx @adcp/sdk@latest [tool] [payload]` | Call any tool directly |
| `npx @adcp/sdk@latest --save-auth ` | Save agent alias |
| `npx @adcp/sdk@latest --list-agents` | List saved aliases |
All commands support `--json`, `--debug`, `--auth TOKEN`, and `--protocol mcp|a2a`.
## When a storyboard fails
* **[Storyboard troubleshooting](/dist/docs/3.2.8/building/operating/storyboard-troubleshooting)** — Error patterns mapped to root causes and fixes (missing fixtures, signature challenges, envelope drift, context echo, capability mismatches)
* **[Known spec ambiguities](/dist/docs/3.2.8/building/cross-cutting/known-ambiguities)** — Open spec gaps that affect conformance, with workarounds and issue links
## What's next
* **[Compliance test controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller)** — Implement deterministic testing for full lifecycle coverage
* **[Task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle)** — Status values, transitions, and polling
* **[Error handling](/dist/docs/3.2.8/building/by-layer/L3/error-handling)** — Error categories, codes, and recovery
# Introduction to AdCP
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/intro
AdCP is an open agentic advertising standard. Follow Alex's team from fragmentation to a unified workflow across all protocol domains.

> [!NOTE]
>
> AdCP 3.2 is generally available (release `3.2.1`, wire pin `"3.2"`). It adds a
> proposal-to-operation lifecycle buyers and sellers can audit, shared
> MediaBuy-level frequency caps, and experimental Reliable Reporting and
> authenticated principals. Existing 3.1 integrations keep working. See
> [what's new in 3.2](/dist/docs/3.2.8/reference/whats-new-in-3-2) and the
> [3.1 to 3.2 migration guide](/dist/docs/3.2.8/reference/migration/3-1-to-3-2).
Alex runs media operations at Pinnacle Agency. Her team buys across six channels — CTV, display, audio, social, retail media, and digital out-of-home. Each channel has its own buying methods, its own terminology, its own way of handling creatives, targeting, and reporting. IOs for some. APIs for others. DSPs for programmatic. Dashboards for everything.
Now her clients want to try AI-generated creative, influencer campaigns, and local radio. Each new channel means new tools, new integrations, new workflows to learn. She can't keep scaling her team every time a client wants to try something new.
The problem isn't her people. It's that every channel speaks a different language, and the industry has no common standard for how agents discover inventory, execute buys, distribute creative, activate data, or report results.
AdCP is that standard. One protocol. Every platform. Every step of the campaign.
AdCP's goal is to become the enterprise coordination protocol for a
trillion-dollar global advertising economy. That requires more than a small
demo API: identity, authorization, immutable commercial state, safe retries,
auditable decisions, version negotiation, and recovery when distributed
systems fail. The protocol keeps those guarantees open and portable, while
maintained [SDKs](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk) absorb most of the
implementation burden for production teams.
## More than activation
AdCP coordinates the full campaign lifecycle — from brief intake through measurement — not just activation. It works across every transaction model: direct deals, sponsorships, broadcast, and out-of-home, not only programmatic exchange. Most global ad spend flows through non-programmatic channels, and AdCP is designed for all of them.
One architecture does not mean every channel or commercial function has equal
implementation depth today. AdCP standardizes the capabilities a participant
actually advertises. Payment rails, legal agreements, settlement, disputes,
credits, and makegoods remain account or platform integrations unless the
relevant AdCP contract is explicitly present. The public [roadmap](/dist/docs/3.2.8/reference/roadmap)
shows the gaps where implementations and domain contributors are actively
needed.
This page follows Alex's team through the entire workflow — from finding new partners to measuring results. Each section shows the human problem, the protocol solution, and the tasks that make it work. By the end, you'll understand every domain AdCP covers and how they connect.
***
## Find new partners

Alex wants to work with publishers she's never talked to before. In the old world, that means sales calls, contracts, and weeks of integration work before she can even see what's available.
With AdCP, discovery is built into the protocol. Every AdCP-enabled publisher hosts an `adagents.json` file — a machine-readable declaration of their properties and authorized agents. Sales operators publish `brand.json` for company identity, sales-agent endpoints, and signing-key discovery. Alex's buyer agent can resolve both files the same way a browser reads `robots.txt`.
```
https://streamhaus.tv/.well-known/adagents.json
```
```json theme={null}
{
"version": "1.0",
"publisher": {
"name": "StreamHaus",
"domain": "streamhaus.tv"
},
"agents": [
{
"url": "https://ads.streamhaus.tv/mcp",
"protocol": "mcp",
"capabilities": ["get_products", "create_media_buy", "sync_creatives"]
}
]
}
```
For broader discovery — "find me CTV publishers with sports inventory" — the [AgenticAdvertising.org registry](/dist/docs/3.2.8/registry) provides entity resolution and agent search. Alex's agent can query the registry by category, geography, or capability, and get back a list of publishers to connect with.
> [accordion] What the registry returns
>
> The registry API resolves brands to their AdCP agents:
>
> ```
> GET /api/registry/agents?capability=get_products&channel=ctv
> ```
>
> ```json theme={null}
> {
> "agents": [
> {
> "domain": "streamhaus.tv",
> "agent_url": "https://ads.streamhaus.tv/mcp",
> "capabilities": ["get_products", "create_media_buy"],
> "channels": ["ctv", "olv"]
> }
> ]
> }
> ```
> [card] [Learn more: adagents.json](/dist/docs/3.2.8/governance/property)
>
> How publishers declare their properties and authorized agents.
***
## Set up accounts

Before Alex's team can buy media, they need a commercial relationship. In the old world, each platform has different onboarding — portals, forms, sales reps, weeks of back-and-forth.
AdCP standardizes this with the accounts protocol. Sam, Alex's media buyer, sets up Pinnacle's relationship with StreamHaus in one call:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/account/sync-accounts-request.json",
"idempotency_key": "f6c0a3d4-2345-48b1-2345-6789012345ab",
"accounts": [
{
"brand": { "domain": "acmeoutdoor.com" },
"operator": "pinnacle-agency.com",
"billing": "operator"
}
]
}
```
The seller responds with the account status — active, pending review, or what additional information is needed. Once active, Sam can buy media.
`list_accounts` shows all active relationships across every platform, so Alex can see at a glance which publishers her team is set up with.
> [card] [Deep dive: Accounts](/dist/docs/3.2.8/accounts/overview)
>
> Commercial identity, billing models, and multi-advertiser management.
***
## Discover what's available

This is where it gets powerful. Sam wants to find premium sports inventory for Acme Outdoor's Q2 campaign. In the old world, he'd log into four dashboards and compare apples to oranges.
With AdCP, `get_products` sends the same structured request and brief to every connected seller. Sam keeps semantic intent in prose and exact constraints in fields every seller can process deterministically:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-request.json",
"idempotency_key": "550e8400-e29b-41d4-a716-446655442003",
"buying_mode": "brief",
"brief": "Premium sports and outdoor-recreation contexts for Acme Outdoor's Q2 launch. Budget $50K.",
"filters": {
"channels": ["ctv", "display"],
"pricing_currencies": ["USD"]
},
"targeting_overlay": {
"geo_countries": ["US"],
"demographics": {
"age": { "min": 25, "max": 45, "include_unknown": false }
}
},
"brand": { "domain": "acmeoutdoor.com" }
}
```
Every seller responds in the same format — products with pricing, forecasts, targeting support, resolution, and creative requirements. Sam can verify exact constraints without asking every seller to infer them from prose.
> [accordion] What a product response looks like
>
> ```json theme={null}
> {
> "products": [
> {
> "product_id": "streamhaus_sports_ctv_q2",
> "name": "StreamHaus Sports Premium",
> "channels": ["ctv"],
> "pricing_options": [
> {
> "model": "cpm",
> "price": 28.50,
> "currency": "USD"
> }
> ],
> "forecast": {
> "impressions": { "min": 500000, "max": 750000 }
> },
> "format_option_refs": [{ "scope": "product", "format_option_id": "video_16x9_30s" }]
> }
> ]
> }
> ```
But Sam isn't done. He likes StreamHaus's sports package but wants to shift budget toward CTV and drop the display allocation. Instead of starting over, he uses **refine mode** — an iterative conversation with the seller:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-request.json",
"idempotency_key": "550e8400-e29b-41d4-a716-446655442004",
"buying_mode": "refine",
"refine": [
{
"scope": "product",
"product_id": "streamhaus_sports_ctv_q2",
"action": "more_like_this",
"ask": "More CTV inventory like this, willing to go up to $35 CPM"
},
{
"scope": "request",
"ask": "Drop display entirely, reallocate budget to CTV and OLV"
}
]
}
```
The seller adjusts and responds with refined options. No new RFP. No starting from scratch. Sam iterates until he has exactly what he wants.
> [card] [Follow Sam's full journey](/dist/docs/3.2.8/media-buy)
>
> The complete media buy walkthrough — brief to delivery across three sellers.
***
## Build the creative

Maya, Pinnacle's creative strategist, needs to produce ads for Sam's campaign. One campaign, three sellers, six formats — CTV video, OLV pre-roll, display banners, companion ads. In the old world, that's six separate production workflows.
First, Maya discovers what each seller accepts:
```json theme={null}
const products = await seller.get_products({
buying_mode: "brief",
brief: "Summer video and display campaign",
brand: { domain: "acmeoutdoor.com" }
});
```
Each product returns canonical `format_options[]` with exact constraints—dimensions, codecs, file sizes, duration limits, and slots. No guessing.
Then Maya briefs the creative agent. One brief produces all formats:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "c1d2e3f4-a5b6-4789-c012-789012345678",
"message": "Adventurous, aspirational summer campaign — gear for people who live outside",
"brand": { "domain": "acmeoutdoor.com" },
"target_capability_ids": ["video_16x9_30s", "display_300x250"]
}
```
The creative agent pulls Acme Outdoor's brand identity — colors, logos, tone guidelines — directly from the brand's `brand.json` (more on that below). No brand guide PDFs. No manual asset handoff.
If Maya doesn't like the first draft, she refines with natural language: *"Make the opening shot more dynamic and swap the product shot for the hiking boots."* The `build_creative` task supports iterative refinement — same task, conversational guidance.
Once approved, `sync_creatives` distributes the finished assets to every seller simultaneously:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/creative/sync-creatives-request.json",
"idempotency_key": "d2e3f4a5-b6c7-4890-d123-890123456789",
"account": { "brand": { "domain": "acmeoutdoor.com" }, "operator": "pinnacle-agency.com" },
"creatives": [
{
"creative_id": "acme_summer_ctv_30s",
"name": "Acme Summer CTV 30s",
"format_kind": "video_hosted",
"assets": {
"video": { "asset_type": "video", "url": "https://cdn.pinnacle.com/acme_summer_30s.mp4", "width": 1920, "height": 1080, "duration_ms": 30000 }
}
}
]
}
```
> [card] [Follow Maya's full journey](/dist/docs/3.2.8/creative/index)
>
> Creative generation, format discovery, and multi-seller distribution.
***
## Execute the buy

Sam has products, creatives, and accounts. Time to buy. One call to `create_media_buy` executes the campaign across every seller:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-request.json",
"idempotency_key": "e3f4a5b6-c7d8-4901-e234-901234567890",
"account": { "brand": { "domain": "acmeoutdoor.com" }, "operator": "pinnacle-agency.com" },
"brand": { "domain": "acmeoutdoor.com" },
"start_time": "2026-04-01T00:00:00Z",
"end_time": "2026-06-30T23:59:59Z",
"packages": [
{
"product_id": "streamhaus_sports_ctv_q2",
"budget": 35000,
"pricing_option_id": "cpm_standard"
}
]
}
```
For sellers that generate creative — AI assistants, conversational ad platforms — the media buy can include a brief instead of pre-built assets. The seller's creative agent generates on the fly, pulling from the brand identity and campaign context. Both models — provided creative and generative creative — use the same `create_media_buy` task.
`update_media_buy` handles mid-flight changes: shift budget between packages, adjust flight dates, swap creative assignments. No need to cancel and recreate.
> [card] The trust surface underneath
>
> That `idempotency_key` on Sam's request isn't decorative. Pinnacle's buyer agent signs the POST with RFC 9421 HTTP Message Signatures before it leaves the network. StreamHaus verifies Pinnacle's signature against Pinnacle's operator-published JWKS, then accepts the buy. When the campaign moves from `pending_start` to `active`, StreamHaus posts a signed webhook back to Pinnacle's orchestrator — same signature profile, with StreamHaus's request-signing key published through its `brand.json` `agents[]` entry and optionally pinned by publisher `adagents.json`. If Sam's laptop drops the response and his agent retries, the `idempotency_key` makes the second call safe — StreamHaus returns the original buy with `replayed: true` instead of charging twice. Governance approvals ride along as signed JWS tokens on `check_governance` so no agent in the chain can forge Jordan's sign-off. See the [Security guide](/dist/docs/3.2.8/building/by-layer/L1/security).
***
## Match at serve time
The campaign is live. When a user loads a StreamHaus page, opens OutdoorNet's mobile app, or asks an AI assistant about hiking gear, the publisher needs to know which of Sam's packages should activate — right now, for this content, for this user.
The [Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match) handles this with two structurally separated operations. **Context Match** evaluates content signals against the available packages — no user identity crosses this boundary. **Identity Match** checks user eligibility using an opaque token — no page context crosses this boundary. The publisher joins both responses locally. Buyers never see identity and content together.
One protocol, every surface: web, mobile, CTV, AI assistants, retail media.
***
## Add your data

Sam's campaign needs targeting beyond what the sellers provide. His client has CRM data (existing customers to exclude), Pinnacle has audience segments from their DMP, and he wants to layer on third-party signals from Kai's data company, Meridian Geo.
**Audiences** travel with the campaign via `sync_audiences`:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-audiences-request.json",
"idempotency_key": "a7d1b4e5-3456-48c2-3456-789012345abc",
"account": { "brand": { "domain": "acmeoutdoor.com" }, "operator": "pinnacle-agency.com" },
"audiences": [
{
"audience_id": "acme_existing_customers",
"name": "Acme Outdoor — existing customers",
"audience_type": "suppression"
}
]
}
```
**Signals** — third-party targeting data — are discovered and activated through the signals protocol. Sam searches for what he needs:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/signals/get-signals-request.json",
"signal_spec": "Outdoor recreation enthusiasts near sporting goods retailers, 25-45"
}
```
Kai's Meridian Geo returns matching signal segments with pricing, coverage, and activation options. Sam activates the ones he wants:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/signals/activate-signal-request.json",
"idempotency_key": "f4a5b6c7-d8e9-4012-f345-012345678901",
"signal_agent_segment_id": "meridian_outdoor_rec_25_45",
"destinations": [
{ "type": "platform", "platform": "streamhaus" }
]
}
```
The signal activates on StreamHaus's platform. Kai's data reaches Sam's campaign without either side building a custom integration.
> [card] [Signals deep dive](/dist/docs/3.2.8/signals/overview)
>
> How Sam discovers and activates Kai's targeting data across platforms.
***
## Govern it

Before any of Sam's campaigns go live, they pass through governance. Jordan, Pinnacle's campaign ops manager, set up the governance framework before Alex let any agent spend money.
`check_governance` runs automatically before execution — budget limits, brand safety, targeting compliance:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/governance/check-governance-request.json",
"plan_id": "acme_outdoor_q2_plan",
"caller": "https://buyer.pinnacle-agency.com/a2a",
"target_agent": "https://seller.streamhaus.example/a2a",
"tool": "create_media_buy",
"payload": {
"brand": { "domain": "acmeoutdoor.com" },
"start_time": "2026-04-01T00:00:00Z",
"end_time": "2026-06-30T23:59:59Z"
}
}
```
If everything passes, the campaign proceeds. If something exceeds the agent's authority — say, the budget is above Jordan's \$20K auto-approval threshold — the governance agent escalates to a human. Jordan reviews, adds conditions if needed, and approves. The agent can't skip this step; it's architectural, not procedural.
After the campaign runs, `get_plan_audit_logs` provides the complete decision trail — who proposed what, who approved it, what conditions were attached, what actually ran. Every decision is recorded and attributable.
> [accordion] What an audit log looks like
>
> ```json theme={null}
> {
> "entries": [
> {
> "timestamp": "2026-03-15T14:30:00Z",
> "actor": "buyer_agent",
> "action": "submit_plan",
> "details": { "budget": 50000, "channels": ["ctv", "olv"] }
> },
> {
> "timestamp": "2026-03-15T14:30:01Z",
> "actor": "governance_agent",
> "action": "escalate",
> "reason": "Budget exceeds auto-approval threshold ($20,000)"
> },
> {
> "timestamp": "2026-03-15T15:12:00Z",
> "actor": "jordan@pinnacleagency.com",
> "action": "approve_with_conditions",
> "conditions": ["Weekly spend cap of $15,000", "CTV only — no OLV until brand safety review"]
> }
> ]
> }
> ```
> [card] [Follow Jordan's full journey](/dist/docs/3.2.8/governance/overview)
>
> The governance walkthrough — from nightmare to audit trail.
***
## Track performance

Sam's campaign is live. In the old world, he'd check four dashboards. Now, `get_media_buy_delivery` aggregates performance from every seller into one response:
```json theme={null}
{
"impressions": 1250000,
"clicks": 18750,
"spend": { "amount": 34200, "currency": "USD" },
"by_package": [
{
"product_id": "streamhaus_sports_ctv_q2",
"impressions": 750000,
"completion_rate": 0.87
}
]
}
```
For deeper performance tracking, AdCP provides two more tools:
**`log_event`** records marketing events — purchases, leads, sign-ups — back to the sellers for attribution and optimization:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/log-event-request.json",
"idempotency_key": "a5b6c7d8-e9f0-4123-a456-123456789012",
"event_source_id": "acme_website_pixel",
"events": [
{
"event_id": "evt_abc123",
"event_type": "purchase",
"event_time": "2026-05-15T10:30:00Z",
"action_source": "website",
"custom_data": { "value": 149.99, "currency": "USD" }
}
]
}
```
**`provide_performance_feedback`** closes the optimization loop — telling sellers what's working and what isn't, so their algorithms can adjust:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/provide-performance-feedback-request.json",
"idempotency_key": "b6c7d8e9-f0a1-4234-b567-234567890123",
"media_buy_id": "mb_acme_q2_001",
"measurement_period": {
"start": "2026-04-01T00:00:00Z",
"end": "2026-04-30T23:59:59Z"
},
"performance_index": 1.35
}
```
***
## Connect your store

Acme Outdoor has a Shopify store with 200 products. They want their catalog available to AI platforms — AI assistants that recommend products, AI search engines that surface them, retail media networks that need feed data.
`sync_catalogs` pushes the product feed to every connected platform:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-catalogs-request.json",
"idempotency_key": "b8e2c5f6-4567-48d3-4567-89012345abcd",
"account": { "brand": { "domain": "acmeoutdoor.com" }, "operator": "pinnacle-agency.com" },
"catalogs": [
{
"catalog_id": "acme_outdoor_products",
"name": "Acme Outdoor Product Feed",
"type": "product",
"url": "https://acmeoutdoor.com/feeds/products.json",
"feed_format": "shopify",
"update_frequency": "daily"
}
]
}
```
The seller ingests the catalog and makes it available for product-level targeting, dynamic creative, and conversational recommendations. When a product goes out of stock or a price changes, the feed updates and the seller syncs automatically.
***
## Protect the brand

Tomoko manages brand operations at Acme Outdoor's parent company, Nova Motors. She published Nova's `brand.json` — a machine-readable brand identity that AI agents consume directly:
```
https://novamotors.com/.well-known/brand.json
```
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/brand.json",
"house": {
"domain": "novamotors.com",
"name": "Nova Motors"
},
"brands": [
{
"id": "acme_outdoor",
"names": [{ "en": "Acme Outdoor" }],
"identity_agent": {
"url": "https://brand.novamotors.com/mcp",
"id": "nova_brand_agent"
}
}
]
}
```
When Maya's creative agents generate ads, they pull brand guidelines directly from `brand.json` and the `get_brand_identity` task — colors, logos, tone, visual guidelines. No brand guide PDF. No manual asset handoff. The brand controls what AI agents see, and the protocol enforces it.
For campaigns using licensed talent or third-party IP, the brand protocol handles [rights licensing](/dist/docs/3.2.8/brand-protocol/walkthrough-rights-licensing) — discovery, acquisition, creative approval, and lifecycle management, all through the same protocol.
> [card] [Brand protocol](/dist/docs/3.2.8/brand-protocol)
>
> Brand identity, rights licensing, and how brands control what AI does with their assets.
***
## The full picture
Alex started with twelve platforms, twelve integrations, and a team drowning in platform mechanics. Now her team works through one protocol:
| What they need | How AdCP handles it | Key tasks |
| - | - | - |
| Find new partners | Publisher discovery + registry | `adagents.json`, Registry API |
| Set up relationships | Standardized onboarding | `sync_accounts`, `list_accounts` |
| Discover inventory | One brief, every seller | `get_products` (brief + refine modes) |
| Build creative | One brief, every format | `get_adcp_capabilities`, `build_creative`, `sync_creatives` |
| Execute campaigns | One buy, multiple sellers | `create_media_buy`, `update_media_buy` |
| Add targeting data | Audiences + third-party signals | `sync_audiences`, `get_signals`, `activate_signal` |
| Govern everything | Human oversight, built in | `check_governance`, `get_plan_audit_logs` |
| Track performance | Unified reporting + events | `get_media_buy_delivery`, `log_event` |
| Connect commerce | Product catalog sync | `sync_catalogs` |
| Protect the brand | Machine-readable identity | `brand.json`, `get_brand_identity` |
Sam buys media. Maya builds creative. Jordan governs. Kai provides data. Tomoko protects the brand. They all speak the same protocol.
***
## How it works underneath
AdCP doesn't assume a single AI handles everything. Specialized agents handle what they're best at:
* **Media buying agents** discover inventory and execute campaigns
* **Creative agents** generate and adapt ads across formats
* **Signals agents** find and activate audiences
* **Governance agents** enforce brand safety and compliance
* **Orchestrators** coordinate the workflow and make sure humans approve what matters
These agents communicate over two transport protocols: **MCP** (for AI assistants calling tools) and **A2A** (for agent-to-agent collaboration). Same tasks, same schemas, different transport.
**How you know an agent does what it claims:** Every agent tells the network which broad areas it handles and which specific flows it supports — and those claims are testable. The protocol ships compliance storyboards that a runner executes against the agent. If it passes, the claim is verifiable. See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog).
## Brief to live ads
Here's what Alex's team does now:
1. **Write a brief**: "Find premium video inventory on sports publishers for Q2 with a \$50K budget"
2. **Agents discover options**: `get_products` goes to every connected seller simultaneously
3. **Compare proposals**: Products come back in a standard format — pricing, forecasts, targeting — all comparable
4. **Agents build creatives**: `build_creative` adapts assets to each seller's formats
5. **Approve and launch**: `create_media_buy` executes across platforms in one call
6. **Match at serve time**: TMP Context Match + Identity Match activate packages at each impression, with structural privacy separation
7. **Monitor delivery**: `get_media_buy_delivery` aggregates performance from every seller into one view
Each step uses a standard AdCP task with a JSON Schema-defined request and response. No platform-specific code. No manual translation between systems.
## Trust through governance
When AI agents spend money autonomously, trust requires structure. AdCP's governance layer provides it:
* **Before a campaign launches**: `check_governance` validates budget limits, brand safety, and regulatory compliance
* **If something exceeds authority**: The governance agent escalates to a human — your team approves, not the AI
* **While campaigns run**: Governance agents monitor delivery against approved parameters
* **After delivery**: `get_plan_audit_logs` provides a complete decision trail — who proposed what, who approved it, what actually ran
Governance isn't a gate that slows things down. It's the safety net that lets you give agents more autonomy over time.
## Where do you want to start?
> [card] [I want to buy on AI platforms](/dist/docs/3.2.8/sponsored-intelligence/monetizing-ai)
>
> For brands, agencies, and businesses who want to advertise on AI surfaces
> [card] [I want to build with AdCP](/dist/docs/3.2.8/building)
>
> For platforms, publishers, and developers implementing the protocol
## Get started
> [card] [Ask Addie](https://adcontextprotocol.org/chat)
>
> Ask questions about AdCP, explore the protocol, and test tasks — no code required
> [card] [Client SDKs](/dist/docs/3.2.8/building/schemas-and-sdks)
>
> JavaScript, Python, and Go libraries with CLI tools for testing
> [card] [Brand.json builder](https://agenticadvertising.org/brand/builder)
>
> Create and validate your brand's brand.json file
> [card] [AdAgents.json builder](https://agenticadvertising.org/adagents/builder)
>
> Validate or create your publisher's adagents.json file
> [card] [Registry](https://agenticadvertising.org/registry)
>
> Browse registered agents, brands, and publishers
> [card] [Building with AdCP](/dist/docs/3.2.8/building)
>
> Choose between MCP and A2A, learn implementation patterns
## See it in action
> [card] [Media buy](/dist/docs/3.2.8/media-buy)
>
> Follow Sam through a complete campaign — brief to delivery
> [card] [Trusted Match](/dist/docs/3.2.8/trusted-match)
>
> Real-time package activation with structural privacy separation
> [card] [Creative](/dist/docs/3.2.8/creative/index)
>
> Follow Maya through creative generation and distribution
> [card] [Governance](/dist/docs/3.2.8/governance/overview)
>
> Follow Jordan through the trust model that protects your spend
## For platform providers
AI is buying ads. Make sure it can buy yours.
If you operate a DSP, SSP, publisher, data platform, creative platform, governance service, or any ad tech solution, AdCP lets AI agents discover and transact with your platform. To get started:
1. **Implement an AdCP agent** — Expose your platform's capabilities as AdCP tasks over MCP or A2A. Start with `get_adcp_capabilities`.
2. **Publish discovery and authorization records** — Use `brand.json` for operator identity, agent endpoints, and signing-key discovery; use publisher `adagents.json` for properties and authorized agents.
3. **Test your implementation** — Validate with [Addie](https://adcontextprotocol.org/chat) or the [client SDKs](/dist/docs/3.2.8/building/schemas-and-sdks).
Implement the protocol domains relevant to your business:
* **Publishers and SSPs**: [Media Buy](/dist/docs/3.2.8/media-buy) and [adagents.json](/dist/docs/3.2.8/governance/property)
* **Data providers**: [Signals](/dist/docs/3.2.8/signals/overview) and [data provider guide](/dist/docs/3.2.8/signals/data-providers)
* **Creative platforms**: [Creative](/dist/docs/3.2.8/creative)
* **Governance vendors**: [Governance protocol](/dist/docs/3.2.8/governance/overview)
* **Brands**: [Brand Protocol](/dist/docs/3.2.8/brand-protocol) and [brand.json](/dist/docs/3.2.8/brand-protocol/brand-json)
## For advertisers and agencies
Run campaigns across more platforms without scaling your team.
AdCP-enabled agents work across all your media partners through a single interface — the same tasks buy CTV inventory, activate audience data, and manage creatives regardless of which platform you're working with.
1. **Read the buyer's guide** — The [monetizing AI guide](/dist/docs/3.2.8/sponsored-intelligence/monetizing-ai) explains how this works for brands, agencies, and SMBs.
2. **Check platform support** — See which of your media partners support AdCP, or browse the [registry](/dist/docs/3.2.8/registry).
3. **Try it with Addie** — [Ask Addie](https://adcontextprotocol.org/chat) to walk you through the protocol — no code required.
4. **Build your own agent** — No engineering team required. The [certification program](/dist/docs/3.2.8/learning/overview) teaches anyone to build a working advertising agent through vibe coding — describe what you want, an AI coding assistant writes the code.
5. **Connect with your team** — Share the [building guide](/dist/docs/3.2.8/building) and [client SDKs](/dist/docs/3.2.8/building/schemas-and-sdks) with your technical team to start integrating.
### Client libraries
```bash JavaScript/TypeScript theme={null}
npm install @adcp/sdk
```
```bash Python theme={null}
pip install adcp
```
```bash Go theme={null}
go get github.com/adcontextprotocol/adcp-go/adcp
```
* **NPM**: [@adcp/sdk](https://www.npmjs.com/package/@adcp/sdk) | [GitHub](https://github.com/adcontextprotocol/adcp-client)
* **PyPI**: [adcp](https://pypi.org/project/adcp/) | [GitHub](https://github.com/adcontextprotocol/adcp-client-python)
* **Go**: [adcp-go](https://github.com/adcontextprotocol/adcp-go)
## Open-source examples
The [Prebid Sales Agent](https://github.com/prebid/salesagent) is a full-stack seller agent (Python backend, TypeScript protocol layer) with GAM integration, built by a Prebid working group. It is a community example, not a maintained reference implementation. To build your own agent, start with the [official SDKs](/dist/docs/3.2.8/building/schemas-and-sdks) and [skill files](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent).
## Organization
AdCP is a project of [AgenticAdvertising.org](https://agenticadvertising.org), an industry organization of publishers, platforms, agencies, and technology providers advancing open standards for AI-powered advertising. Members join AgenticAdvertising.org to develop and adopt the protocol.
Foundation governance — structure, voting classes, Board composition, specification lifecycle, and conduct rules — is summarized in the repository's [CHARTER](https://github.com/adcontextprotocol/adcp/blob/main/CHARTER.md) and published at [agenticadvertising.org/governance](https://agenticadvertising.org/governance).
## Need help?
* Browse the documentation
* Ask in the [Slack community](/dist/docs/3.2.8/community/joining-slack)
* Email: [support@adcontextprotocol.org](mailto:support@adcontextprotocol.org)
# Protocol architecture
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/architecture
AdCP protocol architecture: identity layer (brand, registry, accounts), transaction domains (media buy, creative, signals, sponsored intelligence), and cross-cutting governance.
# Protocol architecture
AdCP operates at multiple layers, providing a clean separation between business roles, orchestration, and technical execution.
## Protocol domain map

### Identity layer
Three protocol domains establish who the parties are before any transaction occurs.
**Brand Protocol** defines organization identity through `brand.json` files hosted at `/.well-known/brand.json`. Buyers use it for advertiser identity and authorized operators; sellers use it for operator identity, sales-agent discovery, signing-key discovery, and property relationship declarations. Any domain can be resolved to a canonical brand identity. See [Brand Protocol](/dist/docs/3.2.8/brand-protocol).
**Registry** provides a public REST API for entity resolution and agent discovery. Resolve a brand domain, find which agents are authorized to sell a publisher's inventory, or discover agents by capability. See [Registry API](/dist/docs/3.2.8/registry).
**Accounts** establishes the commercial relationship between buyers and sellers. Every AdCP transaction happens within an account that defines billing terms, operator authorization, and usage reporting. Accounts are grounded in brand identity from the Brand Protocol. See [Accounts Protocol](/dist/docs/3.2.8/accounts/overview).
### Transaction domains
Four protocol domains handle core advertising operations. The [Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match) serves as the execution layer, connecting planning-time decisions to real-time activation through a four-phase lifecycle:
1. **Planning** — [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) and [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) establish packages, budgets, and targeting criteria.
2. **Execution** — TMP Context Match determines content fit; TMP Identity Match checks user eligibility. Both operations run at serve time with structural privacy separation.
3. **Engagement** — Sponsored Intelligence sessions deliver conversational brand experiences.
4. **Reporting** — [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) aggregates delivery data across sellers.
**Media Buy** covers inventory discovery (`get_products`), campaign creation (`create_media_buy`), and delivery reporting (`get_media_buy_delivery`). Publishers return structured media products with pricing, targeting options, and delivery forecasts. Buyers can request proposals — structured media plans that encode publisher expertise. See [Media Buy](/dist/docs/3.2.8/media-buy).
**Creative** handles canonical capability discovery ([`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities)), AI-powered creative generation ([`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative)), catalog synchronization ([`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs)), and creative delivery tracking. Creative agents resolve brand identity from the Brand Protocol to generate on-brand assets. See [Creative](/dist/docs/3.2.8/creative).
**Signals** enables audience and targeting data discovery ([`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals)) and activation ([`activate_signal`](/dist/docs/3.2.8/signals/tasks/activate_signal)). Data providers publish signal definitions that buyers can discover with natural language queries, then activate on decisioning platforms. See [Signals](/dist/docs/3.2.8/signals/overview).
**Sponsored Intelligence** defines conversational brand experiences in AI assistants. When a user expresses interest in a brand, the host initiates a consent-first session where the brand's agent engages conversationally with text, voice, UI components, or commerce handoffs. See [Sponsored Intelligence](/dist/docs/3.2.8/sponsored-intelligence/overview).
### Governance (cross-cutting)
**Governance** operates across all transaction domains. Governance agents manage property lists (curated sets of properties for targeting or exclusion), content standards (brand suitability policies), and creative governance (security scanning, content categorization). Governance data flows into media buy decisions, creative validation, and signal activation. See [Governance Protocol](/dist/docs/3.2.8/governance/overview).
Human-in-the-loop enters the protocol through two mechanisms: any mutation may be taken async for human review via the task lifecycle, and campaign governance provides a declarative buyer-side review channel via [`sync_plans`](/dist/docs/3.2.8/governance/campaign/tasks/sync_plans) and [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance). See [How human-in-the-loop enters the protocol](/dist/docs/3.2.8/governance/embedded-human-judgment#how-human-in-the-loop-enters-the-protocol). This is not a real-time protocol: operations may take minutes to days when human approval is required.
### Privacy posture across domains
AdCP's privacy posture is not uniform. TMP is the only domain that enforces privacy **structurally** — through separated code paths, schema-level prohibitions on combining identity with context, and independently verifiable decorrelation. Every other domain relies on **contractual confidentiality or per-session consent** — the parties exchanging data are bound by the account's terms or the user's consent, not by protocol-level separation. Governance gating (via campaign governance) is orthogonal: it can require human approval on budget, policy, or brand-safety grounds, but it does not change the privacy mechanism of the underlying domain.
| Domain | Privacy mechanism | Notes |
| - | - | - |
| Trusted Match Protocol | **Structural separation** | Context Match and Identity Match operate on separated code paths; schemas prohibit crossover. See [TMP privacy architecture](/dist/docs/3.2.8/trusted-match/privacy-architecture). |
| Media Buy | Contractual | Buyer and seller exchange full plan context under account terms. |
| Creative | Contractual | Creative assets and targeting signals pass through the creative agent under account terms. |
| Signals | Contractual | Audience and signal data exchanged under account terms and signal-provider agreements. |
| Brand / Registry / Accounts | Public or contractual | Brand identity is public (`brand.json`); commercial terms are account-scoped. |
| Sponsored Intelligence | Consent-first | The user consents per session; the brand agent sees conversation content, and identity only when the user shares it. Networks that route sessions may see routing metadata — see [Networks](/dist/docs/3.2.8/sponsored-intelligence/networks). |
| Governance | Contractual | Governance agents receive the context needed to evaluate policies under account terms. |
"Structural" means the protocol — not the operator's policy — prevents the combination of sensitive data. If you need that property outside TMP, build it yourself or compose with TMP.
***
## Ecosystem layers
The protocol domain map above shows how AdCP tasks relate to each other. The diagram below shows how these map to real-world roles and systems.

### Business parties
**Buy side** — advertisers, agencies, retail media networks, and curators packaging inventory and data for specific use cases.
**Media seller** — publishers, sales houses, rep firms, SSPs, and ad networks.
These parties exchange impressions and money through the orchestration layer.
### Orchestration layer
**Media orchestration platform** — evaluates sellers and audiences, executes buying strategies. Communicates with specialized agents via MCP.
**Signals agent** — MCP servers exposing audience and targeting data discovery and activation.
**Sales agent** — MCP servers exposing media product discovery and campaign execution.
**Creative agent** — MCP servers exposing format discovery and AI-powered creative generation.
### Technical execution
**Trusted Match Protocol (TMP)** — real-time execution layer that determines which pre-negotiated packages should activate for a given impression. Two structurally separated operations — Context Match (content fit) and Identity Match (user eligibility) — connect planning-time media buys to serve-time decisions across web, mobile, CTV, AI assistants, and retail media. See [TMP documentation](/dist/docs/3.2.8/trusted-match).
**Agentic eXecution Engine (AXE)** — deprecated predecessor to TMP. See [AXE documentation](/dist/docs/3.2.8/media-buy/advanced-topics/agentic-execution-engine).
**Decisioning platform** — the infrastructure that selects which ad to serve, via direct campaigns or programmatic (RTB). Examples include DSPs, SSPs, and ad servers.
### Governance and human oversight
**Governance agents** provide compliance and quality control across all layers: property lists, brand suitability scoring, quality measurement (MFA score, ad density), and privacy compliance (COPPA, TCF, GDPR). They operate at setup time, real-time, and post-bid.
**Human-in-the-loop** — manual approval at decision points. See [How human-in-the-loop enters the protocol](/dist/docs/3.2.8/governance/embedded-human-judgment#how-human-in-the-loop-enters-the-protocol).
***
## State persistence and horizontal scaling
AdCP is a multi-instance protocol. A single buyer's workflow with an agent may be routed across multiple backend replicas — [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) may land on one replica, the subsequent `get_media_buy` on another — and both calls MUST see the same state.
### Normative requirements
State keyed by a `(brand, account)` tuple MUST survive across agent process instances. This includes but is not limited to accounts, catalogs, creatives, audiences, event sources, governance configuration, active campaigns, proposals, insertion-order approval records, signal activations, sponsored-intelligence sessions, async task records, and idempotency-key cache entries. Implementations MUST NOT use in-process memory as the primary store for any `(brand, account)`-scoped state that a subsequent call can read back. In-process storage does not satisfy this requirement. For the canonical (non-exhaustive) catalog of state domains, see [Account state](/dist/docs/3.2.8/building/by-layer/L2/account-state).
**Acceptable storage:** Postgres, Redis, DynamoDB, or any shared store that persists across process restarts and is reachable from every replica. **Not acceptable:** module-level variables, per-process Maps or dicts, single-node file storage, or sticky-session routing that masks the absence of shared state.
Within a single `(brand, account)` context, implementations MUST support read-your-writes across replicas: after a successful non-async response, a subsequent request routed to any replica MUST observe the write. Async/pending task state (status transitions, task records, push-notification subscriptions) is itself subject to this rule — once a task record is created, it MUST be readable from any replica. Eventual consistency is acceptable when the staleness window is bounded and disclosed — either capped at the implementation's documented async polling interval, or declared explicitly in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities).
**Sandbox exemption.** Sandbox accounts are allowed to carry ephemeral state that does not persist across process restarts (see [Sandbox mode](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox)). Within a single sandbox session, read-your-writes across replicas still applies.
Implementations may prove this invariant by architecture (managed serverless + shared datastore), by multi-instance compliance testing, or by their own verification; the protocol cares about the invariant, not the methodology. See [Validate your agent — Verifying cross-instance state](/dist/docs/3.2.8/building/verification/validate-your-agent#verifying-cross-instance-state).
# Calling an AdCP agent
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/calling-an-agent
Wire-level invariants every AdCP buyer must follow: mutation idempotency replay, account oneOf variants, async status:'submitted' polling, and error recovery from adcp_error.issues[].
# Calling an AdCP agent
This page is the canonical buyer-side wire contract: the rules that don't live cleanly in any single task schema, but apply to every mutating call you'll make. If you're building a buyer (DSP, planning tool, agentic client) and calling out to AdCP sales, creative, signals, governance, SI, or brand agents, read this once.
The agent-facing version of this content lives at [`skills/call-adcp-agent/SKILL.md`](https://github.com/adcontextprotocol/adcp/blob/main/skills/call-adcp-agent/SKILL.md) — bundled into the [protocol tarball](/dist/docs/3.2.8/building/by-layer/L0/schemas#one-shot-protocol-bundle) so SDKs can ship it to coding agents.
## Discovery chain
Walk these in order on first contact with any new agent:
1. **Agent card** (A2A) or **`tools/list`** (MCP): returns the tools selected for this endpoint or session. An AdCP 3.2 MCP server includes each selected tool's self-contained `inputSchema`; it does not load the complete AdCP catalog or its response schemas into model context. Treat the live names as the authority for what can be called.
2. **[`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities)**: returns supported protocols, AdCP major versions, and feature flags. Tells you *which* tools this agent supports, not how to call them. See [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities).
3. **[`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal)** *(when advertised)*: declares this authenticated caller's durable connection resources, such as agent-level webhooks and reusable reporting destinations. This is caller state, not capability discovery and not advertiser-account authorization.
4. **`get_schema(tool_name)`** *(when the agent exposes it — pending standardization, see [#3057](https://github.com/adcontextprotocol/adcp/issues/3057))*: returns the JSON Schema for a specific tool's request/response.
5. **Bundled schemas** (offline, authoritative): every published AdCP version ships JSON Schemas for every tool, signed via Sigstore. The path differs by SDK — the spec repo source uses `dist/schemas//bundled/`, `@adcp/sdk` puts them at `schemas/cache//bundled/` after `npm run sync-schemas`, Python and Go SDKs use their own conventions. Don't hardcode a path; let the SDK's loader find them. Once located, each schema lives at `/-{request,response}.json`.
## Idempotency: replay vs. new operation
Every mutating tool with a key-required request schema requires an `idempotency_key` (UUID). The published 3.x [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) compatibility facade is the exception: its key remains optional on every arm. Pure-read wrappers must tolerate an optional key, but the seller may ignore it and execute a fresh read; callers cannot rely on read-response replay unless the seller documents that stronger behavior.
For a key-required mutation, or an optional-key operation that the seller documents as replay-protected:
* **Same key on retry** → server replays the **same response**, byte-for-byte. Use this for transport-level retries (timeout, 5xx, dropped connection).
* **Fresh key** → **new operation**, regardless of body. Generating a new UUID because the previous attempt failed is the most common way naïve callers create duplicate media buys.
* **Same key, different canonical body** → [`IDEMPOTENCY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-conflict). Sellers MUST reject (rule 5 in [security.mdx#idempotency](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency)) — do not silently apply the second body, do not silently replay the first response.
* **Same key while first request still running** → [`IDEMPOTENCY_IN_FLIGHT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-in-flight) (rule 9 in [security.mdx#idempotency](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency)). The seller MAY return this code with top-level `error.retry_after` instead of blocking. Wait and retry with the **same key** — minting a fresh key on this code turns a safe retry into a double-execution race.
For async flows, the replayed response carries the **same `task_id`** so polling continues against the same task instead of forking.
The compact 3.2 lifecycle requires `idempotency_key` on [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals), [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals), [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals), [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products), [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal), and [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy). [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) remains a synchronous key-optional read. The legacy 3.x [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) facade keeps the key optional on every arm for wire compatibility. A seller may ignore it on a guaranteed side-effect-free synchronous read. Buyers should supply it whenever the request may allocate a task or change observable state. When supplied and the seller declares `adcp.idempotency.supported: true`, the seller must establish replay protection before the effect. If the key is omitted or the seller declares `adcp.idempotency.supported: false`, the buyer cannot safely retry an ambiguous result with a portable at-most-once guarantee.
`idempotency_key` is required on: [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy), [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy), [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives), [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences), [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts), [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal), [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs), [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs), [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources), [`sync_plans`](/dist/docs/3.2.8/governance/campaign/tasks/sync_plans), [`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance), [`activate_signal`](/dist/docs/3.2.8/signals/tasks/activate_signal), [`acquire_rights`](/dist/docs/3.2.8/brand-protocol/tasks/acquire_rights), [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event), [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage), [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback), [`report_plan_outcome`](/dist/docs/3.2.8/governance/campaign/tasks/report_plan_outcome), [`create_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#create_property_list), [`update_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#update_property_list), [`delete_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#delete_property_list), [`create_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#create_collection_list), [`update_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#update_collection_list), [`delete_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#delete_collection_list), [`create_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/create_content_standards), [`update_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/update_content_standards), [`calibrate_content`](/dist/docs/3.2.8/governance/content-standards/tasks/calibrate_content), [`si_initiate_session`](/dist/docs/3.2.8/sponsored-intelligence/tasks/si_initiate_session), [`si_send_message`](/dist/docs/3.2.8/sponsored-intelligence/tasks/si_send_message).
Although its name resembles a read, [`get_creative_features`](/dist/docs/3.2.8/governance/creative/get_creative_features) may allocate provider work and create consumption or cost records. Its key remains optional in 3.x for wire compatibility, but clients SHOULD supply one for every logical evaluation; providers advertising replay support MUST honor a supplied key for at least 24 hours. The key becomes required in AdCP 4.0.
For the key-required operations listed above, a missing key produces `adcp_error.code: 'VALIDATION_ERROR'` with `/idempotency_key` in `issues`.
## `account` is `oneOf` — pick exactly one variant
`account` is a discriminated union. On [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy), two variants:
```json theme={null}
// variant 0: by seller-assigned id (from list_accounts or out-of-band onboarding;
// buyer-declared sellers may also echo account_id from sync_accounts as an internal handle)
"account": { "account_id": "seller_assigned_id" }
// variant 1: by advertiser natural key
// (brand + operator, optional operator_unit/currency/timezone/sandbox;
// brand may include commercial-identity countries[])
// brand.domain — the buyer's brand domain (e.g., advertiser website)
// operator — the buyer-side entity operating on behalf of the brand
"account": { "brand": { "domain": "acme.com" }, "operator": "pinnacle-media.com" }
```
**Do NOT merge required fields across variants.** `additionalProperties: false` on each variant means `{account_id, brand}` fails BOTH.
When a task schema requires `account`, send an explicit `AccountRef` even if the SDK auto-selected the only account available to the authenticated credential. Hidden credential-implied defaulting is not a protocol model. When a task marks `account` optional, omission has only the semantics documented by that task.
Other tools (e.g. [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives)) may accept a superset — always check the specific tool's schema.
## Async responses: `status: 'submitted'` means queued
A mutating tool can return one of three shapes:
```json theme={null}
// Success (sync): the work is done
{ "media_buy_id": "mb_123", "packages": [...], "confirmed_at": "..." }
// Submitted (async): the work is queued
{ "status": "submitted", "task_id": "tk_abc", "message": "Awaiting IO signature" }
// Error: don't retry without fixing
{ "errors": [{ "code": "PRODUCT_NOT_FOUND", "message": "..." }] }
```
AdCP task state is an **application-layer** contract. MCP and A2A may wrap, stream, or transport an AdCP response, but their native task mechanisms do not replace the AdCP `task_id`, status values, webhook payloads, or polling/reconciliation surfaces. A transport task can complete after delivering an AdCP response whose payload still says `status: 'submitted'`.
When you see `status: 'submitted'`, the work is **not** complete. Under the [AdCP A2A Profile Extension v3](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension), the caller MUST poll by sending fresh structured invocations of [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) with the returned AdCP `task_id`. The enclosing A2A Task is already completed and MUST NOT be polled as a proxy for the AdCP operation. MCP implementations may continue to expose the legacy AdCP `tasks/get` surface; both AdCP polling names use the same snake_case payload shape, including the optional `account` scope for multi-account credentials.
Pass `include_result: true` when polling so the seller includes the completion payload once status transitions to `completed`:
```json theme={null}
// get_task_status request
{
"task_id": "task_456",
"include_result": true,
"account": {
"brand": { "domain": "acmeoutdoor.example" },
"operator": "pinnacle-agency.example",
"sandbox": true
}
}
// get_task_status response — completed
{
"task_id": "task_456",
"task_type": "create_media_buy",
"protocol": "media-buy",
"status": "completed",
"completed_at": "2025-01-22T10:30:00Z",
"result": {
"media_buy_id": "mb_12345",
"packages": [{ "package_id": "pkg_001" }]
}
}
```
The `result` field uses the same payload structure as the push-notification webhook `result` field for completed tasks — buyers who configure both polling and webhooks receive the same data shape either way.
## Error recovery — read `issues[]`
Every validation failure produces an envelope shaped like:
```json theme={null}
{
"adcp_error": {
"code": "VALIDATION_ERROR",
"recovery": "correctable",
"field": "/first/offending/pointer",
"issues": [
{
"pointer": "/account",
"keyword": "oneOf",
"message": "must match exactly one schema in oneOf",
"variants": [
{ "index": 0, "required": ["account_id"], "properties": ["account_id"] },
{ "index": 1, "required": ["brand", "operator"], "properties": ["brand", "operator", "sandbox"] }
]
},
{ "pointer": "/brand/domain", "keyword": "required", "message": "must have required property 'domain'" }
]
}
}
```
* `issues[].pointer` — RFC 6901 JSON Pointer to the offending field
* `issues[].keyword` — Ajv keyword (`required`, `type`, `oneOf`, `anyOf`, `additionalProperties`, `format`, `enum`)
* `issues[].variants` — when `keyword` is `oneOf` or `anyOf`, each entry lists one variant's `required` + declared `properties`
**For `oneOf` failures, pick ONE variant from `variants[]` and send only its `required` fields.** This is the fastest recovery path when you didn't know the field was a union.
`recovery` values:
* `correctable` — buyer-side fix; read `issues[]`, patch the pointers, resend
* `transient` — retry with the **same** `idempotency_key`
* `terminal` — requires human action (account suspended, payment required); do not retry
## Common shape pitfalls
| Symptom | What it means | Fix |
| - | - | - |
| `keyword: 'oneOf'` with `variants[]` | Discriminated union — you sent fields from multiple variants, or none | Pick ONE variant from `variants[]`. Send only its `required` fields. |
| 2-3 `additionalProperties` errors at the same pointer | You merged `oneOf` variants | Drop to one variant. Don't keep "extra" fields "for completeness". |
| `keyword: 'required'`, `pointer: '/idempotency_key'` | Mutating tool, no UUID | Generate fresh UUID per logical operation. Reuse on retries. |
| `keyword: 'type'` or `additionalProperties` at `/budget` | Sent `{amount, currency}` | `budget` is a number. Currency is implied by `pricing_option_id`. |
| `enum` at `/format_kind` | Sent a non-canonical format kind | Choose a registered canonical kind or use a valid `custom` declaration. |
| `keyword: 'enum'` at `/destinations/*/type` | Made-up destination type | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`). |
| Response carries `status: 'submitted'` and `task_id` | Async — work is queued, NOT done | On the AdCP v3 A2A profile, invoke [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json). On MCP, use the advertised AdCP polling task. |
## Transport notes
* **MCP**: `tools/call` with `{ name: 'tool_name', arguments: {...} }`. Read `structuredContent` for the typed response.
* **A2A 1.0**: advertise and activate `https://adcontextprotocol.org/extensions/adcp/v3`, then Send Message with exactly one invocation DataPart shaped `{ skill: 'tool_name', input: {...} }`; optional TextParts are advisory. Read the authoritative response DataPart from the completed Task artifact.
Both transports share idempotency, error shape, schema enforcement, and handler semantics. If a call works on one, the equivalent call works on the other.
A common trap: **A2A `Task.status.state: 'completed'` is not the same as AdCP completion.** A2A task state describes the transport invocation; AdCP-level completion is in the artifact DataPart. A `completed` A2A task can carry a `submitted` AdCP response, whose `task_id` remains only in that DataPart and is polled through [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json). It also carries structured business outcomes that are not transport failures, such as `GetProductsRejected`: A2A remains `completed`, while the artifact payload contains `status: "rejected"`, `reason`, and optional `suggestions[]`.
## Related
* Per-task request/response shapes: see the protocol-specific reference (`/docs/media-buy/`, `/docs/creative/`, `/docs/signals/`, etc.).
* [Protocol architecture](/dist/docs/3.2.8/protocol/architecture) — how the protocol domains fit together.
* [Required tasks](/dist/docs/3.2.8/protocol/required-tasks) — which tasks an agent must implement to claim a specialism.
* [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) — first call against any new agent.
* [Schemas](/dist/docs/3.2.8/building/by-layer/L0/schemas) — how SDKs consume the protocol tarball (which now bundles `skills/`).
* [Build a caller](/dist/docs/3.2.8/building/by-layer/L4/build-a-caller) — build-shaped guide for the caller side: install, call, handle responses, ingest reporting.
# Capabilities explorer
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/capabilities-explorer
Browsable view of the get_adcp_capabilities response schema — every top-level domain, every sub-namespace, with anchors and 'propose extension here' links so new flags land in the right home.
# Capabilities explorer
This page renders the actual top-level shape of the [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) response so you can find the right place for a new capability before you propose it. The most common reason an extension RFC gets bounced is wrong-shape: the proposal puts a flag at a level that doesn't match where similar flags already live. Walk the tree first.
If you're here to draft an RFC, the workflow is:
1. Find the closest existing top-level domain for your flag below.
2. Drill into that domain's sub-namespaces (`features`, `execution`, etc.).
3. If your flag fits an existing sub-namespace, propose it there. Use the **propose extension here** link at the relevant node — it pre-fills the issue title with the path.
4. If nothing fits, scroll to **Before proposing a new top-level key** at the bottom and answer the gate questions in your RFC body.
The authoritative schema lives at [`static/schemas/source/protocol/get-adcp-capabilities-response.json`](https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/source/protocol/get-adcp-capabilities-response.json). The tree below is curated to one level deep for the rich domains; for the full nested shape, read the schema. See also [Design principles — capabilities are commitments, declared under existing buckets](/dist/docs/3.2.8/protocol/design-principles#4-capabilities-are-commitments-declared-under-existing-buckets).
***
## Top-level domains
The 14 domains below are the entire top-level surface of [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). Every capability flag eventually nests under one of these. New top-level keys are extremely rare and should not be the first move — see the gate questions at the end of this page.
### `adcp` — core protocol identity
Version negotiation, idempotency contract, build identifier.
* **`supported_versions`** — release-precision strings (e.g. `"3.0"`, `"3.1"`). Authoritative for buyer-side release pinning.
* **`major_versions`** — DEPRECATED in favor of `supported_versions`; sellers MUST keep emitting through 3.x.
* **`build_version`** — full semver build identifier; advisory metadata for buyer-side incident triage.
* **`idempotency`** — discriminated union (`IdempotencySupported` / `IdempotencyUnsupported`) declaring replay semantics. **A declaration here is a commitment** — sellers that declare `supported: true` are probed by the conformance runner.
* **`capability_changes`** — freshness metadata and optional `capabilities.changed` invalidation webhooks for cached capability documents.
[Propose an extension to `adcp`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+adcp+capability:+%3Cflag%3E\&body=Schema+location:+%60.adcp%60%0AExisting+keys:+supported_versions,+major_versions,+build_version,+idempotency%0A%0A%23%23+Proposal%0A%0A...%0A%0A%23%23+Why+this+belongs+under+%60adcp%60+and+not+a+new+top-level+key%0A%0A...\&labels=rfc,capabilities)
***
### `supported_protocols` — which AdCP protocols this agent implements
Array of protocol names. Each value commits the agent to (a) implement those tools and (b) pass the baseline compliance storyboard at `/compliance/{version}/protocols/{protocol}/`.
Valid values cover `media_buy`, `creative`, `signals`, `governance`, `sponsored_intelligence`, `brand`, `accounts`, `measurement` (in development).
[Propose a new protocol to add to `supported_protocols`](https://github.com/adcontextprotocol/adcp/issues/new?title=Add+protocol+to+supported_protocols:+%3Cname%3E\&body=%23%23+Proposal%0A%0A...%0A%0A%23%23+Compliance+storyboard+plan%0A%0AHow+will+the+baseline+conformance+suite+exercise+this+protocol?+...\&labels=rfc,capabilities,new-protocol)
***
### `account` — account establishment and billing
How accounts are negotiated; whether one is required before product discovery; what billing models are supported.
* **`required_for_products`** — boolean. If true, [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) requires an established account.
* **`authorization_endpoint`** — OAuth/auth URL for account negotiation.
* **`require_operator_auth`** — declares whether operator-level authentication is required.
* **`supported_billing`** — invoiced parties the seller supports (`operator`, `agent`, `advertiser`).
* **`supported_account_currency_modes`** — whether advertiser accounts use an immutable `fixed` currency, `per_media_buy` currency, or both. Required for 3.2 advertiser-account provisioning; older 3.x sellers may omit it, which means the mode is not discoverable.
* **`timezone`** — whether every account uses one seller-fixed timezone or each account carries an immutable seller-assigned/buyer-selected timezone. Feature capabilities explicitly declare when reporting, billing, or daily-cap clocks differ.
* **`account_financials`** — what financial data the seller exposes (credit limits, current balance, etc.).
* **`sandbox`** — sandbox-account capabilities.
[Propose an extension to `account`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+account+capability:+%3Cflag%3E\&body=Schema+location:+%60.account%60\&labels=rfc,capabilities)
***
### `media_buy` — media buying capabilities
The largest domain. Sub-namespaces are where most media-buying flags belong.
* **`features`** — boolean feature flags (e.g. `inline_creative_management`, `property_list_filtering`, `catalog_management`, `committed_metrics_supported`). **Most new media-buy capability flags belong here.**
* **`execution`** — technical execution capabilities. Contains `trusted_match` (TMP), `creative_specs` (VAST/MRAID/VPAID/SIMID versions), `targeting` (geo / audience / device / temporal), `axe_integrations` (deprecated). See note in [Design principles — Where the surface doesn't yet follow these](/dist/docs/3.2.8/protocol/design-principles#where-the-surface-doesnt-yet-follow-these-principles) about the `trusted_match` placement.
* **`audience_targeting`** — declared audience-targeting capabilities.
* **`content_standards`** — content-standards enforcement capabilities.
* **`conversion_tracking`** — conversion-tracking capabilities.
* **`offline_delivery_protocols`** — supported offline delivery protocols (broadcast trafficking, etc.).
* **`portfolio`** — portfolio-management capabilities.
* **`reporting_delivery_methods`** — how reporting is delivered.
* **`supported_pricing_models`** — array (CPM, CPC, CPCV, CPP, revenue share, flat rate, etc.).
[Propose a flag for `media_buy.features`](https://github.com/adcontextprotocol/adcp/issues/new?title=Add+media_buy+feature:+%3Cflag%3E\&body=Schema+location:+%60.media_buy.features%60%0A%0A%23%23+Proposal%0A%0A...%0A%0A%23%23+Why+a+feature+flag+and+not+a+new+task%0A%0A...%0A%0A%23%23+Conformance+probe%0A%0AHow+can+a+buyer+verify+this+capability+is+actually+honored?+...\&labels=rfc,capabilities)
[Propose an extension to `media_buy.execution`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+media_buy.execution:+%3Cflag%3E\&body=Schema+location:+%60.media_buy.execution%60%0AExisting+sub-keys:+trusted_match,+creative_specs,+targeting\&labels=rfc,capabilities)
***
### `signals` — audience and contextual data activation
Authorization scope and feature flags for the signals domain.
* **`data_provider_domains`** — array of domains this signals agent is authorized to resell. Buyers fetch each provider's `adagents.json` to verify.
* **`features`** — boolean feature flags. `catalog_signals` is deprecated; structured `signal_ref` support is part of the Signals protocol and should not require a feature flag. **Additional signals capability flags belong here**, not in a new top-level key. (E.g., a `signal_enforcement_on_guaranteed` flag for direct-sold targeting belongs at `signals.features`, not under `media_buy.execution.trusted_match`.)
[Propose a flag for `signals.features`](https://github.com/adcontextprotocol/adcp/issues/new?title=Add+signals+feature:+%3Cflag%3E\&body=Schema+location:+%60.signals.features%60%0A%0A%23%23+Proposal%0A%0A...%0A%0A%23%23+Conformance+probe%0A%0A...\&labels=rfc,capabilities,signals)
***
### `governance` — governance protocol capabilities
Property and creative governance capabilities.
* **`property_features`** — what the governance agent does with property lists.
* **`creative_features`** — what the governance agent does for creative review.
* **`aggregation_window_days`** — how long the agent aggregates governance events.
[Propose an extension to `governance`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+governance+capability:+%3Cflag%3E\&body=Schema+location:+%60.governance%60\&labels=rfc,capabilities,governance)
***
### `sponsored_intelligence` — conversational brand experiences
For agents that handle SI sessions.
* **`endpoint`** — SI endpoint URL.
* **`brand_url`** — brand identity URL.
* **`capabilities`** — SI-specific capabilities (commerce handoff, voice, UI components, etc.).
[Propose an extension to `sponsored_intelligence`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+sponsored_intelligence+capability:+%3Cflag%3E\&body=Schema+location:+%60.sponsored_intelligence%60\&labels=rfc,capabilities)
***
### `brand` — brand protocol capabilities
For brand agents.
* **`description`** — agent description.
* **`available_uses`** — what the brand data is licensed for.
* **`generation_providers`** — supported generation providers.
* **`right_types`** — right types the agent grants.
* **`rights`** — concrete rights this agent issues.
[Propose an extension to `brand`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+brand+capability:+%3Cflag%3E\&body=Schema+location:+%60.brand%60\&labels=rfc,capabilities)
***
### `creative` — creative protocol capabilities
For creative agents.
* **`has_creative_library`** — whether the agent maintains a creative library.
* **`supports_compliance`** — creative compliance scanning.
* **`supports_generation`** — generative-creative capabilities.
* **`supports_transformation`** — creative transformation capabilities.
[Propose an extension to `creative`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+creative+capability:+%3Cflag%3E\&body=Schema+location:+%60.creative%60\&labels=rfc,capabilities,creative)
***
### `request_signing` — RFC 9421 HTTP Signatures for incoming requests
Signing remains optional through 3.2 and capability-advertised so counterparties can opt in selectively. A 3.2 agent that advertises support must use the body-bound profile.
* **`supported`** — boolean.
* **`required_for`** — array of operations where signing is required.
* **`supported_for`** — array of operations where signing is supported.
* **`warn_for`** — array of operations where unsigned requests produce warnings.
* **`covers_content_digest`** — MUST be `required` for a 3.2 signing profile. The legacy `either` and `forbidden` values are accepted only when negotiating with a 3.0/3.1 endpoint.
[Propose an extension to `request_signing`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+request_signing+capability:+%3Cflag%3E\&body=Schema+location:+%60.request_signing%60\&labels=rfc,capabilities,security)
***
### `webhook_signing` — RFC 9421 signing for outbound webhooks
Top-level peer of `request_signing`.
* **`supported`** — boolean.
* **`profile`** — signing profile name.
* **`algorithms`** — supported signature algorithms.
* **`legacy_hmac_fallback`** — whether HMAC fallback is supported for legacy receivers.
* **`delivery_retry_horizon_seconds`** — maximum retry horizon from the first webhook delivery attempt; receivers retain delivery and publication proof for at least this long.
[Propose an extension to `webhook_signing`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+webhook_signing+capability:+%3Cflag%3E\&body=Schema+location:+%60.webhook_signing%60\&labels=rfc,capabilities,security)
***
### `identity` — operator identity posture
Key-scoping and compromise-response controls. Advisory in 3.x; required in 4.0.
* **`per_principal_key_isolation`** — whether each principal has an isolated key.
* **`key_origins`** — declared key-management origins.
* **`compromise_notification`** — notification posture for key compromise events.
[Propose an extension to `identity`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+identity+capability:+%3Cflag%3E\&body=Schema+location:+%60.identity%60\&labels=rfc,capabilities,security)
***
### `measurement` — measurement capabilities (in development)
Quantitative metrics about ad delivery, exposure, or effectiveness.
* **`metrics`** — array of metric definitions this agent emits.
The protocol surface beyond capabilities discovery (reporting, attribution tasks) lands in subsequent minors.
[Propose an extension to `measurement`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+measurement+capability:+%3Cflag%3E\&body=Schema+location:+%60.measurement%60\&labels=rfc,capabilities,measurement)
***
### `compliance_testing` — deterministic test scenarios
Declares the agent supports [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) and which scenarios are honored.
* **`scenarios`** — array of compliance scenario IDs the agent supports.
[Propose an extension to `compliance_testing`](https://github.com/adcontextprotocol/adcp/issues/new?title=Extend+compliance_testing+capability:+%3Cflag%3E\&body=Schema+location:+%60.compliance_testing%60\&labels=rfc,capabilities,compliance)
***
### `specialisms` — kebab-case specialty IDs
Optional. Specialty compliance claims (e.g., `creative-generative`, `sales-non-guaranteed`). Values are kebab-case enum IDs registered with the working group.
[Propose a new specialism](https://github.com/adcontextprotocol/adcp/issues/new?title=Add+specialism:+%3Ckebab-case-id%3E\&body=%23%23+Specialism+ID%0A%0A%3Ckebab-case-id%3E%0A%0A%23%23+What+it+claims%0A%0A...%0A%0A%23%23+Conformance+criteria%0A%0AHow+do+we+verify+an+agent+actually+meets+this+claim?+...\&labels=rfc,capabilities,specialism)
***
## Things-this-agent-does that aren't a domain
Three top-level lists carry capability metadata that doesn't fit a single protocol domain. The shape inconsistency between them is on the open list ([Design principles — Where the surface doesn't yet follow these](/dist/docs/3.2.8/protocol/design-principles#where-the-surface-doesnt-yet-follow-these-principles)).
* **`extensions_supported`** — array of extension namespaces this agent populates (`ext.{namespace}`).
* **`experimental_features`** — array of experimental surface IDs this agent implements (e.g. `trusted_match.core`).
* **`compliance_testing`** — covered above.
***
## Before proposing a new top-level key
If your flag genuinely doesn't fit any of the 14 domains above, open the RFC — but answer these gate questions in the body. Most reviewers expect them. RFCs that ignore them tend to bounce.
1. **Which existing top-level domain is closest?** Name it. Explain why your flag *isn't* an extension to that domain's `features`, `execution`, or other sub-namespaces.
2. **Why isn't this an `ext.{vendor}` extension?** Vendor-specific behavior belongs in vendor namespaces ([spec-guidelines on platform agnosticism](/dist/docs/3.2.8/spec-guidelines#platform-agnosticism)). Why is your flag normative across all implementers?
3. **What's the conformance probe?** A capability declaration is a commitment, not an advertisement. How does the conformance runner verify a seller that declares your flag actually honors it?
4. **What does this rule out?** What proposals does adding this top-level key make easier — and what does it make harder for someone scanning the top level a year from now?
These are the same questions reviewers will ask. Answering them in the RFC saves a round-trip.
[Propose a new top-level capability key (use only after answering the gate questions)](https://github.com/adcontextprotocol/adcp/issues/new?title=Propose+new+top-level+capability+key:+%3Cname%3E\&body=%23%23+Proposed+top-level+key%0A%0A%3Cname%3E%0A%0A%23%23+Gate+questions%0A%0A**1.+Which+existing+top-level+domain+is+closest+and+why+isn%27t+this+an+extension+there?**%0A%0A...%0A%0A**2.+Why+isn%27t+this+an+%60ext.%7Bvendor%7D%60+extension?**%0A%0A...%0A%0A**3.+What%27s+the+conformance+probe?**%0A%0A...%0A%0A**4.+What+does+this+rule+out?**%0A%0A...\&labels=rfc,capabilities,new-top-level-key)
***
## Related
* [Design principles](/dist/docs/3.2.8/protocol/design-principles) — the reasoning behind the capability surface shape.
* [`get_adcp_capabilities` task reference](/dist/docs/3.2.8/protocol/get_adcp_capabilities) — the response schema as documented per-field.
* [Specification Guidelines](/dist/docs/3.2.8/spec-guidelines) — type naming, enum design, vendor-neutral rule.
# How AdCP is designed
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/design-principles
The load-bearing principles behind AdCP's design — what they rule out, when you'd be right to push back, and where the surface doesn't yet follow them.
# How AdCP is designed
You don't need to read this page to use AdCP. You do need to read it to extend it.
This is the meta-protocol — the philosophical framework behind the calls we made. Each principle is a load-bearing decision that shows up the moment someone proposes "just add this one field." We've made these calls deliberately, and we revisit them deliberately. The goal here is to give contributors enough context to either propose something that fits the existing shape or to argue, with both feet on the ground, for changing the shape itself.
Two principles bounce most RFCs that reach the working group: **the schema is the spec** and **compose before adding a task**. They sit first because they're load-bearing for the rest. Six supporting principles follow. A "where the surface doesn't yet follow these" section at the end names the contradictions we know about — the principles are credible only to the extent that we're honest about them.
Each principle has the same structure: the rule, why we chose it, what it rules out, and the exception path — when pushing back on the principle is the right move.
***
## Enterprise objective
AdCP is designed to become the protocol that can coordinate a trillion-dollar
global advertising economy. Spend-committing systems need deterministic
identity, authorization, commercial state, concurrency, retries, audit, and
recovery. A protocol can hide those problems in prose or proprietary platform
behavior, but it cannot make them disappear.
The design goal is therefore **robustness with concentrated complexity**:
normative schemas and conformance assets define the hard edges; maintained
[SDKs](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk) implement them once for many
adopters; and application teams focus on pricing, planning, creative, policy,
and operations. Raw-wire implementation remains open, but a production
implementation is an enterprise systems commitment, not a casual JSON
integration.
This objective is not permission for accidental complexity. Every task is a
permanent ecosystem coordination cost. Every field still has to earn its place,
and the principles below deliberately reject additions that do not create a
necessary interoperable guarantee.
***
## The two principles that bounce most RFCs
### 1. The schema is the spec
Documentation describes; schemas decide. When documentation and schemas diverge, schemas win. A proposal that extends a field or task that does not exist in the schema is making two claims at once — that a thing exists, and that it should grow — and reviewers will bounce it on the first claim alone.
**Why we chose it.** Generated SDKs come from schemas, conformance tests come from schemas, the registry comes from schemas. A doc page can lag for a release and the protocol still works; a schema change ships everywhere. The schema is also the only place we can enforce the cross-language guarantees AdCP claims (TypeScript, Python, Go all generate cleanly from one source). See [Specification Guidelines — Philosophy](/dist/docs/3.2.8/spec-guidelines#philosophy) for the canonical version of this rule.
**What this rules out.** Proposing a `direct_sold_signals` flag inside a `trusted_match` capability object in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) when the schema's actual top-level keys are `adcp`, `supported_protocols`, `account`, `media_buy`, `signals`, `governance`, `sponsored_intelligence`, `brand`, `creative`, `request_signing`, `webhook_signing`, `identity`, `compliance_testing`, and `specialisms`. There is no `trusted_match` top-level key — and the right shape for the proposed flag is `signals.features.signal_enforcement_on_guaranteed`, not a new bucket. Reviewers bounce the issue on the wrong-shape premise alone, before evaluating the underlying idea — which may be perfectly good.
**When you'd be right to push.** When the schema genuinely lacks a place to put your proposal. State that as the first claim, propose the new schema location with a path, and then propose the field. Two clear claims beat one fuzzy one.
→ Use the [Capabilities explorer](/dist/docs/3.2.8/protocol/capabilities-explorer) before proposing a new flag. It walks the actual schema tree.
***
### 2. Compose with existing primitives before adding a new task
Every new top-level task is a permanent surface every implementer eventually has to reason about, even the ones who don't use it. Before proposing one, the question to answer is: can this be expressed via the existing tasks plus their existing modes? If yes, the proposal is a documentation gap (or a missing field) — not a new task.
**Why we chose it.** Tasks are the protocol's coordination cost. Adding a task is the most expensive thing a contributor can ask for, because it lands on every sales agent, every buyer agent, every SDK, every test suite, every conformance row. Fields and modes compose; tasks don't. A protocol that grows by adding tasks every release ages into something only its authors can hold in their head.
**What this rules out.** Proposing a `get_price_quote` task between discovery
and commitment. The 3.2 lifecycle already distinguishes the two cases: a
published offer carries versioned pricing from [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) into
[`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products); seller-specific pricing or configuration moves through
[`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals), typed [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals), a committed hold, and
[`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal). A quote task would duplicate an existing commercial state
transition without adding a new counterparty role.
**When you'd be right to push.** When no composition reaches the desired semantics — when the proposal demands a state transition or a counterparty role no existing task can carry. The bar is high and that's intentional. Bring evidence: which existing task you tried to extend, why the extension didn't work, what the new task adds that an extension can't.
***
## Six supporting principles
### 3. Discovery and planning are distinct; targeting is an input to both
Targeting is what the buyer wants delivered. It is not a downstream filter on
a generic result. A buyer reading published offers sends structured criteria to
[`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products). A buyer asking
the seller to plan sends a brief plus the same structured criteria to
[`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals). In both
paths the returned product, price, forecast, and targeting resolution describe
the executable result.
Wholesale synchronization belongs to the published-offer path: feed versions
and account-level product webhooks keep a mirror current. Proposal negotiation
is a separate immutable-snapshot lifecycle. Treating wholesale as a planning
mode conflates catalog topology with commercial negotiation.
**Why we chose it.** A brief is the natural unit of seller-planned intent; a
versioned offer feed is the natural unit for buyers that select products
directly. Both need the same targeting semantics. Keeping the paths distinct
lets sellers curate when their expertise matters without forcing catalog
mirrors and direct buyers through a conversational planning loop. Neither path
outranks the other: the wholesale feed is optional and deliberately
lower-resolution, and it is never a capability assessment — a seller's full
planning capability shows in how it answers a brief, not in what it publishes.
**What this rules out.** A separate quote step between products and buy creation. (See principle 2 — the same RFC fails both filters.)
**When you'd be right to push.** When neither a versioned published offer nor
an immutable proposal can express the pricing dependency or commitment being
negotiated. Name the missing state transition and explain why proposal
refinement cannot carry it before adding another task.
→ See [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) for the brief-first model.
***
### 4. Capabilities are commitments, declared under existing buckets
Two things, one principle. **Where capabilities live** in the schema: under existing top-level domains (`signals`, `media_buy`, `creative`, `governance`), not in new top-level keys. **What declaring a capability means**: an enforceable contract, not an advertisement. If a sales agent declares `idempotency.supported: true`, the conformance suite probes it and the contract is testable. Declarations cost something to make.
**Why we chose it.** Top-level keys are the most visible part of the capabilities surface. Each one is a category every implementer scans on every read. Sub-namespacing keeps related capabilities discoverable together (`signals.features.X` belongs near `signals.data_provider_domains`) and keeps the top level scannable. Adding a top-level key for one flag is like adding a department to handle one form. And declarations need to be load-bearing to be useful: a flag the protocol can't enforce or test is a wish, not a contract.
**What this rules out.** "Add a `trusted_match` top-level capability key" for a flag about how signals interact with guaranteed line items. The flag belongs in `signals.features` — a `signal_enforcement_on_guaranteed: "enforced" | "best_effort" | "not_supported"` enum, not a new bucket. Also: declaring a capability you don't actually support, hoping no one probes it. The conformance runner will.
**Reviewer test.** Did the proposal cite the actual top-level keys in the schema today, and explain why none of them is the right home? If the proposal can't answer that question, it's not ready.
→ The [Capabilities explorer](/dist/docs/3.2.8/protocol/capabilities-explorer) renders the existing tree.
***
### 5. Trust is bilateral and `/.well-known`-rooted
Trust in AdCP is bilateral and verifiable, not blessed by a registry. Operators declare organization identity, agents, property relationships, and signing-key discovery via [`brand.json`](/dist/docs/3.2.8/brand-protocol/brand-json) at `/.well-known/brand.json`; publishers declare which agents are authorized for which properties via [`adagents.json`](/dist/docs/3.2.8/governance/property/adagents). Either party can resolve and verify the other's declarations. The [Registry](/dist/docs/3.2.8/registry) helps with discovery and resolution; it does not gate participation. Every discovery hop is an HTTP GET against a deterministic path — the model ads.txt and sellers.json got right, deliberately reused.
**Why we chose it.** Every centralized trust authority eventually becomes a tax. ads.txt and sellers.json got the model right: declarations are public and machine-readable; verification is bilateral; the network discovers truth without a single gatekeeper deciding who counts. AdCP follows that pattern deliberately — adding a "well-known brand registry" or a "verified buyer" tier would re-create the exact ad tech tax structure the protocol is meant to replace.
**What this rules out.** Proposals that frame brand verification as a centralized validation problem — "who decides which brands are well-known?", "should AgenticAdvertising.org verify brand.json submissions before allowing them in the registry?" The premise is the error: `/.well-known/` is a [URI convention from RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615), not a quality signal. A `brand.json` at a domain proves only that whoever controls that domain published it. Trust is built by composing that proof with adagents.json, account-level commercial relationships, and (when needed) signed requests — not by a third party blessing the brand list.
**When you'd be right to push.** When you have evidence of a trust failure that bilateral declarations *demonstrably can't* address — not "what if a fraud declares themselves," but "here's a class of fraud the bilateral model misses, here's the cost, here's the smallest amount of centralization that closes it." Trust extensions are accepted; trust centralization needs receipts. The unresolved question on the substrate (CDN takeovers, DNS games, stale `/.well-known/` crawls) is real — see [Trust & Security](/dist/docs/3.2.8/trust) for what AdCP provides versus what it explicitly does not.
***
### 6. Privacy is layered, not uniform
[Trusted Match Protocol](/dist/docs/3.2.8/trusted-match) has *structural* privacy — separated code paths, schema prohibitions on combining identity with context, decorrelation that's independently verifiable. Every other domain has *contractual* privacy — the parties exchanging data are bound by the account's terms or the user's consent. These are different mechanisms with different guarantees, and proposals that mix them produce confused features.
**Why we chose it.** Structural privacy is expensive — it constrains the schema, requires separated infrastructure, and limits what compositions are possible. We pay that cost in TMP because TMP runs at impression time across mixed buyer/seller boundaries, where contractual confidentiality can't reach. Outside TMP, parties have already established a commercial relationship; a contract is the right unit of trust. Pretending the two are interchangeable means either over-engineering the contractual cases or under-protecting the structural ones.
**What this rules out.** Proposing a "TMP-verified direct-sold targeting"
capability that assumes TMP's privacy guarantees apply to direct-sold ad-server
decisioning. They don't. Whether a seller can enforce signal targeting on
guaranteed inventory is a `signals.features` declaration plus validation of the
published purchase or accepted proposal—a contractual-disclosure feature, not
a structural-privacy one.
**When you'd be right to push.** When you have a cross-domain privacy claim and you can name which mechanism applies. "This is a contractual feature, here's what's in the contract" or "this is a structural feature, here's the schema-level prohibition that makes it work." Vague privacy improvements tend to land on neither and end up in the wrong place.
→ See [Architecture — Privacy posture across domains](/dist/docs/3.2.8/protocol/architecture#privacy-posture-across-domains) for the per-domain mechanism table.
***
### 7. The protocol exposes seams; deployers wire decisions
AdCP defines what fields exist and what guarantees the protocol makes about them. It does not define how a deployer's policy must be enforced, how a governance agent must decide, or what counts as a "good" buyer. This stance shows up in three places, and they share a single posture: **the protocol is realistic about how decisions actually happen — distributed across parties, asynchronous in time, human-checkable in process.**
* *Capabilities are declared, not gated.* [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) is a seam, not an enforcer. A seller that hasn't configured a governance agent will not call it; the protocol doesn't prevent a non-conformant seller from transacting. Schema-level enforcement exists but is rare and named (`fair_housing`, `fair_lending`, `fair_employment` in 3.0); the default is exposure, not coercion.
* *Async is the default; sync is the optimization.* Every mutating task has `*-async-response-{submitted,working,input-required}.json` siblings. A protocol that pretends every operation is synchronous and atomic is one that breaks the moment a real workflow lands.
* *Human review is architectural, not exceptional.* Any mutation can be taken async for human approval via the [task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle); campaign governance provides a declarative buyer-side review channel. HITL composes with everything else — audit logs, governance checks, async responses — rather than being a special case bolted onto certain tasks.
A related invariant lives at the account boundary: **account ownership, not creation surface, determines visibility.** Buys created outside AdCP still belong to the account they fall under, and surface in account-scoped queries. This prevents the shadow-ledger pattern that breaks every "API on top of an ad server."
**Why we chose it.** A protocol that ships policy is a platform with extra steps. The credibility of an open standard is exactly its restraint about what it tries to decide. Deployer policy is also where context-specific judgment belongs — what's a brand-safety violation in one vertical is fine in another, and AdCP can't carry that nuance without picking sides.
**What this rules out.** "The protocol should reject buys that don't match capability X." Most of the time the right answer is "the protocol should make capability X visible, and the deployer rejects the buy." Also: framing autonomy and oversight as opposites — "for agentic to truly work, X must be automated end-to-end." For most regulated and high-stakes operations, that's not what we want, and it's not what the protocol assumes.
**When you'd be right to push.** When the asymmetry is bad enough that a per-deployer policy doesn't solve the coordination problem — when buyers and sellers can't economically agree on enforcement without a protocol-level rule. Schema-level enforcement is rare and earned; argue for it when you have it, not as the first move.
→ See [Trust & Security — Governance](/dist/docs/3.2.8/trust#governance) for what AdCP provides versus what it explicitly does not, and [Governance — Embedded human judgment](/dist/docs/3.2.8/governance/embedded-human-judgment) for how HITL surfaces in the protocol.
***
### 8. Reference data: own the namespace and the resolution contract, not the corpus
AdCP defines the **namespace** (which classification systems exist and the shape of their IDs) and the **resolution contract** (resolve a name against a declared source rather than infer an identifier from a model's training data, and surface ambiguity rather than pick one). It does not publish the underlying code↔name tables — the **corpus** — unless AdCP is itself the authority that mints the values. A code is identity and travels losslessly on the wire; a name is a *rendering* of that code, reconstituted at the edge by whoever displays it, from a lookup they already hold.
**Why we chose it.** The durable asset is the contract, not the corpus. Publishing someone else's reference table makes the registry a downstream mirror that has to track an external publisher forever — owning its correctness, its refresh cadence, and its license exposure, with no ops function behind any of it. And a wrong-but-canonical table is worse than no table: agents hallucinate, and they trust an authority stamp precisely when they shouldn't, so a stale or fabricated entry misdirects real spend silently. The name doesn't need to travel or be centralized — it's a dimension attribute, replicated to the edge once and joined locally, not denormalized onto every request and not fetched from a central service per lookup.
**What this rules out.** A canonical geo-metro registry — a versioned DMA `code → name` table the ecosystem fetches as source of truth (proposed and declined). The proposal's first commit shipped fabricated codes numbered sequentially by market rank — contradicting both the source authority and this repo's own examples — and only a human reviewer caught it. There is no automated authority check, so that error class recurs. The names are also a proprietary, trademarked corpus the project has no license to redistribute. The protocol already handles the read direction correctly: `geo-delivery-metrics` carries an optional `geo_name` beside the required `geo_code`, so a seller *can* render from its own catalog rather than force the buyer to reconstruct a name from a bare code. It equally rules out the opposite over-correction — stapling display names onto targeting values as authoritative. "Albany" names two different DMAs (NY and GA); targeting values are IDs in a declared namespace, and a name rides along only as a non-authoritative label, if at all.
**When you'd be right to push.** When AdCP itself mints the values, owning the table is interop, not data-ops — `v1-canonical-mapping.json` is the legitimate example: AdCP defined both the v1 format vocabulary and the v2 canonical it projects to, the set is additive (entries are never removed, only deprecated), and there is no external rights-holder. And when a single external authority publishes openly (ISO 3166, Eurostat NUTS, ONS ITL, GeoNames under CC-BY), the project *may* ship a thin **generated** mirror with provenance and a regeneration script — a projection, explicitly non-authoritative, demoted the moment the source drifts or a second source disagrees. The bar: name the authority, name the license, and explain why a fetch-once-cache-locally lookup doesn't already solve it.
**Reviewer test.** Is there a single external authority for these values, and is it us? If an external body owns the truth, AdCP declares the namespace and the resolution contract and defers the bytes. "Everyone re-implements this annoying mapping" is a library opportunity, not a protocol mandate.
→ The same anti-centralization instinct as principle 5, applied to reference data instead of trust: the [Registry](/dist/docs/3.2.8/registry) helps resolve and discover, it does not become the ecosystem's lookup table.
***
## Where the surface doesn't yet follow these principles
The principles are credible to the extent we name where the surface still violates them. These are known and tracked.
**`media_buy.execution.trusted_match` (principle 4).** The capabilities schema places TMP-related flags inside `media_buy.execution.trusted_match`, while the architecture page treats TMP as a peer transaction domain alongside Media Buy, Creative, and Signals. A reviewer using these principles to evaluate proposals lands in conflicting answers about where TMP-shaped flags belong. The schema sub-namespacing was right (per principle 4); the parent location is the open question. RFCs proposing changes to TMP capability declarations should expect this to be on the table.
**`axe_integrations` and `axe_include_segment` / `axe_exclude_segment` (principles 1 and the [vendor-neutral rule in spec-guidelines](/dist/docs/3.2.8/spec-guidelines#platform-agnosticism)).** These survive in the v3 schema as normative fields. AXE is a Scope3-originated brand. By the spec-guidelines test, these should have moved to `ext.axe` or replaced cleanly by `trusted_match` before 3.0 GA. They reflect a deprecation in progress, not a stable shape — proposals that build on these fields should expect them to be moved.
**Three top-level keys for "things this agent does that aren't a domain" (principle 4).** `compliance_testing`, `experimental_features`, and `extensions_supported` each carry related-but-shaped-differently capability metadata at the top level. A reviewer would ask why these aren't unified.
**Three signing-related top-level keys (principle 4).** `request_signing`, `webhook_signing`, and `identity` (operator JWKS) are all signing infrastructure metadata. Three top-level keys for one concern is exactly the "scannable top level" cost the principle warns about.
**The trust substrate (principle 5).** Trust in 3.x is trust-on-first-use, rooted in each counterparty's `/.well-known/` + DNS + CDN. Key transparency is deferred to 4.0. ads.txt and sellers.json have been gamed by exactly this attack class for years. The principle is right; the substrate isn't yet what the principle deserves. See [Trust & Security](/dist/docs/3.2.8/trust) for the explicit gap statement.
These are the surface contradictions a sharp third-party reviewer flags on a first read. The honest answer is that some are deprecation in progress, some are unresolved, and at least one (the trust substrate) is the load-bearing 4.0 work. Naming them here keeps the principles credible.
***
## How to use this page
If you're drafting an RFC, work through the principles before you write the title. Most proposals that get bounced get bounced on one of the first two — proposing a field that doesn't exist (principle 1) or proposing a new task for a behavior already expressible via existing tasks plus modes (principle 2). The [Capabilities explorer](/dist/docs/3.2.8/protocol/capabilities-explorer) renders the actual schema tree; check it before you propose a new top-level key.
If you're reviewing an RFC, the principles double as a triage filter. A proposal that names which principle it's pushing back on, and why, is doing the work; a proposal that doesn't recognize a principle applies usually needs a coverage-leading reply before any drafting happens.
The principles aren't immutable. Each one was chosen against a specific trade-off, and each is up for renegotiation when the trade-off shifts. But the renegotiation is the work of an RFC, not the side effect of one — argue for changing the rule explicitly, with the cost of the change named, before proposing the change that depends on it.
# Format References
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/format-references
How canonical format declarations, format-option references, and creative capability IDs differ in AdCP 3.2.
AdCP 3.2 has three deliberately different format-related shapes. Do not substitute one for another.
| Shape | Scope | Used for |
| - | - | - |
| `ProductFormatDeclaration` | Publisher or product contract | Full `format_kind` + `params` declaration in `adagents.json.formats[]`, `Product.format_options[]`, placements, and creative capabilities |
| `FormatOptionRef` | Product/package delivery routing | Selects a publisher or product option without copying its declaration |
| `capability_id` | One creative agent | Selects that agent's build, validation, or preview path |
## Full declaration
```json theme={null}
{
"format_option_id": "homepage_image",
"format_kind": "image",
"params": {
"width": 300,
"height": 250,
"slots": [
{ "asset_group_id": "image_main", "asset_type": "image", "required": true }
]
}
}
```
Products always carry full declarations in `format_options[]`. A product never contains a bare capability reference.
## Option reference
Publisher option:
```json theme={null}
{
"scope": "publisher",
"publisher_domain": "daily-pulse.example",
"format_option_id": "homepage_image"
}
```
Product-local option:
```json theme={null}
{
"scope": "product",
"format_option_id": "homepage_image"
}
```
Use these in package selectors and `creative_manifest.format_option_ref`. A publisher-scoped reference resolves by `{publisher_domain, format_option_id}`; a product-scoped reference resolves only inside the enclosing product/package context.
## Creative capability selector
```json theme={null}
{
"target_capability_id": "homepage_image_builder"
}
```
The value comes from the selected creative agent's `get_adcp_capabilities.creative.supported_formats[].capability_id`. It is meaningful only at that agent endpoint. It must not appear on products, placements, manifests, or creative assets.
## Deprecated named references
The compound `{agent_url, id}` `format_id` shape and `format_ids[]` arrays are deprecated in 3.2. Implementations may read or project them for older 3.x peers, but new examples and authored resources use exactly one canonical selector route. New buyers MUST NOT dual-emit `format_ids[]`.
Receivers remain compatible with older 3.x multi-route requests. They resolve every present route independently before applying precedence. An unresolved option reference or unprojectable legacy ID is rejected with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature). Once all routes resolve, receivers derive the product options selected by each route and require those sets to match; legacy parameter compatibility follows the asymmetric [v2 narrows v1](/dist/docs/3.2.8/creative/canonical-formats#narrows-formal-definition-normative) relation instead of raw object equality. Conflicts are rejected with [`CONFLICTING_SELECTORS`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflicting-selectors); they are never resolved by silently ignoring the legacy projection. Fixed-size image width and height are atomic and both dimensions participate in compatibility.
See [Canonical formats](/dist/docs/3.2.8/creative/canonical-formats) for matching, narrowing, publisher resolution, and migration details.
# get_adcp_capabilities
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/get_adcp_capabilities
get_adcp_capabilities is the first call a buyer makes to discover an AdCP seller's supported protocols, auth model, version, and feature capabilities. Request and response schema reference.
Discover a seller's protocol support and capabilities across all AdCP protocols. This is the first call a buyer should make to understand what a seller supports.
> [!NOTE]
>
> **Why this shape.** Capabilities are organized into \~14 top-level domain keys
> (one per protocol plus identity and signing infrastructure), with feature
> flags nested under each domain's `features`/`execution`/etc. sub-namespace. We
> rejected a flat capability list — it forces every implementer to scan an
> unbounded surface, and it removes the discoverability that comes from related
> flags sitting next to each other. New capability flags belong under existing
> domains, not in new top-level keys; declarations are commitments, not
> advertisements (the conformance runner probes them). → [Capabilities
> explorer](/dist/docs/3.2.8/protocol/capabilities-explorer) walks the tree before you
> propose. → [Design principle: capabilities are
> commitments](/dist/docs/3.2.8/protocol/design-principles#4-capabilities-are-commitments-declared-under-existing-buckets).
**Response Time**: \~2 seconds (configuration lookup)
**Purpose**:
* **AdCP discovery** - Does this agent support AdCP? Which versions?
* **Protocol support** - Which protocols (media_buy, signals, governance, sponsored_intelligence, creative, brand)?
* **Auth model** - Does this seller trust the agent directly, or must each operator authenticate independently?
* **Detailed capabilities** - Features, execution integrations, geo targeting, portfolio
> [!NOTE]
>
> **Per-caller authorization is NOT reported here.** `get_adcp_capabilities`
> returns the seller's surface — everything it *could* do for any authorized
> caller. To discover what *you* are allowed to do on a specific account (which
> tasks are callable for your identity, which request fields are modifiable, any
> named scope like `attestation_verifier`), read the `authorization` object on
> per-account entries in [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts)
> and [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) responses. See
> [Caller authorization](/dist/docs/3.2.8/accounts/overview#caller-authorization) for the
> full shape and semantics.
**Request Schema**: [`/schemas/3.2.8/protocol/get-adcp-capabilities-request.json`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-adcp-capabilities-request.json)
**Response Schema**: [`/schemas/3.2.8/protocol/get-adcp-capabilities-response.json`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-adcp-capabilities-response.json)
## Tool-Based Discovery
AdCP uses native MCP tool discovery and the [AdCP A2A Profile Extension v3](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension) on A2A 1.0. **The presence of `get_adcp_capabilities` in an agent's tool or skill list indicates that runtime AdCP discovery is available.**
```
Discovery Flow:
1. Browse the agent's tool list (MCP), or find and activate the versioned AdCP profile in AgentCard.capabilities.extensions[] (A2A)
2. See the get_adcp_capabilities tool/skill → Runtime AdCP discovery is available
3. Call get_adcp_capabilities → Get version, protocols, features, capabilities
4. Proceed based on returned capabilities
```
This approach:
* Uses native MCP discovery or A2A 1.0's standard extension mechanism
* Always returns current capabilities (not stale metadata)
* Single source of truth for all capability information
:::note
The A2A profile declaration identifies only the wire binding. Its `params` member is omitted or empty. Do not place AdCP versions, domains, or feature flags there: `get_adcp_capabilities` remains the single runtime authority for those values. The unversioned v2 `adcp-extension.json` capability payload remains removed.
:::
## Version Negotiation
Sellers declare which major versions they support via `adcp.major_versions` in the response. Buyers declare which version they're using via `adcp_major_version` on the request.
```
Version Negotiation Flow:
1. Buyer calls get_adcp_capabilities with adcp_major_version: 2
2. Seller checks 2 against its major_versions: [2, 3]
3. Version is supported → seller returns capabilities for v2
4. Buyer includes adcp_major_version: 2 on all subsequent requests
```
`adcp_major_version` is an optional field on every AdCP request schema. Buyers SHOULD include it on all requests when interacting with a multi-version seller.
**Seller behavior:**
* If `adcp_major_version` is provided and supported → respond using that version's schemas
* If `adcp_major_version` is provided but unsupported → return [`VERSION_UNSUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-version-unsupported) (buyer should call without `adcp_major_version` to discover supported versions)
* If `adcp_major_version` is omitted → assume the highest supported version
**Why major versions, not minor?** Semver policy guarantees backward compatibility within a major version for stable surfaces. Explicitly experimental surfaces follow the narrower [experimental-status contract](/dist/docs/3.2.8/reference/experimental-status): they require runtime opt-in through `experimental_features` and may change inside 3.x after the required notice. A seller at 3.1 can otherwise serve a buyer at 3.0 without negotiation. The capability model handles feature-level differences — buyers check specific capabilities (targeting systems, features, extensions) rather than version numbers to determine compatibility.
## Request Parameters
| Field | Type | Description |
| - | - | - |
| `adcp_major_version` | integer | Optional. The AdCP major version the buyer's payloads conform to. When provided, the seller validates against its `major_versions` and returns [`VERSION_UNSUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-version-unsupported) if not in range. When omitted, the seller assumes the highest major version it supports. |
| `protocols` | string\[] | Optional. Filter to specific protocols (`media_buy`, `signals`, `governance`, `sponsored_intelligence`, `creative`, `brand`). If omitted, returns all supported protocols. |
## Response Structure
### adcp
Core AdCP protocol information:
| Field | Type | Description |
| - | - | - |
| `major_versions` | integer\[] | **Required.** AdCP major versions supported (e.g., `[3]`) |
| `idempotency` | object | **Required.** Idempotency semantics. See [idempotency](#idempotency). |
| `capability_changes` | object | Optional. Freshness metadata and opt-in `capabilities.changed` invalidation webhooks for cached capability documents. See [capability_changes](#capability_changes). |
| `attestations` | object | Optional. Allowlisted portable-attestation claim types, issuers, resolvers, verifiers, proof formats, and delivery methods this agent evaluates. See [attestations](#attestations). |
#### idempotency
Declares whether this seller honors `idempotency_key` replay protection on mutations. AdCP requires keys on mutating requests whose published schema declares them required. In the compact AdCP 3.2 product lifecycle, [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals), [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals), and [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals) require keys; [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) and the legacy 3.x [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) facade leave the key optional. Pure reads may ignore a supplied key, so this declaration does not promise read-response replay. See [security.mdx § Idempotency](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency). Clients MUST NOT assume a default; a seller without this block is non-compliant and should be treated as unsafe for retry-sensitive operations.
| Field | Type | Description |
| - | - | - |
| `supported` | boolean | **Required.** Whether the seller deduplicates replays. When `false`, sending an `idempotency_key` is a no-op — the seller will NOT return [`IDEMPOTENCY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-conflict) or [`IDEMPOTENCY_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-expired), and a naive retry WILL double-process. Buyers MUST use natural-key checks (e.g., [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) plus request context such as `context.internal_campaign_id` or package context such as `context.buyer_ref`) before retrying spend-committing operations. |
| `replay_ttl_seconds` | integer | Required when `supported: true`. How long the seller retains a canonical response for a key. Minimum `3600` (1h); recommended `86400` (24h); maximum `604800` (7d). |
```json theme={null}
{
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
}
}
```
Sellers that do not support replay dedup declare it explicitly:
```json theme={null}
{
"adcp": {
"major_versions": [3],
"idempotency": { "supported": false }
}
}
```
**Verifying the declaration.** `idempotency.supported: true` is a trust-bearing claim that enables buyers to safely retry spend-committing operations. A compromised or buggy seller could advertise `true` while silently ignoring keys, causing buyer double-spend on retry. Buyers and conformance runners SHOULD probe the declaration with a deliberate payload-mutation replay: send two requests with the same `idempotency_key` but different canonical payloads — a conformant seller MUST return `IDEMPOTENCY_CONFLICT` on the second. Sellers declaring `supported: true` MUST pass this probe as part of the baseline compliance storyboard before the declaration is considered verified.
#### principal
Declares support for authenticated caller-scoped connection configuration. This is not a second capability document: `get_adcp_capabilities` still describes seller facts, while [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) carries one caller's desired webhooks and reusable reporting destinations, and [`get_principal`](/dist/docs/3.2.8/protocol/get_principal) reads them back.
| Field | Type | Description |
| - | - | - |
| `supported` | boolean | Always `true` when the block is present. |
| `sync_task` | string | Always `sync_principal`. |
| `read_task` | string | Always `get_principal`. Side-effect-free read of caller-scoped state and version. |
| `supported_sections` | string\[] | Any of `notification_configs` and `reporting_destinations`. |
| `max_reporting_destinations` | integer | Required when reporting destinations are supported. Portable schema maximum is 64; a seller may advertise a lower limit. |
| `reporting_destination_offerings` | object\[] | Required when reporting destinations are supported. Objective per-pattern offering — transports, file formats, dataset-share access modes, and verification profiles — so buyers select compatible destinations without submit-and-reject probing. |
| `suspension_interval_seconds` | integer | Required when reporting destinations are supported. Upper bound between a committed destination suspension or revocation and the halt of new deliveries to every generation of that destination. |
| `optimistic_concurrency` | boolean | Whether the seller enforces `expected_configuration_version`. When `false`, a request carrying the fence is rejected rather than silently ignored. |
Agents exposing this block MUST list `protocol.principal` in `experimental_features` and expose both declared tasks. Account authorization remains separate; a ready reusable destination does not grant access to any advertiser account.
#### capability_changes
Declares how consumers should cache and invalidate this agent's capability document. Capabilities are agent-wide and usually stable, so buyers and registries can cache them; this block gives them a bounded TTL, an opaque revision token, and an optional push signal for material changes.
When `notifications.supported: true`, sellers MUST include `cache_ttl_seconds` and `capabilities_version`. The webhook is the fast path; the TTL and opaque revision marker are the recovery path when delivery is missed or delayed. `last_modified` remains useful human-readable metadata, but it is not sufficient as the notification fence.
| Field | Type | Description |
| - | - | - |
| `capabilities_version` | string | Opaque revision token for the full capability document. Required when `notifications.supported: true`. Sellers SHOULD change it whenever any material field in `get_adcp_capabilities` changes. Buyers compare for equality only. |
| `last_modified` | date-time | Timestamp when the seller last changed the advertised capability document. Use this instead of legacy top-level `last_updated` when both are present. |
| `cache_ttl_seconds` | integer | Maximum time a buyer or registry SHOULD reuse this response without a fresher invalidation signal. Required when `notifications.supported: true` so receivers recover from missed fires. |
| `notifications` | object | Whether the seller supports `capabilities.changed` webhooks. When `supported: true`, register subscribers with the declared task: [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) when the broader connection surface is supported, or [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) for the specialized compatibility path. |
```json theme={null}
{
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
"capability_changes": {
"capabilities_version": "rev_20260702_091455",
"last_modified": "2026-07-02T09:14:55Z",
"cache_ttl_seconds": 3600,
"notifications": {
"supported": true,
"registration_task": "sync_agent_notification_configs",
"event_types": ["capabilities.changed"],
"coalescence_window_seconds": 300
}
}
}
}
```
A **material capability change** is any externally advertised contract change that can affect routing, validation, conformance coverage, or task behavior. Examples include sandbox support, `require_operator_auth`, supported billing, account resolution mode, supported protocol versions, task availability, reporting delivery methods, creative-library support, targeting support, and any feature gate a buyer checks before sending a request.
Non-contract operational changes that do not alter the `get_adcp_capabilities` response body do not require a revision or webhook fire.
`capabilities.changed` webhooks are invalidation signals, not replacement documents. The payload identifies the agent, change time, reason, required post-change `capabilities_version`, and optional advisory `changed_paths[]`; receivers SHOULD re-run `get_adcp_capabilities` and replace their cached snapshot from the fresh response. Sellers MUST publish the new capability snapshot before firing the webhook so the webhook's `capabilities_version` is observable on read. If a receiver reads before the webhook revision is observable, it SHOULD retry with normal transient-error backoff and retain the prior cached snapshot until a matching or newer authoritative snapshot is available. The payload schema is [`/schemas/3.2.8/core/capabilities-changed-webhook.json`](https://adcontextprotocol.org/schemas/3.2.8/core/capabilities-changed-webhook.json).
### adcp.governance_enforcement
Declares cross-role enforcement of buyer governance for consequential tasks. This core capability is intentionally separate from the top-level `governance` block: `governance` describes an agent that provides governance services, while `adcp.governance_enforcement` describes a media, signal, brand, creative, or other service that consumes governance authorization before committing state.
| Field | Type | Description |
| - | - | - |
| `tasks` | object\[] | Task-scoped enforcement claims. Each entry has `task` and `modes`; the corresponding request schema defines when the operation is commitment-bearing through `x-governed-commitment`. `task` is the semantic uniqueness key: emit one entry per task and combine modes in that entry. |
| `accepted_governance_agents` | object | Optional seller-wide advisory matchers for governance agents a buyer may bind. `any_of[]` accepts explicit canonicalized HTTPS URLs or deterministic registry-verification criteria. Omission means any otherwise-valid agent is accepted; [`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance) remains authoritative per account. |
```json theme={null}
{
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
"governance_enforcement": {
"tasks": [
{
"task": "create_media_buy",
"modes": ["signed_context", "online_execution_check"]
},
{ "task": "activate_signal", "modes": ["signed_context"] }
],
"accepted_governance_agents": {
"any_of": [
{
"kind": "agent_url",
"agent_url": "https://governance.example/mcp"
},
{
"kind": "verification",
"registry": "https://registry.example/agents",
"role": "governance",
"adcp_version": "3.2",
"verification_modes": ["spec", "live"],
"max_age_seconds": 86400
}
]
}
}
}
}
```
The declaration is part of the experimental `governance.campaign` surface, so an implementing service also lists `governance.campaign` in top-level `experimental_features`. `signed_context` is defined for every governed role. `online_execution_check` is available for the legacy [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) / [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) facades and the compact [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products), [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal), and [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) lifecycle, where `planned_delivery` provides a standardized prepared-result shape. Proposal acceptance binds both `proposal_id` and `proposal_terms_digest`. Online checking always implies `signed_context`; the state transition follows prepare → check → commit and commits atomically only when the response is `approved`.
Advertising a task also commits the service to deterministic applicability. It resolves the commercial account from the request or existing resource before the side effect; when it cannot do so, it returns [`ACCOUNT_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-required). It never treats a missing token as evidence that the buyer is ungoverned. Conditional task annotations use `trigger_overrides_exemption`: any commitment-increasing part of a mixed atomic update requires governance.
AdCP 3.2 conformance selects role-specific governance workflows from exact
entries in `adcp.governance_enforcement.tasks[]`. The legacy
`media_buy.governance_aware` boolean remains a compatibility signal for older
runners, but it is not the 3.2 certification gate.
### adcp.attestations
Declares the portable attestations this agent is prepared to evaluate. The block is shared across protocol roles and therefore lives under `adcp`: a seller may evaluate an attestation directly, while a governance agent may evaluate the same presentation for a governance action.
The authoritative shape is [`attestation-capabilities.json`](https://adcontextprotocol.org/schemas/3.2.8/core/attestation-capabilities.json). See [Portable attestations](/dist/docs/3.2.8/building/by-layer/L1/security#portable-attestations) for the normative resolution and verification procedure.
```json theme={null}
{
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
"attestations": {
"accepted_claim_types": [
"https://claims.example/audience/methodology-reviewed",
"https://adcontextprotocol.org/claims/rights/grant"
],
"accepted_proof_formats": [
"https://www.w3.org/TR/vc-jose-cose/"
],
"supported_delivery_methods": [
"issuer_credential_id",
"embedded"
],
"accepted_issuers": [
{
"issuer": {
"type": "origin",
"origin": "https://credentials.example"
},
"claim_types": ["https://claims.example/audience/methodology-reviewed"],
"resolvers": [
{
"resolver_id": "primary",
"url": "https://resolver.credentials.example/v1/credentials",
"authentication": "evaluator_managed"
}
]
},
{
"issuer": {
"type": "brand",
"brand": { "domain": "novabrands.example", "brand_id": "nova_talent" }
},
"claim_types": ["https://adcontextprotocol.org/claims/rights/grant"],
"proof_formats": ["https://www.w3.org/TR/vc-jose-cose/"],
"resolvers": [
{
"resolver_id": "rights-primary",
"url": "https://rights.novabrands.example/credentials",
"authentication": "evaluator_managed"
}
]
}
],
"accepted_verifiers": [
{
"agent_url": "https://verification.example/adcp"
}
],
"max_embedded_credential_bytes": 262144
}
}
}
```
| Field | Type | Description |
| - | - | - |
| `accepted_claim_types` | URI\[] | **Required.** Open claim identifiers the evaluator accepts. This is evaluator policy, not an AdCP issuer or claim registry. |
| `accepted_proof_formats` | URI\[] | **Required.** Open credential/proof formats the evaluator can verify. |
| `supported_delivery_methods` | string\[] | **Required.** Any of `credential_uri`, `issuer_credential_id`, and `embedded`. |
| `accepted_issuers` | object\[] | **Required.** Canonical issuers plus their permitted credential origins and evaluator-configured resolver endpoints. |
| `accepted_verifiers` | object\[] | Optional verifier-agent allowlist. Presenter nominations must match this list but never control evaluator routing. |
| `max_embedded_credential_bytes` | integer | Optional embedded-proof byte limit; evaluators enforce it before parsing. Protocol maximum: 1 MiB. |
Changing an attestation allowlist can change whether future requests are accepted and whether cached evaluations remain reusable. It is therefore a material capability change and SHOULD update `adcp.capability_changes.capabilities_version` and fire `capabilities.changed` when notifications are enabled.
The rights-grant claim URI is a domain profile, not a globally trusted issuer list. A seller that advertises `media_buy.rights_attestations` also lists `https://adcontextprotocol.org/claims/rights/grant` here and configures each acceptable rights-agent issuer, resolver, proof format, and credential origin. Buyer-supplied values cannot expand that policy.
### supported_protocols
AdCP protocols this agent supports. This is the single capability axis — each value both (a) declares which tools the agent implements *and* (b) commits the agent to pass the baseline compliance storyboard at `/compliance/{version}/protocols/{protocol}/`. The runner maps JSON snake_case → URL kebab-case (`media_buy` → `/compliance/.../protocols/media-buy/`).
```json theme={null}
{
"supported_protocols": ["media_buy", "creative"]
}
```
Valid values: `media_buy`, `creative`, `signals`, `governance`, `brand`, `sponsored_intelligence`.
See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for every protocol's scope. Support for the [compliance test controller](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller) is declared via the separate `compliance_testing` capability block (below), not as a protocol value.
### specialisms
Optional specialization claims. Each entry corresponds to a narrow storyboard at `/compliance/{version}/specialisms/{id}/`. Every specialism rolls up to one protocol in `supported_protocols` — claiming `sales-guaranteed` requires `media_buy`. The runner rejects a specialism whose parent protocol is missing.
```json theme={null}
{
"specialisms": ["sales-guaranteed", "creative-template"]
}
```
See the full [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) for every specialism and the [enum schema](https://adcontextprotocol.org/schemas/3.2.8/enums/specialism.json) for the authoritative list.
### oauth
Introduced in AdCP 3.2. Declares OAuth support for the agent's inbound transport. This is separate from `account.authorization_endpoint`, which is specifically an operator credential-acquisition URL.
```json theme={null}
{
"oauth": {
"supported": true
}
}
```
Setting `oauth.supported: true` opts the agent into the universal [`oauth_setup`](/compliance/latest/universal/oauth-setup.yaml) storyboard. The agent must publish RFC 9728 protected-resource metadata for its endpoint and valid RFC 8414 metadata for every authorization server named there. Agents that authenticate only with static Bearer keys, HTTP Basic, mTLS, or RFC 9421 omit the block or set `supported: false`.
### Capability slot gaps
SDK helpers such as `definePlatform` can project a platform implementation into narrower capability slots. Treat those slots as commitments: only declare a slot when the agent can execute the corresponding task path end to end.
If a storyboard or local test vector targets a slot the agent does not declare, the conformance outcome is `not_applicable`, not failure. Current runners enforce that boundary before dispatch. A custom runner should do the same. Do not work around a missing slot by declaring it and returning placeholder responses; that turns an honest coverage gap into a failed capability claim.
### account
Account and authentication capabilities. All sellers should declare this section — buyers read it before calling [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts), [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts), or any authenticated task. Even simple publishers need account management to handle billing relationships and sandbox testing.
| Field | Type | Description |
| - | - | - |
| `supported_billing` | string\[] | **Required.** Billing models this seller supports: `operator`, `agent`, or `advertiser`. When the buyer calls `sync_accounts`, every entry must select one of these values. |
| `supported_account_currency_modes` | string\[] | **Required for 3.2 advertiser-account provisioning; additive/optional on the shared 3.x wire schema for 3.1 compatibility.** Models this seller supports: `fixed`, `per_media_buy`, or both. A buyer includes `currency` in `sync_accounts` for `fixed` and omits it for `per_media_buy`. When both are advertised, presence or absence selects the model. Absence means an older seller has not exposed currency-mode discovery; it does not imply support for either mode. |
| `timezone` | object | **Required for 3.2 advertiser-account provisioning; additive/optional on the shared 3.x wire schema for compatibility.** `seller_fixed` advertises one `fixed_timezone` for every account. `account_fixed` declares whether each immutable account timezone is `seller_assigned` or `buyer_selected`; buyer-selected mode also publishes the exact `supported_timezones`. |
| `require_operator_auth` | boolean | Default: `false`. Declares who must authenticate; it does not by itself declare whether OAuth is used, whether `list_accounts` is exposed, or which `sync_accounts` modes are supported. When `true`, each operator authenticates independently and account-scoped calls use seller/storefront-assigned `account_id` values. When `false`, the agent is trusted and calls use the advertiser natural key: `brand` + `operator` + optional `operator_unit`, fixed `currency`, optional buyer-selected `timezone`, and `sandbox`. `operator_unit.id` belongs to the operator and is not the seller's `account_id`. Buyer-declared sellers normally provision through `sync_accounts`, MUST continue accepting the natural key, and SHOULD expose `list_accounts` so all key fields can be recovered after a cold start. |
| `authorization_endpoint` | string | OAuth URL for operator authentication. Present when the seller supports OAuth for operator authentication. Relevant when `require_operator_auth: true`; if absent, operators obtain credentials out-of-band (seller portal, API key). |
| `required_for_products` | boolean | Default: `false`. When `true`, the buyer must establish an account before calling [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products). When `false`, the buyer can browse products without an account — useful for price comparison and discovery before committing to a seller. Before an account is provisioned, the buyer omits `account` rather than sending a natural key that doesn't resolve yet; see [Account references before provisioning](/dist/docs/3.2.8/accounts/overview#account-references-before-provisioning). |
| `account_financials` | boolean | Default: `false`. When `true`, the seller supports [`get_account_financials`](/dist/docs/3.2.8/accounts/tasks/get_account_financials) for querying spend, credit, and invoice status. Only applicable to operator-billed accounts. |
| `identity_updates` | object | Optional capability gate for reconciling an existing account's buyer-controlled operator identity through `sync_accounts` settings-update mode. `supported_changes` declares `operator_unit_name`, `operator_unit`, and/or `operator`. |
| `notifications` | object | Optional. Declares durable account lifecycle webhook support. When `supported: true`, buyers may register `account.status_changed` subscribers with `sync_accounts.accounts[].notification_configs[]` and repair by re-reading `list_accounts`. |
| `change_feed` | object | Optional, experimental (`account.change_feed`). Declares the durable [`list_account_changes`](/dist/docs/3.2.8/accounts/tasks/list_account_changes) feed and `account.change_recorded` wake-up. When supported, includes a retention floor of at least 90 days and the resource types covered. |
| `sandbox` | boolean | Default: `false`. Strongly recommended for production sales agents. When `true`, the seller supports sandbox accounts for testing. Account-id namespaces discover pre-existing test accounts through `list_accounts` or out-of-band setup. Buyer-declared accounts use `sandbox: true` in `sync_accounts`, or in the natural-key account reference when the seller uses unambiguous lazy provisioning — no real platform calls or spend. See [Sandbox mode](/dist/docs/3.2.8/media-buy/advanced-topics/sandbox). |
#### account.notifications
Declares whether the seller supports durable account lifecycle invalidation webhooks. This is the capability gate for `account.status_changed`, including billing-related status transitions such as `payment_required`, `suspended`, recovery to `active`, and terminal `closed`.
```json theme={null}
{
"account": {
"supported_billing": ["operator", "agent"],
"supported_account_currency_modes": ["fixed", "per_media_buy"],
"timezone": {
"mode": "account_fixed",
"account_selection": "buyer_selected",
"supported_timezones": ["America/New_York", "Europe/London", "UTC"]
},
"notifications": {
"supported": true,
"registration_task": "sync_accounts",
"read_task": "list_accounts",
"event_types": ["account.status_changed"],
"supports_webhook_activity": true
}
}
}
```
When `supported: false` or absent, buyers MUST NOT assume durable account status webhooks are available. They can still use the one-shot `sync_accounts.push_notification_config` callback for the initial provisioning result when offered, and poll `list_accounts` for later account status changes.
#### account.change_feed
Declares whether the seller exposes a durable ordered account change feed.
This capability is separate from `account.notifications`, which covers the
specialized account lifecycle invalidation, and from `webhook_activity`, which
is only delivery-attempt diagnostics.
The account change feed is [experimental](/dist/docs/3.2.8/reference/experimental-status)
in 3.2 while [RFC #6810](https://github.com/adcontextprotocol/adcp/issues/6810)
remains open. Sellers advertising `supported: true` MUST also list
`account.change_feed` in `experimental_features`.
```json theme={null}
{
"experimental_features": ["account.change_feed"],
"account": {
"change_feed": {
"supported": true,
"read_task": "list_account_changes",
"registration_task": "sync_accounts",
"event_type": "account.change_recorded",
"retention_days": 90,
"resource_types": [
"account",
"account_financials",
"media_buy",
"package",
"creative",
"creative_assignment",
"delivery_report"
]
}
}
}
```
Advertising a resource type is a completeness commitment: every material
change to fields recoverable through that resource's authoritative read is
recorded regardless of origin. Snapshot completeness is normative and is not
weakened into a self-asserted `complete: true` flag. Account-specific connected
source status and freshness are returned by `list_account_changes`.
See [Provision a seller-mediated account](/dist/docs/3.2.8/accounts/provisioning-walkthrough) for the complete discovery, registration, human setup, webhook, and repair sequence.
#### account.timezone
Account timezone is an immutable operational default, not an assumption that every upstream clock is identical. A `seller_fixed` seller advertises one `fixed_timezone` and buyers omit `timezone` during provisioning. An `account_fixed` seller returns a timezone on every account; when `account_selection` is `buyer_selected`, buyers MUST provide one advertised value to `sync_accounts`, and that value participates in the natural account key. When it is `seller_assigned`, buyers omit the field and discover the value from `sync_accounts` or `list_accounts`.
Calendar-day features inherit `Account.timezone` only when their capability says so. Product reporting continues to use `reporting_capabilities.timezone`, account financials use the timezone returned by `get_account_financials`, and daily caps use `budget_capping.timezone_basis`. This prevents a seller from claiming that distinct reporting, billing, and delivery clocks are aligned when the upstream platform does not align them.
#### account.identity_updates
Declares whether the seller accepts a complete desired `operator_identity` on an existing account through `sync_accounts` settings-update mode.
```json theme={null}
{
"account": {
"supported_billing": ["operator", "agent"],
"identity_updates": {
"supported": true,
"supported_changes": ["operator_unit_name", "operator_unit", "operator"]
}
}
}
```
`operator_unit_name` covers display-name-only changes within the current operator. `operator_unit` covers adding, removing, or changing the stable unit ID within the current operator and also implies name changes. `operator` covers an inter-entity operator-domain handoff and encompasses the complete replacement identity, including any simultaneous unit addition, removal, or change; a seller does not also need to advertise `operator_unit` for that cross-operator replacement. Operator-domain handoffs always require seller-mediated approval of the current account authority, verified brand authorization, destination-operator acceptance, and operator-scoped billing and grants. Sellers declaring support MUST return account `revision` from `sync_accounts` and `list_accounts`, require and atomically enforce a submitted revision, preserve account identity and account-scoped resources during rekeying, expose any pending or rejected transition as `identity_change`, and return `identity_change_preview` for `dry_run: true`. When the capability is absent or `supported: false`, buyers MUST NOT submit `operator_identity`; sellers reject it with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature).
See [`sync_accounts` identity reconciliation](/dist/docs/3.2.8/accounts/tasks/sync_accounts#reconciling-operator-identity) for replacement, approval, collision, and stale-key semantics.
#### Auth models
**Buyer-declared accounts** (`require_operator_auth: false`) — The seller trusts the agent's identity claims. The agent authenticates once with its own bearer token, and account-scoped calls use that credential plus the advertiser natural key (`brand` + `operator` + optional `operator_unit`, fixed `currency`, optional buyer-selected `timezone`, and `sandbox`). `brand.countries[]` may qualify the commercial advertiser identity without targeting delivery. Most sellers expose `sync_accounts` so the buyer can declare the relationship and select billing or other settings before use. A seller MAY instead auto-provision on the first account-scoped request when those settings are unambiguous from capabilities or onboarding defaults; in that mode it MUST expose `list_accounts` as the recovery read and MUST keep accepting the natural key. Auto-provisioning is not conformant when buyer input is needed to resolve billing, timezone, terms, sandbox setup, notifications, or other account settings before the operation.
**Account-id namespaces** (`require_operator_auth: true`) — Each operator must authenticate with the seller directly. The agent obtains a credential per operator — via OAuth using `authorization_endpoint`, or out-of-band — opens a per-operator session, and passes seller-assigned `account_id` values on subsequent requests. OAuth is credential acquisition, not an account taxonomy axis. Two namespace patterns use the same wire reference: upstream-managed sellers expose `list_accounts`, making explicit account resolution mandatory before account-scoped calls; seller-defined namespaces without `list_accounts` provide account IDs out-of-band. SDKs SHOULD lazily call `list_accounts` when first needed, auto-select a singleton, cache it per credential/session, and still send explicit `AccountRef` values on required-account calls.
For sandbox, the path follows the account namespace: account-id namespaces discover pre-existing test accounts via `list_accounts` or out-of-band setup; buyer-declared accounts send `sandbox: true` through `sync_accounts` or, for a lazy-provisioning seller, in the natural-key account reference.
See [Accounts and Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#what-sellers-declare) for full workflows and [seller patterns](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#seller-patterns) for common combinations of auth model and billing support.
### media_buy
Media-buy protocol capabilities. Only present if `media_buy` is in `supported_protocols`. Sellers declaring `media_buy` should also include `account` (with `supported_billing`) and `media_buy.portfolio` — buyers need both to establish billing and understand inventory coverage. Compliance testing validates their presence.
#### anonymous_discovery
`media_buy.anonymous_discovery` declares whether the seller accepts product-discovery calls without caller credentials. It covers [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) and [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) in `brief` or `wholesale` mode. It does not cover proposal refinement or finalization, purchasing, account-scoped reads, or mutations; those operations follow their normative authentication requirements.
* `true` means an anonymous discovery request can return a successful response. It does not promise a complete seller catalog, globally public commercial terms, or the same result an authenticated principal or selected account would receive.
* `false` means product discovery requires an authenticated principal.
* Absence means unspecified legacy behavior. Callers MAY probe anonymously and handle [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing); they MUST NOT infer either value.
This declaration describes the minimum caller context accepted by the discovery task, not product visibility. Every response is authoritative only for the authentication and account context of that request. A seller MUST validate credentials when they are presented and MUST NOT silently downgrade invalid credentials to anonymous access.
`anonymous_discovery: true` and `account.required_for_products: true` are inconsistent and fail capability validation: an anonymous caller cannot select protected account context. The inverse dimensions remain independent—a seller may require an authenticated principal without requiring an account reference.
#### acceptance_policy_discovery
`media_buy.acceptance_policy_discovery` advertises a structured catalog for what the seller will accept. `catalog_url` identifies an HTTPS `acceptance-policy-catalog.json` document, `catalog_digest` pins its bytes, and `default_profile_ids[]` selects seller-wide profiles. The declaration does not claim the seller evaluates buyer-supplied acceptance context during discovery; buyers compose the published profiles for advisory preflight and treat exact task responses as authoritative.
This capability is advisory. Missing capability or omitted rules in a partial profile are unknown, not unrestricted acceptance. Products may add profile IDs; defaults and product profiles compose restrictively. The exact task response remains authoritative and may return [`POLICY_VIOLATION`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-policy-violation) for an account-specific or undisclosed rule.
```json theme={null}
{
"media_buy": {
"acceptance_policy_discovery": {
"catalog_url": "https://seller.example/.well-known/adcp-acceptance-policies.json",
"catalog_digest": "sha256:54f04c3e2e8dfdf682b0da0cd0ee4d5265e54a6e0f72b9260785dfc1526fd08a",
"default_profile_ids": ["seller-default"]
}
}
}
```
#### lifecycle_tools
AdCP 3.2 sellers use `lifecycle_tools` to advertise any supported subset of `get_products`, `list_products`, `request_proposals`, `refine_proposals`, `decline_proposals`, `buy_products`, `accept_proposal`, and `control_media_buy`. When absent, buyers use the legacy `get_products`, `create_media_buy`, and `update_media_buy` facades. The advertised subset is a statement of supported surfaces, not a quality signal: a seller that omits `list_products` offers no wholesale feed and is fully conformant — wholesale-path conformance scenarios are capability-gated and grade not applicable for sellers that do not advertise the surface. Buyers SHOULD NOT infer inventory breadth or planning capability from the subset a seller advertises. The compact tools share the authorization framework with their legacy peers, but grants remain task-specific and each stateful tool has its own idempotency identity: retry with the same tool name and payload. SDKs use the release manifest's `legacy_fallback` metadata to distinguish a direct one-call translation from a stateful orchestration or an unsupported fallback; see [Same-major tool replacements](/dist/docs/3.2.8/building/cross-cutting/version-adaptation#same-major-tool-replacements).
#### availability_horizon
`media_buy.availability_horizon: true` declares flexible-window availability discovery: the seller parses `offer_filters.availability_horizon` and answers with `time`-dimensioned forecast points carrying `availability_status` — half-open, non-overlapping windows that partition the requested horizon (gaps signalled via `incomplete[]`), with status computed from all booking eligibility constraints, not only competing holds. See [Flexible Availability Windows](/dist/docs/3.2.8/media-buy/product-discovery/media-products#flexible-availability-windows). When `false` or absent, support is unknown: buyers SHOULD use exact `start_date`/`end_date` filtering instead, and sellers MAY ignore the field or reject it. Conformance storyboards gate flexible-window checks on this declaration.
#### proposal_refinement
When `lifecycle_tools` includes `refine_proposals`, `proposal_refinement` optionally advertises which typed revision dimensions the seller can parse and mechanically validate:
| Dimension | Request field | Deterministic check |
| - | - | - |
| `total_budget` | `constraints.total_budget` | Compare the inclusive range and currency with `commercial_terms.total_budget`. |
| `cpm` | `constraints.cpm` | Compare the ceiling and currency with every purchase's fixed `cpm`/`vcpm` `pricing.fixed_price`. |
| `impressions` | `constraints.impressions` | Sum `commercial_terms.purchases[].impressions` and compare with the minimum. |
| `flight` | `constraints.flight` | Compare `commercial_terms.start_time` and `end_time` with the window bounds. |
| `product_changes` | `product_changes` | Check each keyed `include`/`omit` action against `commercial_terms.purchases[].product_id`. |
| `alternatives` | `alternatives.count` | Count drafts and verify that their `commercial_terms` — and therefore `terms_digest` values — are distinct. |
| `criteria` | `criteria` | Apply structured discovery changes and preserve omitted criteria from the source proposal. |
`alternatives.count` has a protocol maximum of 10. `max_alternatives` may accompany `alternatives` to publish a lower pre-flight count ceiling and therefore cannot exceed 10. A request whose `alternatives.count` exceeds that declared ceiling MUST fail at task level with [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error); `error.field` identifies the offending `refinements[i].alternatives.count`. Sellers MUST NOT silently clamp the count or reinterpret the ceiling as an `alternatives_unavailable` result.
An explicit `supported_dimensions` list is authoritative, including an empty list meaning the seller supports `ask`-only refinement but no typed dimensions. Buyers SHOULD NOT send omitted dimensions, and sellers MUST reject them at task level with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature). Such errors SHOULD carry the [`error-details/unsupported-refinement-dimension.json`](https://adcontextprotocol.org/schemas/3.2.1/error-details/unsupported-refinement-dimension.json) shape — `details.unsupported_dimension` and `details.supported_dimensions` — so an authorized buyer can remove or translate unsupported fields without another capability round trip. This task-level rejection applies to the complete request: no sibling refinement succeeds and no proposal is created, even when the unsupported dimension appears after otherwise supported entries. When `proposal_refinement` is absent, support is unknown; sellers report unsupported dimensions through `partial` or `unable` results instead. `proposal_refinement` is valid only when `lifecycle_tools` includes `refine_proposals`.
This capability is about parse and validation support, never commercial willingness. Free-text `ask` interpretation remains seller competence rather than a boolean capability. Multi-proposal finalization deliberately retains its separate failure-as-discovery model through [`MULTI_FINALIZE_UNSUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-multi-finalize-unsupported): it describes atomic infrastructure topology, while the core typed revision fields must be discoverable before a deterministic buyer constructs a request.
#### outcome_target
`media_buy.outcome_target: true` declares reverse-forecast planning: the seller parses `criteria.outcome_target` (a compact goal — a `forecastable-metric` delivery metric or an `event-type` conversion event — plus a desired volume, a `cost_per` target, or both) and plans against it, answering with `total_budget_guidance` on proposals and forecasts whose points carry the goal's key in `metrics`. A `cost_per` target is answered in `commercial_terms.bidding.cost_per` only within the seller's advertised `features.bidding_policy` profile; otherwise the seller rejects it with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) naming `criteria.outcome_target.cost_per`. The flag alone cannot distinguish a seller that predates cost targets from one that plans them, so buyers rely on the negotiated `adcp_version` together with `features.bidding_policy`. See [Reverse forecasting](/dist/docs/3.2.8/media-buy/task-reference/request_proposals#reverse-forecasting-with-outcome_target) and [Cost targets](/dist/docs/3.2.8/media-buy/task-reference/request_proposals#cost-targets). When `false` or absent, support is unknown: buyers SHOULD express outcome goals in `brief` prose instead, and sellers reject a structured `outcome_target` on `request_proposals` and proposal refinement with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) rather than silently ignoring it. On [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) the field is inert for every seller.
#### budget_capping
`budget_capping` advertises hard daily caps independently at `media_buy` and `package` scopes. A media-buy cap bounds aggregate daily spend without allocating it; package caps add subordinate ceilings and are never reservations. Sellers MUST reject an undeclared scope with `UNSUPPORTED_FEATURE` before mutation and MUST NOT reinterpret `daily_budget_cap` as a soft pacing target.
```json theme={null}
{
"media_buy": {
"budget_capping": {
"supported_scopes": ["media_buy", "package"],
"supported_periods": ["day"],
"timezone_basis": "account",
"buyer_timezone_override": true
}
}
}
```
`timezone_basis: "account"` uses the selected `Account.timezone`, allowing two accounts on the same seller to have different cap days. `timezone_basis: "fixed"` requires `fixed_timezone` and uses that feature-specific boundary for every buy. A buyer override is media-buy-level and applies to every cap on that buy. The accepted effective timezone is echoed as `budget_cap_timezone`; DST transition dates remain one calendar day carrying the full cap. Billing and reporting timezones remain independently explicit and MUST NOT be inferred from the cap basis.
#### frequency_capping
`frequency_capping` retains its legacy meaning: the seller honors package-level
caps, with an independent counter per package, and rejects caps it cannot
enforce rather than silently dropping them. A cap with one counter shared
across every package in a MediaBuy is advertised by the separate, additive
`aggregate_frequency_capping` object, so older buyers never mistake a root-only
seller for one that accepts package caps.
```json theme={null}
{
"media_buy": {
"frequency_capping": {
"supported_per_units": ["individuals", "households"],
"supported_window_units": ["hours", "days", "campaign"]
},
"aggregate_frequency_capping": {
"supported_control_modes": ["max_impressions"],
"supported_per_units": ["individuals", "households"],
"max_impressions_constraints": {
"minimum": 1,
"maximum": 20
},
"window_constraints": [
{ "unit": "hours", "minimum_interval": 1, "maximum_interval": 24 },
{ "unit": "days", "allowed_intervals": [1, 7, 30] },
{ "unit": "campaign", "allowed_intervals": [1] }
]
}
}
}
```
Package execution requires either broad
`Product.overlay_support.frequency_cap: true` or structured
`Product.overlay_support.frequency_cap_support`. Product constraints may narrow
but never broaden seller-wide support: omitted per units inherit
`supported_per_units`, and omitted window or suppression constraints inherit
`supported_window_units` with no interval restriction. Each count or duration
constraint is either an exact preset list or an inclusive range.
`mutable_fields` distinguishes count updates from window or entity changes, and
`[]` means create-only.
Aggregate execution requires `Product.media_buy_support.frequency_cap: true` on
every selected product, and every product's resolved `supported_per_units` must
include the root cap's `per` value. The seller-wide aggregate object must
declare its complete executable domain; product detail may only inherit or
narrow it. Root caps are max-impression-only in 3.2; package caps may also use
suppression. Scope is determined by field location, not by a `FrequencyCap`
discriminator.
:::note 3.0 breaking changes
The following fields have been removed from the capabilities response:
* `media_buy.reporting` — Reporting is implied by `media_buy`. Use product-level `reporting_capabilities` instead.
* `features.content_standards` — Replaced by `media_buy.content_standards` object. Presence of the object indicates support.
* `features.audience_targeting` — Replaced by `media_buy.audience_targeting` object. Presence of the object indicates support.
* `features.conversion_tracking` — Replaced by `media_buy.conversion_tracking` object. Presence of the object indicates support.
* `execution.targeting.device_platform`, `device_type` — Implied by `media_buy` support.
* `execution.targeting.audience_include`, `audience_exclude` — Implied by `audience_targeting` object presence.
* `execution.trusted_match.supported` — Object presence indicates support.
* `brand.identity` — Implied by `brand` in `supported_protocols`. [`get_brand_identity`](/dist/docs/3.2.8/brand-protocol/tasks/get_brand_identity) is always available.
:::
#### reporting_delivery_methods
Declares which push-based delivery methods are available across the seller's product portfolio. Polling via [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) is a required task for all `media_buy` sellers regardless of this field.
| Method | Description | Configuration |
| - | - | - |
| `webhook` | Seller pushes to buyer-provided URL | Buyer configures `reporting_webhook` per media buy |
| `offline` | Seller pushes batch files to a cloud storage bucket | Seller provisions `reporting_bucket` per account |
When absent, only polling is available. Cadence and metrics are declared per product in `reporting_capabilities`.
When `offline` is declared, also include `offline_delivery_protocols` to declare which cloud storage protocols are supported (`s3`, `gcs`, `azure_blob`). Buyers express a protocol preference via `preferred_reporting_protocol` in `sync_accounts`; the seller provisions the account's `reporting_bucket` using a supported protocol.
For offline delivery, the seller provisions a per-account bucket and grants the buyer read access out-of-band. The bucket location (including `file_retention_days`) appears on the account object returned by `sync_accounts` as `reporting_bucket`. See [Offline File Delivery](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting#offline-file-delivery-based-reporting) for details.
#### reporting_delivery (experimental)
`media_buy.reporting_delivery` advertises **Reliable Reporting** in three tiers over
one data model. Presence requires `media_buy.reporting_delivery` in top-level
`experimental_features`.
The affirmative machine-readable answer to **“Do you support Reliable
Reporting?”** is all three of:
* `experimental_features` contains `media_buy.reporting_delivery`;
* `media_buy.reporting_delivery.supported` is `true`; and
* `media_buy.reporting_delivery.reliable_reporting_version` is `"1.0"`.
Then inspect the optional tier flags and atomic offerings below. Legacy
`reporting_delivery_methods`, a generic reporting endpoint, or an AAMP
declaration does not imply this AdCP feature; AAMP and AdCP are not
wire-compatible, so each is evaluated through its own capability surface.
| Tier | Advertised by | Contains | Required? |
| - | - | - | - |
| **Core** | `supported: true` | Obligations, revisions, immutable post-official adjustments, the five health states, and seller [`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status). Current source also defines opt-in buyer-to-seller [`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status) over ordinary task transport; it becomes required only in the next eligible minor after the notice window. Core offerings omit `method`, destinations, materializations, Managed canonicalization, billing receipts, and bespoke status webhooks. | **Yes** — the only required tier |
| **Managed delivery** | `managed_delivery: true` | Offerings whose `method` names `file_transfer`, `dataset_share`, or `warehouse_materialization`, plus exact-resource retention and authorization-revocation bounds. | No |
| **Reconciled billing** | `reconciled_billing: true` | `receipt_task` ([`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts)), `consumer_receipt` reconciliation, and the canonical-digest contract in offering profiles. | No |
A seller with no outbound reporting push remains Core-conformant: status sync is
an ordinary inbound task, not a buyer-hosted callback. A supported RFC 9421
`webhook_signing` profile is required only
when the seller declares any reporting notification.
Three optional doorbells: `status_notification` (`reporting.status_changed`) is
tier-independent invalidation for health transitions in either direction —
valid for Core, since it names no destination, and repaired through a full
current status read; `ledger_notification`
(`reporting.ledger_changed`) announces each new revision or adjustment even when
health is unchanged; and `readiness_notification` (`reporting.delivery_ready`)
is managed-delivery-only positive readiness. Ledger changes repair through
`changes_after`; health-only changes use a non-incremental summary or periods read.
`offerings[]` are atomic—not a cross-product—and each binds one feed purpose,
content-addressed reporting profile/schema, schedule, and supported finality;
managed-delivery offerings additionally bind transport, orchestration,
provider/access mode/format, and destination modes.
The Core capability can declare both status directions:
* `status_task: "get_reporting_status"` exposes the seller's obligation and
revision ledger; and
* optional `consumer_status_task: "sync_reporting_status"` records what the
authenticated buyer could actually consume. It becomes mandatory only in the
next eligible minor after the active notice window.
The second task does not require the buyer to expose an agent endpoint or
webhook. A buyer using a Reliable Reporting configuration calls the seller task
automatically after bounded repair and whenever its period status changes.
Missing buyer status remains unknown and never excuses seller reporting.
Schedules may align to UTC, the AdCP account timezone, an explicit upstream
`source_timezone`, or an anchored billing cycle. `source_timezone` covers clocks
such as an ad server network timezone and is accepted only when the source can
produce those exact periods natively or through lossless finer-grained
re-bucketing. Optional `reliability_statistics[]` publish evidence-scoped
on-time counts, publication latency, and post-official adjustment frequency,
latency, and magnitude for exact offering IDs.
#### performance_feedback
Presence declares that a seller accepts compact baseline/metric/provenance fields from a buyer orchestrator and returns a `feedback_id` for accepted assertions.
| Field | Description |
| - | - |
| `reports_application_status` | A seller response honestly distinguishes `accepted`, `applied`, and `not_applied` in `application_status`. `accepted` means stored and eligible for evaluation, not optimizer use. |
Because this compact contract is experimental, a seller declaring `media_buy.performance_feedback` also lists `measurement.core` in top-level `experimental_features`. This does not make the seller a measurement provider or require `measurement` in `supported_protocols`.
See [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) and `measurement_gateway` below for the provider → orchestrator → seller flow.
#### creative_approval_mode
Declares the seller's tenant-wide creative approval posture after creatives are assigned and automated validation passes. This is not a notification surface or a new approval workflow; it tells buyers and compliance runners whether human review can still block serving eligibility. Compliance runners use this declaration mainly to decide whether auto-approval-dependent storyboards such as `media_buy_seller/pending_creatives_to_start` apply.
| Value | Description |
| - | - |
| `auto_approve` | Human review does not block serving eligibility after creatives are assigned and automated validation passes. Auto-approval-dependent storyboards can run. |
| `require_human` | One or more products/accounts may require manual review before creatives become eligible to serve. Treat this as a tenant-wide worst-case ceiling until a product-level override exists. |
Sellers with mixed approval policies SHOULD declare `require_human` unless every product/account that can be reached by the advertised agent supports automatic eligibility after automated validation. When the field is absent, approval behavior is legacy-unspecified; runners SHOULD NOT treat omission as an affirmative `auto_approve` claim. `ai_assisted` is intentionally not a value until the protocol defines what assistance changes in observable behavior.
#### measurement_terms_acceptance
`media_buy.measurement_terms_acceptance: true` declares that the seller can accept the
default `measurement_terms` it advertises on at least one product. A buyer discovers
those terms with [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products), replays
the exact object on a package in
[`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy), and receives the
confirmed terms on the resulting package. This declaration does not promise acceptance
of arbitrary buyer-authored terms or of terms that differ from the product default.
Compliance runners execute `media_buy_seller/measurement_terms_accepted` only when this
capability is true. When it is false or absent, that affirmative scenario is not
applicable, but the universal `media_buy_seller/measurement_terms_rejected` contract
still applies: unsupported terms must fail with
[`TERMS_REJECTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-terms-rejected)
rather than being silently ignored.
#### supported_indicator_types and relationship_notifications
Lists the seller interpretations available on media-buy resource relationships.
```json theme={null}
{
"media_buy": {
"supported_indicator_types": [
"creative_fatigue",
"creative_quality_opportunity",
"creative_diversity_low",
"audience_saturation",
"inventory_shortfall_forecast",
"pacing_risk",
"budget_constrained"
],
"relationship_notifications": {
"supported": true,
"registration_task": "sync_accounts",
"event_types": ["indicators.changed", "creative.assignment_changed"],
"repair_tasks": ["get_media_buys"],
"projection_tasks": ["list_creatives"],
"supports_webhook_activity": true
}
},
"webhook_signing": {
"supported": true,
"profile": "adcp/webhook-signing/v1",
"algorithms": ["ed25519"],
"legacy_hmac_fallback": false,
"delivery_retry_horizon_seconds": 86400
}
}
```
Indicator meaning follows the negotiated AdCP release rather than an independent version. This capability does not promise complete upstream coverage. Each present array names exact type coverage in `indicator_types_evaluated`.
`supported_indicator_types` declares polling readback and does not require webhook infrastructure. A poll-only seller exposes those types through `get_media_buys` and omits `relationship_notifications`. When a seller does declare `relationship_notifications`, `indicators.changed` requires `supported_indicator_types`; a seller without an indicator catalog may instead declare `creative.assignment_changed` alone for assignment and approval changes, including when it is inline-only. Every notification declaration names `get_media_buys` as the complete authoritative repair read. A creative-library seller may include [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) as a bounded reverse projection; it mirrors relationship identity and scoped approval, while evaluated indicator snapshots reconcile toward the strictly newer `indicators_as_of`. Because this optional block advertises outbound invalidations, `webhook_signing` MUST include `supported: true`, `profile`, `algorithms`, `legacy_hmac_fallback`, and `delivery_retry_horizon_seconds`.
Subscriptions, when supported, are prospective: activation does not replay current conditions. Buyers establish a complete `get_media_buys` baseline by enumerating known IDs or requesting all seven statuses and following pagination to exhaustion, without `indicator_types`. Sellers then fire the applicable invalidation after observing a semantic change. Poll-only buyers simply repeat direct reads. See [Indicators and Warnings](/dist/docs/3.2.8/media-buy/media-buys/indicators).
An inline-only declaration is therefore valid with `event_types: ["indicators.changed", "creative.assignment_changed"]` and `repair_tasks: ["get_media_buys"]`. Conversely, a creative-library seller may advertise `projection_tasks: ["list_creatives"]` without the assignment event when it cannot detect those changes; that declaration also requires `supported_protocols` to contain `creative`. Both additions are independent of each other, and `repair_tasks` remains the complete repair contract.
#### features
Optional media-buy features. Boolean declarations are commitments when true. Structured declarations commit only to the explicitly advertised sub-capabilities.
| Feature | Description |
| - | - |
| `inline_creative_management` | Deprecated 3.x compatibility capability for inline creatives in `create_media_buy` and `update_media_buy`; compact lifecycle tools never accept them |
| `property_list_filtering` | Honors `property_list` parameter in `get_products` |
| `catalog_management` | Supports [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs) for catalog feed management |
| `catalog_item_availability_updates` | Supports buyer-pushed [`sync_catalogs` availability updates and queries](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs#immediate-item-availability) for revision-guarded suppression, restoration, and current-state readback in buyer-managed catalogs |
| `seller_optimized_budget` | Supports the core shared-budget contract: one hard `total_budget`, seller allocation across packages against cross-package goals, media-buy-level pacing (omitted or `even` MUST be accepted; `asap`/`front_loaded` MAY be rejected with `UNSUPPORTED_FEATURE`, never coerced), and allocation echo on reads |
| `seller_optimized_package_budgets` | Honors package `budget` as an optional hard cap inside a seller-optimized buy. Requires `seller_optimized_budget: true` |
| `seller_optimized_min_spend_targets` | Honors package `min_spend_target` as a soft minimum-spend target inside a seller-optimized buy, including over-subscription validation. Requires `seller_optimized_budget: true` |
| `seller_optimized_package_pacing` | Honors package `pacing` beneath media-buy pacing inside a seller-optimized buy. Requires `seller_optimized_budget: true` |
| `bidding_policy` | Structured canonical bidding support by authored scope, allocation context, modes, strengths, and supported combinations |
The three package-control sub-capabilities are meaningful only with `seller_optimized_budget: true`; a seller declaring one as `true` without the parent fails schema validation. A seller that supports only the core contract declares the parent alone. It then MUST reject a seller-optimized request carrying an undeclared package control (for pacing, one that differs from the media-buy pacing) with `UNSUPPORTED_FEATURE` before any over-subscription validation or provider mutation, and MUST NOT silently drop or coerce it. The same rule applies on `create_media_buy`, `update_media_buy`, `buy_products`, and `control_media_buy`, and the seller does not issue seller-optimized proposals carrying the matching allocation constraint. Over-subscription checks run only for declared controls. A seller advertising `seller_optimized_min_spend_targets` rejects package minimums summing above `total_budget` with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request), and if it also advertises `seller_optimized_package_budgets`, it rejects a `min_spend_target` above its package `budget` the same way. A core-only seller that receives an over-subscribed `min_spend_target` returns `UNSUPPORTED_FEATURE`, not `INVALID_REQUEST`. Buyer `required_features` filters may request a sub-capability alone.
`bidding_policy` is intentionally not a boolean. Each `media_buy` or `package` scope contains independent `fixed` and/or `seller_optimized` profiles. Every profile's `modes` lists standalone support from `automatic`, `bid_amount`, `max_bid`, `cost_per`, and `roas`. A profile advertising standalone `cost_per` also declares `cost_per_strengths`; `roas` similarly declares `roas_strengths`. Optional `supported_combinations` entries independently identify `max_bid_with_cost_per` or `max_bid_with_roas` and list the strengths supported in that combination; a combination-only component need not appear in `modes`. Presence of one scope, allocation context, mode, strength, or combination makes no claim about another.
```json theme={null}
{
"features": {
"bidding_policy": {
"media_buy": {
"fixed": {
"modes": ["max_bid", "cost_per"],
"cost_per_strengths": ["cap", "target"],
"supported_combinations": [
{
"kind": "max_bid_with_cost_per",
"cost_per_strengths": ["cap"]
}
]
}
},
"package": {
"seller_optimized": {
"modes": ["automatic", "cost_per"],
"cost_per_strengths": ["cap"]
}
}
}
}
}
```
#### content_standards
Content standards implementation details. Presence of this object indicates the seller supports content_standards configuration including sampling rates and category filtering. Gives buyers pre-buy visibility into local evaluation and artifact delivery capabilities.
| Field | Type | Description |
| - | - | - |
| `supports_local_evaluation` | boolean | Whether the seller runs a local evaluation model. When `false`, `local_verdict` will always be `unevaluated` and the `failures_only` filter on [`get_media_buy_artifacts`](/dist/docs/3.2.8/governance/content-standards/tasks/get_media_buy_artifacts) is not useful. |
| `supported_channels` | string\[] | Channels for which the seller can provide content artifacts. Helps buyers understand which parts of a mixed-channel buy will have content standards coverage. |
| `supports_webhook_delivery` | boolean | Whether the seller supports push-based artifact delivery via `artifact_webhook` configured at buy creation time. |
**Example:**
```json theme={null}
{
"content_standards": {
"supports_local_evaluation": true,
"supported_channels": ["display", "olv", "podcast"],
"supports_webhook_delivery": true
}
}
```
If `supports_local_evaluation` is `false`, the `failures_only` filter on `get_media_buy_artifacts` will return an empty result set — all verdicts will be `unevaluated`.
#### execution
Technical execution capabilities:
| Field | Type | Description |
| - | - | - |
| `trusted_match` | object | [TMP](/dist/docs/3.2.8/trusted-match) support. When present, this seller supports real-time contextual and/or identity matching. Check individual products for per-product TMP capabilities. |
| `axe_integrations` | string\[] | Deprecated. Legacy AXE URLs this seller can execute through. Use `trusted_match` for new integrations. |
| `creative_specs` | object | Creative specification support (VAST versions, MRAID, etc.) |
| `targeting` | object | Targeting capabilities (geo granularity) |
##### axe_integrations
`axe_integrations` is an array of Agentic Ad Exchange (AXE) endpoint URLs that this seller can execute through. AXE is the real-time execution layer for AdCP campaigns — it connects buyer agents to programmatic inventory via standardized exchanges.
When a seller declares AXE URLs in their capabilities, buyers can:
* Route impression-level execution through the declared exchange
* Use the exchange's targeting, optimization, and measurement capabilities
* Execute alongside the seller's direct-sold inventory
Buyers discover AXE support via `get_adcp_capabilities` and filter products to AXE-enabled sellers using `required_axe_integrations` on [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products).
##### creative_specs
| Field | Type | Description |
| - | - | - |
| `vast_versions` | string\[] | VAST versions supported (e.g., `["4.0", "4.1", "4.2", "4.3"]`) |
| `macro_resolution_capabilities` | object\[] | Seller-wide ceiling of resolvable macro dialects, semantics, and URL-encoding depths. Product format options remain binding. |
| `mraid_versions` | string\[] | MRAID versions supported |
| `vpaid` | boolean | VPAID support |
| `simid` | boolean | SIMID support |
##### targeting
| Field | Type | Description |
| - | - | - |
| `geo_countries` | boolean | Country-level targeting using ISO 3166-1 alpha-2 codes |
| `geo_regions` | boolean or object | ISO 3166-2 subdivision inclusion targeting. Structured entries declare individual country/value support; a boolean is the legacy coarse rollup. |
| `geo_regions_exclude` | boolean or object | ISO 3166-2 subdivision exclusion targeting, declared independently from inclusion, with structured entries declaring individual country/value support. |
| `geo_metros` | object | Metro area targeting with system-specific support |
| `geo_postal_areas` | object | Postal area targeting with country and precision support |
| `geo_places` | object | Named-place targeting keyed by collision-safe identifier system, with exact country/type support, catalog versions, and resolver metadata |
| `age_restriction` | object | Age restriction capabilities with `supported` flag and `verification_methods` |
| `demographics` | object | Seller-wide discovery rollup for canonical demographic targeting. `supported: true` means at least one product supports the surface; inspect each product's `demographic_targeting` declaration for exact execution. |
| `language` | boolean or object | Language-preference targeting. The structured form may declare `supported` and exact selectable BCP 47 ranges in `supported_languages`; the boolean is the legacy coarse declaration. |
| `keyword_targets` | object | Keyword targeting with `supported_match_types` array (`broad`, `phrase`, `exact`). Presence indicates support. |
| `negative_keywords` | object | Negative keyword targeting with `supported_match_types` array. Presence indicates support. |
| `collection_list` | boolean | Collection list inclusion targeting. `true` is a seller-wide rollup; inspect each product's `overlay_support`. |
| `collection_list_exclude` | boolean | Collection list exclusion targeting. `true` is a seller-wide rollup; inspect each product's `overlay_support`. |
| `property_list` | boolean | Property list inclusion targeting. `true` is a seller-wide rollup; inspect each product's `overlay_support`. |
| `property_list_exclude` | boolean | Property list exclusion targeting. `true` is a seller-wide rollup; inspect each product's `overlay_support`. |
| `placement_selection` | boolean | Placement selection targeting. `true` is a seller-wide rollup; inspect each product's targetable placements and `overlay_support`. |
| `geo_proximity` | object | Proximity targeting from arbitrary coordinates (see below) |
Device platform and device type targeting are implied by `media_buy` support. Audience include/exclude targeting is implied by the presence of the `audience_targeting` capabilities object.
Subdivision inclusion and exclusion are declared independently through `geo_regions` and `geo_regions_exclude`. Seller-wide structured values are individual routing claims within the capability response's scope; they do not promise that multiple values are jointly composable or available through the same execution route or account. Only Product `overlay_support` supplies the binding set of executable targeting permissions for that Product. For other geographic levels that retain a combined legacy rollup, sellers SHOULD support both directions. For **any targeting-overlay list dimension** declared in this table — geo, `collection_list`, or `property_list` — if a seller only supports one direction, it MUST return a validation error for unsupported fields rather than silently ignoring them; silently dropping an exclusion is an unsafe failure mode. See [Targeting Overlays](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) for exclusion semantics.
**geo_proximity** specifies which proximity targeting methods are supported:
| Field | Type | Description |
| - | - | - |
| `radius` | boolean | Simple radius targeting (distance circle from a point) |
| `travel_time` | boolean | Travel time isochrone targeting (requires a routing engine) |
| `geometry` | boolean | Pre-computed GeoJSON geometry (buyer provides the polygon) |
| `transport_modes` | string\[] | Transport modes supported for isochrones: `driving`, `walking`, `cycling`, `public_transport` |
**geo_metros** specifies which metro classification systems are supported:
| System | Description |
| - | - |
| `nielsen_dma` | Nielsen DMA codes (US market, e.g., `501` for NYC) |
| `uk_itl1` | UK ITL Level 1 regions |
| `uk_itl2` | UK ITL Level 2 regions |
| `eurostat_nuts2` | Eurostat NUTS Level 2 regions (EU) |
**geo_postal_areas** specifies which country-local postal code systems are supported. The preferred shape is keyed by ISO 3166-1 alpha-2 country, with each country listing supported systems:
```json theme={null}
{
"us_zip": true,
"us_zip_plus_four": true,
"US": ["zip", "zip_plus_four"],
"GB": ["outward", "full"],
"CA": ["fsa", "full"],
"ZA": ["postal_code"]
}
```
Use `postal_code` for the normal postal code string in countries without a more specific registered local system. During the 3.x migration, sellers SHOULD emit equivalent deprecated aliases such as `us_zip` alongside native country keys where an alias exists. Buyers and SDKs SHOULD normalize both shapes before making capability decisions.
**geo_places** is keyed by place identifier system. Registered keys are `geonames`, `google_ads`, and `microsoft_ads`; private or additional catalogs use an owner-controlled absolute HTTPS URI. Each system declares exact country-to-place-type support, exact accepted versions, and a machine-readable resolver:
```json theme={null}
{
"geonames": {
"countries": {
"US": ["city", "county"],
"NL": ["city", "municipality"],
"GB": ["city", "post_town"]
},
"catalog": {
"source": "https://seller.example/data-sources/geonames-mirror",
"current_version": "2026-05",
"supported_versions": ["2026-05", "2026-04"],
"resolver": {
"url": "https://seller.example/adcp/geo/resolve/geonames",
"auth": "seller_credentials",
"protocol": "adcp_geo_place_resolver_v1"
}
}
},
"https://seller.example/geo/catalogs/places": {
"countries": {
"NL": ["city"]
},
"catalog": {
"current_version": "2026-q2",
"supported_versions": ["2026-q2"],
"resolver": {
"url": "https://seller.example/adcp/geo/resolve/private",
"auth": "seller_credentials",
"protocol": "adcp_geo_place_resolver_v1"
}
}
}
}
```
If `geo_places` is absent, buyers MUST NOT assume place targeting is available. If present, the seller MUST honor only the explicitly declared country/type pairs and exact `supported_versions`, or return a validation error. `current_version` MUST appear in `supported_versions` and is applied when the buyer omits `system_version` on new targeting. `supported_versions` describes versions accepted for new targets and target-changing updates; removing a version MUST NOT silently mutate, drop, or invalidate existing packages already pinned to that version. Optional `source` identifies a dataset or derivative without creating a new ID namespace—for example, a MaxMind-derived catalog still uses `system: "geonames"`. The resolver accepts an HTTPS GET with `get-geo-place-resolution-request.json` query fields and returns `get-geo-place-resolution-response.json`, including lifecycle status and replacement IDs. Unsupported or deprecated identifiers must be rejected rather than silently ignored or replaced. Display labels are never authoritative targeting keys.
Registered system semantics are exact:
| System | Authoritative `values` namespace | Type mapping |
| - | - | - |
| `geonames` | GeoNames `geonameId` integers encoded as strings. MaxMind `geoname_id` uses this same namespace. | The resolver maps GeoNames feature class/code into the registered AdCP type. Populated-place targets such as `PPL`, `PPLA`, `PPLC`, and `PPLG` map to `city`; administrative features map according to their official country-specific meaning. |
| `google_ads` | Google Ads geo target Criterion IDs encoded as strings | Lowercase snake-case mapping of Google target types to the registered AdCP type when one exists; otherwise use an owner-controlled HTTPS type URI. |
| `microsoft_ads` | Microsoft Advertising Location IDs encoded as strings | Lowercase snake-case mapping of Microsoft location types to the registered AdCP type when one exists; otherwise use an owner-controlled HTTPS type URI. |
Registered place types are semantic classes, not a universal hierarchy. `city`, `municipality`, and `post_town` are distinct; likewise `borough`, `neighborhood`, `quarter`, and `ward` are not interchangeable. The resolver's country-specific mapping is authoritative for the system/version it serves. Sellers MUST NOT claim a country/type pair unless their resolver returns that type and their execution platform can honor it.
Resolver calls use HTTPS GET. Supply exactly one of `q` for name search or `value` to refresh an existing identifier against a catalog version. For example:
```text theme={null}
GET https://seller.example/adcp/geo/resolve/geonames?q=Springfield&country=US&subdivision=US-IL&place_type=city&system_version=2026-05&limit=20
```
`auth: "seller_credentials"` means the buyer uses the same authorization credentials as the seller's AdCP endpoint and is valid only when the resolver has the same origin as that endpoint. Buyers MUST NOT forward seller credentials cross-origin and MUST apply normal SSRF protections to resolver requests. `auth: "none"` declares a public resolver. A URI-valued `system` is an opaque namespace identifier and is not automatically fetched. Results identify the exact system version and lifecycle state:
```json theme={null}
{
"request": {
"q": "Springfield",
"country": "US",
"subdivision": "US-IL",
"place_type": "city",
"system_version": "2026-05",
"limit": 20
},
"system": "geonames",
"system_version": "2026-05",
"matches": [{
"value": "4250542",
"country": "US",
"subdivision": "US-IL",
"place_type": "city",
"label": "Springfield",
"canonical_name": "Springfield, Illinois, United States",
"parent_labels": ["Illinois", "United States"],
"status": "active"
}]
}
```
The response `system` MUST equal the capability-map key that advertised the resolver. Its version MUST equal the requested `system_version`, or the advertised `current_version` when omitted. The response echoes the normalized request, and every match MUST equal its `country` and any requested `subdivision` and `place_type`. `canonical_name` and `parent_labels` are required so same-named results remain distinguishable; `subdivision` is also required on a match when the request constrained it. Registered numeric systems reject non-numeric values and replacement IDs.
Successful searches, including zero matches, return `200` with `Content-Type: application/json` and the response schema above. Invalid queries return `400`; missing or invalid credentials return `401` or `403`; throttling returns `429`; and resolver failures return an appropriate `5xx`. Non-`200` responses MUST NOT be interpreted as an empty result set. Pagination repeats the normalized original request and uses `cursor`/`next_cursor`.
Buyers MUST traffic only an unambiguous `active` result. `removal_planned` results may still describe an existing target but should not be used for a new buy. `deprecated` results are invalid for new targeting; `replaced_by_values` may guide a new resolution, but sellers MUST require the buyer to submit the replacement rather than silently changing intent. To refresh a persisted ID after catalog rollover, query `value=` against the current version. Existing packages remain pinned to their echoed applied version until the buyer intentionally changes targeting; unrelated updates preserve that overlay. If the seller can no longer execute it, `get_media_buys` MUST preserve the echoed target and return nonfatal [`PLACE_TARGET_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-place-target-unavailable) in response-level `errors[]`, with `recovery: "correctable"`, an exact package-target `field` path, and target identity in `details`, rather than silently changing geography.
#### rights_attestations
Declares how this seller evaluates portable rights-grant credentials carried in creative `rights[]`. Presence requires `adcp.attestations`, and its `accepted_claim_types` MUST include `https://adcontextprotocol.org/claims/rights/grant`.
| Field | Type | Required | Description |
| - | - | - | - |
| `requirement` | `optional \| required` | yes | `required` makes a current verified seller evaluation a serving-eligibility condition. `optional` permits an independent legacy contractual path, but unattested constraints remain machine-unverified. |
```json theme={null}
{
"media_buy": {
"rights_attestations": {
"requirement": "required"
}
}
}
```
The buyer carries `AttestationReference` values and never supplies a trusted outcome. The seller evaluates the exact reference, holder issuer, authorized rights-agent key, subject, grant digest, validity, and fresh revocation status and returns seller-produced `rights_attestation_evaluations` on creative readback. Sparse [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) reads request `rights_attestation_evaluations`; the seller automatically includes `creative_id` and `rights` so each result can be paired with the retained constraint. Neither capability mode permits fallback to `rights_constraint.verification_url`; that deprecated URL has no authorization meaning.
#### audience_evidence
Structured product audience-evidence support. Presence means the seller publishes immutable `Product.audience_evidence` snapshots, evaluates the declared buyer policy modes in `get_products.filters.audience_evidence_requirements`, and retains digest-pinned package readback. This is discovery and planning support, not audience targeting.
| Field | Type | Required | Description |
| - | - | - | - |
| `supported_requirement_modes` | string\[] | **Required** | Supported policy modes: `required`, `preferred`, or both. Unsupported hard modes must be rejected, never silently ignored. |
| `supported_presence_modes` | string\[] | **Required** | Supported presence semantics: `required`, `when_available`, or both. |
| `supports_attestation_evaluation` | boolean | **Required** | Whether the seller evaluates evidence `attestation_refs[]` under `adcp.attestations` and preserves the exact reference and evaluation in package readback. |
```json theme={null}
{
"media_buy": {
"audience_evidence": {
"supported_requirement_modes": ["required", "preferred"],
"supported_presence_modes": ["required", "when_available"],
"supports_attestation_evaluation": true
}
}
}
```
See [Audience evidence](/dist/docs/3.2.8/media-buy/product-discovery/media-products#audience-evidence) and [`get_products` evidence requirements](/dist/docs/3.2.8/media-buy/task-reference/get_products#audience-evidence-requirements).
#### audience_targeting
Audience targeting capabilities. Presence of this object indicates the seller supports audience targeting, including [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) and `audience_include`/`audience_exclude` in targeting overlays. Describes what identifier types the seller accepts for audience matching, size constraints, and expected matching latency.
| Field | Type | Required | Description |
| - | - | - | - |
| `supported_identifier_types` | string\[] | **Required** | PII-derived identifier types accepted for audience matching. Buyers should only send identifiers the seller supports. Values: `hashed_email`, `hashed_phone`. |
| `minimum_audience_size` | integer | **Required** | Minimum matched audience size required for targeting. Audiences below this threshold will have `status: too_small`. Varies by platform (100–1000 is typical). |
| `supports_platform_customer_id` | boolean | | When `true`, the seller accepts the buyer's CRM/loyalty ID as a matchable identifier. Only applicable when the seller operates a closed ecosystem with a shared ID namespace (e.g., a retailer matching against their loyalty program). Buyers can include `platform_customer_id` values in `AudienceMember.identifiers`. Reporting on matched IDs typically requires a clean room or the seller's own reporting surface. |
| `supported_uid_types` | string\[] | | Universal ID types accepted for audience matching (MAIDs, RampID, UID2, etc.). MAID support varies significantly by platform — check this field before sending `uids` with `type: maid`. |
| `matching_latency_hours` | object | | Expected matching latency range in hours after upload. Use to calibrate polling cadence and set appropriate expectations before configuring `push_notification_config`. Shape: `{ min: integer, max: integer }`. |
| `supported_activation_methods` | object\[] | | **Experimental** (`media_buy.audience_activation` — MUST be listed in `experimental_features` when present; see [Experimental status](/dist/docs/3.2.8/reference/experimental-status)). Union of per-product [`audience_activation.methods`](/dist/docs/3.2.8/media-buy/product-discovery/media-products#audience-activation) across the seller's catalog. Fast-fail discovery: read this once and skip the catalog walk when nothing overlaps your pipeline. Per-product declarations are the source of truth; sellers MUST keep this consistent with the catalog. Operational coordinates are account-scoped: this union may omit `consumer_identities` and `destination_ref` until bilateral setup establishes them, and must never expose another account's coordinates. Absence of this field with `media_buy.audience_activation` listed in `experimental_features` means walk the catalog — only a present, non-overlapping union is a fast-fail signal. Each entry is an [activation method](/dist/docs/3.2.8/media-buy/product-discovery/media-products#activation-method-patterns). |
#### conversion_tracking
Seller-level conversion tracking capabilities. Declares what the seller supports for `kind: "event"` optimization goals.
| Field | Type | Description |
| - | - | - |
| `multi_source_event_dedup` | boolean | Whether the seller can deduplicate events across multiple event sources within a single goal. When `true`, the same `event_id` from multiple sources counts once. When `false` or absent, buyers should use a single event source per goal. |
| `supported_event_types` | string\[] | Event types this seller can track. If omitted, all standard event types are supported. |
| `supported_uid_types` | string\[] | Universal ID types accepted for user matching. |
| `supported_hashed_identifiers` | string\[] | Hashed PII types accepted (`hashed_email`, `hashed_phone`). Buyers must hash before sending (SHA-256, normalized). |
| `supported_action_sources` | string\[] | Action sources this seller accepts events from. |
| `attribution_windows` | object\[] | Available attribution windows. Single-element arrays indicate fixed windows; multi-element arrays indicate configurable options the buyer can choose from via `attribution_window` on optimization goals. |
#### portfolio
Inventory portfolio information. Media-buy sellers SHOULD declare both routing
arrays. The existing `primary_*` names are retained for 3.x compatibility, but
a present array is exhaustive for brief routing: buyers MAY skip the agent when
a brief's requested countries or channels do not intersect it. Omission means
unknown scope, never global coverage. These are routing pre-filters—not promises
that a matching product is currently available.
`primary_countries` is not executable geo-targeting capability. It answers
whether the sales agent accepts a country-scoped discovery brief; the structured
fields under `media_buy.execution.targeting` and each product's
`overlay_support` determine whether and how a returned product can execute
geographic targeting.
| Field | Type | Description |
| - | - | - |
| `publisher_domains` | string\[] | **Required.** Publisher domains this seller represents |
| `primary_channels` | string\[] | Complete AdCP channel allowlist for briefs this agent accepts; omission means unknown |
| `primary_countries` | string\[] | Complete ISO 3166-1 alpha-2 country allowlist for briefs this agent accepts; omission means unknown |
| `description` | string | Markdown portfolio description |
| `advertising_policies` | string | Content policies and restrictions |
### signals
Signals protocol capabilities. Only present if `signals` is in `supported_protocols`.
| Field | Type | Description |
| - | - | - |
| `anonymous_discovery` | boolean | Whether [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) accepts anonymous discovery in `brief` or `wholesale` mode. `true` permits a successful anonymous response but makes no completeness or cross-account equivalence claim; `false` requires an authenticated principal; absence is unspecified legacy behavior. Presented credentials are always validated and invalid credentials never downgrade to anonymous access. |
| `data_provider_domains` | string\[] | Data provider domains this signals agent is authorized to resell. Buyers should fetch each provider's `adagents.json` for signal definitions and to verify authorization. |
| `discovery_modes` | string\[] | Discovery modes the agent supports on [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals). `"brief"` (semantic discovery via `signal_spec` / `signal_refs`, with deprecated `signal_ids` accepted for older clients) is implicit and always supported. Declare `"wholesale"` to advertise that callers can omit `signal_spec` / `signal_refs` / `signal_ids` and enumerate the full priced signals feed. Agents not declaring `"wholesale"` MAY return [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) for wholesale calls. Absent declaration is treated as `["brief"]`. |
| `features.catalog_signals` | boolean | **Deprecated.** Legacy wire flag for structured `signal_ref` references to provider-published signal definitions in adagents.json `signals[]`. |
> [!NOTE]
>
> `catalog_signals` is deprecated. Existing 3.x agents may continue to emit it
> for compatibility, but new agents SHOULD omit it and callers MUST NOT require
> it before using `signal_ref`. Treat `supported_protocols: ["signals"]`,
> `signals.data_provider_domains`, `signals.discovery_modes`, and the actual
> `get_signals` response as the capability surface.
### creative
Creative protocol capabilities. Only present if `creative` is in `supported_protocols`.
| Field | Type | Description |
| - | - | - |
| `supports_compliance` | boolean | When `true`, this creative agent can process briefs with compliance requirements and validate them against its canonical supported-format declarations. |
| `has_creative_library` | boolean | When `true`, the agent exposes reusable [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) and `list_creatives` library operations. |
| `supports_revisions` | boolean | When `true`, the library accepts buyer-authored immutable `revision_id` values and preserves them through sync echo, current readback, review attribution, and revision-homogeneous delivery rows. Requires `has_creative_library: true`. Does not imply revision history, rollback, or staged activation. |
| `representation_resolution` | object | Destination-sales-agent opt-in to accept a complete `creative_representation_set` on [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative), verify its revision digest, and select one compatible `representation_id` against that seller's current product and execution contract using an advertised deterministic strategy. Standalone creative agents cannot advertise seller-bound resolution. Absence means the caller selects before sending a seller-bound manifest; the agent cannot guess. See [creative representation sets](/dist/docs/3.2.8/creative/representation-sets). |
| `supported_formats` | object\[] | Canonical creative operation catalog. New 3.2 producers MUST emit a stable `capability_id`, a full canonical `format` declaration, and explicit `operations` (`build`, `validate`, `preview`). Exact publisher support carries `{publisher_domain, format_option_id}` inside `format`; generic capabilities declare a satisfiable canonical parameter envelope. For 3.x compatibility, consumers accept entries without `capability_id` and interpret absent `operations` as `build`; such entries can be matched by contract but not selected through a capability-ID route. Replaces [`list_creative_formats`](/dist/docs/3.2.8/creative/task-reference/list_creative_formats) in 3.2. |
| `preview` | object | Per-route [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) declaration. `routes[].capability_id` names `supported_formats[]` entries whose `operations` includes `preview`; `rendering_origin` reports `platform_native` or `agent_approximation` per route. This self-description is informational and never grants authority; only a matching publisher placement `preview_provider` delegation does. See [rendering authority](/dist/docs/3.2.8/creative/canonical-formats#rendering-authority-and-fallback-order). |
| `supports_transformers` | boolean | When `true`, this creative agent offers account-scoped transformers — the selectable units of build capability (voices, models, styles) discovered via [`list_transformers`](/dist/docs/3.2.8/creative/task-reference/list_transformers) and selected with `transformer_id` (plus the typed `config` bag) on [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative). When `false` or absent, the agent does not expose transformers; `list_transformers` is unavailable and `build_creative` ignores `transformer_id`/`config`. Pre-call discriminator for routing across creative agents. |
| `supports_refinement` | boolean | When `true`, this creative agent retains produced `build_variant` leaves (for an agent-defined window) and can re-build from one via `refine_from_build_variant_id` on [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) — applying a natural-language instruction in `message` plus an optional `config` delta, returning new lineage-linked variants. A build-time capability independent of generation/transformation. When `false` or absent, `refine_from_build_variant_id` returns [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature); refine via the transform path (`creative_manifest` + `message`) instead. |
| `refinable_retention_seconds` | integer | When `supports_refinement` is `true`, the **guaranteed-minimum** window (a floor, not a ceiling) during which a produced `build_variant_id` stays refinable via `refine_from_build_variant_id`. A ref within the window SHOULD resolve; the agent MAY retain longer. Omit to leave the window agent-defined (buyers treat refinability as best-effort and handle [`REFERENCE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-reference-not-found)). |
| `multiplicity` | object | Pre-call fan-out discriminators so a buyer knows before sending `max_creatives`/`max_variants`: `supports_catalog_fanout` + `max_creatives_limit`, `supports_variants` + `max_variants_limit`, and `variant_dimensions[]` (which `variant_axis.dimension` values are supported). Over-limit requests are **clamped** to the ceilings (shortfall shown via `items_returned` \< `items_total`), not rejected. Absent means no fan-out — `build_creative` produces a single creative. Individual transformers may narrow this via `transformer.multiplicity`. |
| `supports_spend_controls` | boolean | When `true`, `build_creative` honors a per-call `max_spend` ceiling (returns a partial paid build with `budget_status: "capped"` + a [`BUDGET_CAP_REACHED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-budget-cap-reached) advisory rather than overspending) and supports `mode: "estimate"` dry-runs (a projected cost band, producing/billing nothing). When `false` or absent, both are rejected with `UNSUPPORTED_FEATURE`. Meaningful only with `bills_through_adcp: true`. |
| `localization` | object | Presence advertises materialized source-only or source-plus-target locale topology on [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives)/`list_creatives` and therefore requires `has_creative_library: true`. `locale_matching` is always `rfc4647_lookup`; optional per-creative `locale_fallbacks` provide explicit buyer-approved language-family substitutions, and `max_target_variants` optionally narrows the protocol ceiling of 50 (`0` means source-only). This is a coarse structural capability, not an all-locales promise: accepted ranges are published per product format through `locale_policy`, and the seller validates locale/format/account support per assignment. Advertised support commits the agent to explicit fallback/default/unmatched behavior, creative-wide review, transactional replacement, exact readback, seller-policy precedence, and delivery attribution. It does not request or advertise translation generation. |
| `bills_through_adcp` | boolean | When `true`, this creative agent bills through the AdCP rate-card surface — `list_creatives` returns `pricing_options` (with `include_pricing=true` and an authenticated account), `build_creative` populates `pricing_option_id` and `vendor_cost`, and [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) accepts records against the rate card. When `false` or absent, the agent bills out of band (flat license, SaaS contract, bundled enterprise agreement); buyers should skip pricing fields and tolerate `report_usage` returning `accepted: 0` with [`BILLING_OUT_OF_BAND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-out-of-band) errors. Pre-call discriminator for routing across creative agents. |
### governance
Governance protocol capabilities. Only present if `governance` is in `supported_protocols`. Governance agents declare capabilities across four domains: property evaluation, creative evaluation, content standards verification, and policy registry integration.
#### runtime_attestations
Signal-activation policy layered on the shared `adcp.attestations` allowlist. Presence means this governance agent accepts `check_governance.runtime_attestations[]` when `purchase_type` is `signal_activation`.
| Field | Type | Description |
| - | - | - |
| `signal_activation.requirement` | string | `optional` permits a signal-activation check with no runtime evidence; `required` means omission cannot approve the check. Optional means evidence may be absent, not that supplied invalid evidence becomes trusted. |
| `signal_activation.claim_types` | URI\[] | Signal-quality claims accepted for this action. MUST be a subset of `adcp.attestations.accepted_claim_types`; issuer, resolver, verifier, proof, and delivery policy remains in the shared block. |
See [`check_governance` runtime signal attestations](/dist/docs/3.2.8/governance/campaign/tasks/check_governance#runtime-signal-attestations) for request, evaluation, signed-context, and audit binding.
#### property_features
Array of property features this governance agent can evaluate. See [Property Governance](/dist/docs/3.2.8/governance/property/index).
| Field | Type | Description |
| - | - | - |
| `feature_id` | string | **Required.** Unique identifier (e.g., `mfa_score`, `coppa_certified`). Use `registry:{policy_id}` prefix for features mapped to [Policy Registry](/dist/docs/3.2.8/governance/policy-registry) entries. |
| `type` | string | **Required.** Data type: `binary`, `quantitative`, or `categorical` |
| `range` | object | For quantitative: `{ min, max }` |
| `categories` | string\[] | For categorical: valid values |
| `description` | string | Human-readable description |
| `methodology_url` | string | URL to methodology documentation |
#### creative_features
Array of creative features this governance agent can evaluate. Same field schema as `property_features`. See [Creative Governance](/dist/docs/3.2.8/governance/creative/index).
Creative governance agents evaluate creatives for security, content categorization, and regulatory compliance. Buyers filter creatives by feature requirements — for example, blocking creatives flagged for `auto_redirect` or requiring `registry:eu_ai_act_article_50` compliance.
#### content_standards
Content standards verification capabilities. See [Content Standards](/dist/docs/3.2.8/governance/content-standards/index).
| Field | Type | Description |
| - | - | - |
| `supported` | boolean | Whether this agent can serve as a content standards verification agent |
| `calibration_formats` | string\[] | Artifact asset types this agent can evaluate (e.g., `text`, `image`, `video`, `audio`) |
#### policy_registry
Policy registry integration capabilities. See [Policy Registry](/dist/docs/3.2.8/governance/policy-registry).
| Field | Type | Description |
| - | - | - |
| `supported` | boolean | Whether this agent consumes policies from the AdCP Policy Registry |
| `domains` | string\[] | Governance domains this agent covers (e.g., `campaign`, `property`, `creative`, `content_standards`) |
**Example governance agent response:**
```json theme={null}
{
"$schema": "/schemas/3.2.8/protocol/get-adcp-capabilities-response.json",
"status": "completed",
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
},
"supported_protocols": ["governance"],
"governance": {
"property_features": [
{
"feature_id": "mfa_score",
"type": "quantitative",
"range": { "min": 0, "max": 100 },
"description": "Made For Advertising detection (0=quality content, 100=likely MFA)",
"methodology_url": "https://vendor.example.com/methodology/mfa"
},
{
"feature_id": "coppa_certified",
"type": "binary",
"description": "COPPA compliance certification"
},
{
"feature_id": "registry:uk_hfss",
"type": "binary",
"description": "UK HFSS advertising restrictions compliance"
},
{
"feature_id": "carbon_score",
"type": "quantitative",
"range": { "min": 0, "max": 100 },
"description": "Carbon footprint sustainability score",
"methodology_url": "https://vendor.example.com/methodology/carbon-score"
}
],
"creative_features": [
{
"feature_id": "registry:eu_ai_act_article_50",
"type": "binary",
"description": "EU AI Act Article 50 — AI-generated content disclosure"
},
{
"feature_id": "registry:ca_sb_942",
"type": "binary",
"description": "California SB 942 — AI transparency compliance"
},
{
"feature_id": "auto_redirect",
"type": "binary",
"description": "Detects auto-redirect behavior in creative code"
},
{
"feature_id": "credential_harvest",
"type": "binary",
"description": "Detects credential harvesting patterns"
}
],
"content_standards": {
"supported": true,
"calibration_formats": ["text", "image", "video"]
},
"policy_registry": {
"supported": true,
"domains": ["campaign", "property", "creative", "content_standards"]
}
}
}
```
### measurement_gateway
Experimental buyer-orchestrator role within the measurement protocol. Presence means the orchestrator exposes a controlled task boundary to providers without granting them seller credentials. Orchestrators implementing it include `measurement` in `supported_protocols` and `measurement.gateway` in `experimental_features`.
The first experimental tier deliberately has one interoperable path: providers pull buyer-approved delivery from the orchestrator's `get_media_buy_delivery` task and return one compact assertion through its `provide_performance_feedback` task. Webhook and offline interchange remain future work until their registration, credential, payload, and receipt contracts are defined.
| Field | Type | Description |
| - | - | - |
| `delivery_task` | string | Required constant: `get_media_buy_delivery`. Providers call it on the orchestrator gateway. |
| `feedback_task` | string | Required constant: `provide_performance_feedback`. Providers call it on the orchestrator gateway. |
```json theme={null}
{
"supported_protocols": ["measurement"],
"experimental_features": ["measurement.gateway"],
"measurement_gateway": {
"delivery_task": "get_media_buy_delivery",
"feedback_task": "provide_performance_feedback"
}
}
```
The gateway reuses `get_media_buy_delivery` and `provide_performance_feedback` shapes without claiming `supported_protocols: ["media_buy"]`; the orchestrator is not a seller and does not commit to the seller compliance storyboard.
### measurement
Experimental measurement protocol capabilities. Only present if `measurement` is in `supported_protocols`; agents implementing it must also list `measurement.core` in `experimental_features`. The provider-side surface is currently scoped to catalog discovery plus declaration of compact performance-feedback output. Measurement agents exchange data with a buyer-controlled orchestrator gateway rather than receiving seller credentials. Additional provider tasks and a baseline compliance storyboard should land only for concrete workflows that cannot use the gateway's existing delivery paths.
**Scope.** An agent claiming `measurement` computes one or more quantitative metrics about ad delivery, exposure, or effect (impression verification, viewability, IVT, attention, brand lift, incrementality, outcomes, emissions — vendors define the surface in `metrics[]`). It returns metric definitions and may declare optimizer-ready feedback production, not pricing or coverage (negotiated per buy via `measurement_terms`) or raw/live datasets. Per-buy measured values remain on delivery reports; compact decision signals use `provide_performance_feedback`.
Measurement agents publish a per-metric catalog so buyers know which metrics each vendor offers. This is the canonical source of truth — AgenticAdvertising.org crawls it to populate the federated [measurement-vendor index](/dist/docs/3.2.8/registry/index#measurement-vendor-discovery).
| Field | Type | Description |
| - | - | - |
| `produces_performance_feedback` | boolean | Whether the agent produces compact `provide_performance_feedback` assertions for a buyer-controlled orchestrator gateway. The orchestrator authenticates the provider and decides what to forward to sellers. |
| `metrics` | object\[] | **Required.** Per-metric catalog described below. |
Providers using the first gateway tier consume `get_media_buy_delivery` and produce `provide_performance_feedback`; there are no method-negotiation arrays in this release.
#### metrics
Array of metrics this measurement agent computes.
| Field | Type | Description |
| - | - | - |
| `metric_id` | string | **Required.** Vendor-scoped identifier (`attention_units`, `gco2e_per_impression`, etc.) — matches the `metric_id` populated in `vendor_metric_values` on delivery. The full identity is the tuple `(vendor.domain, vendor.brand_id, metric_id)`. Each `metric_id` MUST be unique within a single agent's catalog. |
| `standard_reference` | string (URI) | Optional URI pointing at the published standard this metric **implements** (IAB Attention Measurement Guidelines, MRC Viewable Impression Measurement, GARM emissions framework). Distinct from `accreditations` below — `standard_reference` is what the metric is built against; `accreditations` is third-party certification of conformance. |
| `accreditations` | object\[] | Optional list of third-party accreditations this metric holds (MRC, ARF, JIC bodies, ABC, BARB, AGOF, etc.). Each entry: `accrediting_body` (required), optional `certification_id`, `valid_until`, `evidence_url`. Buyers asking "is this MRC-accredited?" SHOULD check this array — implementing a standard is not the same as being independently accredited. |
| `unit` | string | Unit of the value when reported in `vendor_metric_values.value` (`score`, `seconds`, `persons`, `gCO2e`, `lift_percent`, `USD`, etc.). Sellers populating `vendor_metric_values.unit` MUST match this declaration. |
| `description` | string | Human-readable description of what the metric measures and any methodology notes. AgenticAdvertising.org and buyer agents normalize across catalogs from this field plus the structured fields above; classification facets are not declared at the metric level. |
| `methodology_url` | string (URI) | URL to vendor's full methodology documentation. Mirrors `governance.property_features[].methodology_url`. |
| `methodology_version` | string | Optional version identifier (semver, ISO date, or vendor-defined string) for the methodology. When present, buyer agents can pin a contracted version via `committed_metrics[].methodology_version` so silent methodology changes are detectable; absence means the vendor does not version their methodology and buyers MUST treat any change as untracked. |
| `ext` | object | Vendor extensions per the AdCP `ext` convention. |
```json Response example theme={null}
{
"measurement": {
"produces_performance_feedback": true,
"metrics": [
{
"metric_id": "attention_units",
"standard_reference": "https://iabtechlab.com/standards/attention-measurement",
"accreditations": [
{
"accrediting_body": "MRC",
"certification_id": "MRC-ATT-2026-001",
"valid_until": "2027-12-31",
"evidence_url": "https://mediaratingcouncil.org/accreditations/attentionvendor"
}
],
"unit": "score",
"description": "Eye-tracking-based attention score (0-100). Computed from a panel of 25K opted-in households.",
"methodology_url": "https://attentionvendor.example/docs/attention-units",
"methodology_version": "v2.1"
},
{
"metric_id": "engagement_seconds",
"unit": "seconds",
"description": "Active dwell time in seconds, measured via in-content telemetry."
}
]
}
}
```
**Discovery vs. settlement.** Buyers MAY hit a measurement agent's `get_adcp_capabilities` directly to see its current catalog (live, canonical, no staleness), or query AgenticAdvertising.org's federated index for cross-vendor aggregation. The index trades a TTL refresh window for cross-vendor speed; live calls trade speed for currency. Both are valid — typically planning queries hit the index, settlement/audit queries hit the agent.
**This is a discovery surface, not a rate card.** The catalog tells buyers *what* a vendor measures and *what standards/accreditations* back it. Pricing per impression, minimum measurable inventory, attribution windows, geographic coverage, and data-freshness SLAs are negotiated per buy through the seller's `measurement_terms` on `create_media_buy` — not through this catalog.
### compliance_testing
Compliance testing capabilities. The presence of this block declares that the agent supports deterministic testing via [`comply_test_controller`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller). Omit the block if the agent does not support compliance testing.
**Production deployments MUST NOT include this block.** `comply_test_controller` is sandbox-only at the deployment level; advertising the capability on a production endpoint is non-conformant even if dispatch is gated. See [Compliance test controller § Sandbox gating](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#sandbox-gating).
| Field | Type | Description |
| - | - | - |
| `scenarios` | string\[] | Compliance testing scenarios this agent supports. Values SHOULD include every canonical controller scenario the agent implements, excluding `list_scenarios` because that value is a discovery operation rather than a test capability. Current canonical values include `force_creative_status`, `force_account_status`, `force_media_buy_status`, `force_create_media_buy_arm`, `force_task_completion`, `force_session_status`, `simulate_delivery`, `simulate_budget_spend`, `seed_rights_grant`, `seed_product`, `seed_pricing_option`, `seed_creative`, `seed_plan`, `seed_media_buy`, `seed_creative_format`, `seed_measurement_catalog`, `query_upstream_traffic`, `query_provenance_audit_observations`, and `force_upstream_unavailable`. Values MAY also include implementation-specific scenarios. Runners MUST treat scenario names as open strings — new scenarios may be added in additive releases. |
Storyboard runners check for the `compliance_testing` block before running deterministic testing steps. If the agent does not include the block, controller-dependent storyboard steps cannot be validated.
Agents that implement `comply_test_controller` SHOULD include the `compliance_testing` capability block and list supported scenarios. Agents that only support a subset of scenarios (e.g., media buy status but not SI sessions) declare only those scenarios — the runner reports unsupported scenario coverage as skipped or partial rather than as a hidden pass.
:::note
Compliance testing is sandbox-only at the deployment level — production deployments MUST NOT advertise this block or expose `comply_test_controller` on any surface. [`FORBIDDEN`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#error-codes) is returned only when an in-sandbox caller passes `params` that reference a non-sandbox account; live-mode probes for the tool by name receive the transport's standard unknown-tool error. See [Sandbox gating](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#sandbox-gating).
:::
### webhook_signing
Declares a seller's webhook-signing posture and maximum delivery-retry horizon. Any seller whose capability surface advertises mutating-webhook emission — including but not limited to `media_buy.reporting_delivery_methods` containing `webhook`, `media_buy.content_standards.supports_webhook_delivery: true`, `media_buy.relationship_notifications.supported: true`, `wholesale_feed_webhooks.supported: true`, `adcp.capability_changes.notifications.supported: true`, or `account.notifications.supported: true` — MUST include this block with `supported: true`. A seller that emits no webhooks at all MAY omit the block entirely; the absence of both mutating-webhook emission in other capabilities and this block is an unambiguous "does not emit webhooks" posture. Buyers read the block at onboarding to determine which algorithms to expect per the [AdCP webhook-signing profile](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-callbacks) and how long delivery and publication evidence must survive. Buyers integrating with a seller that advertises mutating-webhook emission while advertising `supported: false` or omitting this block MUST fail onboarding with a user-actionable error; silent integration with a non-signing-but-webhook-emitting seller is unsafe for any mutating-webhook use case.
| Field | Type | Description |
| - | - | - |
| `supported` | boolean | **Required when the seller advertises mutating-webhook emission elsewhere in its capability surface.** `true` iff the seller signs outbound webhooks. `false` means the seller emits webhooks but does not sign them; buyers MUST fail onboarding. Sellers that emit no webhooks SHOULD omit the entire block rather than set `supported: false` — `false` is reserved for the unsafe posture of unsigned-webhook emission, not absence-of-webhooks. |
| `profile` | string | **Required when `supported: true`.** The profile version string. Currently `"adcp/webhook-signing/v1"`. Future versions bump the string. |
| `algorithms` | string\[] | **Required when `supported: true`.** Subset of `["ed25519", "ecdsa-p256-sha256"]` — the algorithms this seller will sign webhooks with. Matches the webhook-signing verifier allowlist (see [Verifier checklist for webhooks](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-callbacks), step 4). Buyers MUST be prepared to verify any algorithm listed AND MUST reject onboarding with a user-actionable error if an advertised algorithm is outside this enumerated set — a seller advertising an out-of-set algorithm (e.g., `hs256`) is either misconfigured or signalling a non-conforming profile. |
| `legacy_hmac_fallback` | boolean | **Required when `supported: true`.** `true` iff the seller supports the legacy HMAC-SHA256 scheme when the buyer populates `push_notification_config.authentication.credentials`, `accounts[].notification_configs[].authentication.credentials`, `sync_principal.configuration.notification_configs[].authentication.credentials`, or `sync_agent_notification_configs.notification_configs[].authentication.credentials`. `false` is the recommended posture in 3.x — the HMAC scheme is removed in AdCP 4.0. |
| `delivery_retry_horizon_seconds` | integer | **Required when a 3.2 agent declares `supported: true`.** Maximum interval from the first attempt during which the seller may retry one delivery. Minimum `86400` (24h), maximum `604800` (7d). The seller retains the immutable delivery-key-to-payload binding for this interval and does not extend it on retry. A 3.x receiver retains its matching binding and terminal publication proof for at least the greater of 24h and this value. This delivery property is nested here because all conformant 3.2 webhook emitters declare the signing profile; a future non-9421 delivery profile will require a transport-neutral capability location. |
**Example:**
```json theme={null}
{
"webhook_signing": {
"supported": true,
"profile": "adcp/webhook-signing/v1",
"algorithms": ["ed25519", "ecdsa-p256-sha256"],
"legacy_hmac_fallback": false,
"delivery_retry_horizon_seconds": 86400
}
}
```
The webhook-signing block is parallel to `request_signing` (inbound) and the two blocks cover the two signing directions between buyer and seller. Buyers SHOULD validate both at onboarding; a seller that signs one direction but not the other has a lopsided security posture that operators need to notice explicitly.
### extensions_supported
Array of extension namespaces this agent supports. Buyers can expect meaningful data in `ext.{namespace}` fields on responses from this agent.
| Field | Type | Description |
| - | - | - |
| `extensions_supported` | string\[] | Extension namespaces (e.g., `["iab_tcf", "iab_gpp"]`) |
Extension schemas are published in the [AdCP extension registry](/dist/docs/3.2.8/building/by-layer/L2/context-sessions#extensions). When an agent declares support for an extension, buyers know to look for and process `ext.{namespace}` data in responses.
**Example:**
```json theme={null}
{
"extensions_supported": ["iab_tcf", "iab_gpp", "acmecorp"]
}
```
This tells buyers:
* Responses may include `ext.iab_tcf` with IAB TCF consent data
* Responses may include `ext.iab_gpp` with IAB GPP (Global Privacy Platform) signals
* Responses may include `ext.acmecorp` with vendor-specific data from Acme Corp
### experimental_features
Array of experimental AdCP surfaces this agent implements. A surface is experimental when its schema carries `x-status: experimental` — it is part of the core protocol but not yet frozen and may break between 3.x releases with 6 weeks' notice. Sellers that implement any experimental surface MUST list its feature id here.
| Field | Type | Description |
| - | - | - |
| `experimental_features` | string\[] | Experimental feature ids (e.g., `["brand.rights_lifecycle", "governance.campaign", "measurement.core", "trusted_match.core", "sponsored_intelligence.core"]`) |
Buyers should inspect `experimental_features` before relying on an experimental surface. A seller that does not list a surface is asserting it does not implement it — there is no "silently experimental" mode.
**Example:**
```json theme={null}
{
"experimental_features": [
"brand.rights_lifecycle",
"measurement.core",
"trusted_match.core"
]
}
```
See [experimental status](/dist/docs/3.2.8/reference/experimental-status) for the full stability contract, graduation criteria, and client guidance.
### wholesale_feed_versioning
Conditional-fetch token capabilities for [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products#wholesale-feed-versioning) and [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals#wholesale-feed-versioning). Independent of wholesale feed webhooks: an agent MAY support cheap version probes without pushing change payloads, and an agent MAY push change payloads while still requiring reconciliation reads for repair.
| Field | Type | Description |
| - | - | - |
| `supported` | boolean | **Required.** Whether the agent returns `wholesale_feed_version` on responses and honors `if_wholesale_feed_version` on requests. When absent or `false`, buyers can still probe by reading the response (the field-presence detection path) but can't pre-flight-decide which agents to cache versions for. |
| `pricing_version_separate` | boolean | Whether the agent tracks `pricing_version` independently of `wholesale_feed_version`. When `true`, callers can send `if_pricing_version` alongside `if_wholesale_feed_version` for finer-grained "did prices change?" probes. When `false` or absent, the agent collapses both into `wholesale_feed_version` — sending `if_pricing_version` is wasted bytes. |
| `cache_scope_account` | boolean | Whether the agent ever returns `cache_scope: "account"` (i.e., publishes per-account overlays distinct from the public rate card). When `true`, buyers MUST be prepared to maintain account-overlay caches alongside the public layer. When `false` or absent, all responses are `cache_scope: "public"` — the agent's rate card is universal across accounts. Note: declaring `true` advertises that the agent runs custom-pricing deals, which is itself a small market-posture signal; agents preferring confidentiality MAY omit the field and detect-on-call instead. |
**Example:**
```json theme={null}
{
"wholesale_feed_versioning": {
"supported": true,
"pricing_version_separate": true,
"cache_scope_account": true
}
}
```
### wholesale_feed_webhooks
Per-agent wholesale product-feed and wholesale signals-feed webhook capabilities. Declared by sales agents (products) and signals agents (signals). When `supported` is `true`, consumers can register `sync_accounts.accounts[].notification_configs[]` entries for `product.*`, `signal.*`, and `wholesale_feed.bulk_change` events and receive the actual change payload in each webhook. See `specs/wholesale-feed-webhooks.md` for the full spec.
**Terminology.** Here "wholesale feed" means the agent's buyable wholesale product feed and wholesale signals feed exposed by `get_products` and `get_signals`. It is distinct from `sync_catalogs`, which pushes buyer-provided campaign input feeds into a seller account for campaign execution.
Complementary to (and independent of) [`wholesale_feed_versioning`](#wholesale_feed_versioning): webhooks push changed products/signals or bulk-change summaries; version tokens give a cheap repair and reconciliation probe. Adopters MAY ship either, both, or neither.
Agents that declare `supported: true` MUST apply the same account/caller authorization and scope predicate used by the corresponding wholesale read before emitting each webhook. A caller that could not see a product, signal, price, or account overlay through `get_products buying_mode: "wholesale"` or `get_signals discovery_mode: "wholesale"` MUST NOT receive a webhook revealing that change. Agents unable to guarantee per-principal filtering MUST NOT declare support.
**Capability consistency.** Agents listing any `product.*` value in `event_types[]` MUST declare and support wholesale `get_products` (`media_buy.buying_modes` includes `"wholesale"`). Agents listing any `signal.*` value MUST declare and support wholesale `get_signals` (`signals.discovery_modes` includes `"wholesale"`). Agents listing `wholesale_feed.bulk_change` MUST have at least one of those wholesale repair paths, and each bulk-change payload's `affected_entity_type` MUST name only a feed family the agent can repair through a declared wholesale read.
**Consumer precedence.** When more than one mechanism is declared, consumers SHOULD prefer them in this order: (1) `wholesale_feed_webhooks` when maintaining a long-lived mirror (lowest latency, lowest seller cost); (2) `wholesale_feed_versioning` conditional fetch for occasional polling and webhook repair; (3) wholesale enumeration via `buying_modes` / `discovery_modes` for cold start, `wholesale_feed.bulk_change`, or any missed/distrusted push.
| Field | Type | Description |
| - | - | - |
| `supported` | boolean | **Required.** Whether this agent can push wholesale feed change payloads through account-level `sync_accounts.accounts[].notification_configs[]`. When `false` or this stanza is absent, consumers fall back to wholesale polling, optionally with `if_wholesale_feed_version` probes. |
| `event_types` | string\[] | Event types this agent can emit. Sales agents emit `product.*` events; signals agents emit `signal.*` events; agents that are both can emit both event families. `product.*` requires wholesale `get_products`; `signal.*` requires wholesale `get_signals`; `wholesale_feed.bulk_change` requires at least one declared wholesale repair path and names one affected feed the consumer repairs by re-reading via `get_products` or `get_signals`. |
**Example (sales + signals agent):**
```json theme={null}
{
"wholesale_feed_webhooks": {
"supported": true,
"event_types": [
"product.created",
"product.updated",
"product.priced",
"product.removed",
"signal.created",
"signal.updated",
"signal.priced",
"signal.removed",
"wholesale_feed.bulk_change"
]
}
}
```
## The Capability Contract
**If a capability is declared, the seller MUST honor it.**
* `media_buy.execution.targeting.geo_postal_areas.US` contains `zip` → Buyer can send `{ country: "US", system: "zip", values: [...] }`, seller MUST honor it
* `media_buy.execution.targeting.geo_postal_areas.us_zip: true` → Buyer can send the deprecated `{ system: "us_zip", values: [...] }` form, and SDKs can backfill the native `{ country: "US", system: "zip", values: [...] }` form
* `media_buy.execution.targeting.geo_postal_areas.ZA` contains `postal_code` → Buyer can send normal South African postal codes, seller MUST honor them
* `media_buy.execution.targeting.geo_metros.nielsen_dma: true` → Buyer can send DMA codes, seller MUST honor them
* `media_buy.execution.targeting.demographics.supported: true` → At least one product supports canonical demographic targeting; this rollup does not authorize the field on every product, so buyers MUST inspect `Product.demographic_targeting`
* `media_buy.execution.targeting.collection_list: true` → At least one product supports collection inclusion; inspect that product's `overlay_support.collection_list` before selecting values later
* `media_buy.execution.targeting.collection_list_exclude: true` → At least one product supports collection exclusion; inspect that product's `overlay_support.collection_list_exclude`
* `media_buy.execution.targeting.property_list: true` → At least one product supports property inclusion; inspect that product's `overlay_support.property_list`
* `media_buy.execution.targeting.property_list_exclude: true` → At least one product supports property exclusion; inspect that product's `overlay_support.property_list_exclude`
* `media_buy.execution.targeting.placement_selection: true` → At least one product supports purchased-placement selection; inspect that product's targetable placements and `overlay_support.placement_selection`
* `media_buy.content_standards` object present → Seller MUST apply content standards when provided
* `media_buy.audience_targeting` object present → Seller MUST support [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) and audience targeting overlays
* `media_buy.conversion_tracking` object present → Seller MUST support [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) and [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event)
* AXE URL in `media_buy.execution.axe_integrations` → Seller can execute through that exchange (legacy — new integrations use [TMP](/dist/docs/3.2.8/trusted-match))
No silent ignoring. If a seller can't support a capability, they should declare `false` or omit it.
## Common Scenarios
### Basic Capability Discovery
```javascript theme={null}
import { AdcpClient } from "@adcp/sdk";
const client = new AdcpClient({ baseUrl: "https://seller.example.com/mcp" });
// Get seller capabilities
const result = await client.getAdcpCapabilities({});
if (result.errors) {
throw new Error(`Request failed: ${result.errors[0].message}`);
}
// Check protocol support
console.log(`AdCP versions: ${result.adcp.major_versions.join(", ")}`);
console.log(`Supported protocols: ${result.supported_protocols.join(", ")}`);
// Check media-buy capabilities
if (result.supported_protocols.includes("media_buy")) {
const mediaBuy = result.media_buy;
// Check content standards support (object presence = signal)
if (mediaBuy.content_standards) {
console.log("Content standards supported");
}
// Check AXE integrations (legacy — new integrations use TMP via trusted_match on products)
if (
mediaBuy.execution?.axe_integrations?.includes("https://axe.example.com")
) {
console.log("AXE integration available");
}
// Check geo targeting (normalize native country keys and deprecated aliases)
const postalSupport = mediaBuy.execution?.targeting?.geo_postal_areas;
if (postalSupport?.US?.includes("zip") || postalSupport?.us_zip === true) {
console.log("US ZIP code targeting supported");
}
// Portfolio overview
console.log(`Publishers: ${mediaBuy.portfolio.publisher_domains.length}`);
console.log(`Channels: ${mediaBuy.portfolio.primary_channels?.join(", ")}`);
}
```
### Check multi-protocol support
```javascript theme={null}
const caps = await client.getAdcpCapabilities({});
const sellsMedia = caps.supported_protocols.includes("media_buy");
const managesCreatives = caps.supported_protocols.includes("creative");
if (sellsMedia && managesCreatives) {
// Single agent handles both protocols — no need to discover a separate service
const formats = await client.listCreativeFormats({});
const delivery = await client.getCreativeDelivery({
media_buy_ids: ["mb_12345"],
});
}
```
### Filter sellers by capability
```javascript theme={null}
// Find sellers that support specific requirements
async function findCompatibleSellers(sellers, requirements) {
const compatible = [];
for (const sellerUrl of sellers) {
const client = new AdcpClient({ baseUrl: sellerUrl });
const caps = await client.getAdcpCapabilities({});
if (caps.errors) continue;
// Must support media_buy protocol
if (!caps.supported_protocols.includes("media_buy")) continue;
const mediaBuy = caps.media_buy;
// Check AXE integration requirement (legacy — new integrations use TMP)
if (requirements.axeIntegration) {
if (
!mediaBuy.execution?.axe_integrations?.includes(
requirements.axeIntegration
)
) {
continue;
}
}
// Check geo targeting requirement
if (requirements.postalCodeTargeting) {
const postalSupport = mediaBuy.execution?.targeting?.geo_postal_areas;
if (
!(postalSupport?.US?.includes("zip") || postalSupport?.us_zip === true)
) {
continue;
}
}
// Check content standards requirement (object presence = signal)
if (requirements.contentStandards) {
if (!mediaBuy.content_standards) {
continue;
}
}
compatible.push({ url: sellerUrl, capabilities: caps });
}
return compatible;
}
// Usage
const sellers = await findCompatibleSellers(
["https://seller1.com/mcp", "https://seller2.com/mcp"],
{
axeIntegration: "https://axe.example.com",
postalCodeTargeting: true,
contentStandards: true,
}
);
```
### Use Capabilities to Build Targeting
Seller capabilities are a routing rollup. Use `required_overlay_support` to
request the product-scoped targeting surface that must be selectable later, and
`targeting_overlay` for concrete constraints that must affect discovery:
```javascript theme={null}
// First, check capabilities
const caps = await client.getAdcpCapabilities({});
if (!caps.supported_protocols.includes("media_buy")) {
throw new Error("Seller does not support media_buy protocol");
}
const mediaBuy = caps.media_buy;
const postalSupport = mediaBuy.execution?.targeting?.geo_postal_areas;
// Filter products to sellers with specific geo targeting capabilities
const products = await client.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655442047',
buying_mode: 'brief',
brief: "Premium video inventory in US for ZIP-targeted campaign",
filters: { channels: ['olv', 'ctv'] },
targeting_overlay: { geo_countries: ['US'] },
required_overlay_support: {
geo_postal_areas: { US: ['zip'] }
}
});
// Then, create media buy with fine-grained targeting
// (if seller supports postal areas, we can target specific ZIP codes)
const buy = await client.createMediaBuy({
brand: { domain: 'mybrand.com' },
packages: [{
product_id: products.products[0].product_id,
pricing_option_id: products.products[0].pricing_options[0].id,
budget: 10000,
// The configured product already represents US targeting. Add the ZIP
// selection the buyer deferred during discovery.
targeting_overlay: {
geo_countries: ['US'],
// Only specify ZIP targeting if seller supports it
...((postalSupport?.US?.includes('zip') || postalSupport?.us_zip === true) && {
geo_postal_areas: [{
country: 'US',
system: 'zip',
values: ['10001', '10002', '10003', '10004', '10005']
}]
})
}
}],
start_time: { type: 'asap' },
end_time: '2025-03-01T00:00:00Z'
});
```
**Two models for product geography:**
| Inventory Type | Filter By | Example |
| - | - | - |
| Digital (display, OLV, CTV) | Capability: `required_geo_targeting` | Products have broad coverage, target at buy time |
| Local (radio, DOOH, local TV) | Coverage: `metros`, `regions` | Products ARE geographically bound |
* **Digital inventory**: Use `countries` + `required_geo_targeting` (capability), apply fine-grained targeting in [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy)
* **Local inventory**: Use `metros`/`regions` (coverage) to find products with coverage in your target markets
### Local Inventory Example (Radio, DOOH)
For locally-bound inventory, products ARE geographically specific. A radio station in NYC DMA only covers NYC.
```javascript theme={null}
// Find radio products in specific DMAs
const radioProducts = await client.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655442048',
buying_mode: 'brief',
brief: "Radio inventory in NYC and LA markets",
filters: {
channels: ["radio"],
// Coverage filter: products must cover these metros
metros: [
{ system: "nielsen_dma", code: "501" }, // NYC
{ system: "nielsen_dma", code: "803" }, // LA
],
},
});
// For local inventory, targeting_overlay is optional -
// the product's coverage IS the geography
const buy = await client.createMediaBuy({
brand: { domain: "mybrand.com" },
packages: [
{
product_id: radioProducts.products[0].product_id,
pricing_option_id: radioProducts.products[0].pricing_options[0].id,
budget: 5000,
// No targeting_overlay needed - product covers NYC DMA
},
],
start_time: { type: "asap" },
end_time: "2025-03-01T00:00:00Z",
});
```
## Response Example
```json theme={null}
{
"$schema": "/schemas/3.2.8/protocol/get-adcp-capabilities-response.json",
"status": "completed",
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
},
"supported_protocols": ["media_buy"],
"experimental_features": ["media_buy.audience_activation"],
"account": {
"require_operator_auth": false,
"supported_billing": ["operator", "agent"],
"supported_account_currency_modes": ["fixed", "per_media_buy"],
"timezone": { "mode": "seller_fixed", "fixed_timezone": "UTC" }
},
"media_buy": {
"creative_approval_mode": "auto_approve",
"features": {
"inline_creative_management": true,
"property_list_filtering": true,
"seller_optimized_budget": true,
"bidding_policy": {
"media_buy": {
"fixed": {
"modes": ["max_bid", "cost_per"],
"cost_per_strengths": ["cap", "target"],
"supported_combinations": [
{
"kind": "max_bid_with_cost_per",
"cost_per_strengths": ["cap"]
}
]
},
"seller_optimized": {
"modes": ["cost_per"],
"cost_per_strengths": ["cap"]
}
},
"package": {
"fixed": {
"modes": ["automatic", "bid_amount", "cost_per"],
"cost_per_strengths": ["cap"]
},
"seller_optimized": {
"modes": ["automatic"]
}
}
}
},
"execution": {
"axe_integrations": ["https://axe.example.com"],
"creative_specs": {
"vast_versions": ["4.0", "4.1", "4.2", "4.3"],
"macro_resolution_capabilities": [
{
"dialect": "adcp",
"dialect_semantic": "GDPR_CONSENT",
"mapping_status": "verified_universal",
"universal_semantic": "GDPR_CONSENT",
"operation": "resolve_value",
"performed_by": "seller",
"supported_contexts": ["url_query_value"],
"supported_encodings": [{ "kind": "rfc3986", "depth": 1 }]
},
{
"dialect": "iab_vast",
"dialect_namespace": "https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html",
"dialect_revision": "git:e0858cd714474bf17ef61065097456d7643ff838",
"dialect_semantic": "PLAYERSTATE",
"mapping_status": "dialect_defined",
"operation": "resolve_value",
"performed_by": "request_executor",
"supported_contexts": ["url_query_value"],
"supported_encodings": [{ "kind": "iab_vast_uri", "depth": 1 }]
}
],
"mraid_versions": ["3.0"],
"vpaid": false,
"simid": true
},
"targeting": {
"geo_countries": true,
"geo_regions": true,
"geo_metros": {
"nielsen_dma": true
},
"geo_postal_areas": {
"us_zip": true,
"us_zip_plus_four": true,
"US": ["zip", "zip_plus_four"],
"GB": ["outward", "full"],
"CA": ["fsa", "full"],
"ZA": ["postal_code"]
},
"geo_places": {
"geonames": {
"countries": {
"US": ["city", "county"],
"NL": ["city", "municipality"],
"GB": ["city", "post_town"]
},
"catalog": {
"source": "https://seller.example/data-sources/geonames-mirror",
"current_version": "2026-05",
"supported_versions": ["2026-05", "2026-04"],
"resolver": {
"url": "https://seller.example/adcp/geo/resolve/geonames",
"auth": "seller_credentials",
"protocol": "adcp_geo_place_resolver_v1"
}
}
},
"https://seller.example/geo/catalogs/places": {
"countries": {
"NL": ["city"]
},
"catalog": {
"current_version": "2026-q2",
"supported_versions": ["2026-q2"],
"resolver": {
"url": "https://seller.example/adcp/geo/resolve/private",
"auth": "seller_credentials",
"protocol": "adcp_geo_place_resolver_v1"
}
}
}
},
"language": {
"supported": true,
"supported_languages": ["en", "fr-CA", "es"]
},
"keyword_targets": {
"supported_match_types": ["broad", "phrase", "exact"]
},
"negative_keywords": {
"supported_match_types": ["broad", "exact"]
}
}
},
"content_standards": {
"supports_local_evaluation": true,
"supported_channels": ["display", "olv"],
"supports_webhook_delivery": false
},
"audience_targeting": {
"supported_identifier_types": ["hashed_email", "hashed_phone"],
"supports_platform_customer_id": false,
"supported_uid_types": ["uid2", "rampid"],
"minimum_audience_size": 500,
"matching_latency_hours": { "min": 1, "max": 24 },
"supported_activation_methods": [
{ "pattern": "sync_audiences" },
{
"pattern": "dataset_query",
"vendor": { "domain": "data-cloud.example" },
"consumer_identities": [
{ "cloud": "aws", "region": "us-east-1", "identity": "SELLERORG.ADCP_INGEST" }
]
},
{
"pattern": "platform_distribution",
"vendor": { "domain": "activation-hub.example" },
"destination_ref": "dest_12345",
"bind_expiry_days": 14
}
]
},
"conversion_tracking": {
"multi_source_event_dedup": false,
"supported_event_types": [
"purchase",
"lead",
"add_to_cart",
"view_content"
],
"supported_action_sources": ["website", "app"],
"attribution_windows": [
{
"post_click": [
{ "interval": 7, "unit": "days" },
{ "interval": 28, "unit": "days" }
],
"post_view": [
{ "interval": 1, "unit": "days" },
{ "interval": 7, "unit": "days" }
]
}
]
},
"portfolio": {
"publisher_domains": ["example.com", "news.example.com"],
"primary_channels": ["display", "olv"],
"primary_countries": ["US", "CA"]
}
},
"extensions_supported": ["acmecorp"],
"last_updated": "2025-01-23T10:00:00Z"
}
```
This tells buyers:
* **AdCP versions**: Version 1
* **Protocols**: Media buy only
* **Auth model**: Agent-trusted (`require_operator_auth: false`) — authenticate once and use natural-key accounts, normally declared via [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts)
* **Billing**: Operator or agent billing; default is operator
* **Country targeting**: Available (ISO 3166-1 alpha-2: `US`, `GB`, etc.)
* **Region targeting**: Available (ISO 3166-2: `US-NY`, `GB-SCT`, etc.)
* **Metro targeting**: Nielsen DMA only (US market)
* **Postal targeting**: US ZIP, UK outward codes, Canadian FSA
* **Audience targeting**: Accepts hashed email, hashed phone, UID2, and RampID; minimum matched audience size of 500; matching latency 1–24 hours
* **Conversion tracking**: Accepts purchase, lead, add_to_cart, view_content events from website/app; no multi-source dedup
* **Extensions**: Vendor-specific data in `ext.acmecorp`
### Multi-protocol agent
An agent can implement multiple protocols from a single endpoint. This is common for sellers that manage both media buying and creative generation — the buyer calls all tasks on the same URL.
```json theme={null}
{
"$schema": "/schemas/3.2.8/protocol/get-adcp-capabilities-response.json",
"status": "completed",
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
"capability_changes": {
"capabilities_version": "rev_20260702_091455",
"last_modified": "2026-07-02T09:14:55Z",
"cache_ttl_seconds": 3600,
"notifications": {
"supported": true,
"registration_task": "sync_agent_notification_configs",
"event_types": ["capabilities.changed"]
}
}
},
"supported_protocols": ["media_buy", "creative"],
"account": {
"require_operator_auth": false,
"supported_billing": ["operator"],
"supported_account_currency_modes": ["fixed"],
"timezone": { "mode": "seller_fixed", "fixed_timezone": "UTC" }
},
"media_buy": {
"anonymous_discovery": true,
"creative_approval_mode": "require_human",
"features": {
"inline_creative_management": true
},
"portfolio": {
"publisher_domains": ["news.example.com"],
"primary_channels": ["display", "olv"]
}
},
"creative": {
"has_creative_library": true,
"supports_generation": true,
"supports_transformation": false,
"representation_resolution": {
"supported": true,
"strategies": ["representation_order", "highest_compatible_vast"]
},
"supports_compliance": false,
"bills_through_adcp": true,
"supported_formats": [
{
"capability_id": "display_image_generator",
"operations": ["build", "validate", "preview"],
"format": {
"format_kind": "image",
"params": { "width": 300, "height": 250 }
}
}
],
"preview": {
"routes": [{
"capability_id": "display_image_generator",
"rendering_origin": "platform_native"
}]
}
}
}
```
This agent supports:
* **Media Buy Protocol**: Product discovery, media buying, delivery reporting
* **Creative Protocol**: Creative library management, AI-powered creative generation, variant-level delivery analytics via [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery)
* **Delivery representation resolution**: Deterministic selection from a `CreativeRepresentationSet` by the destination sales agent; absence of `representation_resolution` means callers must select before sending a seller-bound manifest, and standalone creative agents cannot claim seller deliverability
* **Shared account**: A single account established via `sync_accounts` applies to both protocols
When `supported_protocols` includes `"creative"`, inspect the `creative` capability block for the tasks and canonical formats this endpoint actually supports. [`list_creative_formats`](/dist/docs/3.2.8/creative/task-reference/list_creative_formats) is deprecated in 3.2. See [Creative capabilities on sales agents](/dist/docs/3.2.8/creative/sales-agent-creative-capabilities).
### Geo Standards Reference
| Level | System | Examples |
| - | - | - |
| Country | ISO 3166-1 alpha-2 | `US`, `GB`, `DE`, `CA` |
| Region | ISO 3166-2 | `US-NY`, `GB-SCT`, `DE-BY`, `CA-ON` |
| Metro (US) | `nielsen_dma` | `501` (NYC), `803` (LA), `602` (Chicago) |
| Metro (UK) | `uk_itl2` | `UKI` (London), `UKD` (North West) |
| Metro (EU) | `eurostat_nuts2` | `DE30` (Berlin), `FR10` (Île-de-France) |
| Postal (US) | `US` / `zip` | `10001`, `90210` |
| Postal (US) | `US` / `zip_plus_four` | `10001-1234` |
| Postal (UK) | `GB` / `outward` | `SW1`, `EC1`, `M1` |
| Postal (UK) | `GB` / `full` | `SW1A 1AA` |
| Postal (CA) | `CA` / `fsa` | `K1A`, `M5V` |
## Migration from list_authorized_properties (v2)
The `list_authorized_properties` task was removed in v3. If migrating from v2:
| Old Field | New Location |
| - | - |
| `publisher_domains` | `media_buy.portfolio.publisher_domains` |
| `primary_channels` | `media_buy.portfolio.primary_channels` |
| `primary_countries` | `media_buy.portfolio.primary_countries` |
| `portfolio_description` | `media_buy.portfolio.description` |
| `advertising_policies` | `media_buy.portfolio.advertising_policies` |
| `last_updated` | `last_updated` (top level) |
New fields:
* `adcp.major_versions` - Version compatibility
* `supported_protocols` - Which domain protocols are supported
* `media_buy.features` - Optional feature support
* `media_buy.execution.axe_integrations` - Ad exchange support
* `media_buy.execution.creative_specs` - VAST/MRAID versions
* `media_buy.execution.targeting` - Geo targeting granularity
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing) | No credentials presented | Provide credentials via auth header |
| [`AUTH_INVALID`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-invalid) | Credentials rejected (expired / revoked) | Human credential rotation required |
| [`VERSION_UNSUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-version-unsupported) | Declared `adcp_major_version` not in seller's `major_versions` | Call without `adcp_major_version` to discover supported versions, then retry |
| [`SERVICE_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-service-unavailable) | Temporary service or dependency failure | Retry with backoff |
## Best Practices
**1. Cache Capabilities**
Capabilities rarely change. Cache results for no longer than `adcp.capability_changes.cache_ttl_seconds` when present, compare `capabilities_version` on refresh when present, and subscribe to `capabilities.changed` if the seller advertises notification support. When notifications are enabled, `capabilities_version` is the required read-after-notify fence; retry refresh if a webhook revision is not yet observable. Fall back to `last_modified` or legacy `last_updated` only when `capability_changes.notifications.supported` is absent or false.
**2. Check Protocol Support First**
Before accessing protocol-specific fields, verify the protocol is in `supported_protocols`.
**3. Check Before Requesting**
Don't send postal areas for a system the seller doesn't support. Don't request features the seller doesn't support.
**4. Fail Fast on Incompatibility**
If a seller doesn't support required capabilities, skip them early rather than discovering failures later.
**5. Read the Auth Model Before Proceeding**
Check `account.require_operator_auth` immediately after discovery. Agent-trusted and operator-scoped flows diverge significantly: the former uses a single credential for all brands and operators, the latter requires per-operator credentials and sessions.
**6. Use Protocol Version for Routing**
Route requests to appropriate API versions based on `adcp.major_versions`.
## Next Steps
After discovering capabilities:
1. **Set up accounts**: Follow the auth model from `account.require_operator_auth` — see [Accounts and Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#what-sellers-declare)
2. **Filter products**: Use [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) with capability-aware filters
3. **Validate properties**: Fetch publisher `adagents.json` files for property definitions
4. **Create buys**: Use [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) with supported features
## Learn More
* [Accounts and Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) - Auth models, account setup, billing
* [adagents.json Specification](/dist/docs/3.2.8/governance/property/adagents) - Publisher authorization files
* [Product Filters](/dist/docs/3.2.8/media-buy/task-reference/get_products#filters) - Capability-aware filtering
* [Content Standards](/dist/docs/3.2.8/governance/content-standards) - Brand safety configuration
# get_principal
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/get_principal
get_principal reads the authenticated caller's seller-resolved identity, principal configuration, version, and destination setup states.
`get_principal` returns the authenticated caller's seller-resolved durable identity and current principal configuration with one AdCP agent: the same caller-scoped state that [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) replaces, plus retained superseded and revoked destination generations. A recognized durable identity remains readable before the caller has standing configuration.
The read is side-effect free. It never creates a principal record, issues identifiers, sends endpoint proof challenges, mutates state, or advances `configuration_version`.
For the full lifecycle from credentials through destination proof and readback, see [Set up your buyer agent with a seller](/dist/docs/3.2.8/accounts/principal-registration-walkthrough).
**Request schema:** [`/schemas/3.2.1/protocol/get-principal-request.json`](https://adcontextprotocol.org/schemas/3.2.1/protocol/get-principal-request.json)
**Response schema:** [`/schemas/3.2.1/protocol/get-principal-response.json`](https://adcontextprotocol.org/schemas/3.2.1/protocol/get-principal-response.json)
## When to call
Call it whenever you need current state rather than a change:
* **Verify identity before configuration.** A `recognized` result exposes the seller-resolved `principal_kind` and existing `principal_id` before the first state-changing call.
* **Bootstrap the concurrency fence.** Read `configuration_version` before a guarded [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) replacement instead of writing blind.
* **Recover after local-state loss.** A restarted service reads `principal_id`, `configuration_version`, every `destination_ref`, and each destination's setup state before deciding what to sync.
* **Observe setup progress.** After a destination returns `action_required` or `validating`, poll here until it reaches `ready` — or subscribe to the `principal.changed` webhook and use this read as the repair path. Polling never disturbs the version fence.
* **Read the negotiated async contract.** The `declarations` state carries both the declared set and the seller-computed accepted intersection that governs webhook payload versions and signing algorithms.
* **Audit generations.** Superseded generations appear in each destination's `prior_destination_refs`; revoked destinations appear in `retired_destinations`. Both remain resolvable for existing authorized account bindings and retained reporting history.
Only call this task when [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) advertises `adcp.principal` with `read_task: "get_principal"`. Sellers advertising `principal` implement both the sync and read tasks.
## Identity
Identity resolution is identical to [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal): the seller resolves the stable authenticated principal from transport and ignores every request-body field for identity and authorization. The request body carries no parameters beyond the protocol envelope.
For RFC 9421 signed callers, that stable identity is the canonical URL of the exactly matched operator `brand.json` `agents[]` entry after publication and key verification. Rotation to another key authorized for the same canonical Agent URL preserves the principal; a domain, JWKS URI, or key never replaces the Agent URL as the subject.
`principal_kind` is resolved from authorization state, but the response exposes it only with a durable principal record: in `current` and `recognized` results. `principal_id` identifies that same record in both arms. A read never creates the record or mints the identifier; stable authentication without a materialized durable record remains the exact kind-only `unconfigured` result.
## Results
| `result.kind` | Meaning |
| - | - |
| `current` | The caller has standing configuration. Returns `principal_id`, the seller-resolved `principal_kind` (`buyer_agent` or `operator`), `configuration_version`, and complete credential-free configuration state. |
| `recognized` | The caller maps to an existing durable principal record but has no standing configuration. Returns `principal_id` and seller-resolved `principal_kind`, with no configuration or version. |
| `unconfigured` | Stable authentication succeeded, but the caller has no durable principal record. Carries only `kind`. |
| `failed` | The read could not be served. Carries only structured errors, never identifiers or state. |
The response reveals only the authenticated caller's identity and state. It never exposes whether another principal exists or has configuration, and `failed` results carry no identity facts.
Before configuration, a registered buyer agent with a durable principal record receives:
```json theme={null}
{
"status": "completed",
"result": {
"kind": "recognized",
"principal_kind": "buyer_agent",
"principal_id": "prin_01K4C6RGT5Q18VCPGXE7DDWQ5F"
}
}
```
An authenticated caller with no durable record receives the existing result without an invented identifier or exposed party kind:
```json theme={null}
{
"status": "completed",
"result": {
"kind": "unconfigured"
}
}
```
```json theme={null}
{
"status": "completed",
"result": {
"kind": "current",
"principal_id": "prin_01K4C6RGT5Q18VCPGXE7DDWQ5F",
"principal_kind": "buyer_agent",
"configuration_version": "cfg_01K4C6V2N5PC1TQAH9WTT8D2HP",
"configuration": {
"notification_configs": [],
"reporting_destinations": [
{
"destination_id": "analytics-warehouse",
"destination_ref": "dest_01K4C6T6Q0A9E6Y3N1FQ1T8YKV",
"prior_destination_refs": ["dest_01K4C5A2M9XPZ0T4B7QCW3JHRD"],
"state": "ready",
"configuration": {
"pattern": "warehouse_materialization",
"destination_id": "analytics-warehouse",
"active": true,
"provider": { "domain": "data-warehouse.example" },
"transport": "bigquery",
"location": "pinnacle-analytics.adcp_reporting",
"accepted_verification_profiles": ["native_commit", "canonical_digest"]
}
}
]
}
}
}
```
Seller-driven setup-state transitions observed through this task — a destination moving from `validating` to `ready`, a refreshed `setup.expires_at` — do not advance `configuration_version`. Only successful configuration mutations through [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) or [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) advance it.
# Language and localization
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/language-and-localization
The shared language-tag contract and the distinct patterns AdCP uses for agent input, agent responses, published multilingual content, and executable creative.
# Language and localization
AdCP uses one shared language-identity primitive, but it does not use one
universal localization topology. An agent declaring what language it can parse,
a caller requesting response text, a publisher releasing multilingual content,
and a seller trafficking executable creative have different lifecycle and
failure requirements.
This page defines the reusable architecture for those surfaces. It does not add
the pending negotiation or published-content fields tracked in
[#3658](https://github.com/adcontextprotocol/adcp/issues/3658) and
[#3668](https://github.com/adcontextprotocol/adcp/issues/3668). The materialized
creative contract is the first implementation of these shared rules, not a
template that every other localization concern must copy.
## One language-tag primitive
`/schemas/core/locale-tag.json` is the shared AdCP schema for BCP 47 language
identity. The historical file name is retained for wire compatibility, but the
concept is a **language tag**, not a general locale-settings object. It does not
determine currency, time zone, number or date formatting, market, or legal
jurisdiction.
Every new AdCP field that carries a BCP 47 language identity or concrete
language range MUST reference this schema. A surface MUST NOT redeclare a plain
string with its own BCP 47 wording, pattern, or casing behavior. This prevents a
tag such as `FR-ca` from being accepted by one task and rejected by another.
The shared schema applies the AdCP canonical wire profile: lower-case language
and variants, title-case script, and upper-case region. This is intentionally
stricter than RFC 5646, where comparison is case-insensitive and case
regularization is optional. Receivers reject a non-profile spelling instead of
silently rewriting it.
Existing fields that describe language with unconstrained strings are legacy
compatibility boundaries. This rule does not retroactively make their old
payloads invalid. When a new contract consumes one of those values, it must
either migrate the field through a versioned change or apply the shared schema
contextually, as localized creative does for text and markdown assets.
## Name the matching operation
"Language matching" is not a complete interoperability rule. Every surface
MUST name the RFC 4647 operation and the direction in which it is applied.
| Purpose | Operation | Direction | Example |
| - | - | - | - |
| Declare which tagged values are eligible | RFC 4647 §3.3.1 Basic Filtering | Declared range filters a candidate tag | Seller range `fr` accepts `fr-CA`; seller range `fr-CA` does not accept `fr` |
| Select one representation from available tags | RFC 4647 §3.4 Lookup | Requested range is progressively truncated and compared by equality | Request `fr-CA` can select available `fr`; it does not select sibling `fr-FR` |
Eligibility is a set-membership question; selection chooses one value. A
surface must not call an eligibility set "Lookup" merely because a simple test
case happens to produce the same result.
## Four distinct localization patterns
| Concern | Contract pattern |
| - | - |
| Agent input comprehension | An adjacent authoritative `*_language` declaration plus a supported-input capability. Treat capability entries as eligibility ranges using Basic Filtering and fail closed when the declared input language is not eligible. Language detection may validate content, but it must not silently replace the sender's declaration or determine a different eligibility result. |
| Agent response language | Requested language preference plus an echo of the language actually used. Select from supported response languages with Lookup so any fallback is deterministic and observable. |
| Published multilingual content | Whole-value language maps plus an explicit default. Localize ordered collections as complete values rather than independently translating elements and producing a mixed-language array. This is content selection, not an unsupported-input error flow. |
| Executable creative | Materialized source and target variants, exact readback, seller eligibility, buyer selection, explicit fallback, and `do_not_serve`. Translation or generation remains a separate production operation. |
The first three patterns do not inherit creative's variant IDs, atomic
replacement, review state, or delivery attribution. Those exist because an
executable asset must be trafficked and later identified exactly. A brief,
response description, or brand guidance value needs a language declaration and
the matching rule appropriate to its surface—not a creative variant graph.
## Current protocol boundaries
Native creative localization implements the executable-creative pattern and
uses the shared tag schema throughout. Its product and placement eligibility
uses Basic Filtering; delivery selection uses Lookup.
Future agent-input and response-language work should reuse the same tag schema,
use Basic Filtering for declared comprehension eligibility, make the adjacent
input-language declaration authoritative, and echo the actual response
language. Published-content work should reuse the tag profile while defining
whole-value maps and explicit defaults rather than agent capability or error
semantics.
**`targeting.language` uses the shared BCP 47 wire profile.** The language
filter in [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) and related tasks carries canonical language ranges and applies RFC 4647 §3.3.1
Basic Filtering in the direction buyer range → user language-preference tag.
Thus `fr` accepts `fr`, `fr-CA`, and `fr-FR`, while `fr-CA` accepts only
`fr-CA` and its more-specific descendants. Capability discovery is deliberately
stricter: `media_buy.execution.targeting.language.supported_languages` lists
exact selectable request values, so a seller declaring `fr` has not also
declared that it accepts `fr-CA` as a request value. This exact capability
membership prevents buyers from inferring narrower execution controls that the
seller did not advertise.
**`locale_policy` absence, populated array, and `und` have distinct semantics.**
Omitting `locale_policy` entirely means unconstrained — no locale restriction,
and any creative variant is eligible for assignment. A populated
`accepted_language_ranges` array means a closed set — at least one materialized
creative variant must match a seller range via Basic Filtering. Including `und`
in that array means unknown language: `und` is not a wildcard and matches only
creative variants explicitly tagged `und`, not untagged or generic creatives.
Use `zxx` explicitly when a creative has no linguistic content (for example, an
animation with no text or speech); `zxx` must appear in `accepted_language_ranges`
for the policy to cover it.
Legacy underscore keys such as `en_US` in `brand.json` are not shared language
tags. A bridge replaces `_` with `-`, applies the AdCP wire profile, and
validates the result; it does not pass the legacy key through unchanged.
# Required tasks by protocol
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/required-tasks
Consolidated reference of required and optional tasks for each AdCP protocol, organized by agent role.
# Required tasks by protocol
Each AdCP protocol defines tasks that agents implement depending on their role. This page consolidates the requirements from each protocol specification into a single reference.
**Legend**: **Required** — the specification mandates implementation. **Conditional** — required when the agent has a specific capability. **Optional** — the specification recommends but does not mandate.
Some tasks span protocols. For example, [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) is defined in the Creative Protocol but may also be implemented by Media Buy sales agents. Canonical format discovery itself is no longer a shared task: each owning surface publishes its declaration directly.
## Shared
Every AdCP agent, regardless of protocol, implements:
| Task | Requirement | Reference |
| - | - | - |
| [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) | Required | [Capability discovery](/dist/docs/3.2.8/protocol/get_adcp_capabilities) |
| [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) | Conditional | Required when `get_adcp_capabilities.adcp.principal.supported` is `true`; synchronizes transport-principal-scoped webhooks and reusable reporting destinations. |
| [`get_principal`](/dist/docs/3.2.8/protocol/get_principal) | Conditional | Required when `get_adcp_capabilities.adcp.principal.supported` is `true`; reads the caller's connection configuration, version, and destination setup states without mutation. |
| [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) | Conditional | Required when `get_adcp_capabilities.adcp.capability_changes.notifications.registration_task` names this compatibility task; registers caller-scoped agent-level `capabilities.changed` webhooks. Sellers MUST reject registrations without a stable authenticated principal. |
Caller-scope RBAC introspection is not a standalone task. Sellers that support scope introspection return a per-account `authorization` object on [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) responses. See [Accounts Protocol — Caller authorization](/dist/docs/3.2.8/accounts/overview#caller-authorization).
AdCP task lifecycle state is application-layer state, not MCP-native or A2A-native task state. 3.x sellers MAY advertise non-colliding AdCP aliases for polling and reconciliation: [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) for legacy `tasks/get`, and [`list_tasks`](https://adcontextprotocol.org/schemas/3.2.8/protocol/list-tasks-request.json) for legacy `tasks/list`. These aliases remain optional compatibility surfaces generally in 3.x; callers MUST continue to support the legacy names through the 3.x line. The [AdCP A2A Profile Extension v3](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension) is the scoped exception: an agent that can return an AdCP Submitted response on that profile MUST expose `get_task_status`, and the A2A caller uses that non-colliding task. Alias and legacy request payloads use the same snake_case shape, including the optional `account` scope used to keep task visibility within the caller's authenticated account + principal pair.
## Media Buy Protocol
### Sales agent (seller)
| Task | Requirement | Notes |
| - | - | - |
| [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) | Required | Inventory discovery |
| [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) | Required | Agent capabilities; sellable formats remain product-scoped in `get_products` |
| [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) | Required | Campaign creation and order confirmation |
| [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) | Required | Budget, targeting, pause, cancel |
| [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) | Required | Operational state retrieval |
| [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) | Required | Delivery metrics at the package level; `reporting_capabilities` MUST be included on every product |
| [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) | Required | Accept buyer optimization signals |
| [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) | Conditional | Required when the sales agent hosts a creative library (Creative Protocol task) |
| [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) | Optional | Creative catalog browsing (Creative Protocol task) |
| [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs) | Optional | Product/inventory catalog sync |
| [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) | Optional | Conversion tracking setup |
| [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event) | Conditional | Required when event sources are configured |
| [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) | Optional | First-party CRM audience upload |
Sales agents MUST also support at least one transport (MCP or A2A) and declare `media_buy` in `supported_protocols`.
**Reference**: [Media Buy Specification](/dist/docs/3.2.8/media-buy/specification) · [Seller integration guide](/dist/docs/3.2.8/building/operating/seller-integration)
### Orchestrator (buyer)
Orchestrators are not MCP/A2A servers — they call sales agent tasks. Conformant orchestrators MUST:
1. Authenticate with sales agents
2. Include required fields per request schemas
3. Handle asynchronous task-level responses (`submitted`, `working`, `input-required`) and webhook delivery of completion artifacts
4. Use `media_buy_id` for all subsequent operations
5. Respect `creative_deadline` for creative uploads
**Reference**: [Media Buy Specification — Orchestrator conformance](/dist/docs/3.2.8/media-buy/specification#orchestrator-conformance)
## Creative Protocol
### Creative agent
| Task | Requirement | Notes |
| - | - | - |
| [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) | Required | Canonical creative capability discovery through `creative.supported_formats[]` |
| [`list_transformers`](/dist/docs/3.2.8/creative/task-reference/list_transformers) | Conditional | Required when the agent advertises `creative.supports_transformers: true` |
| [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) | Optional | Generation, transformation, or library retrieval |
| [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) | Optional | Preview rendering |
| [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) | Conditional | Required when `has_creative_library: true` |
| [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) | Conditional | Required when the agent accepts creative uploads |
| [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery) | Optional | Variant-level delivery metrics |
Creative agents MUST publish accurate canonical capability declarations. Exact publisher-format claims carry publisher identity; generic claims carry an honest parameter envelope.
**Reference**: [Creative Specification](/dist/docs/3.2.8/creative/specification)
## Signals Protocol
### Signal agent
| Task | Requirement | Notes |
| - | - | - |
| [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) | Required | Signal discovery |
| [`activate_signal`](/dist/docs/3.2.8/signals/tasks/activate_signal) | Required | Signal activation on decisioning platforms |
Signal agents MUST enforce access control for private signals and activation keys.
**Reference**: [Signals Specification](/dist/docs/3.2.8/signals/specification)
## Brand Protocol
### Brand agent
| Task | Requirement | Notes |
| - | - | - |
| [`get_brand_identity`](/dist/docs/3.2.8/brand-protocol/tasks/get_brand_identity) | Required | Core identity is public; authorized callers get deeper data |
| [`get_rights`](/dist/docs/3.2.8/brand-protocol/tasks/get_rights) | Conditional | Required when the agent manages brand rights |
| [`acquire_rights`](/dist/docs/3.2.8/brand-protocol/tasks/acquire_rights) | Conditional | Required when the agent manages brand rights |
| [`update_rights`](/dist/docs/3.2.8/brand-protocol/tasks/update_rights) | Conditional | Required when the agent manages brand rights |
Brand agents MUST declare `brand` in `supported_protocols`.
Creative approval is delivered to the `approval_webhook` declared by
[`acquire_rights`](/dist/docs/3.2.8/brand-protocol/tasks/acquire_rights); its
`creative-approval-request.json` shape is a webhook payload, not an AdCP task.
**Reference**: [Brand Protocol](/dist/docs/3.2.8/brand-protocol) · [Building a brand agent](/dist/docs/3.2.8/brand-protocol/building-a-brand-agent)
## Accounts Protocol
### Any agent accepting accounts
| Task | Requirement | Notes |
| - | - | - |
| [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) | Conditional | Buyer-declared accounts (`require_operator_auth: false`) use this when the buyer must select billing, terms, sandbox setup, notifications, or other settings before use. It MAY be omitted only for unambiguous lazy provisioning from the natural key when [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) is exposed. Account-id namespaces may use it only for settings updates unless a future explicit capability declares provisioning. |
| [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) | Conditional / recommended | Account-id namespaces (`require_operator_auth: true`) MUST expose it when a credential can access multiple accounts and SHOULD return a singleton otherwise. Buyer-declared-account sellers (`require_operator_auth: false`) SHOULD expose it as the cold-start recovery read and MUST expose it when they lazily provision instead of implementing `sync_accounts`. |
| [`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance) | Conditional | Required when the buyer uses campaign governance |
| [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) | Conditional | Required when the agent charges for services |
| [`get_account_financials`](/dist/docs/3.2.8/accounts/tasks/get_account_financials) | Optional | Financial summary per account |
Agents MUST implement at least one of `sync_accounts` or `list_accounts` depending on their account model. An agent MAY implement both. Buyer-declared-account sellers SHOULD implement both: `sync_accounts` establishes the relationship, while `list_accounts` lets a stateless buyer recover the seller's acknowledged `(brand, operator, sandbox)` portfolio without already possessing the natural keys it lost. A buyer-declared seller that exposes only `list_accounts` is conformant only when it lazily provisions on the first natural-key account-scoped request and can determine every required account setting without additional buyer input.
**Reference**: [Accounts Protocol](/dist/docs/3.2.8/accounts/overview)
## Governance: Campaign
### Governance agent
| Task | Requirement | Notes |
| - | - | - |
| [`sync_plans`](/dist/docs/3.2.8/governance/campaign/tasks/sync_plans) | Required | Plan creation and amendment |
| [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) | Required | Validation at purchase, modification, and delivery phases |
| [`report_plan_outcome`](/dist/docs/3.2.8/governance/campaign/tasks/report_plan_outcome) | Required | Outcome reporting and budget commitment |
| [`get_plan_audit_logs`](/dist/docs/3.2.8/governance/campaign/tasks/get_plan_audit_logs) | Required | Audit trail retrieval |
**Reference**: [Campaign Governance Specification](/dist/docs/3.2.8/governance/campaign/specification)
## Governance: Property
### Governance agent
| Task | Requirement | Notes |
| - | - | - |
| [`create_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#create_property_list) | Required | List creation with filters |
| [`get_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#get_property_list) | Required | Resolved property retrieval |
| [`update_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#update_property_list) | Required | List modification |
| [`delete_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#delete_property_list) | Required | List removal |
| [`list_property_lists`](/dist/docs/3.2.8/governance/property/tasks/property_lists#list_property_lists) | Required | List enumeration |
| [`validate_property_delivery`](/dist/docs/3.2.8/governance/property/tasks/validate_property_delivery) | Optional | Post-campaign compliance validation |
**Reference**: [Property Governance Specification](/dist/docs/3.2.8/governance/property/specification)
## Governance: Collection
### Governance agent
| Task | Requirement | Notes |
| - | - | - |
| [`create_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#create_collection_list) | Required | List creation with collection sources and filters |
| [`get_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#get_collection_list) | Required | Resolved collection retrieval |
| [`update_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#update_collection_list) | Required | List modification |
| [`list_collection_lists`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#list_collection_lists) | Required | List enumeration |
| [`delete_collection_list`](/dist/docs/3.2.8/governance/collection/tasks/collection_lists#delete_collection_list) | Required | List removal |
**Reference**: [Collection Governance](/dist/docs/3.2.8/governance/collection)
## Governance: Content Standards
### Content standards agent
| Task | Requirement | Notes |
| - | - | - |
| [`create_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/create_content_standards) | Required | Standards creation |
| [`get_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/get_content_standards) | Required | Standards retrieval |
| [`list_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/list_content_standards) | Required | Standards enumeration |
| [`update_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/update_content_standards) | Required | Standards modification |
| [`calibrate_content`](/dist/docs/3.2.8/governance/content-standards/tasks/calibrate_content) | Optional | Seller calibration against standards |
| [`validate_content_delivery`](/dist/docs/3.2.8/governance/content-standards/tasks/validate_content_delivery) | Optional | Post-delivery content compliance |
| [`get_media_buy_artifacts`](/dist/docs/3.2.8/governance/content-standards/tasks/get_media_buy_artifacts) | Optional | Artifact retrieval for validation |
**Reference**: [Content Standards](/dist/docs/3.2.8/governance/content-standards)
## Governance: Creative
### Creative governance agent
| Task | Requirement | Notes |
| - | - | - |
| [`get_creative_features`](/dist/docs/3.2.8/governance/creative/get_creative_features) | Required | Security scanning, content categorization |
**Reference**: [Creative Governance](/dist/docs/3.2.8/governance/creative)
## Sponsored Intelligence Protocol
### Brand agent
| Task | Requirement | Notes |
| - | - | - |
| [`si_get_offering`](/dist/docs/3.2.8/sponsored-intelligence/tasks/si_get_offering) | Optional | Pre-session offering lookup |
| [`si_initiate_session`](/dist/docs/3.2.8/sponsored-intelligence/tasks/si_initiate_session) | Required | Session creation with consent |
| [`si_send_message`](/dist/docs/3.2.8/sponsored-intelligence/tasks/si_send_message) | Required | Conversational messaging |
| [`si_terminate_session`](/dist/docs/3.2.8/sponsored-intelligence/tasks/si_terminate_session) | Required | Session cleanup |
Brand agents MUST declare `sponsored_intelligence` in `supported_protocols`.
**Reference**: [Sponsored Intelligence Specification](/dist/docs/3.2.8/sponsored-intelligence/specification)
## Trusted Match Protocol
TMP uses a different communication model (direct HTTP, not MCP/A2A tasks). See the [TMP Specification](/dist/docs/3.2.8/trusted-match/specification) for message types and conformance requirements.
# Snapshot and log
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/snapshot-and-log
The contract for AdCP state surfaces that pair a read API with a push channel — authoritative state, event identity, and recovery after missed notifications.
# Snapshot and log
AdCP state surfaces that pair a read API with push notifications have two faces: a **snapshot** read from a task and a **log** of events fired against a registered webhook URL. The snapshot says *what is true now*. The log says *what fired, when, with what id*. This page is the contract that keeps those paired surfaces coherent. A read API is not automatically a snapshot/log pair merely because its result contains state.
You don't need to read this page to call an AdCP task. You do need to read it to build a webhook receiver, to propose a new notification type, or to argue that a missing-event scenario is a spec gap rather than a buyer-side bug.
## The two faces
### Snapshot
The current truth, exposed on a read API:
* [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) returns each buy's `status`, `health`, open `impairments[]`, and optional `webhook_activity[]`.
* [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) returns delivery data for the same reporting windows carried by delivery-report fires.
* [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) returns each creative's current lifecycle state, including soft-purge tombstones when requested.
* [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) returns each account's current status.
* Wholesale [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) and [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) reads return versioned feed snapshots.
* [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) returns the agent's current capability revision.
A snapshot is always re-readable. It carries no history — only what's true at the moment of the read.
### Log
A stream of push events fired to the buyer's registered webhook URL:
* Delivery report fires (`notification_type: scheduled | final | delayed | adjusted | window_update`).
* Dependency impairment fires (`notification_type: impairment`).
* Creative and account lifecycle fires.
* Wholesale product and signal feed-change fires.
* Agent capability-change fires.
* Future event types that adopt this contract are added the same way: a new `notification-type` value, a defined payload, and a named repair read.
Each state-shaped event carries a stable logical-event `notification_id` and names the resource or revision needed for a repair read. Point-in-time delivery-report events have no persistent event id and use only `idempotency_key`.
## The five rules
These rules apply across every snapshot/log pair in the protocol. A new notification type can claim this contract only if its design satisfies all five.
### 1. Separate transport, event, and resource identity
**Dedupe transport retries by `idempotency_key`. Recognize a logical event by `notification_id`. Repair through the resource key defined by that notification type.** These identifiers serve different purposes, and receivers MUST NOT substitute one for another.
* **`idempotency_key`** — transport-layer, **per logical fire**. Issued by the seller and reused across delivery attempts of that fire. Receivers dedupe on this to suppress transport retries. A deliberate re-emission is a new fire with a new `idempotency_key`. Defined in the [webhooks transport contract](/dist/docs/3.2.8/building/by-layer/L3/webhooks).
* **`notification_id`** — event-layer, **per logical event**. Stable across re-emissions of that event. It is not generally a resource id: creative and account notifications use transition ids, wholesale notifications use `event.event_id`, and capability notifications use revision-event ids. Impairment is the special case where `notification_id` equals `impairment_id`. Typed at the envelope level on [`mcp-webhook-payload.json`](https://adcontextprotocol.org/schemas/3.2.8/core/mcp-webhook-payload.json); each [`notification-type`](https://adcontextprotocol.org/schemas/3.2.8/enums/notification-type.json) description defines its population. Point-in-time delivery events do not define it.
* **Repair key** — the resource identifier or revision used on the authoritative read: for example, `creative_id`, `account_id`, a media buy and reporting range, wholesale feed scope/version, or `capabilities_version`. The event payload for every conforming pair MUST expose enough information to select that read.
The split is intentional. A receiver seeing the same `idempotency_key` twice is observing a transport retry — uninteresting, dedupe and move on. A receiver seeing the same `notification_id` twice under **different** `idempotency_key`s is observing a re-emission — signal. The seller is repeating itself, usually because the buyer's receiver was unreachable for long enough that the seller wants to make sure the state was delivered. That's a missed-events warning the receiver should not collapse.
For point-in-time delivery events there is no persistent logical-event id — the per-fire `idempotency_key`, reporting range, and optional `sequence_number` are the available identity and recovery coordinates. That asymmetry is intentional.
### 2. Every push event points to readable authoritative state
There is no webhook-only **authoritative current state** within a snapshot/log pair. If an `impairment` webhook fires, a pair that declares both propagation surfaces exposes the current open impairment set through [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys). If a delivery report fires inside the seller's declared parity set, [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) can reproduce the reporting data for that range and granularity.
State-change pushes MAY include transition metadata useful for routing or diagnostics—such as prior status, reason, initiator, changed paths, or feed-event metadata—that a current snapshot does not retain. That metadata is advisory history, not authoritative current state, and is not recoverable after a missed event in 3.2. Push-only events and data outside a declared pull-parity set are outside this contract and MUST be identified as such.
### 3. Push is at-least-once; the snapshot is authoritative
When push and snapshot disagree, the snapshot wins. A transport retry (same `idempotency_key`) is expected under at-least-once delivery — buyer agents dedupe and continue. A re-emission (same `notification_id`, new `idempotency_key`) is a missed-events warning, so receivers reconcile the snapshot instead of collapsing it as a retry. A stale webhook fire (the push reports a state that the snapshot no longer reflects because the resource moved on) is also expected — buyer agents re-read the snapshot rather than acting on the push payload.
This is why receivers MUST verify against the snapshot before taking irreversible action on a push.
### 4. The read path provides the declared recovery guarantee
Snapshot/log pairs make one of two recovery guarantees. A notification type MUST state which guarantee applies; implementations and reviewers MUST NOT infer historical replay from current-state convergence.
* **State convergence** — for impairment, lifecycle, feed, and capability-change events, the named read returns the complete authoritative state *now*. Missing a push may lose its transition-only metadata, but it cannot prevent the receiver from converging on the resource's current state. Recovery is complete for current state, not for event history.
* **Data parity** — for delivery-report events, `get_media_buy_delivery` MUST reproduce the reporting data and windowing at every granularity the seller lists in `reporting_capabilities.windowed_pull_granularities`. The pull uses `time_granularity` plus `include_window_breakdown: true`; `window_update` recovery also uses `measurement_window` and `supersedes_window` to replace the superseded slice.
Sellers MUST declare the data-parity set honestly. A seller that declares `["hourly", "daily"]` MUST honor both hourly and daily windowed pulls. Pulls outside the set return [`UNSUPPORTED_GRANULARITY`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-granularity) with `error.details.supported_granularities`. A seller MAY emit a higher-frequency webhook outside the declared set, but that fire does not claim snapshot/log recovery at that frequency.
### 5. Push events and log entries share an id space
When a read surface exposes `webhook_activity[]`, it reuses wire identifiers rather than minting a parallel namespace: `idempotency_key` MUST equal the push value, and a populated `notification_id` MUST equal the push value. Sellers SHOULD populate `notification_id` on newly recorded attempts for event types that define it. The field remains optional in 3.2 so retained activity created before event identity was persisted can still be returned for the required 30-day window. Point-in-time delivery events do not define `notification_id` and omit it.
## Current conforming pairs
The table below is the durable catalog of pairs that claim this contract. "Guarantee" distinguishes current-state convergence from delivery-data parity; a pair does not acquire replay history merely because its push payload has a timestamp.
| Pair | Snapshot and repair key | Push identity | Ordering / schema | Missed-event recovery | Guarantee |
| - | - | - | - | - | - |
| Media-buy dependency health | [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) by `media_buy_id`; read `health` and the open `impairments[]` set | `impairment`; `notification_id = impairment_id` | Order open impairments by `observed_at`, not arrival time. The MCP envelope and impairment object allow additive fields. | Re-read `get_media_buys`; the open set is authoritative. | Current-state convergence, only when `propagation_surfaces` declares both `snapshot` and `webhook`. |
| Delivery reporting | [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) by media buy, reporting range, and declared granularity | `scheduled`, `final`, `delayed`, `adjusted`, `window_update`; no `notification_id` | `sequence_number` detects a gap but does not identify every missing range. Delivery payloads allow additive fields. | Pull from the last reconciled reporting-period boundary through the current range at a declared granularity. Reconcile every returned window; for measurement progression, replace `supersedes_window` with `measurement_window`. | Data parity within `windowed_pull_granularities`; higher-frequency fires outside that set are excluded. |
| Creative lifecycle | [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) by `creative_id`; use `include_purged: true` for soft-purge tombstones | `creative.status_changed` and soft `creative.purged`; stable transition/event `notification_id` | No global sequence. Transition time, prior status, reason, and initiator are advisory event metadata. Top-level payloads are closed schemas; version against the advertised AdCP schema. | Re-read `list_creatives`; current status or the soft-purge tombstone is authoritative. | Current-state convergence. Transition metadata is not replayed; hard purge is excluded. |
| Account lifecycle | [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) by `account_id` | `account.status_changed`; stable transition `notification_id` | No global sequence. `observed_at`, prior status, reason, and detail describe the event; the snapshot decides current state. The payload is a closed schema. | Re-read `list_accounts`; use its status, setup hints, billing terms, and authorization state. | Current-state convergence. Transition metadata is not replayed. |
| Wholesale product feed | [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) with `buying_mode: wholesale`, cache scope, and `wholesale_feed_version` | `product.*` and `wholesale_feed.bulk_change`; `notification_id = event.event_id` | No durable event cursor. `previous_wholesale_feed_version` exposes some gaps; the webhook is a closed schema. Changed fields, retired pricing ids, effective times, retractions, and removal reasons are event metadata. | Reconcile from the last trusted `if_wholesale_feed_version`; restart from an unversioned bootstrap when the version chain cannot be trusted. | Current-feed convergence when product reads and `wholesale_feed_webhooks.supported` are both declared; event metadata is not replayed. |
| Wholesale signal feed | [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) with `discovery_mode: wholesale`, cache scope, and `wholesale_feed_version` | `signal.*` and `wholesale_feed.bulk_change`; `notification_id = event.event_id` | No durable event cursor. `previous_wholesale_feed_version` exposes some gaps; the webhook is a closed schema. Changed fields, retired pricing ids, effective times, retractions, and removal reasons are event metadata. | Reconcile from the last trusted `if_wholesale_feed_version`; restart from an unversioned bootstrap when the version chain cannot be trusted. | Current-feed convergence when signal reads and wholesale signal webhooks are both declared; event metadata is not replayed. |
| Agent capabilities | [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities); repair fence is `adcp.capability_changes.capabilities_version` | `capabilities.changed`; stable logical-event `notification_id`, plus the target `capabilities_version` | No global sequence; compare the opaque capability revision only for equality. `reason` and `changed_paths` are advisory event metadata. The payload is a closed schema. | Retain the prior cache, re-read, and adopt the response only when its `capabilities_version` equals the pushed revision. If the revision is not yet observable, keep the prior cache and retry with normal transient-error backoff. | Current-state convergence; advisory change metadata is not replayed. |
The following surfaces are deliberately outside the catalog:
* Webhook-only impairment propagation—`propagation_surfaces: ["webhook"]` without `snapshot`—has no repair read and does not claim this contract.
* Delivery fires at a granularity absent from `windowed_pull_granularities` have no promised data-parity recovery at that frequency.
* [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) and event-source health remain pull-only because 3.2 defines no matching lifecycle notification.
* Hard `creative.purged` is reserved for compelled legal erasure and deliberately retains no read-side tombstone. It is a push-only exception, not a conformant snapshot/log pair; receivers that require durable evidence must persist the signed fire themselves.
## Webhook activity log pattern
The transport half of Rule 5. Any AdCP resource that exposes a snapshot read API and has webhook fires associated with it MAY also surface a `webhook_activity[]` array on that read API — recent per-fire transport records, scoped to the calling principal, useful for buyer-side debugging when a fire didn't land or a retry trail looks suspect. This section is the contract any resource adopting that surface MUST follow.
### Canonical record shape
The record shape is fixed at [`/schemas/core/webhook-activity-record.json`](https://adcontextprotocol.org/schemas/3.2.8/core/webhook-activity-record.json). Read schemas adopting this surface MUST `$ref` the canonical record rather than inline it — the shape is intentionally uniform across resources so a buyer's debug tooling can consume `webhook_activity[]` from any read API without resource-specific parsing.
Each record carries `idempotency_key` (equals the payload's `idempotency_key` per Rule 5 — no parallel `delivery_id`), optional `notification_id`, `subscriber_id`, `fired_at`, `completed_at`, `notification_type`, `sequence_number`, `attempt` (1-indexed; one record per attempt), `status` (`success` / `failed` / `timeout` / `connection_error` / `pending`), `url` (query string and fragment stripped, secret-shaped path segments redacted), `http_status_code`, `response_time_ms`, `payload_size_bytes`, and `error_message` (server-side classification only — never request/response bodies or headers).
For a fire whose payload defines `notification_id`, sellers SHOULD populate it on newly recorded attempts and MUST copy the payload value exactly when they do. Sellers MAY omit it on retained records created before 3.2 so adopting the field does not invalidate the existing 30-day activity window. Delivery-report fires do not define `notification_id` and omit it.
### Request-field convention
Read schemas that surface `webhook_activity[]` MUST use the same two request-field names so callers can opt in uniformly across resources:
* **`include_webhook_activity`** — boolean, default `false`. When true, the seller MAY return a `webhook_activity[]` array on each item (subject to the three-state presence semantics below).
* **`webhook_activity_limit`** — integer, range 1–200, default 50. Per-item cap on returned records, most-recent first.
### Scoping (normative)
`webhook_activity[]` MUST be scoped to the **calling principal**. When multiple principals share visibility into the same resource via account-level access, each principal sees only fires targeting its own registered endpoint. This is the same scoping rule that applies to push delivery itself.
### Retention (normative)
Sellers that surface `webhook_activity[]` **MUST** retain records for at least 30 days from each record's `completed_at`. This applies uniformly to every terminal status — `success`, `failed`, `timeout`, and `connection_error` all populate `completed_at` (for `timeout` and `connection_error` it is the moment the seller declared the attempt terminal) and the 30-day clock runs from there. For records still in `pending` status (the attempt is in flight or queued for retry, `completed_at` is null), the clock runs from `fired_at` until the attempt terminates and then transitions to 30 days from `completed_at` — so a retry trail does not age out mid-flight just because the initial fire happened 29 days ago.
The 30-day floor is a hard contract — sellers unable to honor it MUST omit the field entirely (see three-state presence below) rather than return a shorter window. This gives buyers a single retention guarantee they can build debug tooling against, and gives sellers with thin storage a clean opt-out via the three-state semantics rather than forcing the spec to negotiate per-seller retention floors.
### Three-state presence semantics
| State | Meaning |
| - | - |
| Field **omitted** | Seller does not surface webhook activity for this resource. Causes are resource-specific (see "Adoption checklist" below) but typically include: the seller does not persist fire history; the resource has no registered webhook endpoint for the calling principal; the seller's declared capability surface excludes the webhook channel for the relevant notification types. Buyers MUST NOT infer "no fires occurred" from omission. |
| Empty array `[]` | Seller persists fire history but has fired nothing recent for this principal. |
| Non-empty array | Actual fire records, most-recent first. |
Sellers MUST NOT collapse these into a single state. Opting in via `include_webhook_activity: true` does not override the seller's intrinsic capability — a seller that cannot meet the retention floor returns omission regardless of the request.
Buyers diagnosing an unexpected omission have two readily observable signals to discriminate the cause without needing operator help: (1) their own `push_notification_config` registration state for the resource (rules out "no registered endpoint") and (2) the seller's capability declaration (rules out "capability surface excludes the channel"). When both check out, "seller does not persist fire history" is the remaining cause and no further protocol-side fix is available — escalate.
### Record cardinality
One record per attempt. A successful first-attempt fire appears as a single record with `attempt: 1`. A 3-attempt retry trail (e.g., two failures then a success) appears as three records sharing `idempotency_key` — the trail is reconstructed by the buyer grouping records on that key.
### Privacy
* `url` MUST have query string and fragment stripped, and high-entropy / token-shaped path segments SHOULD be further redacted.
* `error_message` is a server-side classification string only — never request headers, response bodies, or buyer-endpoint stack traces.
* Request and response bodies are out of scope for the basic surface. A future `include_webhook_payloads` extension may add them under stricter access controls, and would use the [universal truncation sentinel](https://adcontextprotocol.org/schemas/3.2.8/core/truncation-sentinel.json) at `/schemas/core/truncation-sentinel.json` when bodies exceed a configured cap.
### Adoption checklist
Resources adopting `webhook_activity[]` MUST satisfy all of the following. The list is intentionally explicit so the "MUST" hooks are unambiguous; everything not on this list is at adopter discretion (e.g., per-resource cardinality tuning within the 1–200 range).
1. **Notification channel (prerequisite).** Adoption requires a registered notification channel for the relevant fire types. Media buys use per-buy `push_notification_config` and `reporting_webhook`; account-scoped resources use `notification_configs[]` managed through [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts); agent capability changes use [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) or the specialized [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) compatibility task. Without a channel there are no fires for `webhook_activity[]` to log. Adopters MUST cite the specific channel in their call-site documentation.
2. **Record shape.** Item schema MUST `$ref` `/schemas/core/webhook-activity-record.json`. Resource-specific cross-references (e.g., a parent-resource id when records are nested inside an account-level read) go on the canonical record's `ext` envelope, not as top-level record fields.
3. **Request fields.** The opt-in field names MUST be `include_webhook_activity` (boolean, default `false`) and `webhook_activity_limit` (integer, 1–200, default 50). The 200 ceiling is the canonical cap; adopters MAY narrow the maximum on a per-resource basis but MUST NOT exceed 200 or rename the fields.
4. **Scoping.** MUST be calling-principal only, per § Scoping above.
5. **Retention floor.** MUST honor the 30-day floor per § Retention above. The pivot (`completed_at`, with carve-out for `pending`) is the same across resources.
6. **Three-state presence cardinality.** Omitted / `[]` / non-empty are the three states; adopters MUST NOT collapse them.
7. **Capability gate.** Adopters MUST document which resource-specific capability declaration gates the field (for media buys this is `capabilities.media_buy.propagation_surfaces` including `webhook`). The specific *causes* of the "field omitted" state ARE resource-specific and adopters MUST enumerate them in their call-site documentation; the cardinality and the rule that omission is not "no fires occurred" are universal.
8. **Notification type registry.** Adopters whose webhook fires carry notification types not in [`/schemas/enums/notification-type.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/notification-type.json) MUST add those types to that shared enum rather than minting a parallel enum on the canonical record. The enum is the cross-resource registry.
### Consumers and the dependency chain
#### Media-buy consumer
* `get_media_buys.media_buys[].webhook_activity[]` uses the per-buy `push_notification_config`. Capability gate: `capabilities.media_buy.propagation_surfaces` MUST include `webhook` for the field to be surfaced on a buy. See [get_media_buys § Webhook activity](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys#webhook-activity) for the call-site documentation and the [persistent webhook contract](/dist/docs/3.2.8/building/by-layer/L3/webhooks#persistent-channel-contract) for the transport-side rules this surface debugs against.
#### Account-level consumers
Resources that outlive a single media buy register their push channel on the account, not on any one buy. The account-level surface is `notification_configs[]` — an array of per-subscriber registrations carried on [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts#account-level-webhook-subscriptions) and echoed on [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts). Each entry filters by `event_types[]` so a subscriber only receives the types its endpoint handles, and multiple entries with distinct `subscriber_id`s fan a single event out to multiple endpoints (multi-subscriber composition).
* **[#2261](https://github.com/adcontextprotocol/adcp/issues/2261) creative lifecycle, assignment, and indicator webhooks** — `list_creatives.creatives[].webhook_activity[]` adopts this pattern for `creative.status_changed`, `creative.purged`, `creative.assignment_changed`, and assignment-level `indicators.changed`. The notification channel is the account's `notification_configs[]` set, registered via `sync_accounts` in either provisioning or settings-update mode. Supported event types and per-type coalescence windows are declared via [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). The parent creative is unambiguous, so `ext.creative_id` MAY be omitted on inner records. Assignment and indicator events are invalidations repaired completely through [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys); [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) is an optional bounded reverse projection, and neither its rows nor the webhook payload replaces the authoritative snapshot. See [list_creatives § Webhook activity](/dist/docs/3.2.8/creative/task-reference/list_creatives#webhook-activity) for the call-site documentation.
* **[#5915](https://github.com/adcontextprotocol/adcp/issues/5915) account status webhooks** — `list_accounts.accounts[].webhook_activity[]` uses the same pattern for `account.status_changed`. The webhook invalidates the account snapshot; buyers re-read `list_accounts` for the authoritative status, setup hints, billing terms, and authorization state. The payload intentionally omits `setup.url` so single-use setup links are fetched through the authenticated read path instead of fanned out to every subscriber.
* **Durable account changes (3.2 experimental, `account.change_feed`)** — [`list_account_changes`](/dist/docs/3.2.8/accounts/tasks/list_account_changes) is a separate business-state change feed, while `account.change_recorded` is its generic wake-up. It does not replace specialized resource notifications or `webhook_activity[]`. The feed records material changes regardless of origin and points to authoritative repair reads; the webhook activity surface still records only delivery attempts.
* **Future account-scoped resources** follow the same chain only after defining both halves: subscribe through `sync_accounts.accounts[].notification_configs[]`, name an authoritative repair read, and adopt `webhook_activity[]` on that read when transport observability is supported.
Adopters follow this checklist verbatim regardless of whether the notification channel is per-buy, per-account, or agent-level.
## What this rules out
* **A push channel for suggestions that don't change state.** If "the seller wants you to know X" doesn't correspond to a readable field, it's not a snapshot/log event. Build a pull tool instead. (See the indicator proposal.)
* **A replay tool that re-fires past webhooks.** Snapshot reads are the replay. A replay tool is an operator-side debug feature; it's not part of the buyer-facing protocol contract.
* **Per-event subscription filtering on per-buy push.** A buyer who registers `push_notification_config` on a media buy receives every event type fired against that buy. Filtering at the receiver is fine; filtering at the per-buy protocol surface is out of scope. Account-level subscriptions (`notification_configs[]`) are the exception — they filter by `event_types` at registration time because that surface is heterogeneous and an endpoint that handles only one resource family would otherwise receive events it cannot interpret.
* **A "did you receive my webhook?" confirmation step.** Receivers acknowledge via HTTP 2xx; senders retry on non-2xx per the [persistent webhook contract](/dist/docs/3.2.8/building/by-layer/L3/webhooks#persistent-channel-contract). Sellers do not poll buyers for receipt.
## Current limits
* **Full historical payload replay is not a 3.2 surface.** The optional account change feed retains bounded change metadata and repair pointers, not before/after resource documents. Buyers that require regulatory archives still persist authorized snapshots and reporting data themselves.
* **Delivery parity is capability-scoped.** [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) reproduces reporting data only at declared `windowed_pull_granularities`; buyers must persist higher-frequency webhook data when the frequency is outside that set.
* **Activity identity is migration-safe.** `notification_id` is optional on `webhook_activity[]` records in 3.2 so sellers can return retained pre-adoption records. Strict presence for identity-bearing event types requires a major-version migration contract.
* **Audience coverage is capability-gated.** A seller cannot advertise audience coverage in the account change feed until discovery exposes stable native/connected identity, management origin, and current revision. Until then a fresh [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) remains the reliable lifecycle signal.
## When you'd be right to push back
> [!NOTE]
>
> This section is non-normative. It describes when raising an exception is reasonable, not when one is sanctioned.
When a use case genuinely needs an event with no snapshot half — a high-frequency signal where polling cost dominates and recovery isn't critical (e.g., a metrics stream). AdCP doesn't have one of these today. If you're proposing one, name it explicitly and argue why pull-via-snapshot doesn't fit; reviewers will weigh that against the contract this page commits to.
## Related
* [Push notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks) — the transport contract that this page sits on top of.
* [Media buy lifecycle](/dist/docs/3.2.8/media-buy/media-buys/lifecycle) — applies snapshot/log to `status` + `health` + `impairments[]`.
# sync_agent_notification_configs
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/sync_agent_notification_configs
Register agent-level webhook subscribers, starting with capabilities.changed notifications that invalidate cached get_adcp_capabilities responses.
Register, replace, pause, or clear caller-scoped agent-level webhook subscribers. This task manages notifications whose lifecycle belongs to the seller agent itself rather than to an account, media buy, creative, or other account-scoped resource.
This is the specialized compatibility surface. When the seller advertises [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal), use its `notification_configs` section so webhooks and reusable connection resources share one versioned caller-scoped configuration. Sellers exposing both tasks maintain one underlying subscriber set.
The initial event type is `capabilities.changed`, an invalidation signal for cached [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) responses.
**Request Schema**: [`/schemas/3.2.8/protocol/sync-agent-notification-configs-request.json`](https://adcontextprotocol.org/schemas/3.2.8/protocol/sync-agent-notification-configs-request.json)
**Response Schema**: [`/schemas/3.2.8/protocol/sync-agent-notification-configs-response.json`](https://adcontextprotocol.org/schemas/3.2.8/protocol/sync-agent-notification-configs-response.json)
## When to call
First call [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). Only call this task when the seller advertises it as the registration task:
```json theme={null}
{
"adcp": {
"capability_changes": {
"capabilities_version": "rev_20260702_091455",
"cache_ttl_seconds": 3600,
"notifications": {
"supported": true,
"registration_task": "sync_agent_notification_configs",
"event_types": ["capabilities.changed"]
}
}
}
}
```
When `registration_task` is [`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal), call that task instead.
Sellers that do not advertise support MUST reject the task rather than silently accepting a subscriber that will never fire. When `notifications.supported: true`, the same `capability_changes` block MUST include `cache_ttl_seconds` and `capabilities_version` so receivers have a bounded polling fallback and a stable comparison after missed webhooks.
## Authentication and Caller Scope
This task MUST only be accepted when the transport request resolves to a stable authenticated principal. The principal can be an OAuth client subject, API-key subject, verified signed-request subject, registry identity, or equivalent deployment identity, but it MUST be stable across retries and future replacements. Sellers MUST reject NO_AUTH, anonymous, or otherwise unbound registrations with [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing) when no credentials are present, [`AUTH_INVALID`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-invalid) when presented credentials fail validation, or [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) when the transport exposes anonymous registration as a malformed request.
The authenticated principal is the owner key for declarative replacement. Sellers MUST NOT key agent-level subscribers only by `subscriber_id` or URL, because two callers can legitimately choose the same local subscriber ID. One caller's replacement set MUST NOT read, delete, pause, overwrite, or infer subscribers owned by another principal.
## Request Parameters
| Field | Type | Description |
| - | - | - |
| `idempotency_key` | string | **Required.** Unique key for at-most-once replacement. Reuse the same key and same payload on retry. |
| `notification_configs` | array | **Required.** Complete desired agent-level subscriber set for the authenticated principal. Send `[]` to clear this principal's subscribers. |
| `dry_run` | boolean | Optional. Validate without applying changes or sending endpoint proof challenges. |
Each `notification_configs[]` entry has:
| Field | Type | Description |
| - | - | - |
| `subscriber_id` | string | **Required.** Stable logical key for this caller's endpoint. Re-sending the same ID replaces that caller's subscriber. |
| `url` | URI | **Required.** HTTPS webhook endpoint. Sellers apply the same SSRF protections and proof-of-control rules as other webhook configs. |
| `event_types` | string\[] | **Required.** Currently only `capabilities.changed` is valid. |
| `authentication` | object | Optional legacy Bearer or HMAC-SHA256 selector. Omit for the default RFC 9421 webhook profile. Credentials are write-only. |
| `active` | boolean | Optional, default `true`. Set `false` to pause a subscriber without removing it. |
## Endpoint proof
Before activating a new or changed active subscriber, the seller MUST validate the URL and complete endpoint proof of control. The challenge POST is signed with the seller's RFC 9421 webhook profile key and uses [`agent-webhook-challenge.json`](https://adcontextprotocol.org/schemas/3.2.8/core/agent-webhook-challenge.json). The receiver echoes the challenge with [`webhook-challenge-response.json`](https://adcontextprotocol.org/schemas/3.2.8/core/webhook-challenge-response.json).
Agent-level challenges intentionally do not carry `account_id` because capability notifications are valid before any account exists. The proof scope is `(authenticated caller identity, seller_agent_url, subscriber_id, normalized url, authentication mode/credential binding, normalized event_types)`. Changing any element of that tuple requires fresh proof before the subscriber can become active.
## Replacement Semantics
The submitted array is declarative and complete for the authenticated principal:
* Omit `notification_configs` is invalid.
* Send `notification_configs: []` to remove every agent-level subscriber owned by this caller.
* Send a non-empty array to replace this caller's current set with exactly those entries.
* `subscriber_id` is the match key within the caller scope. Existing IDs owned by this caller are replaced; this caller's persisted IDs missing from the submitted array are removed.
* Duplicate `subscriber_id` values in one request are invalid within that caller-scoped array.
* If any entry fails validation or endpoint proof, the seller rejects the replacement and leaves the caller's prior set unchanged.
One caller's replacement MUST NOT delete, pause, or mutate subscribers registered by another authenticated caller. Sellers that host shared registry and buyer subscribers on the same agent therefore need an owner key in storage even though that owner is not exposed in the webhook payload.
## Webhook Payload
When the seller's advertised capability document materially changes, it publishes the new [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) snapshot first, then fires `capabilities.changed` to active subscribers:
```json theme={null}
{
"idempotency_key": "whk_01J1T3K6YZR7V5P9Q2M4N6B8CD",
"notification_id": "capchg_20260702_0001",
"notification_type": "capabilities.changed",
"fired_at": "2026-07-02T09:15:30Z",
"subscriber_id": "registry-cache",
"agent_url": "https://seller.example/adcp",
"changed_at": "2026-07-02T09:14:55Z",
"reason": "capability_enabled",
"capabilities_version": "rev_20260702_091455",
"changed_paths": ["/account/sandbox"]
}
```
The webhook does not carry the full capability document. The `capabilities_version` in the webhook is the post-change revision token and MUST be observable in `get_adcp_capabilities` before the seller sends the webhook. Receivers SHOULD re-run `get_adcp_capabilities`, compare `adcp.capability_changes.capabilities_version` with the webhook's `capabilities_version`, and replace their local cache with the fresh response. If the webhook's `capabilities_version` is not yet observable, receivers SHOULD retry `get_adcp_capabilities` with normal transient-error backoff and MUST retain their prior cached snapshot until a fresher authoritative snapshot is read or the cache TTL expires.
## Example
```json theme={null}
{
"idempotency_key": "b6aa9428-9d5f-4d16-a6d2-1a27db67ef5b",
"notification_configs": [
{
"subscriber_id": "registry-cache",
"url": "https://registry.example/webhooks/adcp/capabilities",
"event_types": ["capabilities.changed"],
"active": true
}
]
}
```
Response:
```json theme={null}
{
"status": "completed",
"action": "updated",
"notification_configs": [
{
"subscriber_id": "registry-cache",
"url": "https://registry.example/webhooks/adcp/capabilities",
"event_types": ["capabilities.changed"],
"active": true
}
]
}
```
# sync_principal
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/protocol/sync_principal
sync_principal synchronizes authenticated caller-scoped webhooks and reusable reporting destinations with an AdCP agent.
A **principal** is the durable party behind an authenticated caller — a buyer agent, or an operator-side identity. `sync_principal` replaces the principal's standing configuration with one AdCP seller agent: webhooks, reusable reporting destinations, and its position in capability negotiation. The three tiers of the hierarchy:
| Tier | Entity | Surface |
| - | - | - |
| 1 | **Principal** — who you are, resolved from authenticated transport | `sync_principal` / [`get_principal`](/dist/docs/3.2.8/protocol/get_principal) |
| 2 | The principal's standing configuration with this seller | carried on the principal record |
| 3 | **Accounts** — principal × advertiser authority, feeds, schedules | [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and domain tasks |
[`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) states what the seller can support; `sync_principal` states which of it this principal uses; account-level tasks authorize work for particular advertisers.
The task does not register a buyer agent and does not accept a buyer-agent URL or identity in its body. Who the principal is comes only from authenticated transport.
For an end-to-end buyer-side example, see [Set up your buyer agent with a seller](/dist/docs/3.2.8/accounts/principal-registration-walkthrough).
**Request schema:** [`/schemas/3.2.1/protocol/sync-principal-request.json`](https://adcontextprotocol.org/schemas/3.2.1/protocol/sync-principal-request.json)
**Response schema:** [`/schemas/3.2.1/protocol/sync-principal-response.json`](https://adcontextprotocol.org/schemas/3.2.1/protocol/sync-principal-response.json)
## Identity and authority
The principal is a party, in the same sense the protocol already bills and authorizes parties. It comes in two kinds:
* **A buyer agent** authenticating as itself — its registered workload, OAuth client-credentials subject, server-side API-key owner, verified signed-request identity, or equivalent machine principal. The operators an agent acts for are agent-scoped labels within its own principal space, asserted the same way `operator_identity` is on accounts; they confer no identity across agents.
* **An operator-side identity** — a person at the operator authenticated as themselves. The client application they act through (Claude, ChatGPT, the seller's UI) is the instrument, never the owner. A person using ChatGPT therefore configures under their own login at the seller; nothing about ChatGPT is registered.
Whether "the operator's identity" means individual users or one org-level service identity is the seller's authorization design. Separate credentials become one principal only through explicit administrative linking — never inferred from org membership, matching operator labels, or matching domains, because that inference is a cross-party takeover path. Sellers MUST NOT link, dedupe, or grant authority across principals based on matching operator identifiers.
If an interactive client presents only one shared service credential for all its users, the seller cannot isolate user-owned configuration — one user's sync could read or erase another's — so it MUST refuse to persist configuration under it until the client completes delegated authorization or account linking. Anonymous and shared-credential callers own nothing durable, at this layer or the account layer.
The model composes across hops. A buyer agent → Interchange → seller chain is two independent principal relationships: Interchange is the (agent) principal at the seller, and the buyer agent is the (agent) principal at Interchange. A person using Claude to buy through Interchange is an operator principal at Interchange. No hop sees through the next; each holds its own counterparty accountable, and end-to-end reconciliation happens at the data layer, where rows and partitions carry seller and account identity.
Request-body fields, a raw signing key ID, an API-key fingerprint, an access token, a session ID, and a bucket URL are not owner identifiers. A verified JWKS key proves which key signed a request; it does not by itself prove authority to act for an advertiser account. Key rotation or token renewal preserves the configuration only when the seller maps the new credential to the same stable principal.
For an RFC 9421 signed caller, the stable Agent subject is the canonical URL of the exactly matched operator `brand.json` `agents[]` entry—but only after the seller verifies the publication chain and confirms that entry authorizes the request-signing key. The URL is therefore a verified identity input, not a body assertion. The operator domain, raw URL spelling, `brand_json_url`, `jwks_uri`, `kid`, key thumbprint, and key generation remain trust or credential-binding facts beneath that identity. Two canonical Agent URLs are two principals even when they share a domain, operator, type, or JWKS endpoint; key rotation under one canonical Agent URL preserves that principal. If the verified chain cannot select exactly one canonical Agent URL, the seller fails closed without reading or creating principal state.
Every applied, current, or recognized readback carries the seller-resolved `principal_kind` — `buyer_agent` or `operator` — resolved solely from the authorization system, never from request content, so per-party policy such as billing gates can rely on it before configuration begins. A request may carry `expected_principal_kind` as an assertion fence ("I believe I am authenticating as the agent"); on mismatch with the resolved kind the seller rejects with [`CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflict) before mutation. The assertion never influences resolution.
The response's `principal_id` is a seller-issued audit and routing handle for the principal record. It is not a credential and does not authorize any advertiser account.
## Establishing a connection
The principal layer begins **after authentication**. AdCP defines no credential-registration protocol: the seller's authorization system — OAuth, API keys, signed requests, workload identity — issues and maps credentials before the first call. The same lifecycle then works for an autonomous buyer agent, a person in an interactive client, an API-key integration, or M2M OAuth:
1. **Authenticate.** Autonomous software presents its workload identity; a person presents their delegated user identity. No `register_buyer_agent` step exists or is needed.
2. **Read [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities).** Discover `adcp.principal`, its supported sections, event and delivery offerings, and limits.
3. **Verify the resolved identity.** Call [`get_principal`](/dist/docs/3.2.8/protocol/get_principal). A `recognized` result returns the existing durable `principal_id` and seller-resolved `principal_kind` without standing configuration. `unconfigured` means stable authentication succeeded but no durable record exists. The read creates neither records nor identifiers.
4. **Call `sync_principal`.** Declare consumption facts (`declarations`), register webhook subscribers (including `principal.changed` and, with explicit scope, account-anchored events), and register reusable reporting destinations.
5. **Authorize advertiser accounts separately** through [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and account-level tasks. Nothing in steps 1–4 grants account authority.
6. **Bind each account's feeds** to the reusable `destination_ref`s.
7. **Observe readiness.** [`get_principal`](/dist/docs/3.2.8/protocol/get_principal) shows destination and declaration state; `principal.changed` keeps it fresh.
That yields four deliberately separate objects: the **credential** (seller's authorization system, out of AdCP scope), the **principal record** (this layer — one party's standing configuration), **account authorization** (which advertiser data the principal may access), and **delivery configuration** (where authorized data goes). A destination can be registered before any account exists, but it cannot receive account data until an account-scoped feed binding succeeds.
## Discovery
Only call this task when [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) includes both:
```json theme={null}
{
"adcp": {
"principal": {
"supported": true,
"sync_task": "sync_principal",
"read_task": "get_principal",
"supported_sections": [
"notification_configs",
"reporting_destinations",
"declarations"
],
"caller_event_types": [
"capabilities.changed",
"principal.changed",
"creative.status_changed",
"account.change_recorded"
],
"max_reporting_destinations": 16,
"reporting_destination_offerings": [
{
"pattern": "file_transfer",
"transports": ["s3"],
"formats": ["parquet", "csv"],
"verification_profiles": ["manifest_checksums", "canonical_digest"]
},
{
"pattern": "dataset_share",
"transports": ["delta_sharing"],
"access_modes": ["databricks_to_databricks", "open_sharing"],
"verification_profiles": ["native_commit"]
}
],
"suspension_interval_seconds": 900,
"optimistic_concurrency": true
}
},
"experimental_features": ["protocol.principal"]
}
```
Unsupported sections are rejected, not ignored. `reporting_destination_offerings` is the seller's objective delivery offering: a buyer selects a compatible pattern, transport, format, access mode, and verification-profile intersection from it *before* submitting, instead of discovering support through rejections. A destination outside the offering fails the whole request with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature); a destination inside the offering that fails provider-side setup is reported per destination as `validating`, `action_required`, or `rejected` inside an applied response.
## Synchronization semantics
`configuration` contains one or more independently replaceable sections:
| Section | Meaning |
| - | - |
| `notification_configs` | Caller-scoped webhook subscribers for caller-anchored events (`capabilities.changed`, `principal.changed`) and, with [fire-time authorization scoping](#principal-level-webhooks), account-anchored events. |
| `reporting_destinations` | Reusable, non-secret file, warehouse, or dataset-share destinations. |
| `declarations` | Buyer-declared [consumption facts](#declarations) — async payload versions, verifiable signing algorithms, experimental opt-ins — with a seller-computed accepted intersection. |
For each submitted section:
* The array is complete desired state for that section.
* Omitting a previously present entry removes it; for reporting destinations, removal is [revocation](#suspension-and-revocation).
* `[]` clears the whole section.
* An omitted section remains unchanged.
* All submitted sections apply atomically, or none do. Sections are validated and authorized in full before any proof challenge or grant is issued, so a failed request leaves no external side effects.
* `dry_run: true` returns `result.kind: validated` with the would-be action, without persistence, grants, endpoint challenges, principal IDs, destination references, or configuration versions. Dry-run outcomes and warnings are computed solely against the caller's own state and never reveal what other principals have registered.
When `expected_configuration_version` is present, the seller applies a new operation only if it equals the current opaque version. A stale version returns [`CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflict) without mutation. This prevents two services using the same principal from silently overwriting each other. Read the current version with [`get_principal`](/dist/docs/3.2.8/protocol/get_principal) before a guarded replacement — never write blind to discover it. Retries of one logical request reuse both its `idempotency_key` and body. The seller resolves an exact idempotent replay before evaluating the version fence, so a lost successful response remains replayable after the persisted version advances. Idempotency records are scoped to the stable principal; a key first seen under a different principal starts a new operation, never a replay.
`configuration_version` advances on every successful mutation of the shared underlying state — through this task or through [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) — and never on seller-driven setup-state transitions such as a destination becoming `ready`.
## principal-level webhooks
One subscriber registered here can carry every webhook the relationship needs — the "sign me up for everything, once" surface:
* **Caller-anchored events** (`capabilities.changed`, `principal.changed`) fire principal-wide. `principal.changed` is the invalidation doorbell for seller-driven state transitions — a destination reaching `ready`, a setup action expiring, the accepted declarations intersection changing — and receivers repair by re-reading [`get_principal`](/dist/docs/3.2.8/protocol/get_principal).
* **Account-anchored events** (`creative.status_changed`, `account.change_recorded`, `product.*`, …) may be listed on caller-level subscribers, and require the explicit `all_authorized_accounts: true` acknowledgment — subscribing an endpoint to every account is never implicit. Authorization is evaluated **at each delivery attempt, including retries**: losing authority for an account both stops new fires and suppresses queued retries carrying that account's data, without touching the subscription. Registration itself requires no account authority and grants none.
* **Media-buy-anchored cadence reports** (`scheduled`, `final`, `delayed`, `adjusted`, `window_update`) stay on each buy's `reporting_webhook` — they carry per-buy cadence choices this layer deliberately does not own. `impairment` is also media-buy-anchored but fires against `push_notification_config` — it is a dependency-state change on the buy, not a cadence report.
There is no wildcard. Callers enumerate `event_types` and may set `include_future_event_types: true` — which extends only to future caller-eligible types classified **invalidation-only** (identifiers plus a repair pointer, no domain data). Payload-bearing types always require explicit enumeration, so the flag can never silently opt a caller into more-sensitive payloads. Sellers advertise which types they can emit here in `principal.caller_event_types`; an out-of-offering type fails the request with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature).
Caller-level and account-level subscriptions to the same event are independent: both fire, and receivers dedupe by the event's logical `notification_id`. Setting a subscriber's `active: false` is the webhook kill switch — all fires to that endpoint, across every account, halt within the advertised `suspension_interval_seconds`.
## Declarations
Synchronous calls negotiate versions per request, but a webhook fired weeks after registration has no request context to negotiate against. The `declarations` section is that channel: the caller declares bounded facts about what it can consume, and the seller returns the **accepted intersection** it will honor for asynchronous interactions.
```json theme={null}
{
"idempotency_key": "8b54cf59-77f4-41ce-9f2a-6d1f0c8b1a77",
"configuration": {
"declarations": {
"async_adcp_versions": ["3.2"],
"webhook_signing_algorithms": ["ed25519"],
"experimental_features": ["protocol.principal"]
}
}
}
```
Rules:
* Declarations are facts about consumption ability — never preferences or policy. [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) stays objective seller facts; the intersection is the negotiated contract.
* Unknown `experimental_features` identifiers are accepted and simply excluded from the intersection, so one declaration works across sellers with different surfaces.
* An empty `webhook_signing_algorithms` intersection while any webhook subscriber is active fails the request with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) — fires would be unverifiable.
* A later seller-side change to the accepted intersection fires `principal.changed` with reason `declarations_intersection_changed` and does not advance `configuration_version`.
* The readback persists the full negotiation record: the declared set, the accepted intersection, the `selected_async_adcp_version` the seller will actually use for pushes, and an `exclusions` entry with a reason for every declared value not accepted — so "what can this buyer implementation consume, and what did the seller decide?" always has one durable answer.
* Submitting `{}` clears the declared set.
## Reusable reporting destinations
A destination is registered once on the caller's principal record and can later be referenced from several advertiser accounts for which that caller is independently authorized. In the example below, the authenticated principal might be a delegated human user in Claude or an autonomous buyer-agent workload; the request body is identical because identity never comes from the payload.
```json theme={null}
{
"idempotency_key": "528f1f06-e2a7-49b9-bd13-c953f35a1c49",
"configuration": {
"reporting_destinations": [
{
"pattern": "file_transfer",
"destination_id": "reporting-archive",
"active": true,
"provider": { "domain": "object-store.example" },
"transport": "s3",
"location": "s3://pinnacle-reporting/adcp/",
"accepted_formats": ["parquet"],
"accepted_verification_profiles": [
"manifest_checksums",
"canonical_digest"
]
},
{
"pattern": "warehouse_materialization",
"destination_id": "analytics-warehouse",
"active": true,
"provider": { "domain": "data-warehouse.example" },
"transport": "bigquery",
"location": "pinnacle-analytics.adcp_reporting",
"accepted_verification_profiles": [
"native_commit",
"canonical_digest"
]
},
{
"pattern": "dataset_share",
"destination_id": "daily-share",
"active": true,
"provider": { "domain": "data-platform.example" },
"transport": "delta_sharing",
"access_mode": "open_sharing",
"recipient": {
"identity": "reporting@example.com"
},
"accepted_verification_profiles": ["native_commit"]
}
]
}
}
```
Each destination declares one atomic delivery pattern. Register separate destination IDs when the same provider coordinates support materially different ownership or access paths.
The response returns a seller-issued `destination_ref` and one of these states:
| State | Meaning |
| - | - |
| `validating` | Automated ownership or access validation is in progress. |
| `ready` | The pattern-specific proof succeeded. The destination is eligible for a new authorized account/feed binding. |
| `action_required` | A typed provider-native setup action must be completed. The `setup` object names it. |
| `inactive` | The caller suspended the destination (`active: false`). New deliveries halt; existing caller-owned data is not deleted. |
| `rejected` | The coordinates or requested path cannot be used. |
`destination_ref` is not a bearer capability. It identifies one immutable destination generation for the same authenticated principal. Exact replays preserve the reference; changing provider, transport, normalized coordinates or recipient, accepted formats, access mode, or accepted verification profiles requires fresh proof and produces a new reference. Superseded references stay resolvable for existing account bindings and retained reporting history, and remain enumerable to their owner through `prior_destination_refs` on [`get_principal`](/dist/docs/3.2.8/protocol/get_principal). Every use still checks account authorization separately, and unknown, cross-principal, and unauthorized references fail indistinguishably.
### Destination lifecycle
The typical flow for a destination that needs provider-native setup:
1. **Register.** The caller syncs the destination. The seller validates it against its advertised offering, issues `destination_ref`, and returns `state: "action_required"` with a typed `setup` object — for example `{"action": "grant_access"}` for a BigQuery dataset the seller's published principal cannot yet reach, or `{"action": "accept_share"}` for a dataset share awaiting recipient activation.
2. **Complete provider-native setup.** The caller performs the action in the provider's control plane: grants the seller's principal on the bucket or dataset, accepts the share as the named recipient, or writes the seller-named proof object. Credentials never transit AdCP.
3. **Poll the read task.** The caller polls [`get_principal`](/dist/docs/3.2.8/protocol/get_principal) until the destination reaches `ready`. Reading never mutates state or the version. Resubmitting the identical section under a fresh `idempotency_key` is also safe — it returns `action: "unchanged"` and preserves `destination_ref` — but the read task is the intended poll mechanism.
4. **Bind.** Account-scoped reporting configuration references the `ready` destination by `destination_ref`, subject to its own authorization.
What `ready` asserts is pattern-specific:
* **`file_transfer`** — the caller proved control of the normalized location through a seller-verifiable challenge, *and* the seller successfully wrote and read back a probe object under the prefix. A grant that exists but was never exercised is not `ready`.
* **`warehouse_materialization`** — the seller verified, through access it was actually granted, that it can create and commit into the locator.
* **`dataset_share`** — the named recipient affirmatively completed the provider's acceptance or activation step and the provider reports the recipient able to read the share. Access modes that grant to a bare identifier with no acceptance step require an equivalent recipient-initiated proof, such as a recipient read of a seller-published proof dataset. Grant creation alone never produces `ready`, and because provider grant propagation can lag, account-level delivery readiness additionally requires consumer-read verification as defined by managed reporting delivery.
### Suspension and revocation
Destination deactivation is a delivery control, not just a registration flag:
* **Suspend** — resubmit the destination with `active: false`. The seller stops initiating new deliveries to *every generation* of that `destination_id` within its advertised `suspension_interval_seconds` and marks affected account bindings with a typed `destination_suspended` issue. Resubmitting with `active: true` lifts the suspension without new proof when nothing else changed.
* **Revoke** — omit the destination from the submitted `reporting_destinations` array (or submit `[]` to revoke all). Revocation has every suspension effect, removes the destination from current state, and retains its generations under `retired_destinations` for audit and reporting history. Reusing a retired `destination_id` requires fresh registration and proof and produces a new generation.
One suspension or revocation cuts delivery for every account bound to the destination — a compromised bucket does not require per-account unwinding. Neither operation deletes data already delivered, and neither revokes provider-side grants the caller manages in its own control plane.
### Account consolidation
A consolidated destination can receive reporting from many seller accounts. The destination registration proves where this caller may receive data; it does not prove which data the caller may receive. The managed reporting delivery specification ([RFC #6911](https://github.com/adcontextprotocol/adcp/issues/6911)) supplies that second authorization by binding an account-scoped feed configuration to the reusable `destination_ref`. Consolidated files, rows, and partitions must retain seller and account identity so downstream consumers can reconcile them independently.
An agent principal serving many operators may set the optional `operator_id` label on each destination — its own bookkeeping about which operator a destination serves. That enables per-operator isolation ("this operator's data goes only to their bucket"), audit ("list every destination serving this operator"), and one-call per-operator suspension or revocation when an operator offboards. The label confers no identity: matching `operator_id` values or domains across different principals are never linked, and each agent maps its operators its own way.
## Verification profiles
Destination setup advertises verification profiles the caller can accept:
* `native_commit`: provider-native transaction/version evidence with row counts and control totals. Appropriate for frequent warehouse snapshots when allowed by the feed profile.
* `manifest_checksums`: a manifest-last file commit with cryptographic object checksums.
* `canonical_digest`: recomputation of a canonical logical-content digest. Appropriate for billing and strict-conformance feeds.
This is an allowed set, not a claim that every feed may use the weakest member. The selected seller offering and account-level feed configuration choose one acceptable profile.
## Secrets and proof
AdCP carries destination coordinates and recipient identifiers, never provider credentials. Private keys, passwords, bearer profiles, signed URLs, and cloud credentials are exchanged through provider-native control planes or an out-of-band onboarding channel. The schema pattern on `location` is a transport guard, not the enforcement boundary: sellers additionally screen canonicalized values for credential shapes the pattern cannot express, such as userinfo-style `key:secret@host` prefixes inside an otherwise valid locator.
Before proof binding and uniqueness comparison, sellers canonicalize coordinates per transport — Unicode NFC, lowercase scheme and host authority, no default ports, canonical path separators — and reject locators or recipient identities whose host authority is not ASCII after canonicalization. Proof binds to the canonical form, so cosmetic variations of the same coordinates cannot evade the fresh-proof requirement.
Before a destination becomes `ready`, the seller completes the [pattern-specific proof](#destination-lifecycle) and binds it to the authenticated principal, seller agent, destination ID, normalized coordinates, and accepted delivery contract. A changed proof-bound tuple requires fresh proof and a new immutable destination reference; replacement never mutates the meaning of a reference already used by an account configuration.
For `notification_configs`, the endpoint proof and webhook-signing rules are identical to [`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs). Implementations exposing both tasks maintain one underlying caller-scoped subscriber set.
## Errors
Failed responses carry `result.kind: "failed"` with structured errors and deliberately cannot carry a principal ID, version, or configuration state.
| Code | When | Recovery |
| - | - | - |
| [`AUTH_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-required) | Anonymous or unstable caller identity. | Authenticate as a stable principal, then retry. |
| [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) | Schema violation, duplicate `destination_id`, credential-shaped `location` or recipient, or oversize section. | Fix the request; do not retry unchanged. |
| [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) | Section not in `supported_sections`, destination outside `reporting_destination_offerings`, subscriber event type outside `caller_event_types`, empty signing-algorithm intersection with an active subscriber, or `expected_configuration_version` sent to a seller advertising `optimistic_concurrency: false`. | Re-read capabilities and select from the advertised offering. |
| [`CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflict) | `expected_configuration_version` is stale. Nothing was mutated. | Read the current version with [`get_principal`](/dist/docs/3.2.8/protocol/get_principal), reconcile, and resubmit under a new `idempotency_key`. |
| [`IDEMPOTENCY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-conflict) | An `idempotency_key` was reused with a different body. | Use a fresh key for the new logical operation. |
| [`IDEMPOTENCY_IN_FLIGHT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-in-flight) | The original operation for this key is still executing. | Retry the identical request after a short delay. |
| [`IDEMPOTENCY_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-idempotency-expired) | The retention window for this key elapsed. | Read current state, then resubmit as a new operation if still needed. |
Provider-side setup failures for in-offering destinations are not request errors: they surface as `validating`, `action_required`, or `rejected` destination states inside an applied response.
## Compatibility
[`sync_agent_notification_configs`](/dist/docs/3.2.8/protocol/sync_agent_notification_configs) remains the specialized compatibility task for agents that only support capability-change subscribers. When `capability_changes.notifications.registration_task` is `sync_principal`, clients manage those subscribers through the `notification_configs` section here.
The broader task does not turn [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) into caller-specific state. Capabilities remain cacheable seller facts; principal configuration remains authenticated caller state.
# Quickstart
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/quickstart
Pick your path — buyers call an AdCP agent in 5 minutes, publishers and sellers stand up their own agent.
Pick your path. Buyers call the public test agent in 5 minutes. Publishers and sellers stand up an agent buyers can call.
> [card] I'm calling an agent
>
> Buyer side. The rest of this page walks through calling the public test agent — no signup, copy-pasteable curl.
> [card] [I'm building an agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent)
>
> Publisher or seller side. Stand up an agent buyers can call.
## Setup
Use the public test token to get started immediately — no signup required:
```bash theme={null}
export ADCP_AUTH_TOKEN="1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
export AGENT_URL="https://test-agent.adcontextprotocol.org/sales/mcp"
```
The test agent is path-routed: `/sales/mcp` serves media-buy tools (this quickstart's path), and sibling URLs serve the other specialisms — `/signals/mcp`, `/governance/mcp`, `/creative/mcp`, `/creative-builder/mcp`, `/brand/mcp`. Hit [`/.well-known/adagents.json`](https://test-agent.adcontextprotocol.org/.well-known/adagents.json) for the full tenant + tool list.
For your own API key (org-scoped, usage tracking), create one at the [AAO dashboard](https://agenticadvertising.org/dashboard/api-keys).
## 1. Discover products
AdCP over MCP uses JSON-RPC 2.0. The transport is [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) — responses arrive as server-sent events.
```bash theme={null}
curl -X POST $AGENT_URL \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_products",
"arguments": {
"idempotency_key": "550e8400-e29b-41d4-a716-446655442067",
"buying_mode": "brief",
"brief": "Video ads for pet food brand",
"brand": { "domain": "premiumpetfoods.com" }
}
}
}'
```
**Response** (SSE envelope omitted for clarity):
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"products\":[{\"product_id\":\"pinnacle_news_video_premium\",\"name\":\"Pinnacle News Group video guaranteed\",\"channels\":[\"olv\",\"ctv\"],\"pricing_options\":[{\"pricing_option_id\":\"pinnacle_news_video_premium_pricing_0\",\"pricing_model\":\"cpm\",\"currency\":\"USD\",\"fixed_price\":15}],\"delivery_type\":\"guaranteed\"}, ...],\"sandbox\":true}"
}
]
}
}
```
**Extract the result** — the AdCP payload is JSON-encoded inside `content[0].text`:
```javascript theme={null}
const response = /* parsed JSON-RPC response */;
const payload = JSON.parse(response.result.content[0].text);
console.log(payload.products[0].product_id); // "pinnacle_news_video_premium"
console.log(payload.products[0].channels); // ["olv", "ctv"]
console.log(payload.products[0].pricing_options[0].pricing_option_id); // "pinnacle_news_video_premium_pricing_0"
console.log(payload.products[0].pricing_options[0].fixed_price); // 15
```
## 2. Handle errors
Send an invalid tool name to see what errors look like:
```bash theme={null}
curl -X POST $AGENT_URL \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "nonexistent_tool",
"arguments": {}
}
}'
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"code\":\"INVALID_REQUEST\",\"message\":\"Unknown tool: nonexistent_tool\"}"
}
],
"isError": true
}
}
```
**Handle it** — check `isError`, then parse the error payload:
```javascript theme={null}
const response = /* parsed JSON-RPC response */;
if (response.result.isError) {
const err = JSON.parse(response.result.content[0].text);
console.log(err.code); // "INVALID_REQUEST"
console.log(err.message); // "Unknown tool: nonexistent_tool"
}
```
Common error codes: `INVALID_REQUEST` (bad input), `RATE_LIMITED` (retry with backoff), `UNAUTHORIZED` (check credentials).
## 3. Create a media buy (idempotently)
Use the product IDs from step 1 to create a campaign. Every mutating request MUST carry an `idempotency_key` — a client-generated UUID v4 that makes retries safe. Send the same key with the same payload and the seller returns the original result instead of creating a duplicate buy:
```bash theme={null}
export IDEMPOTENCY_KEY="$(uuidgen | tr '[:upper:]' '[:lower:]')"
curl -X POST $AGENT_URL \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $ADCP_AUTH_TOKEN" \
-d "{
\"jsonrpc\": \"2.0\",
\"id\": 1,
\"method\": \"tools/call\",
\"params\": {
\"name\": \"create_media_buy\",
\"arguments\": {
\"idempotency_key\": \"$IDEMPOTENCY_KEY\",
\"account\": { \"account_id\": \"test_account\" },
\"brand\": { \"domain\": \"premiumpetfoods.com\" },
\"start_time\": \"asap\",
\"end_time\": \"2026-04-30T00:00:00Z\",
\"packages\": [{
\"product_id\": \"pinnacle_news_video_premium\",
\"budget\": 5000,
\"pricing_option_id\": \"pinnacle_news_video_premium_pricing_0\"
}]
}
}
}"
```
Replay the same request (same key, same payload) and the seller returns the original response with `replayed: true`. Send the same key with a different payload and you get `IDEMPOTENCY_CONFLICT`. Check a seller's window via `get_adcp_capabilities`:
```json theme={null}
{ "idempotency": { "supported": true, "replay_ttl_seconds": 86400 } }
```
See the [Security guide](/dist/docs/3.2.8/building/by-layer/L1/security) for the full retry model, including `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_EXPIRED`, and UUID v4 guidance for AdCP Verified agents.
**Response** (IDs will differ on each call):
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"media_buy_id\":\"mb_f4139524\",\"status\":\"active\",\"revision\":1,\"packages\":[{\"package_id\":\"pkg_3df649f0\",\"product_id\":\"pinnacle_news_video_premium\",\"budget\":5000,\"pricing_option_id\":\"pinnacle_news_video_premium_pricing_0\"}],\"valid_actions\":[\"pause\",\"cancel\",\"update_budget\",\"update_dates\",\"update_packages\",\"add_packages\",\"sync_creatives\"],\"sandbox\":true}"
}
]
}
}
```
**Extract the result:**
```javascript theme={null}
const response = /* parsed JSON-RPC response */;
const buy = JSON.parse(response.result.content[0].text);
console.log(buy.media_buy_id); // "mb_f4139524"
console.log(buy.status); // "active"
console.log(buy.packages[0].budget); // 5000
console.log(buy.valid_actions); // ["pause", "cancel", "update_budget", ...]
```
## 4. Push notifications (signed webhooks)
Production agents send webhooks for long-running operations. AdCP 3.0 signs webhooks with the **same RFC 9421 HTTP Message Signatures profile used for agent-to-agent requests** — one verifier, one JWKS, one trust surface. No shared HMAC secrets.
Point the agent at your webhook endpoint and advertise your JWKS. The agent signs each POST with a key it trusts; you fetch the agent's JWKS and verify the signature before acting on the payload:
```json theme={null}
{
"name": "create_media_buy",
"arguments": {
"idempotency_key": "5c4c6f29-...",
"account": { "account_id": "your_account" },
"brand": { "domain": "premiumpetfoods.com" },
"push_notification_config": {
"url": "https://you.example.com/webhooks/adcp",
"authentication": {
"schemes": ["HTTP_MESSAGE_SIGNATURES"]
}
}
}
}
```
When the operation completes, the agent POSTs a signed request to your URL. The payload carries its own `idempotency_key` so your receiver can dedupe retries:
```json theme={null}
{
"task_id": "task_456",
"idempotency_key": "webhook_evt_8f2a...",
"task_type": "create_media_buy",
"status": "completed",
"timestamp": "2026-04-22T10:30:00Z",
"result": {
"media_buy_id": "mb_12345",
"packages": [{ "package_id": "pkg_001" }]
}
}
```
Verify the signature before trusting the payload — resolve the `keyid` via the seller operator's `brand.json` `agents[].jwks_uri`, apply any publisher `adagents.json` `signing_keys[]` pin when present, run the AdCP webhook verifier checklist, and reject unknown keys, expired dates, or mismatched digests with a typed `webhook_signature_*` reason code:
```typescript theme={null}
app.post('/webhooks/adcp/*', async (req, res) => {
try {
await verifyAdcpWebhookSignature(req, {
sellerAgentUrl: req.sellerContext.agentUrl,
requiredTag: 'adcp/webhook-signing/v1',
allowedAlgs: ['ed25519', 'ecdsa-p256-sha256'],
});
} catch (err) {
return res.status(401)
.setHeader('WWW-Authenticate', `Signature error="${err.code}"`)
.end();
}
const { idempotency_key } = req.body;
if (await seen(idempotency_key)) return res.status(200).end();
await process(req.body);
res.status(200).end();
});
```
See the [Security guide](/dist/docs/3.2.8/building/by-layer/L1/security) and [Webhooks guide](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for the full verification profile — required headers, covered components, nonce and date windows, and the negative-vector suite the compliance runner exercises.
## Using the client library
The examples above use raw HTTP for clarity. In practice, use the AdCP client library which handles SSE parsing, retries, and authentication:
```bash theme={null}
npm install @adcp/sdk # JavaScript/TypeScript
pip install adcp # Python
```
```javascript theme={null}
import { ADCPMultiAgentClient } from '@adcp/sdk';
const client = new ADCPMultiAgentClient([{
id: 'test',
name: 'Test Agent',
agent_uri: 'https://test-agent.adcontextprotocol.org/sales/mcp',
protocol: 'mcp',
auth_token: process.env.ADCP_AUTH_TOKEN,
}]);
const result = await client.agent('test').getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655442043',
buying_mode: 'brief',
brief: 'Video ads for pet food brand',
brand: { domain: 'premiumpetfoods.com' },
});
console.log(result.data.products);
```
## What's next
* **[Build an agent](/dist/docs/3.2.8/building/by-layer/L4/build-an-agent)** — use skill files to generate a storyboard-compliant agent with a coding agent
* **[Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent)** — test your agent with storyboards and compliance checks
* **[Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog)** — the domains and specialisms an agent can claim, and the storyboards that verify each claim
* **[MCP integration guide](/dist/docs/3.2.8/building/by-layer/L0/mcp-guide)** — transport, sessions, auth details
* **[A2A integration guide](/dist/docs/3.2.8/building/by-layer/L0/a2a-guide)** — streaming, artifacts, push notifications
* **[Media buy lifecycle](/dist/docs/3.2.8/media-buy/media-buys/lifecycle)** — state machine, sequenced flow, guaranteed deal IO path, creative sync timing
* **[Task reference](/dist/docs/3.2.8/media-buy/task-reference)** — all available tasks with testable examples
* **[Error handling](/dist/docs/3.2.8/building/operating/transport-errors)** — error codes, recovery strategies
* **[Authentication](/dist/docs/3.2.8/building/by-layer/L2/authentication)** — production credential setup
# AdCP 3.2 prerelease history
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/3-2-beta
Archive of the AdCP 3.2 beta and release-candidate checkpoints: artifact versions, wire pins, SDK pairings, and changes from RC.7 to 3.2.1.
# AdCP 3.2 prerelease history
> [!NOTE]
>
> **AdCP 3.2 is generally available** as release `3.2.1` (published 2026-09-30), wire pin `"3.2"`. The number `3.2.0` was never released. Move integrations pinned to a 3.2 beta or RC to `"3.2"` and to the stable SDKs: TypeScript `@adcp/sdk@14.0.0` and Python `adcp==8.0.0`. Start with [What's new in AdCP 3.2](/dist/docs/3.2.8/reference/whats-new-in-3-2) and [Migrating from 3.1 to 3.2](/dist/docs/3.2.8/reference/migration/3-1-to-3-2).
This page is the record of the 3.2 prerelease cycle. Every prerelease remains an immutable, signed checkpoint, so adopters who pinned one can still reproduce and debug their results.
## Changes between RC.7 and 3.2.1
Adopters moving from `3.2.0-rc.7` to `3.2.1` should check these changes, which landed during the GA freeze:
* **Seller-optimized budgets.** `media_buy.features.seller_optimized_budget` now covers only the core shared-budget contract and media-buy pacing. Package budget caps, minimum-spend targets, and package pacing need `seller_optimized_package_budgets`, `seller_optimized_min_spend_targets`, and `seller_optimized_package_pacing`. An RC seller that declared the parent and honors those controls must add the matching sub-capabilities, or buyers' requests carrying them are rejected with `UNSUPPORTED_FEATURE`. Core sellers must accept omitted or `even` pacing and may reject `asap` or `front_loaded`.
* **Delivery reporting timezone.** `get_media_buy_delivery` dates and `daily_breakdown[].date` are calendar dates in the products' `reporting_capabilities.timezone`, with the optional `reporting_period.timezone` echo. RC wording required exact UTC day boundaries. A dated or windowed (`time_granularity`) request spanning more than one reporting timezone is rejected with `VALIDATION_ERROR`.
* **Account change feed.** `list_account_changes` is now experimental (`account.change_feed`). Sellers implementing it list `account.change_feed` in `experimental_features`.
* **`views` goal definition.** The optimization-goal `views` metric now matches delivery metrics (content views toward the billable view threshold), not viewable impressions. Use `viewable_rate` for viewability.
* **Conformance.** 27 new content-digest-covered request-signing vectors under `test-vectors/request-signing/profile-3.2/`, a restructured `seller_optimized_budget` storyboard (1.1.0) with two new scenarios, and storyboard fixes for `reporting_core`, `get_creative_features_idempotency`, non-guaranteed sellers, and cross-phase generated IDs.
## Checkpoints
| Checkpoint | Added | SDK pairing |
| - | - | - |
| `3.2.0-beta.0` | Canonical schemas, compliance assets, skills, and protocol manifest for SDK implementation | Not SDK-backed |
| `3.2.0-beta.1` – `beta.3` | Integration-correction checkpoints | — |
| `3.2.0-beta.4` | Flexible-window availability, outcome-target reverse forecasting, and availability conformance | — |
| `3.2.0-beta.5` | Cross-transport async identity and convergence, policy-backed creative rejection, outcome-target conformance | TypeScript `14.0.0-beta.7`, Python `8.0.0b7` |
| `3.2.0-beta.6` | Reporting negotiation and breakdowns, CTV experience profiles, premium display canonicals, A2A request-signing method names | TypeScript `14.0.0-beta.13`, Python `8.0.0b9` |
| `3.2.0-beta.7` | Audience activation and external sources, creative delivery and tracker execution, static OOH and radio measurement, viewed-seconds distributions | — |
| `3.2.0-beta.8` | Metric-container subsumption conformance and corrected documentation snapshots | — |
| `3.2.0-beta.9` | Account change feed, inventory-list receipts, inventory delivery identity, seller policy and change rights | — |
| `3.2.0-beta.10` | Managed reporting delivery, authenticated principals, audio VAST and DOOH, programmed channel collections, committed collection selection | TypeScript `14.0.0-beta.28`, Python `8.0.0b11` |
| `3.2.0-beta.11` | `get_principal` in the MCP media-buy role profile | TypeScript `14.0.0-beta.29`, Python `8.0.0b12` |
| `3.2.0-rc.0` | First release candidate; reporting lifecycle conformance | TypeScript `14.0.0-beta.31`, Python `8.0.0b13` |
| `3.2.0-rc.1` | Reliable Reporting 1.0; delivery currency, aggregate reach, and vendor-metric hardening | TypeScript RC.35, Python `8.0.0b14`, Go `adcp/v3@v3.2.1` |
| `3.2.0-rc.2` | Opt-in `sync_reporting_status`, buyer and orchestrator storyboards, breakdown cursor pagination | No SDK embeds it |
| `3.2.0-rc.3` | Consumer-status hardening, MediaBuy-level `frequency_cap`, request-only targeting with `null`-clear | TypeScript RC.40, Python `8.0.0b15` |
| `3.2.0-rc.4` | Anonymous discovery declarations, required `recovery` on 3.2 errors, `sync_accounts` account echo, supply-path vectors | TypeScript RC.44 |
| `3.2.0-rc.5` | Not published; the release process withheld it | — |
| `3.2.0-rc.6` | Shared MediaBuy `name`, seller-policy decline reasons, request-signing error vocabulary, three sales specialisms, waiver reconciliation | TypeScript RC.48 |
| `3.2.0-rc.7` | `viewable_rate` goal with viewability `standard` and `vendor`; deprecated `account` on media-buy `list_creative_formats` | TypeScript `14.0.0-rc.49` and `rc.50`, Python `8.0.0b18` |
TypeScript "RC.N" means `@adcp/sdk@14.0.0-rc.N`. Go module versions are not AdCP versions: `adcp/v3@v3.2.1` embeds `3.2.0-rc.1` schemas and is not AdCP 3.2.1.
## Version strings
The artifact version, wire pin, and documentation selector are related but not interchangeable:
| Surface | Betas | Release candidates | GA |
| - | - | - | - |
| Protocol artifact | `3.2.0-beta.N` | `3.2.0-rc.N` | `3.2.1` |
| Git tag | `v3.2.0-beta.N` | `v3.2.0-rc.N` | `v3.2.1` |
| `adcp_version` wire pin | `"3.2-beta.N"` | `"3.2-rc.N"` | `"3.2"` |
| Documentation selector | `3.2-beta` (frozen at beta.11) | `3.2-rc` | `3.2` |
Prerelease pins are exact. A buyer pinned to `"3.2-rc.7"` never silently negotiates to another prerelease, and a stable `"3.2"` pin never resolves onto a prerelease. A peer that still advertises only a prerelease pin must move to `"3.2"` before stable 3.2 buyers can reach it. If you keep running a pinned prerelease compliance bundle for regression evidence, run it against a staging endpoint. Do not weaken production authentication to accommodate a prerelease runner.
## Artifact retention
Release-candidate and stable artifacts are never retired. Superseded 3.x beta artifacts were retired from the repository and runtime image on 2026-09-14; only the `3.2.0-beta.11` schema bundle stays hosted, backing the frozen `3.2-beta` documentation snapshot. Earlier beta URLs resolve from the artifact CDN on a best-effort basis. The prerelease documentation snapshots stay reachable by URL after their selectors leave the version picker.
## Related
* [What's new in AdCP 3.2](/dist/docs/3.2.8/reference/whats-new-in-3-2)
* [Migrating from 3.1 to 3.2](/dist/docs/3.2.8/reference/migration/3-1-to-3-2)
* [Release Notes](/dist/docs/3.2.8/reference/release-notes#version-3-2-1)
* [Versions & Compatibility](/dist/docs/3.2.8/reference/versions)
* [Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk)
# Migrating from 3.0 to 3.1
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/3-0-to-3-1
A focused upgrade guide for moving AdCP 3.0 integrations to the 3.1 stable release.
# Migrating from 3.0 to 3.1
> [!NOTE]
>
> **3.1 is released.** New 3.1 integrations should pin `"3.1"` after confirming the agent advertises it in `supported_versions`. Existing 3.0 integrations can remain pinned to `"3.0"` while they migrate.
3.1 is a minor release over 3.0. The stable protocol changes are additive: existing 3.0-conformant agents can remain on `"3.0"` without changing request or response shapes. Experimental surfaces follow their separate stability contract; TMP operators should apply the immediate v3.1.22 guidance below. Use this guide when you are preparing an SDK, buyer, seller, creative agent, signal agent, brand agent, or compliance workflow to claim or consume 3.1.
For the feature narrative, start with [What's New in AdCP 3.1](/dist/docs/3.2.8/reference/whats-new-in-3-1). For the full release record, see [Release Notes](/dist/docs/3.2.8/reference/release-notes#version-3-1-0).
## Immediate Context Match cache action
Version 3.1.22 shipped emergency privacy/security corrections for Context Match: [#7396](https://github.com/adcontextprotocol/adcp/pull/7396) restricts non-public single-user context, and [#7397](https://github.com/adcontextprotocol/adcp/pull/7397) requires request-aware response-cache partitioning. Router operators affected by unsafe caching MUST bypass or disable Context Match response caching until they implement both the v3.1.22 request-aware partition and a trusted namespace covering every result-affecting authentication, authorization, tenant, active-package, endpoint, provider-configuration, model, and targeting/rules generation.
A trusted `cache_namespace` conformance contract is proposed in [#7446](https://github.com/adcontextprotocol/adcp/pull/7446) for a later release. It is not part of any published release and is not a retroactive 3.1 conformance requirement; the namespace guidance here is immediate safe-operations advice for affected deployments. If the router cannot establish either the complete request partition or the trusted provider-evaluation namespace, keep cache lookup, coalescing, and insertion disabled.
Version 3.1.22 was an emergency security exception to the normal six-week experimental-change notice process. Its published package, tag, and versioned artifacts remain immutable; the missing #7397 changelog coverage is carried forward by an independent v3.1.23 patch changeset. See the [v3.1.22 release note](/dist/docs/3.2.8/reference/release-notes#version-3-1-22) for the release record.
## Upgrade checklist
| Step | Who | Action |
| - | - | - |
| 1 | Everyone | Decide whether this integration is staying on `"3.0"` for now or moving to `"3.1"`. |
| 2 | SDKs and hand-rolled clients | Add an `adcp_version` release pin on every request. Send `"3.1"` only to agents that advertise it. |
| 3 | Sellers and agents | Advertise every accepted release in `get_adcp_capabilities.adcp.supported_versions` and echo the served release at the envelope root. |
| 4 | Buyers | Decode `VERSION_UNSUPPORTED` and retry only against a version that the seller advertised. |
| 5 | Hand-rolled buyers | Add `idempotency_key` to mutating tasks; accept optional envelope fields on read responses and tolerate an optional key on read requests. |
| 6 | MCP and A2A adapters | Accept envelope fields and transport wrappers without rejecting unknown root members. |
| 7 | Error handlers | Treat `error.code` as an open string and dispatch on `error.recovery` when present. |
| 8 | Compliance operators | Run the 3.1 storyboard bundle and keep the 3.0 compatibility line green until the 3.1 badge is issued. |
## Version pinning
3.0 integrations negotiated by major version only. 3.1 adds release-precision negotiation:
* Use `"3.0"` for stable 3.0 traffic.
* Use `"3.1"` for stable 3.1 traffic after the agent advertises it.
* Do not send patch values such as `"3.0.19"` or full semver prereleases such as `"3.1.0-rc.15"` on the wire.
Sellers should reject unsupported pins with `VERSION_UNSUPPORTED` and include the supported release list in `error.data.supported_versions`. Buyers should not silently downshift across minor releases. Surface the mismatch or retry against a version the seller explicitly advertised.
## Runtime changes to audit
### Idempotency and read-envelope tolerance
3.0 required `idempotency_key` on mutating requests. The original 3.1 text extended keyed replay to reads, but reference SDKs continued to generate keys only for requests they classified as mutating. Read wrappers must tolerate an optional key; buyers should not rely on byte-stable read replay. Hand-rolled buyers should generate UUID v4 keys for mutations and may omit them on pure reads.
When a response is marked `replayed: true`, treat it as the historical result of the original operation. If you need fresh state before acting, re-read the relevant resource after handling the replayed response.
### Envelope tolerance
3.1 relies on transport adapters tolerating the AdCP envelope root. MCP and A2A clients should unwrap the transport-specific wrapper first, then read AdCP fields such as `status`, `result`, `errors`, `adcp_version`, `replayed`, and `context`. Unknown envelope members must not cause rejection.
### Error decoding
The standard error catalog expanded in 3.1, but `error.code` remains an open string. Clients should:
* Accept unknown error codes.
* Prefer `error.recovery` when present.
* Apply a bounded transient fallback for unknown legacy errors when `error.recovery` is absent.
* Handle the auth split between `AUTH_MISSING` and `AUTH_INVALID`.
* Treat `CREDENTIAL_IN_ARGS` as terminal and move credentials to the proper transport channel before retrying.
### Proposal and action discovery cleanup
3.1 makes `proposal_status` the proposal source of truth and uses structured action discovery on products and buys. Sellers should not emit the pre-GA `requires_proposal` action mode. Buyers with cached prerelease action metadata should invalidate it and re-read the product, proposal, or buy surface.
### Brand verification signing
Brand agents that implement `verify_brand_claim` or `verify_brand_claims` must return signed response evidence. Publish a per-brand response-signing key and bind signatures to the task, resolved brand tenant, responding agent URL, caller/request hash, and validity window.
### Signal targeting
Signal identity moves toward `SignalRef`, with product-scoped `included_signals`, `signal_targeting_options`, and buy-time `signal_targeting_groups`. Owned-signal discovery and marketplace activation are separate capabilities. Buyers should call `activate_signal` only when the agent declares marketplace or activation support.
### Creative formats and transformers
Creative agents should expose canonical `format_kind` values and discover build units through `list_transformers`. Format-attached input/output/pricing declarations are deprecated in favor of transformer-scoped configuration and pricing. Hosted audio/video slots should use `duration_ms_exact` for fixed durations and `duration_ms_range` for bounded or one-sided ranges.
### Reporting and billing
3.1 adds delivery and usage finality markers, reach-window semantics, `viewability.viewed_seconds`, and the `BILLING_OUT_OF_BAND` error for creative billing outside AdCP. Buyers should avoid treating delivery numbers as final until the relevant finality fields say they are final.
## Role-based migration
| Role | Minimum prep before claiming 3.1 |
| - | - |
| SDK buyer | Upgrade to an SDK that emits `adcp_version`, pins `"3.1"` when the seller supports it, adds idempotency keys to mutations, and accepts open error codes. |
| Hand-rolled buyer | Add release pins, mutation idempotency keys, read-envelope tolerance, forward-compatible error decoding, and replay handling. |
| Seller | Advertise `supported_versions`, echo the served release, tolerate envelope fields, reject unsupported pins with `VERSION_UNSUPPORTED`, and audit idempotency/replay/error behavior. |
| Creative agent | Move discovery to `list_transformers`, publish canonical formats, and keep legacy format references only as compatibility aliases. |
| Signal agent | Separate owned-signal discovery from marketplace activation; expose product-scoped targeting options only where buyers can select them. |
| Brand agent | Publish response-signing keys and return signed evidence for brand verification tasks. |
| Compliance operator | Run 3.1 storyboards, retain 3.0 compatibility evidence, and issue version-scoped badges only for the release actually tested. |
## Prerelease artifacts
The 3.1 prerelease artifacts remain available for adopters who pinned them during validation, but new integrations should use the stable `"3.1"` wire value. If you built against a prerelease, invalidate cached prerelease-only fields such as `requires_proposal`, re-read current product/proposal/action metadata, and rerun the 3.1 storyboard bundle before claiming the stable release.
## Related
* [What's New in AdCP 3.1](/dist/docs/3.2.8/reference/whats-new-in-3-1)
* [Release Notes](/dist/docs/3.2.8/reference/release-notes#version-3-1-0)
* [Versions & Compatibility](/dist/docs/3.2.8/reference/versions)
* [Versioning & Governance](/dist/docs/3.2.8/reference/versioning)
* [Version Adaptation](/dist/docs/3.2.8/building/cross-cutting/version-adaptation)
# Migrating from 3.1 to 3.2
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/3-1-to-3-2
Role-based checklist for adopting AdCP 3.2 (release 3.2.1, wire pin 3.2) while keeping 3.1 compatibility: exceptions, signing, SDKs, and budgets.
# Migrating from 3.1 to 3.2
> [!NOTE]
>
> **AdCP 3.2 is generally available** (published 2026-09-30). The release
> artifact is `3.2.1` and the wire pin is `"3.2"`; the number `3.2.0` was never
> released. TypeScript `@adcp/sdk@14.0.0` and Python `adcp==8.0.0` ship
> alongside `3.2.1` and embed it. Go and Java support for final 3.2 is planned as a
> follow-up. See [SDK versions for 3.2](#sdk-versions-for-3-2).
3.2 is a minor release over 3.1. Existing integrations do not need to adopt the
new compact tools immediately: `get_products`, `create_media_buy`, and
`update_media_buy` remain the 3.x compatibility facades. A caller opts into 3.2
only after the peer advertises `"3.2"` in `supported_versions`.
For the feature narrative, start with [What's New in AdCP 3.2](/dist/docs/3.2.8/reference/whats-new-in-3-2).
If you pinned a beta or release candidate, see the [3.2 prerelease history](/dist/docs/3.2.8/reference/3-2-beta) for what changed between RC.7 and 3.2.1.
## Start here
1. Read [3.2 compatibility exceptions](#3-2-compatibility-exceptions). They list the
few places where 3.2 can reject a payload 3.1 accepted.
2. If you sign requests, read [Mixed-version request signing](#mixed-version-request-signing)
before any counterparty advertises 3.2 on an endpoint you already call.
3. Pick your SDK line from [SDK versions for 3.2](#sdk-versions-for-3-2).
4. Work through the [day-one checklist for your role](#day-one-checklists-by-role).
5. Check the [wire changes from 3.1 to 3.2](#wire-changes-from-3-1-to-3-2) against
any hand-written validators, parsers, or code generators.
6. If you buy or sell shared budgets, read
[Seller-optimized budgets](#seller-optimized-budgets-core-contract-and-package-controls).
If your products report on a non-UTC clock, read
[Delivery dates on the reporting timezone](#delivery-dates-on-the-reporting-timezone).
## The migration cost is intentional—and bounded
The compact lifecycle adds a second surface during the 3.x compatibility
window because the old facades combine discovery, proposal mutation,
commitment, creation, and operational changes behind overloaded modes. Those
states cannot all be made safe merely by renaming one request.
Use a maintained [AdCP SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk) for
production wherever possible. The SDK can select an advertised compact tool,
perform a proven direct translation, or run a purpose-built stateful adapter.
It must fail with a typed unsupported-capability error when a legacy peer
cannot preserve immutable proposal history, atomic holds, accepted-term
readback, amendments, or idempotent resume. A generic adapter must never
pretend those semantics exist.
Existing 3.1 implementations remain valid. Adopting 3.2 is an incremental
enterprise migration, not a flag day and not a requirement to reimplement both
surfaces by hand.
## Upgrade checklist
| Step | Who | Action |
| - | - | - |
| 1 | Everyone | Upgrade to a 3.2 SDK line with the wire pin still at `"3.1"`, then opt into `"3.2"` per peer. Existing `"3.1"` traffic keeps working. |
| 2 | SDK and codegen maintainers | Generate from the signed `3.2.1` protocol tarball, not `main` or `/schemas/3.2.8/`. |
| 3 | Sellers and agents | Advertise `"3.2"` in `adcp.supported_versions` alongside every release you still serve, and echo the release actually served. |
| 4 | Buyers | Send `adcp_version: "3.2"` only to peers that advertise it. Replace any prerelease pin (`"3.2-rc.N"`, `"3.2-beta.N"`) with `"3.2"`. |
| 5 | Media-buy implementations | Move create/update success handling completely to `media_buy_status`. |
| 6 | Signing implementations | Require `content-digest` coverage and migrate request `Signature` and `Content-Digest` binary values to RFC 8941 padded Base64. The endpoint selects the signing profile, not the request pin; see [Mixed-version request signing](#mixed-version-request-signing). |
| 7 | Producers and SDK maintainers | Emit `error.recovery` on every 3.2 error; keep decoders compatible with 3.1 errors that omit it. |
| 8 | Creative implementations | Adopt canonical format capability/product discovery and isolate legacy projection at compatibility boundaries. |
| 9 | Compliance operators | Grade 3.2 claims against the `3.2.1` compliance bundle with `@adcp/sdk@14.0.0` or `adcp==8.0.0`. Retain the exact package and wire versions. |
| 10 | Delivery-reporting implementations | Emit and consume currency at media-buy or package grain, move qualified outcomes to `by_package[].metric_values`, and stop producing new `aggregated_totals`. Report dates on the products' reporting timezone. |
| 11 | Shared-budget buyers and sellers | Send `budget_allocation` explicitly. Sellers declaring `seller_optimized_budget` also declare the package-control sub-capabilities they honor. |
## 3.2 compatibility exceptions
The [3.x stability guarantees](/dist/docs/3.2.8/reference/versioning#3-x-stability-guarantees)
say stable fields are not removed, and authentication and core security do not
change, within 3.x. 3.2 has a bounded, recorded set of exceptions. The
complete list is in
[3.2 exceptions to 3.x compatibility](/dist/docs/3.2.8/reference/versioning#3-2-exceptions-to-3-x-compatibility):
* **One removed field.** The deprecated body-level `status` on
`create_media_buy` / `update_media_buy` success responses is removed
([DR-0011](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0011-media-buy-status-removal-in-3-2.md)).
Read `media_buy_status`.
* **One request-signing security correction.** 3.2 endpoints require
`content-digest` coverage and RFC 8941 padded Base64. The endpoint selects
the profile, so a signed 3.1 request to a shared endpoint that advertises 3.2
is rejected even when it pins `"3.1"`.
* **Eight tightened request rules.** `create_media_buy` shape and currency,
`build_creative` routes, image package dimensions, `sync_governance` schemes,
account notification `event_types`, `preview_creative` inputs, and the
`adcp_version` pattern. Most encode rules 3.1 already documented; the
versioning table records the basis for each. The Bearer-only
`sync_governance` rule also counts as an authentication exception.
* **Three producer-side tightenings.** Preview `recommended_sandbox`,
committed-proposal `pricing_option_id`, and capability `vast_versions` /
`request_signing` list patterns.
Other stable-surface changes add or widen shapes rather than rejecting 3.1
payloads. Some widened response shapes can still fail a strictly typed 3.1
parser. See
[Version negotiation across 3.1 and 3.2](#version-negotiation-across-3-1-and-3-2).
## Required to claim 3.2 behavior
### Serve and echo the release
Advertise `"3.2"` in `supported_versions` only when you serve the 3.2
contract, keep advertising every earlier release you still serve, and echo the
release actually served. Do not treat a major-only declaration as evidence of
3.2 support. Prerelease pins (`"3.2-rc.N"`, `"3.2-beta.N"`) match exactly and
never resolve to `"3.2"`, so a seller that still advertises only a prerelease
must move to `"3.2"` before stable buyers can reach it.
The 3.2 compliance posture makes missing `supported_versions` or a missing
response echo a blocking failure for a 3.2 claim, even though the fields remain
optional at the 3.x schema level for compatibility.
### Use `media_buy_status` on create/update success
AdCP 3.2 removes the deprecated body-level MediaBuyStatus named `status` from
`create_media_buy` and `update_media_buy` success schemas. Root `status` is the
task-envelope state. Read and emit `media_buy_status` for the buy lifecycle.
Nested `media_buys[].status` and `media_buy_deliveries[].status` do not change
until 4.0. See [Migrating to `media_buy_status`](/dist/docs/3.2.8/reference/migration/media-buy-status)
for cross-version decoder code.
### Bind every signed request body
Request signing is still optional in 3.2. When a 3.2 endpoint does support
request signing, however, it must advertise
`covers_content_digest: "required"`. Every accepted signature on a request with
a body covers `content-digest`; a signed body without coverage is rejected.
Keep legacy `"either"` or `"forbidden"` behavior on a separately configured
3.0/3.1 compatibility endpoint or disable signing for that endpoint. A field
inside an untrusted request body cannot select a weaker verifier posture.
The request-profile binary encoding also changes in 3.2. Emit `Signature` and
`Content-Digest` values as RFC 8941 `sf-binary`: standard RFC 4648 Base64 using
the `+` and `/` alphabet and required `=` padding inside the `::` token.
The 3.0/3.1 request profile used unpadded Base64URL. A 3.2 verifier must reject
that legacy alphabet rather than retrying it through a permissive decoder.
Select the parser from the trusted negotiated endpoint and signing profile, not
from a version field inside the untrusted body. Keep an explicitly routed
3.0/3.1 request endpoint if legacy request signing is required. The separate
`adcp/webhook-signing/v1` profile retains its legacy unpadded Base64URL binary
encoding throughout AdCP 3.x; do not apply the request-profile migration to
webhook receivers. See [Signed requests](/dist/docs/3.2.8/building/by-layer/L1/security#signed-requests-transport-layer).
### Mixed-version request signing
The endpoint selects the request-signing profile. The request's `adcp_version`
pin does not. The [security specification](/dist/docs/3.2.8/building/by-layer/L1/security#signed-requests-transport-layer)
defines the rule in three parts:
* A shared endpoint that advertises a 3.2 release applies the 3.2 rule to
every signed request with a body.
* A signer uses the legacy 3.0/3.1 encoding only on an explicitly negotiated
3.0/3.1 request-signing endpoint.
* A 3.2 verifier never retries a legacy token through a permissive decoder,
and a client never retries unsigned after a signature failure.
| Signer | Endpoint's `supported_versions` | Result |
| - | - | - |
| 3.1 profile (unpadded Base64URL; digest coverage optional) | `["3.0", "3.1"]` | Accepted under the endpoint's legacy `covers_content_digest` policy. |
| 3.1 profile | Contains a 3.2 release, for example `["3.0", "3.1", "3.2"]` | **Rejected, even when the request pins `"3.1"`.** Expect `request_signature_header_malformed` for the Base64URL alphabet, or `request_signature_components_incomplete` when `content-digest` is not covered. |
| 3.2 profile (padded Base64, digest always covered) | Contains a 3.2 release | Accepted, regardless of the request's `adcp_version`. |
| 3.2-capable signer | `["3.0", "3.1"]` only | Sign with the legacy 3.0/3.1 profile for this endpoint. The security specification recommends covering `content-digest` even when the endpoint's policy is `"either"`. |
**Sellers.** Adding a 3.2 release to `supported_versions` on an existing URL
changes the verifier for every signed caller of that URL. If you have signed
3.1 counterparties, choose one of these paths:
1. Keep the existing URL on the 3.0/3.1 posture and serve 3.2 from a
separately configured endpoint or origin. AdCP has no capability field that
points from one endpoint to another. The new endpoint is a distinct agent
URL that you publish, for example as its own `agents[]` entry, or
communicate directly.
2. Coordinate the cutover. Confirm that each signing counterparty signs with
the 3.2 profile for your endpoint before you advertise 3.2 on the shared URL.
**Buyers.** Move to a 3.2-capable SDK before your signing counterparties
advertise 3.2. Confirm that your signer uses the 3.2 profile for any endpoint
that advertises a 3.2 release, including requests you still pin to `"3.1"`.
The TypeScript 14.x and Python 8.x migration guides describe choosing the
profile from the configured or negotiated wire version. If your client pins
`"3.1"` to an endpoint that advertises 3.2, set the 3.2 signing profile
explicitly for that peer. See [SDK versions for 3.2](#sdk-versions-for-3-2).
Webhook signing (`adcp/webhook-signing/v1`) keeps its legacy encoding
throughout 3.x and is unaffected.
### Populate recovery without rejecting legacy errors
AdCP 3.2 producers MUST populate `error.recovery` on every error. AdCP 3.1
producers SHOULD populate it, and the shared 3.x schema deliberately continues
to require only `code` and `message`. Do not make `recovery` schema-required in
a shared decoder: stored responses and live 3.1 peers may validly omit it.
Consumers use wire `recovery` when present. When it is absent, use the
registered classification for a known code and the bounded `transient`
fallback for an unknown code. Determine that classification before consulting
`retry_after`; a delay never makes a `correctable` or `terminal` error eligible
for automatic retry.
SDK suites should consume the versioned [error-recovery reference vectors](https://adcontextprotocol.org/compliance/latest/test-vectors/error-recovery/vectors.json), replacing `latest` with the exact protocol artifact version for release qualification. The vectors include the known/unknown decision table, semantic `buyer_reason` consistency, retry-budget exhaustion, and legacy fractional delays.
### Emit integer retry delays
3.2 producers emit `error.retry_after` as an integer number of seconds. Clients
that still receive a legacy fractional value should round up before applying
their bounded retry policy. Apply the delay only after classifying the error as
`transient`; never automatically retry a `correctable` or `terminal` error
merely because the field is present. Do not read `retry_after` from
`error.data`.
### Move delivery reporting to row-level semantics
The response-wide `currency` and `aggregated_totals` fields on
`get_media_buy_delivery` are deprecated in 3.2 and removed in 4.0. Sellers
SHOULD omit new `aggregated_totals` output. When retaining `aggregated_totals`,
sellers MUST also emit the legacy response-wide `currency` to denominate its
spend. Buyers MUST tolerate both fields being absent and MUST NOT otherwise
treat the legacy currency as an aggregation currency.
For a single-currency media buy, sellers SHOULD emit
`media_buy_deliveries[].currency`; package currencies MUST match it. For a
legacy or externally created mixed-currency buy, omit the row currency and
`daily_breakdown`, and omit monetary or money-derived values from row and
window totals. Report those values only on package rows (including window
package rows) with each package's own currency. AdCP does not define currency
conversion.
Qualified standard delivery metrics move from the deprecated cross-buy
`aggregated_totals.metric_aggregates` array to
`by_package[].metric_values`. Reconcile `committed_metrics`, `metric_values`,
and `missing_metrics` on `(scope, metric_id, qualifier)`. Vendor-defined
delivery continues to use `by_package[].vendor_metric_values`. During migration,
buyers MAY read legacy aggregate rows but SHOULD prefer package values and
calculate a higher-level result only after checking currency, qualifiers,
measurement windows, finality, and deduplication semantics.
When a qualified standard metric is present in `metric_values`, sellers MUST
omit its flat package scalar so consumers never see two sources of truth.
## Version negotiation across 3.1 and 3.2
The [negotiation rules](/dist/docs/3.2.8/reference/versioning#version-negotiation) do not
change in 3.2. The seller advertises `supported_versions`, and the buyer sends
`adcp_version`. The seller serves the exact release or the highest supported
release at or below the pin, then echoes the release it served. Prerelease pins
match exactly, and a release pin never resolves onto a prerelease.
| Buyer pin | Seller advertises | Served | What the buyer should expect |
| - | - | - | - |
| `"3.1"` | `["3.0", "3.1"]` | `"3.1"` | Unchanged 3.1 behavior. |
| `"3.1"` | `["3.0", "3.1", "3.2"]` | `"3.1"` | 3.1 contract through the compatibility facades. `error.recovery` is usually present, and `retry_after` is an integer. **Signed requests are rejected** unless signed with the 3.2 profile ([Mixed-version request signing](#mixed-version-request-signing)). |
| `"3.2"` | `["3.0", "3.1", "3.2"]` | `"3.2"` | Compact tools when `media_buy.lifecycle_tools` declares them. Gate every other 3.2 field on capabilities. |
| `"3.2"` | `["3.0", "3.1"]` | `"3.1"` | Downshift to 3.1. Read the echo and use the 3.x facades or an SDK coordinator. |
| `"3.2"` | `["3.0", "3.1", "3.2-rc.7"]` | `"3.1"` | A release pin never resolves onto a prerelease. The seller must advertise `"3.2"`. |
| `"3.2-rc.7"` | `["3.0", "3.1", "3.2"]` | none | `VERSION_UNSUPPORTED`. Prerelease pins never resolve to a release. Re-pin to `"3.2"`. |
3.x sellers keep the `get_products`, `create_media_buy`, and
`update_media_buy` compatibility facades. A seller that exposes only the
compact tools cannot serve an unchanged 3.1 buyer.
**Response shapes when serving `"3.1"`.** The spec requires the echo, and it
tells buyers to validate against the echoed release. It does not yet state
normatively that a seller serving `"3.1"` must produce a response valid under
the 3.1 schema. [#7718](https://github.com/adcontextprotocol/adcp/issues/7718)
tracks that gap. Until then, follow the
[non-normative guidance](/dist/docs/3.2.8/reference/versioning#serving-an-older-pin). These
3.2 shapes fail a strict 3.1 validator if a seller emits them under a 3.1 pin:
* `get_adcp_capabilities`: `media_buy.execution.targeting.geo_regions` and
`.language` can be objects instead of booleans. This is the discovery call
itself, so parse it tolerantly.
* `core/pricing-option.json`: new `revenue_share` arm.
* `get_products`: terminal `status: "rejected"` response without `products`.
* `sync_accounts` rows that carry `account` without `brand` / `operator`.
* `get_media_buys` `available_actions[]` canonical action objects.
* `get_media_buy_delivery` without root `currency` or `totals.spend`.
Sellers should project these shapes, or omit them, when serving 3.1. Buyers
should accept unknown enum values, unknown union arms, and the object forms
above.
## Adopt by capability
### Plan anonymous catalog discovery
Before omitting caller credentials, read `media_buy.anonymous_discovery` for
`list_products` and discovery-mode `get_products`, or
`signals.anonymous_discovery` for `get_signals`. `true` means an anonymous call
can succeed; it does not mean the response is a complete seller catalog or that
authenticated buyers and accounts receive identical data. `false` means the
discovery call requires an authenticated principal. Absence is the 3.1 and
early-3.2 posture: treat the requirement as unspecified, probe if appropriate,
and handle `AUTH_MISSING` without assuming a seller defect.
Presented credentials are always validated. An invalid credential does not
fall back to anonymous discovery. Mutations and private or account-scoped reads
remain authenticated by protocol rule and do not use these discovery flags.
### Compact product and MediaBuy lifecycle
Read `get_adcp_capabilities.media_buy.lifecycle_tools` before choosing a tool.
Use:
* `list_products` for published offer listing;
* `request_proposals`, `refine_proposals`, and `decline_proposals` for immutable
proposal negotiation;
* `buy_products` for direct purchase;
* `accept_proposal` for committed new-buy, amendment, or negotiated-cancellation
terms;
* `control_media_buy` for operational controls inside accepted terms.
Absence of the declaration means use the 3.x compatibility facades. Retry a
stateful request with the same tool name, idempotency key, and payload; an
idempotency key does not create replay identity across old and new task names.
**Correction: the proposal-flow schemas are open.** 3.2.7 and earlier published
these tasks' request and response schemas closed, with
`additionalProperties: false`. They also closed `canonical-proposal`,
`canonical-product`, `product-discovery-criteria`, `proposal-refinement`,
`package-control`, and `opportunity-context`.
[DR-0019](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0019-closed-row-schemas-deliberate-class.md)
keeps roots and containers open, so later 3.2 patches reopen them. This is a
correction recorded in
[DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)
([#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). Every payload
that was valid stays valid. A field that only the legacy Product defines,
such as `format_ids`, `is_custom`, or `installments`, is still rejected on a
canonical product. A root `feed_version` or `pricing_version` on a
`request_proposals` response, and `warnings` on an error or submitted
`buy_products`, `accept_proposal`, or `control_media_buy` response, are also
still rejected. `commercial_terms` and the purchases inside it stay closed. A
validator on 3.2.7 or earlier still rejects unknown fields on these schemas, so
don't send fields the served release doesn't define.
### Scope idempotency to mutations
AdCP 3.2 requires durable replay for state-mutating requests, not guaranteed
pure reads. Read-tool wrappers still accept an optional `idempotency_key`, but
the handler may ignore it and execute normally. Buyers must not interpret
`adcp.idempotency.supported: true` as a promise of byte-stable read replay.
Buyer SDKs should omit keys on pure reads. Generic wrappers that attach one
must treat every poll or state re-read as a fresh request and must not reuse the
key from the mutation whose state they are reading. Sellers that voluntarily
cache keyed reads follow the complete replay, durability, rate-limit, and
encryption rules and document the resulting freshness behavior.
The 3.x `get_products` facade leaves the key optional on every arm for wire
compatibility. A seller may ignore a supplied key on a guaranteed
side-effect-free synchronous read. Buyers should supply a key whenever the
request may allocate a task, finalize a proposal, or otherwise change observable
state. When supplied and the seller declares `adcp.idempotency.supported: true`, the
seller applies replay protection before that effect. If the key is omitted or
the seller declares `adcp.idempotency.supported: false`, an ambiguous result has no portable
at-most-once retry guarantee. New callers should use the compact tasks so the
read/mutation boundary is explicit.
### Resolve product, proposal, and live action rights
Use product `allowed_actions[]` only to select offers. Binding rights live in
accepted `commercial_terms.change_terms[]`; the live buy's
`available_actions[]` is the authoritative current-state subset. A 3.2 buyer
uses `available_actions[].change_term_id` to resolve the accepted proposal
term, including its `allowed_statuses`, constraints, mode, and processing SLA.
The `available_actions[].terms_ref` field shipped in 3.1 and remains valid but
opaque. Continue parsing it for 3.1 peers. A 3.2 seller may echo a
`change_term_id` there for an older consumer, but new integrations emit and
prefer `change_term_id`; if both are used as term links, they must agree.
Remove the alias only with AdCP 4.0.
### Targeting-aware discovery
Move structured delivery constraints from briefs and legacy filters into
`targeting_overlay`. Use `required_overlay_support` only for dimensions whose
values will be supplied later. Treat returned configured product IDs as scoped
to their declared lineage, account, cache scope, and expiry.
Follow the complete field map in [Targeting-aware product discovery](/dist/docs/3.2.8/reference/migration/targeting-aware-discovery).
### Canonical creative discovery
For new integrations:
* sales agents expose accepted `format_options[]` on products;
* creative agents expose `creative.supported_formats` with stable capability
IDs and supported operations;
* build and transformer calls select the canonical capability;
* buyers do not require `list_creative_formats` when canonical discovery is
available.
The compatibility task remains functional on its own schedule. Exact plural
`format_ids` is deprecated in 3.2 for removal in 4.0; singular legacy
`format_id` mappings retain their separate compatibility path.
### Secured assets
Stop producing inline `service_account.credentials`. Prefer a short-lived
asset-scoped signed URL, pre-authorized workload identity, or a bounded bearer
token when the origin requires an Authorization header. Continue parsing the
legacy shape for 3.x compatibility, but never activate received credentials
automatically. See [Migrating secured asset access](/dist/docs/3.2.8/reference/migration/asset-access).
### MediaBuy-level frequency caps
3.2 adds a root `frequency_cap` on `create_media_buy` and `buy_products`. It is
a maximum-impression cap with **one counter shared across every package** in
the buy. Package caps (`packages[].targeting_overlay.frequency_cap`) keep their
independent per-package counters.
* **Sellers** advertise `media_buy.aggregate_frequency_capping` in
`get_adcp_capabilities`. Each participating product declares
`media_buy_support.frequency_cap`, plus any narrower
`frequency_cap_constraints`. Reject an unsupported root cap with
`UNSUPPORTED_FEATURE` before any mutation. Never drop, soften, or clamp it.
Products can also declare structured package-cap support on
`overlay_support.frequency_cap_support`.
* **Buyers** send a root cap only when the seller advertises
`aggregate_frequency_capping` and every selected product declares compatible
`media_buy_support`. Use `required_media_buy_support` in product discovery to
find those products. The root cap requires `max_impressions` and does not
accept `suppress` or `suppress_minutes`. It is not accepted when executing a
committed proposal: the `create_media_buy` schema forbids `frequency_cap`
alongside `proposal_id` + `total_budget`.
* **Live buys** change the cap through the `update_media_buy_frequency_cap`
action when `available_actions[]` offers it.
The 3.1 `create_media_buy` schema has no root `frequency_cap` and allows
additional properties, so a 3.1 seller can ignore the field without an error.
Gate on the capability before relying on the cap.
### Seller-optimized budgets: core contract and package controls
A seller-optimized buy (`budget_allocation.mode: "seller_optimized"`) lets the
seller allocate one shared `total_budget` across packages against
`budget_allocation.optimization_goals`. In 3.2 the capability is split so a
platform that supports only shared budgets can declare it honestly. All four
flags live in `get_adcp_capabilities.media_buy.features`
(`core/media-buy-features.json`):
| Capability | What it covers |
| - | - |
| `seller_optimized_budget` | The core contract: one hard `total_budget`, seller allocation across packages, media-buy-level pacing, and allocation echo on read surfaces |
| `seller_optimized_package_budgets` | Package `budget` hard caps inside a seller-optimized buy, and proposal `max_spend_percentage` |
| `seller_optimized_min_spend_targets` | Package `min_spend_target`, including over-subscription validation, and proposal `min_spend_target_percentage` |
| `seller_optimized_package_pacing` | Package `pacing` that differs from media-buy pacing, and proposal allocation `pacing` |
A seller that implements every control declares all four:
```json theme={null}
{
"media_buy": {
"features": {
"seller_optimized_budget": true,
"seller_optimized_package_budgets": true,
"seller_optimized_min_spend_targets": true,
"seller_optimized_package_pacing": true
}
}
}
```
* **Sellers.** Declare a sub-capability only with `seller_optimized_budget: true`;
the capabilities schema rejects one without the parent. Without a given
sub-capability, reject a seller-optimized request that carries that control
with `UNSUPPORTED_FEATURE`, before any over-subscription check or provider
mutation. Never drop or coerce it. Accept omitted media-buy `pacing` (it
defaults to `even` when `total_budget` is present) and `pacing: "even"`. You
may reject `asap` or `front_loaded` with `UNSUPPORTED_FEATURE`
(`error.field: "pacing"`), but never coerce them to `even`. If you declared
`seller_optimized_budget: true` against a release candidate and honor package
caps, minimum-spend targets, or package pacing, add the matching
sub-capabilities.
* **Buyers.** Send `budget_allocation` explicitly: `{"mode": "fixed"}` or a
`seller_optimized` block. Omission still means fixed allocation, but it hides
intent. When the principal's instruction doesn't say whether the budget is
one shared pool or split per package, ask the principal instead of guessing.
Before sending package caps, minimum-spend targets, or package pacing on a
seller-optimized buy, check the matching sub-capability. `required_features`
filters in product discovery can request a sub-capability on its own.
### Delivery dates on the reporting timezone
3.1 described every `get_media_buy_delivery` period as UTC, while
`reporting_capabilities.timezone` could name another zone. 3.2 resolves the
conflict in favor of the seller's reporting clock:
* `start_date`, `end_date`, and buy-level and package-level
`daily_breakdown[].date` are calendar dates in the reporting timezone, which
is the in-scope products' `reporting_capabilities.timezone`. They are UTC
days only when that timezone is `UTC`.
* `reporting_period.start` and `end` stay RFC 3339 instants: where the
requested dates begin in the reporting timezone, for example
`2026-04-15T00:00:00-04:00`, as a start-inclusive, end-exclusive interval.
Windowed `daily`, `weekly`, and `monthly` slices use the same boundaries.
* The new optional `reporting_period.timezone` echoes the zone applied.
Sellers SHOULD return it on reads without `reporting_revision_id`.
* A dated request, or a request with `time_granularity` `daily`, `weekly`,
`monthly`, or `quarterly`, whose in-scope packages span more than one
reporting timezone MUST be rejected with `VALIDATION_ERROR`. Narrow
`media_buy_ids`, or omit both dates and `time_granularity` for lifetime
totals.
* Sellers serving a `"3.1"` pin may keep their existing 3.1 delivery-date
behavior; the reporting-timezone semantics and `reporting_period.timezone`
apply to `"3.2"` (see [Serving an older pin](/dist/docs/3.2.8/reference/versioning#serving-an-older-pin)).
**Sellers not on UTC:** compute date boundaries in your declared reporting
timezone, echo `reporting_period.timezone`, and reject mixed-timezone dated
requests. **Buyers:** interpret dates in the echoed or declared reporting
timezone and don't assume UTC midnight. Sellers whose products report in
`UTC` see no change.
### Reliable Reporting (experimental)
Reliable Reporting 1.0 is an experimental, separately discovered surface
(`media_buy.reporting_delivery`, `reliable_reporting_version: "1.0"`). It adds
expected-period obligations, immutable revisions, and `get_reporting_status`
readback. Optional tiers add Managed Delivery and Reconciled Billing
(`sync_reporting_receipts`). Nothing changes for 3.1 integrations that do not
opt in.
* **Sellers** publish the `media_buy.reporting_delivery` capability block for
the tiers they implement and list `media_buy.reporting_delivery` in
`experimental_features`.
* **Buyers** configure delivery through
`sync_accounts.reporting_delivery_configs[]`. Derive expected periods
independently. Do not treat a missing report as zero delivery.
* **Consumer-status loop.** `sync_reporting_status` is opt-in in 3.2. Sellers
advertise `consumer_status_task` only when it is implemented. An active
breaking-change notice makes it required for Reliable Reporting Core no
in the next eligible minor after October 24, 2026. See the
[consumer-status migration](/dist/docs/3.2.8/reference/migration/reliable-reporting-status-loop).
Start with [Implementing Reliable Reporting Core](/dist/docs/3.2.8/media-buy/reporting-core-implementation-guide).
### Authenticated principals (experimental)
The experimental `protocol.principal` surface
([`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal) and
[`get_principal`](/dist/docs/3.2.8/protocol/get_principal)) stores configuration that
belongs to an authenticated caller's standing relationship with a seller. That
covers caller-level webhook subscriptions, reusable reporting destinations,
and declarations of the async versions, signing algorithms, and experimental
features the caller can consume.
* It never grants advertiser-account authority. Every account and
reporting-feed binding is still authorized independently.
* Discover it through the `adcp.principal` capability. Call `get_principal` to
repair cached state after a `principal.changed` notification.
* 3.1 integrations need no change. Per-account `notification_configs` on
`sync_accounts` keep working.
The account change feed
([`list_account_changes`](/dist/docs/3.2.8/accounts/tasks/list_account_changes), gated by
`account.change_feed.supported`) is also experimental in 3.2, under feature id
`account.change_feed`. Adopt it only behind its capability declaration.
### New sales specialisms
3.2 adds four seller specialisms that `get_adcp_capabilities.specialisms` can
claim. See the [compliance catalog](/dist/docs/3.2.8/building/verification/compliance-catalog)
for storyboards and grading.
| Specialism | Status | Claim it when |
| - | - | - |
| `sales-dooh` | stable | You sell non-guaranteed digital out-of-home venue and screen inventory with canonical screen formats and play reporting. Guaranteed-only DOOH sellers keep claiming `sales-guaranteed`. |
| `sales-streaming-tv` | preview | You sell CTV/streaming inventory with SSAI video, audience buying, and household frequency capping. |
| `sales-retail-media` | preview | You run a retail media network with catalog-driven sponsored search and display. |
| `sales-exchange` | preview | You operate a programmatic exchange or SSP with floor prices, bid guidance, and auction transparency. |
3.2 also adds preview buyer specialisms (`buyer-discovery`,
`buyer-activation`, `buyer-negotiation`, `buyer-monitoring`, `buyer-recovery`)
and `orchestrator-multi-agent`. Buyers that exhaustively switch on
`specialisms` must tolerate these new values.
### Experimental governance
If you implement `governance.campaign`, update authenticated caller binding,
task-scoped enforcement, intent/execution separation, payload and commitment
binding, and outcome reconciliation together. Do not partially adopt the new
authorization semantics under an old capability declaration.
See [Cross-role governance enforcement](/dist/docs/3.2.8/reference/migration/cross-role-governance-enforcement).
## SDK versions for 3.2
The SDK major version tracks the AdCP minor it embeds. Upgrading the SDK major
is a separate step from adopting the 3.2 wire. SDK 14 and SDK 8 still call and
serve 3.0/3.1 peers.
| Language | Package | AdCP 3.1 line | AdCP 3.2 line | Stable 3.2 release | Upgrade guides |
| - | - | - | - | - | - |
| TypeScript | `@adcp/sdk` | 13.x (npm `adcp-3.1` tag) | 14.x | `14.0.0` (npm `latest` and `adcp-3.2` tags), embeds `3.2.1` | [13 → 14](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-13-to-14.md), [12 → 14](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/migration-12-to-14.md) |
| Python | `adcp` | 7.x | 8.x | `8.0.0`, embeds `3.2.1` | [v7 → v8](https://github.com/adcontextprotocol/adcp-client-python/blob/main/MIGRATION_v7_to_v8.md), [AdCP 3.1 → 3.2](https://github.com/adcontextprotocol/adcp-client-python/blob/main/MIGRATION_ADCP_3.1_TO_3.2.md) |
| Go | `github.com/adcontextprotocol/adcp-go/adcp/v3` | `v3.x`, default wire pin `"3.1"` | Planned follow-up | None yet (planned follow-up); current `v3.2.1` embeds `3.2.0-rc.1` preview types | [MIGRATING.md](https://github.com/adcontextprotocol/adcp-go/blob/main/MIGRATING.md) (v2 → v3 import paths only) |
| Java | — | — | Planned follow-up | None yet | — |
Go module versions are not AdCP versions. `adcp/v3@v3.2.1` is an SDK release
that embeds the `3.2.0-rc.1` schemas and defaults to the `"3.1"` wire pin. It
is not "AdCP 3.2.1". Treat Go as a 3.1 production SDK with preview 3.2 types
until a Go release embeds final 3.2 schemas. Java support for 3.2 is also
planned as a follow-up.
**Recommended rollout.** Upgrade the SDK and keep the wire pin at `"3.1"`.
Deploy and verify. Then opt into 3.2 one peer at a time, after each peer
advertises it. Sellers keep advertising every release they still serve.
**SDK changes that need attention during the upgrade.** Details are in each
SDK's guide.
* TypeScript 13 → 14:
* Requires Node `^20.19.0 || >=22.12.0` and `@a2a-js/sdk` 1.x.
* Upgrade durable idempotency storage (the `retain_until` column and the
atomic store methods) before serving traffic. Retries that hit an SDK 13
idempotency entry return `IDEMPOTENCY_CONFLICT`.
* Servers separate `adcpVersion` (the supported ceiling) from
`defaultAdcpVersion` (used for unversioned callers).
* Media-buy handlers return `media_buy_status`.
* `accounts.resolution: 'derived'` becomes an upstream-managed account-id
namespace.
* Python 7 → 8:
* `handle_webhook()` rejects unsigned callbacks by default.
* Low-level `sign_request()` requires an explicit `signing_profile_version`.
* `ADCPClient` derives the signing profile from its trusted wire pin.
## Day-one checklists by role
Each checklist has two parts. "If you do nothing" is what happens when a
counterparty moves to 3.2 and you stay on 3.1. "Day one on 3.2" is the minimum
to adopt 3.2 yourself.
### Seller (sales agent)
**If you do nothing:** 3.2 buyers downshift to your advertised 3.1 release and
use the 3.x facades. Nothing breaks. Buyers still pinned to a 3.2 prerelease
get `VERSION_UNSUPPORTED` and must re-pin to `"3.2"`.
**Day one on 3.2:**
* [ ] Decide how signed 3.1 callers keep working before you add a 3.2 release
to `supported_versions` on a shared URL
([Mixed-version request signing](#mixed-version-request-signing)).
* [ ] Keep the 3.0/3.1 handlers and `get_products` / `create_media_buy` /
`update_media_buy` facades. Advertise every release you serve, and echo
the served release.
* [ ] Emit `media_buy_status` and no body-level `status` on 3.2
create/update success.
* [ ] Emit `error.recovery` on every error and integer `retry_after`.
* [ ] If you advertise request signing, advertise
`covers_content_digest: "required"` and verify RFC 8941 Base64.
* [ ] Declare only the capabilities you implement: `lifecycle_tools`,
`aggregate_frequency_capping`, `anonymous_discovery`, and specialisms.
* [ ] When serving `"3.1"`, project or omit 3.2-only shapes
([guidance](#version-negotiation-across-3-1-and-3-2)).
* [ ] Move delivery reporting to row-level currency and `by_package[].metric_values`.
### Buyer
**If you do nothing:** A 3.2 seller that retains its 3.1 release keeps serving
you. There are two exceptions:
* **Signed requests** fail once the seller advertises 3.2 on the endpoint you
call.
* **Strict parsers** can fail on 3.2 capability or response shapes if the
seller does not project them.
**Day one on 3.2:**
* [ ] Upgrade to a 3.2-capable SDK line ([SDK versions](#sdk-versions-for-3-2))
with your pin still at `"3.1"`.
* [ ] Sign with the 3.2 profile for every endpoint that advertises a 3.2
release.
* [ ] Read `supported_versions`. Pin 3.2 only for peers that advertise it, and
validate against the echoed release.
* [ ] Read `media_buy_status` on create/update success.
* [ ] Classify errors with `error.recovery`, and fall back to the code registry
when it is absent. Apply `retry_after` only to `transient` errors.
* [ ] Gate compact tools on `media_buy.lifecycle_tools`, and the root
`frequency_cap` on `aggregate_frequency_capping`.
* [ ] Fix request shapes that 3.2 rejects: `create_media_buy` packages versus
`proposal_id`, uppercase `total_budget.currency`, and `preview_creative`
inputs ([wire changes](#wire-changes-from-3-1-to-3-2)).
* [ ] Read delivery currency per media buy or package, and tolerate a missing
root `currency` or `totals.spend`.
### Creative agent
**If you do nothing:** Buyers that call `build_creative` with no target route,
or with both manifest and library inputs to `preview_creative`, are rejected by
3.2 validators, not by you. Your 3.1 preview renders fail 3.2 validation if
`embedding.recommended_sandbox` is non-empty.
**Day one on 3.2:**
* [ ] Emit `embedding.recommended_sandbox: ""`. Never grant iframe sandbox
capabilities.
* [ ] Publish canonical `creative.supported_formats[]` capability IDs and
supported operations.
* [ ] Accept exactly one `build_creative` target route, and accept
`target_capability_id(s)` as well as legacy `target_format_id(s)`.
* [ ] Isolate named-format (`format_id`, `list_creative_formats`) handling at
a compatibility boundary. Named formats are deprecated in 3.2.
### Signals agent
**If you do nothing:** No 3.2 change breaks a 3.1 signals agent. Buyers still
discover and activate signals on the 3.1 contract.
**Day one on 3.2:**
* [ ] Advertise and echo the exact release you serve.
* [ ] Declare `signals.anonymous_discovery` only if an anonymous `get_signals`
call can succeed.
* [ ] Emit `error.recovery` on every error.
* [ ] Claim only the attestation, targeting, or feedback capabilities you
implement.
### Governance agent (experimental)
**If you do nothing:** Campaign governance is experimental, and its 3.2
revision changes request and outcome shapes. 3.2 closes
`report_plan_outcome.delivery` and requires `target_agent` in
`check_governance` tool+payload mode, so 3.1-shaped governance calls fail 3.2
validation. Governance parties migrate together.
**Day one on 3.2:**
* [ ] Migrate caller binding, task-scoped enforcement, `target_agent`, and
outcome reconciliation together, under the `governance.campaign`
experimental declaration.
* [ ] Accept `report_plan_outcome.delivery` in its closed 3.2 shape:
`observation_id`, `source`, `observed_at`, `reporting_period`,
`cumulative_spend`, and `currency`.
* [ ] Register Bearer credentials only. `sync_governance` rejects
`HMAC-SHA256`.
* [ ] Follow [Cross-role governance enforcement](/dist/docs/3.2.8/reference/migration/cross-role-governance-enforcement).
## Role-based minimums
| Role | Minimum before advertising or sending 3.2 |
| - | - |
| Hand-rolled buyer | `"3.2"` discovery and pin, validation against the `3.2.1` schemas, `media_buy_status` handling, open error-code decoding, and capability gates for every new tool/field. |
| SDK buyer | `@adcp/sdk@14.0.0` or `adcp==8.0.0` (or another SDK that names the `3.2.1` bundle), plus the same capability and negotiation checks. |
| Seller | Exact release advertisement and echo, 3.1 compatibility routing, canonical status emission, integer retry delays, and truthful task/targeting/format capabilities. |
| Creative agent | Canonical supported-format capabilities, operation selection, and explicit compatibility handling for legacy named formats. |
| Signals or measurement agent | `"3.2"` advertisement and echo, and only the attestation, targeting, or feedback capabilities actually implemented. |
| Governance provider/service | `"3.2"` advertisement and echo, `governance.campaign` experimental declaration, and the complete cross-role authorization migration. |
| SDK maintainer | Signed `3.2.1` bundle ingestion, generated-type/validator tests, and an exact support matrix entry. |
| Compliance operator | The `3.2.1` compliance bundle, a matching SDK package, and the `"3.2"` wire pin end to end. Prerelease runs are diagnostic only. |
## Wire changes from 3.1 to 3.2
This table compares the `3.1.24` schemas with the `3.2.1` release. It lists changes that can break an existing
3.1 implementation or that need a code change. Purely additive optional fields
and new tasks are omitted.
**Direction key:**
* **Sender**: a 3.1 request is rejected.
* **Parser**: a strict 3.1 parser may reject a 3.2 response.
* **Producer**: a 3.1 producer's output fails 3.2 validation.
* **Deprecation**: still accepted in 3.x.
**Stable surfaces**
| # | Change | Direction | Affects | Action |
| - | - | - | - | - |
| 1 | Body-level `status` removed from `create_media_buy` / `update_media_buy` success | Parser | Buyers still reading body `status` | Read `media_buy_status` ([guide](/dist/docs/3.2.8/reference/migration/media-buy-status)). |
| 2 | Request `Signature` / `Content-Digest` use RFC 8941 padded Base64; `content-digest` coverage mandatory on 3.2 endpoints | Sender | Signing buyers, verifying sellers | See [Mixed-version request signing](#mixed-version-request-signing). |
| 3 | `error.recovery` populated on every 3.2 error; `retry_after` is an integer | Producer | Sellers and all agents | Always emit both. Decoders keep tolerating 3.1 errors without `recovery`. |
| 4 | `get_media_buy_delivery`: root `currency` no longer required (it is required only with `aggregated_totals`); `totals.spend` no longer required; `aggregated_totals` deprecated. The delivery webhook result (`media-buy-delivery-webhook-result`) also drops root `currency` from `required` | Parser | Reporting pipelines | Read currency per media buy or package. Tolerate missing `spend` on mixed-currency buys. |
| 5 | `create_media_buy` root `anyOf`: explicit `packages` without `proposal_id`, or `proposal_id` + `total_budget` without `packages` | Sender | Buyers sending both, or neither | Send exactly one shape. |
| 6 | `total_budget.currency` pattern `^[A-Z]{3}$` | Sender | Buyers sending lowercase codes | Send uppercase ISO 4217. |
| 7 | `build_creative`: exactly one target route; refinements carry none; `target_format_ids` `maxItems: 50` | Sender | Buyers and orchestrators calling creative agents | Send one of `target_capability_id(s)` / `target_format_id(s)`. |
| 8 | Package `format_kind: "image"` with `params` requires `width` and `height` together | Sender | Buyers using canonical image selectors | Send both dimensions. |
| 9 | `sync_governance` `authentication.schemes` is `"Bearer"` only | Sender | Buyers registering governance agents with HMAC | Use Bearer. |
| 10 | Account `notification_configs[].event_types` rejects `scheduled`, `final`, `delayed`, `adjusted`, `window_update`, `impairment` | Sender | Buyers configuring `sync_accounts` notifications | Remove media-buy-anchored types. 3.1 prose already forbade them. |
| 11 | `preview_creative`: `creative_manifest` and `creative_id` are mutually exclusive | Sender | Buyers sending both | Send one. |
| 12 | `adcp_version` / `supported_versions[]` pattern rejects leading zeros and trailing separators | Sender | Hand-rolled clients | Emit canonical `MAJOR.MINOR[-PRERELEASE]`. |
| 13 | Preview `embedding.recommended_sandbox` must be `""` | Producer | Creative agents | Emit `""`. |
| 14 | Committed proposals require `allocations[].pricing_option_id`; capability `vast_versions` is a closed enum; `request_signing.*_for` entries match `^[a-z][a-z0-9_]*$` | Producer | Sellers | Emit the constrained values. |
| 15 | `targeting.language` accepts BCP 47 tags (`en-US`), not only ISO 639-1 | Parser (both directions) | 3.1 sellers validating incoming targeting, and buyers validating echoed or read-back targeting | Accept BCP 47 tags; 3.1 two-letter codes stay valid. |
| 16 | Capabilities `targeting.geo_regions` and `targeting.language`: boolean → boolean or object | Parser | Strictly typed capability parsers | Accept both forms ([negotiation](#version-negotiation-across-3-1-and-3-2)). |
| 17 | `get_products` terminal `status: "rejected"` arm (no `products` or `cache_scope`) | Parser | Buyers validating `get_products` | Handle `rejected`, with `reason` and optional `suggestions`. |
| 18 | `pricing-option` `revenue_share` arm; `pricing_model` gains `revenue_share` | Parser | Buyers with a closed pricing `oneOf` | Skip unknown pricing models. |
| 19 | `sync_accounts` rows: `brand` / `operator` required only without `account` and forbidden with it; `status` optional on failed rows | Parser | Buyers requiring `brand` / `operator` | Accept the `account`-anchored row form. |
| 20 | `get_media_buys` `available_actions[]` accepts canonical action objects; actions gain `update_name`, `update_budget_allocation`, `update_bidding`, `update_media_buy_frequency_cap`; action mode gains `seller_managed` | Parser | Buyers switching on actions | Tolerate unknown actions and modes. |
| 21 | New union arms: `product-format-declaration` (`audio_vast`, `seller_rendered_stateful_display`, `coordinated_placements`), `asset-union` (`display_tag`), async `submitted` arms on `preview_creative` / `get_creative_features` | Parser | Strict validators and code generators | Tolerate unknown arms. |
| 22 | New either-or requirements: `capability_id` or `format_id` on build previews; `output_capability_ids` or `output_format_ids` on transformers; `property_ids` or `identifiers` on collection distributions | Parser | Creative and collection consumers | Accept either form. |
| 23 | Enum additions, including `delivery_status: "not_delivering"` on `get_media_buy_delivery` packages and the delivery webhook (it already existed on `get_media_buys`), `partially_approved`, `proposal_status: "accepted"`, reporting frequencies (`weekly`, `quarterly`, `post_campaign`), 10 specialisms, and notification types | Parser | Exhaustive switches | Unknown-value tolerance. |
| 24 | `bid_price` and pricing-option `max_bid` deprecated in favor of `bidding.bid_amount` / `bidding.max_bid` | Deprecation | Auction buyers and sellers | Emit `bidding`; keep reading `bid_price`. |
| 25 | Named formats deprecated: `core/format-id.json`, `core/format.json`, `list_creative_formats` | Deprecation | Creative and sales agents | Move to canonical capability discovery ([Canonical creative discovery](#canonical-creative-discovery)). |
| 26 | `get_media_buy_delivery` dates are reporting-timezone calendar dates, not UTC; mixed-timezone dated or windowed (`time_granularity`) requests return `VALIDATION_ERROR` | Sender / Parser | Buyers of non-UTC products | Interpret dates in `reporting_period.timezone`; narrow `media_buy_ids` ([details](#delivery-dates-on-the-reporting-timezone)). |
**Experimental surfaces** (changed under the six-week notice contract; affect
only implementations that declare the feature)
| # | Change | Direction | Affects | Action |
| - | - | - | - | - |
| 27 | Governance: `report_plan_outcome.delivery` is closed (`additionalProperties: false`) with six required fields; `check_governance` tool+payload mode requires `target_agent` and `plan_id` | Sender | Governance buyers, sellers, and agents | [Cross-role governance enforcement](/dist/docs/3.2.8/reference/migration/cross-role-governance-enforcement). |
| 28 | Trusted Match: `Offer.macros` removed in favor of `creative_data`; `signals.targeting_kvs`, `context`, and `ext` forbidden on context-match responses | Sender / Producer | TMP routers, providers, and publishers | See the [Offer](/dist/docs/3.2.8/trusted-match/specification#offer) definition in the Trusted Match specification. |
| 29 | Brand rights: acquired `rights_constraint` requires `rights_holder`, `grant_status`, `content_digest`, and `attestation_refs` | Producer | Rights agents | Emit the attestation fields ([Rights-grant attestation](/dist/docs/3.2.8/building/by-layer/L1/security#rights-grant-attestation-profile-3-2)). |
`comply_test_controller` `force_task_completion` results are also narrowed to a
small set of task-completion shapes. That affects only sandbox controller
authors.
## Rollback
Keep the 3.1 handler and schema bundle available while you roll out 3.2. If a
3.2 integration fails:
1. Stop advertising `"3.2"` on the affected endpoint.
2. Re-pin the peer to `"3.1"` only if it advertises 3.1.
3. Route through the 3.x compatibility facades and 3.1 schemas.
4. Preserve the failed payload and exact artifact version for diagnosis.
Do not retry a 3.2 payload under a 3.1 pin without applying an explicit
version adapter; additive fields and compact task names may not exist in the
3.1 contract.
## Related
* [3.2 exceptions to 3.x compatibility](/dist/docs/3.2.8/reference/versioning#3-2-exceptions-to-3-x-compatibility)
* [3.2 prerelease history](/dist/docs/3.2.8/reference/3-2-beta)
* [What's New in AdCP 3.2](/dist/docs/3.2.8/reference/whats-new-in-3-2)
* [Release Notes](/dist/docs/3.2.8/reference/release-notes#version-3-2-1)
* [Versions & Compatibility](/dist/docs/3.2.8/reference/versions)
* [Version Adaptation](/dist/docs/3.2.8/building/cross-cutting/version-adaptation)
# Migrating secured asset access (3.2)
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/asset-access
Stop embedding cloud credentials in artifact payloads and choose signed URLs, workload identity, or bounded bearer tokens in AdCP 3.2.
# Migrating secured asset access (3.2)
AdCP 3.2 deprecates `assets[].access.credentials` on the `service_account` access method. Without that legacy field, the method means that the asset origin has authorized a workload identity already controlled by the component that performs the asset fetch. No provider credential crosses the AdCP payload.
For most integrations, use a short-lived signed URL. It gives consumers one interoperable operation—an ordinary HTTPS `GET`—without cloud-provider setup.
## Choose the simplest path
| Situation | Access method |
| - | - |
| One-off delivery or no prior identity relationship | `signed_url` (recommended) |
| Established cloud-IAM relationship and repeated access | `service_account` without `credentials` |
| Origin requires an Authorization header | Short-lived, asset-scoped `bearer_token` |
Do not place long-lived API keys, private keys, cloud access keys, or other standing credentials in any artifact field.
## Before: inline provider credentials
This legacy shape remains schema-valid during the 3.x compatibility window, but new producers must not emit it:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/content-standards/artifact.json",
"property_rid": "property_streamhaus_001",
"artifact_id": "episode_42_segment_3",
"assets": [
{
"type": "audio",
"url": "https://storage.streamhaus.example/episodes/42/segment-3.mp3",
"access": {
"method": "service_account",
"provider": "gcp",
"credentials": {
"type": "service_account",
"private_key": "legacy-secret-redacted"
}
}
}
]
}
```
Presence of this field denotes only the deprecated legacy form; it is not workload-identity authorization. Consumers must continue parsing and validating it for 3.x wire compatibility, but must not activate received credentials automatically. Process it only for a peer explicitly allowlisted for legacy compatibility; otherwise reject or quarantine it. Redact the complete value from logs, traces, errors, metrics, analytics, model context, and durable storage.
## After: signed URL (recommended)
Issue a URL scoped to one asset and the shortest practical access window:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/content-standards/artifact.json",
"property_rid": "property_streamhaus_001",
"artifact_id": "episode_42_segment_3",
"assets": [
{
"type": "audio",
"url": "https://assets.streamhaus.example/episodes/42/segment-3.mp3?expires=1786003200&signature=redacted",
"access": {
"method": "signed_url"
}
}
]
}
```
The complete URL is a bearer capability. Consumers must redact it from logs, traces, errors, metrics, analytics, model context, and durable storage because providers may place credential material in either its path or query string. No additional Authorization header is sent, and the URL must not be forwarded outside the intended recipient trust boundary.
## Alternative: pre-authorized workload identity
For an established relationship, authorize the consumer's identity out of band and omit `credentials`:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/content-standards/artifact.json",
"property_rid": "property_streamhaus_001",
"artifact_id": "episode_42_segment_3",
"assets": [
{
"type": "audio",
"url": "https://storage.streamhaus.example/episodes/42/segment-3.mp3",
"access": {
"method": "service_account",
"provider": "gcp"
}
}
]
}
```
The component that fetches the asset uses its normal provider credential chain at fetch time. The payload does not assert which principal is authorized, and the asset origin remains responsible for authorization. An intermediary must either fetch the asset itself or arrange out-of-band authorization for the downstream component that will fetch it.
## Fetch safely
Treat every asset URL and access object as untrusted. Require HTTPS and validate the resolved destination before the first request and after every redirect. Reject loopback, link-local, metadata-service, private, and locally disallowed destinations unless a specific destination was explicitly approved during authenticated onboarding.
Never select or attach ambient credentials based only on `access.method`, `provider`, or the supplied URL. Bind workload credentials out of band to an allowed origin and resource prefix. Send bearer tokens only to the authorized origin, never forward an Authorization header across redirects, and fail closed rather than falling back to another access method.
## Producer checklist
* Prefer `signed_url` unless the parties already maintain an identity-based access relationship.
* Scope signed URLs and bearer tokens to one asset and the shortest practical access window under a documented maximum TTL.
* Omit `service_account.credentials` in all new payloads.
* Never copy consumer-owned provider credentials into an artifact.
## Consumer checklist
* Continue parsing and validating legacy `service_account.credentials` throughout 3.x. Process it only for an explicitly allowlisted legacy peer; otherwise reject or quarantine it.
* Never infer authorization from an identity string in the payload; authorization is enforced by the asset origin.
* Keep any temporary encrypted cache no longer than both the credential expiry and a configured maximum lifetime.
* Do not fall back between supplied credentials, workload identity, bearer tokens, and signed URLs after an authorization failure.
* Expect `service_account.credentials` to become removable in AdCP 4.0 or later, once the deprecation-policy notice and release-cycle gates are satisfied.
## Related
* [Content artifacts](/dist/docs/3.2.8/governance/content-standards/artifacts#secured-asset-access)
* [AdCP versioning and deprecation policy](/dist/docs/3.2.8/reference/versioning#deprecation-policy)
* [Issue #5698](https://github.com/adcontextprotocol/adcp/issues/5698) — 3.2 deprecation
* [Issue #5699](https://github.com/adcontextprotocol/adcp/issues/5699) — 4.0 removal
* [Issue #6224](https://github.com/adcontextprotocol/adcp/issues/6224) — 4.0 extensible access-method design
# Migrating attribution windows
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/attribution
Migrate AdCP attribution windows from v2 to v3. Replaces integer day counts with structured Duration objects and adds required attribution model field.
# Migrating attribution windows
AdCP 3.0 renames attribution window fields and replaces integer day counts with structured `Duration` objects. An attribution `model` field is now required.
## What changed
| v2 field | v3 field | Change type |
| - | - | - |
| `click_window_days` (integer) | `post_click` (Duration) | Renamed + type changed |
| `view_window_days` (integer) | `post_view` (Duration) | Renamed + type changed |
| `model` (required) | `model` (required) | Unchanged |
***
## Attribution window object
### Before (v2)
```json theme={null}
{
"attribution_window": {
"click_window_days": 7,
"view_window_days": 1,
"model": "last_touch"
}
}
```
### After (v3)
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/attribution-window.json",
"post_click": {
"interval": 7,
"unit": "days"
},
"post_view": {
"interval": 1,
"unit": "days"
},
"model": "last_touch"
}
```
Key differences:
* **Field renames** — `click_window_days` → `post_click`, `view_window_days` → `post_view`. The new names describe the user action that starts the lookback window.
* **Structured Duration** — Time windows are `{ interval, unit }` objects instead of integer day counts. This enables sub-day granularity (`minutes`, `hours`) and campaign-scoped windows.
* **Attribution model** — Required in both v2 and v3. No change needed.
***
## Duration object
The `Duration` type is shared across frequency caps, attribution windows, and other time-based settings.
```json theme={null}
{
"interval": 30,
"unit": "minutes"
}
```
| Unit | Meaning |
| - | - |
| `minutes` | Clock minutes |
| `hours` | Clock hours |
| `days` | Calendar days |
| `campaign` | Full campaign flight (interval must be `1`) |
***
## Migration steps
**1. Rename attribution fields**
Replace `click_window_days` with `post_click` and `view_window_days` with `post_view` in all attribution window objects.
**2. Convert integer days to Duration objects**
Replace integer day counts (e.g., `7`) with structured Duration objects (e.g., `{ "interval": 7, "unit": "days" }`).
**3. Update frequency cap windows**
Frequency caps have a similar migration. v2 used `suppress_minutes` (integer). v3 uses `suppress` (Duration object) and adds `max_impressions` with a `window` (Duration). Convert `suppress_minutes: 30` to `suppress: { "interval": 30, "unit": "minutes" }`.
**4. Validate against v3 schemas**
Ensure attribution window objects validate against the `attribution-window.json` schema.
> [card] [Conversion tracking & optimization goals](/dist/docs/3.2.8/media-buy/conversion-tracking/index)
>
> Configure event sources, send conversion events, and set attribution windows.
***
**Related:** [Channels](/dist/docs/3.2.8/reference/migration/channels) | [Pricing](/dist/docs/3.2.8/reference/migration/pricing) | [Geo targeting](/dist/docs/3.2.8/reference/migration/geo-targeting) | [Creatives](/dist/docs/3.2.8/reference/migration/creatives) | [Catalogs](/dist/docs/3.2.8/reference/migration/catalogs) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Migrating audiences
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/audiences
Migrate AdCP audiences from beta.3 to rc.1. Promotes external_id to a required top-level field on AudienceMember with stable buyer-assigned identifiers.
# Migrating audiences
AdCP 3.0 rc.1 promotes `external_id` from a value in the `uid-type` enum to a required top-level field on `AudienceMember`. Every audience member must now have a buyer-assigned stable identifier plus at least one matchable identifier.
## What changed
| beta.3 | rc.1 | Notes |
| - | - | - |
| `external_id` in uid-type enum | `external_id` required top-level field | Always present on every member |
| Optional buyer identifier | Required buyer identifier | Used for deduplication and removal |
| Single identifier model | Dual requirement: `external_id` + matchable ID | At least one of `hashed_email`, `hashed_phone`, or `uids` |
## AudienceMember schema
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/audience-member.json",
"external_id": "crm_user_12345",
"hashed_email": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"uids": [
{ "type": "uid2", "value": "uid2_token_abc123" }
]
}
```
Two requirements enforced by the schema:
1. `external_id` is **required** — buyer-assigned stable identifier (CRM record ID, loyalty ID)
2. At least one matchable identifier — `hashed_email`, `hashed_phone`, or `uids` array
## Before and after
**beta.3 — external_id as a uid-type entry:**
```json test=false theme={null}
{
"uids": [
{ "type": "external_id", "value": "crm_user_12345" },
{ "type": "uid2", "value": "uid2_token_abc123" }
]
}
```
**rc.1 — external_id as required top-level field:**
```json test=false theme={null}
{
"external_id": "crm_user_12345",
"uids": [
{ "type": "uid2", "value": "uid2_token_abc123" }
]
}
```
## uid-type enum
The `uid-type` enum no longer includes `external_id`. Current values:
| Value | Description |
| - | - |
| `rampid` | LiveRamp RampID |
| `id5` | ID5 universal ID |
| `uid2` | Unified ID 2.0 |
| `euid` | European Unified ID |
| `pairid` | Publisher Addressable Identity (IAB PAIR) |
| `maid` | Mobile Advertising ID (IDFA/GAID) |
| `other` | Other universal ID type (specify in `ext`) |
## Why the change
Separating `external_id` from the uid-type enum makes the buyer's stable identifier explicit. It enables:
* **Deduplication** — Remove duplicate members across syncs by `external_id`
* **Targeted removal** — Remove specific members without re-uploading the full list
* **Cross-referencing** — Correlate audience membership with buyer CRM systems
CDPs that don't natively assign IDs can derive one (e.g., hash of the member's identifiers).
## Sync audiences
`sync_audiences` uses delta operations (`add`/`remove`) per audience. Members are identified by `external_id` for removal:
```json test=false theme={null}
{
"account": { "account_id": "acct_pinnacle" },
"audiences": [
{
"audience_id": "high_value_customers",
"name": "High-Value Customers",
"add": [
{
"external_id": "crm_user_12345",
"hashed_email": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
}
],
"remove": [
{
"external_id": "crm_user_99999",
"hashed_email": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5"
}
]
}
]
}
```
## Migration steps
**1. Extract external_id from uids**
Move any `{ "type": "external_id", "value": "..." }` entry from the `uids` array to the top-level `external_id` field.
**2. Ensure every member has external_id**
If members don't have a buyer-assigned ID, derive one (e.g., hash of identifiers). The schema requires `external_id` on every member.
**3. Keep at least one matchable identifier**
Every member must also have at least one of `hashed_email`, `hashed_phone`, or `uids`. This is enforced by the schema's `anyOf` constraint.
**4. Update removal logic**
When removing members via `sync_audiences`, use `external_id` as the stable key. The member still needs a matchable identifier in the `remove` array.
**5. Validate against schema**
Run member objects against `audience-member.json` schema. It enforces both `external_id` (required) and the matchable identifier constraint.
> [card] [Signals Protocol](/dist/docs/3.2.8/signals/overview)
>
> Full reference for signal discovery, activation, and pricing models.
***
**Related:** [Brand identity](/dist/docs/3.2.8/reference/migration/brand-identity) | [Optimization goals](/dist/docs/3.2.8/reference/migration/optimization-goals) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Migrating brand identity
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/brand-identity
Migrate AdCP brand identity from beta.3 to rc.1. Replaces inline brand_manifest objects with BrandRef references resolved via brand.json or the community registry.
# Migrating brand identity
AdCP 3.0 rc.1 replaces inline `brand_manifest` objects with lightweight brand references (`BrandRef`). Brand data is resolved at execution time from `/.well-known/brand.json` or the community brand registry.
## What changed
| beta.3 | rc.1 | Notes |
| - | - | - |
| `brand_manifest` (inline object) | `brand` (`BrandRef`) | Reference resolved at execution time |
| Brand data passed in every request | Brand data fetched once from `brand.json` | Caching recommended (24h TTL) |
| No standard identity format | `/.well-known/brand.json` specification | Four variants: House Portfolio, Brand Agent, House Redirect, Authoritative Location |
## BrandRef schema
A brand reference identifies a brand by domain and optional `brand_id`:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/brand-ref.json",
"domain": "nova-brands.com",
"brand_id": "spark"
}
```
* `domain` (required) — Domain where `/.well-known/brand.json` is hosted, or the brand's operating domain
* `brand_id` (optional) — Brand identifier within a house portfolio. Omit for single-brand domains.
For single-brand domains:
```json theme={null}
{
"domain": "acme-corp.com"
}
```
## Where brand appears
| Task | Required? | Purpose |
| - | - | - |
| `create_media_buy` | Yes | Campaign identity — immutable once set |
| `get_products` | No | Discovery context. Required when `catalog` is provided |
| `build_creative` | No | Resolves to colors, logos, tone for creative generation |
`brand` does not appear on `update_media_buy` (immutable from creation), `sync_creatives` (scoped to account), or `sync_catalogs` (scoped to account).
## Before and after
**beta.3 — inline brand_manifest on create_media_buy:**
```json test=false theme={null}
{
"brand_manifest": {
"name": "Spark",
"domain": "spark.nova-brands.com",
"logo_url": "https://spark.nova-brands.com/logo.png",
"industries": ["technology.hardware"]
},
"account": { "account_id": "acct_nova" },
"start_time": "2025-04-01T00:00:00Z",
"end_time": "2025-04-30T23:59:59Z"
}
```
**rc.1 — brand reference:**
```json test=false theme={null}
{
"brand": {
"domain": "nova-brands.com",
"brand_id": "spark"
},
"account": { "account_id": "acct_nova" },
"start_time": "2025-04-01T00:00:00Z",
"end_time": "2025-04-30T23:59:59Z"
}
```
The seller resolves `nova-brands.com` + `spark` to the full brand identity (logos, colors, tone, properties) via the Brand Protocol.
## Resolution flow
Given a `BrandRef`, the resolution is:
1. Fetch `https://{domain}/.well-known/brand.json`
2. If it's a **House Redirect** (has `house` field), follow to the house domain (max 3 redirects)
3. If it's a **House Portfolio**, look up the brand by `brand_id` in the `brands` array
4. If it's a **Brand Agent**, call the MCP agent for dynamic brand data
5. If it's an **Authoritative Location**, follow the `location` URL
Sellers cache resolved brand data (recommended 24-hour TTL for validated files, 1 hour for failed lookups).
## Migration steps
**1. Replace brand_manifest with brand**
In all task requests (`create_media_buy`, `get_products`, `build_creative`), replace the `brand_manifest` object with a `brand` BrandRef: `{ "domain": "...", "brand_id": "..." }`.
**2. Host brand.json**
Publish `/.well-known/brand.json` on the brand's domain. Choose a variant: House Portfolio for multi-brand companies, Brand Agent for dynamic data, or single-brand for simple cases.
**3. Register in brand registry**
If the brand domain doesn't host `brand.json`, register it in the community brand registry so sellers can resolve it.
**4. Update seller resolution**
Seller agents must resolve `BrandRef` to full brand data at execution time. Implement caching and handle all four `brand.json` variants.
**5. Remove inline brand data**
Remove any code that constructs or parses `brand_manifest` objects. Brand data is no longer passed inline.
**6. Validate against schema**
Run requests against `brand-ref.json` schema. The `domain` field requires a valid lowercase domain pattern.
> [card] [Brand identity](/dist/docs/3.2.8/brand-protocol/brand-json)
>
> Full reference for brand.json variants, the brand registry, and BrandRef resolution.
***
**Related:** [Channels](/dist/docs/3.2.8/reference/migration/channels) | [Catalogs](/dist/docs/3.2.8/reference/migration/catalogs) | [Brand Protocol](/dist/docs/3.2.8/brand-protocol) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Migrating catalogs
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/catalogs
Migrate AdCP catalogs from v2 to v3. Replaces promoted_offerings with first-class catalog objects, sync_catalogs task, and format-level catalog requirements.
# Migrating catalogs
AdCP 3.0 removes the `promoted_offerings` creative asset type and the `promoted_offering` string field from media buys and creative manifests. Catalogs are now first-class protocol objects with their own sync task, format-level requirements, and conversion event alignment.
## What changed
| v2 field | v3 field | Change type |
| - | - | - |
| `promoted_offerings` (creative asset type) | `catalog` assets in creative manifest `assets` | Replaced |
| `promoted_offering` (string on media-buy) | Removed | Removed |
| `promoted_offering` (string on creative-manifest) | `catalog` assets in `assets` | Replaced |
| No catalog sync | `sync_catalogs` task | New |
| No format catalog requirements | `catalog` asset type on Format `assets` | New |
| No catalog-event linking | `conversion_events` on Catalog | New |
***
## Creative manifests
### What changed
In v2, catalog data was embedded inside `creative_manifest.assets` as a `promoted_offerings` object that bundled brand identity, inline offerings, and SI agent URL together.
In v3, brand identity is a first-class parameter on tasks (`build_creative`, `sync_creatives`), and catalogs are included as `catalog` asset types in the manifest's `assets`.
### Before (v2)
```json theme={null}
{
"creative_id": "product-carousel",
"format_id": {
"agent_url": "https://creatives.example.com",
"id": "product_carousel"
},
"assets": {
"promoted_offerings": {
"brand": {
"domain": "acmecorp.example.com"
},
"offerings": [
{
"offering_id": "winter-sale",
"name": "Winter Sale Collection",
"description": "50% off all winter items"
}
]
}
}
}
```
### After (v3.2 canonical)
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/creative-manifest.json",
"format_kind": "sponsored_placement",
"format_option_ref": {
"scope": "product",
"format_option_id": "product_carousel"
},
"assets": {
"source_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "winter-products"
}
}
}
```
Key differences:
* **Brand identity** comes from the `brand` parameter on the task, not embedded in creative assets
* **Format identity** is portable canonical `format_kind` plus an optional product or publisher `format_option_ref`; compound `format_id` is deprecated in 3.2
* **Catalogs** are `catalog` asset types in the `assets` map, keyed by the canonical slot name (for `sponsored_placement`, `source_catalog`)
* **Catalog references synced data** by `catalog_id` instead of inlining items (though inline items are still supported for simple cases)
***
## Media buys
### What changed
The `promoted_offering` string field is removed from media buy objects. What's being promoted is now expressed through the `brief` on `get_products`/`create_media_buy` and through catalog references on creatives.
### Before (v2)
```json theme={null}
{
"media_buy_id": "mb_123",
"promoted_offering": "Winter Sale Collection",
"status": "draft",
"total_budget": {
"amount": 10000,
"currency": "USD"
},
"packages": []
}
```
### After (v3)
```json theme={null}
{
"media_buy_id": "mb_123",
"status": "draft",
"total_budget": {
"amount": 10000,
"currency": "USD"
},
"packages": []
}
```
If you were using `promoted_offering` for reporting or display purposes, that context now comes from:
* The `brief` field on `get_products` and `create_media_buy`
* The `brand` parameter on tasks
* Catalog assets in creative manifest `assets`
***
## Syncing catalogs (new in v3)
The `sync_catalogs` task lets buyers push catalog data to sellers before submitting creatives. This replaces the pattern of embedding product data inside creative assets.
Key features:
* **Bulk sync** with per-catalog results
* **Async approval** workflow (working, input-required, submitted)
* **Item-level review** with approve/reject per catalog item
* **Discovery mode** — omit the catalogs field to see existing synced catalogs
* **Validation modes** — strict, lenient, or dry_run
### Workflow
```
get_products.format_options[] → resolve effective canonical catalog slots → sync_catalogs → sync_creatives with canonical manifests
```
1. Discover what catalogs a product contract needs by resolving the selected canonical's default slots plus any narrowing or override in `get_products.format_options[].params.slots`
2. Sync those catalogs using `sync_catalogs`
3. Wait for approval if the seller requires review
4. Submit creatives that reference the synced `catalog_id`
> [card] [Catalogs documentation](/dist/docs/3.2.8/creative/catalogs)
>
> Complete reference including all 13 catalog types, sync workflow, and item-level review.
***
## Format catalog requirements (new in v3)
Formats declare catalog needs as `catalog` asset types in their `assets` array:
```json theme={null}
{
"assets": [
{
"item_type": "individual",
"asset_id": "product_catalog",
"asset_type": "catalog",
"required": true,
"requirements": {
"catalog_type": "product",
"min_items": 3,
"required_fields": ["name", "price", "image_url"]
}
}
]
}
```
Format declarations use `asset_type: "catalog"` with a `requirements` object containing:
| Field | Type | Description |
| - | - | - |
| `catalog_type` | string | Required. The catalog type (e.g., `product`, `store`, `job`) |
| `min_items` | integer | Minimum items the catalog must contain |
| `max_items` | integer | Maximum items the format can render |
| `required_fields` | string\[] | Fields that must be present on every item |
| `feed_formats` | string\[] | Accepted feed formats (e.g., `google_merchant_center`, `linkedin_jobs`) |
This replaces the v2 pattern where formats implicitly required `promoted_offerings` in their assets — the requirement is now explicit and discoverable.
### Creative agent migration
Creative agents that read format definitions to determine catalog requirements need to change how they discover and fulfill catalog slots.
**Before (v2)** — checking a dedicated `catalog_requirements` field:
```javascript theme={null}
// v2: catalog requirements were a separate top-level array
for (const req of format.catalog_requirements) {
const catalogType = req.catalog_type;
const minItems = req.min_items;
}
```
**After (v3)** — iterating the `assets` array and filtering by `asset_type`:
```javascript theme={null}
// v3: catalogs are assets like any other
const catalogAssets = format.assets.filter(a => a.asset_type === "catalog");
for (const slot of catalogAssets) {
const catalogType = slot.requirements.catalog_type;
const minItems = slot.requirements.min_items;
const slotId = slot.asset_id; // use as key in manifest.assets
}
```
When building a manifest, catalog assets are keyed by their `asset_id` from the format definition:
```json theme={null}
{
"assets": {
"product_catalog": {
"type": "product",
"catalog_id": "winter-products"
}
}
}
```
The `asset_id` (e.g., `product_catalog`) from the format's `assets` array becomes the key in the manifest's `assets` object.
***
## Conversion event alignment (new in v3)
Catalogs declare which event types represent conversions for their items:
```json theme={null}
{
"catalog_id": "job-feed",
"type": "job",
"content_id_type": "job_id",
"conversion_events": ["submit_application", "complete_registration"]
}
```
This links catalogs to the conversion tracking system. When a `log_event` is sent with `content_ids` matching catalog items, the platform knows which events to attribute.
The `content_id_type` field declares what identifier type `content_ids` values represent. For vertical catalogs, this matches the item's canonical ID field (`job_id`, `hotel_id`, etc.). For product catalogs, it distinguishes between `sku` and `gtin` for cross-retailer matching. Omit when using a custom identifier scheme.
| Catalog type | Typical conversion events |
| - | - |
| `product` | `purchase`, `add_to_cart` |
| `hotel` | `purchase` (booking) |
| `flight` | `purchase` (booking) |
| `job` | `submit_application` |
| `vehicle` | `lead`, `schedule` |
| `real_estate` | `lead`, `schedule` |
| `education` | `submit_application`, `complete_registration` |
| `destination` | `purchase` (booking) |
> [card] [Conversion events](/dist/docs/3.2.8/creative/catalogs#conversion-events)
>
> Full documentation on catalog-event alignment.
***
## product_selectors replaced by catalog on get_products
The `product_selectors` field on `get_products` has been replaced by `catalog`. The `PromotedProducts` schema has been removed.
### Before
```json theme={null}
{
"brand": { "domain": "acmecorp.com" },
"product_selectors": {
"manifest_gtins": ["00013000006040"],
"manifest_tags": ["organic"]
}
}
```
### After
```json theme={null}
{
"brand": { "domain": "acmecorp.com" },
"catalog": {
"type": "product",
"gtins": ["00013000006040"],
"tags": ["organic"]
}
}
```
### Field mapping
| Old (`product_selectors`) | New (`catalog`) |
| - | - |
| `manifest_gtins` | `gtins` |
| `manifest_skus` | `ids` |
| `manifest_tags` | `tags` |
| `manifest_category` | `category` |
| `manifest_query` | `query` |
### Response changes
* `product_selectors_applied` is now `catalog_applied`
* `catalog_match.matched_skus` is now `catalog_match.matched_ids`
***
## New fields on Product
* **`catalog_types`** — Array of catalog types this product supports (e.g., `["product"]`, `["job", "offering"]`)
* **`catalog_match.matched_ids`** — Generic item ID matches (replaces `matched_skus`)
* **`catalog_match.matched_count`** — Count of matched items
***
## Catalog on packages
Packages now accept a `catalog` field for catalog-driven campaigns. One budget envelope promotes an entire catalog, with the platform optimizing delivery across items.
***
## Store catchment targeting
`targeting_overlay` now supports `store_catchments` — referencing synced store catalogs for proximity targeting.
***
## Per-catalog-item delivery
`get_media_buy_delivery` now includes `by_catalog_item` breakdowns within packages for catalog-driven campaigns.
***
## Migration steps
**1. Remove promoted_offerings from creative assets**
Remove `promoted_offerings` objects from `creative_manifest.assets`. Brand identity is now provided via the `brand` task parameter.
**2. Add catalog assets to creative manifests**
For creatives that render catalog items (product carousels, store locators, etc.), add catalog assets to the manifest's `assets` map. Each catalog asset is a catalog object with `type` and `catalog_id` (e.g., `{ "type": "product", "catalog_id": "winter-products" }`).
**3. Remove promoted_offering from media buys**
Remove the `promoted_offering` string from `create_media_buy` requests. Use the `brief` field to describe what's being promoted.
**4. Discover catalog requirements**
Resolve the selected declaration's effective canonical slots — canonical defaults plus any `format_options[].params.slots` narrowing or override — and check for catalog inputs. Use `get_adcp_capabilities.creative.supported_formats[]` only when selecting a separate creative agent to build or validate the resulting manifest; `list_creative_formats` is deprecated in 3.2.
**5. Sync catalogs before submitting creatives**
Use the `sync_catalogs` task to push catalog data to sellers. Handle async approval if the seller requires review.
**6. Add conversion events and content ID type for attribution**
Include `conversion_events` on catalogs to link catalog items to your conversion tracking setup. Add `content_id_type` to declare what identifier type (e.g., `sku`, `gtin`, `job_id`) the event's `content_ids` should be matched against.
**7. Validate against v3 schemas**
Ensure creative manifests, media buys, and catalog objects validate against v3 schemas.
***
**Related:** [Channels](/dist/docs/3.2.8/reference/migration/channels) | [Pricing](/dist/docs/3.2.8/reference/migration/pricing) | [Geo targeting](/dist/docs/3.2.8/reference/migration/geo-targeting) | [Creatives](/dist/docs/3.2.8/reference/migration/creatives) | [Attribution](/dist/docs/3.2.8/reference/migration/attribution) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Migrating channels
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/channels
Migrate AdCP channels from v2 to v3. Maps v2's 9 format-oriented channels to v3's 20 planning-oriented media channels with field-by-field examples.
# Migrating channels
AdCP 3.0 replaces v2's 9 channels with 20 planning-oriented channels that reflect how buyers allocate budgets. Five channels carry over unchanged, the rest are split, removed, or renamed, and several channels — including `sponsored_intelligence` for AI surfaces — are net-new in v3 with no v2 equivalent.
## Why the channel model changed
v2 mixed format-oriented channels (`video`, `audio`, `native`) with planning-oriented ones (`social`, `ctv`, `dooh`). Buyers don't plan budgets around rendering technology — they plan around media types. A video budget gets split between OLV, CTV, and cinema. An audio budget spans radio, streaming, and podcasts.
v3 channels consistently match how agencies structure media plans.
## Channel mapping
| v2 channel | v3 channel(s) | Notes |
| - | - | - |
| `display` | `display` | Unchanged |
| `video` | `olv`, `linear_tv`, `cinema` | Split by distribution (`ctv` was already separate in v2) |
| `audio` | `radio`, `streaming_audio` | Split by distribution (`podcast` was already separate in v2) |
| `native` | Removed | Use format-level properties instead |
| `social` | `social` | Unchanged |
| `ctv` | `ctv` | Unchanged |
| `podcast` | `podcast` | Unchanged |
| `dooh` | `dooh` | Unchanged |
| `retail` | `retail_media` | Renamed for clarity |
## Complete v3 channel enum
All 20 values from the `channels.json` schema:
```
display, olv, social, search, ctv, linear_tv,
radio, streaming_audio, podcast, dooh, ooh,
print, cinema, email, gaming, retail_media,
influencer, affiliate, product_placement,
sponsored_intelligence
```
| Channel | Description |
| - | - |
| `display` | Digital display advertising (banners, native, rich media) across web and app |
| `olv` | Online video advertising outside CTV (pre-roll, outstream, in-app video) |
| `social` | Social media platforms |
| `search` | Search engine advertising and search networks |
| `ctv` | Connected TV and streaming on television screens |
| `linear_tv` | Traditional broadcast and cable television |
| `radio` | Traditional AM/FM radio broadcast |
| `streaming_audio` | Digital audio streaming services |
| `podcast` | Podcast advertising (host-read or dynamically inserted) |
| `dooh` | Digital out-of-home buying context, including venue-operated screens and audio players |
| `ooh` | Classic out-of-home (physical billboards, transit, etc.) |
| `print` | Newspapers, magazines, and other print publications |
| `cinema` | Movie theater advertising |
| `email` | Email advertising and sponsored newsletter content |
| `gaming` | In-game advertising across platforms (intrinsic in-game, rewarded video, playable ads) |
| `retail_media` | Retail media networks and commerce marketplaces |
| `influencer` | Creator and influencer marketing partnerships |
| `affiliate` | Affiliate networks, comparison sites, and performance-based partnerships |
| `product_placement` | Product placement, branded content, and sponsorship integrations |
| `sponsored_intelligence` | Sponsored Intelligence — advertising within AI assistants, AI search, and generative AI experiences via the reversed data flow (net-new in v3; no v2 equivalent) |
> [!NOTE]
>
> The `gaming` channel covers all in-game advertising. Rewarded video in gaming apps could also be classified as `olv` — use `gaming` when the inventory comes from a gaming budget, `olv` when it comes from a video budget.
## Migrating `video` products
The v2 `video` channel must be split across 3 v3 channels based on distribution (`ctv` was already a separate v2 channel):
* **`olv`** — Online video (web, mobile app, social): pre-roll, outstream, in-app video
* **`linear_tv`** — Traditional broadcast and cable television
* **`cinema`** — Movie theater pre-show advertising
A single publisher may support multiple channels. A streaming service might declare both `olv` and `ctv` if their inventory serves both mobile and TV.
## Migrating `audio` products
The v2 `audio` channel splits into 2 v3 channels (`podcast` was already a separate v2 channel):
* **`radio`** — Traditional AM/FM radio broadcast
* **`streaming_audio`** — Digital audio streaming services (music platforms)
## Migrating `native` products
v3 removes `native` as a channel. Native is a rendering style, not a budget category.
If you have products tagged `native` in v2, assign the appropriate v3 channel based on how the budget is planned:
* Native display ads -> `display`
* Native social ads -> `social`
* Native content recommendations -> `display` or `affiliate` depending on model
## Migrating `retail` products
Simple rename from `retail` to `retail_media`.
## Multi-channel products
v3 products declare an array of channels, so a single product can span multiple channels. Here's a capabilities response showing a seller that supports multiple channels:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/protocol/get-adcp-capabilities-response.json",
"status": "completed",
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
},
"supported_protocols": ["media_buy"],
"account": {
"supported_billing": ["operator", "agent"],
"supported_account_currency_modes": ["fixed", "per_media_buy"]
},
"media_buy": {
"portfolio": {
"primary_channels": ["display", "olv", "ctv"],
"publisher_domains": ["pinnaclemedia.example.com"],
"primary_countries": ["US"]
}
}
}
```
When products are returned from `get_products`, each product's `channels` array declares which channels that product is sold as:
```json theme={null}
{
"channels": ["olv", "ctv"]
}
```
## Preparing product channels for 4.0
[`Product.channels` is proposed to become required in 4.0](https://github.com/adcontextprotocol/adcp/issues/7869), with at least one value from the existing `MediaChannel` enum. The 3.x schemas still accept omitted or empty arrays, and the existing property-based inheritance remains unchanged. Sellers SHOULD populate an explicit nonempty declaration on every product now.
For each product, declare the channels in which that inventory is sold. Use `ctv` for connected TV, `olv` for online video, and the relevant audio channels such as `radio`, `streaming_audio`, or `podcast`. A product sold in multiple buying contexts declares all applicable values. Product channels SHOULD be a subset of the union of their properties' `supported_channels`.
Do not derive the declaration from creative format alone: a VAST video format can serve both `ctv` and `olv`. Do not copy a seller-wide channel list onto every product; a seller can sell different channels on different products.
Format options keep optional `applies_to_channels` as a narrowing of the product declaration. Every listed value must belong to the product's `channels`. When the narrowing is omitted, the format option applies to all channels declared on that product. It does not independently declare the product's channels.
Buyers reading 3.x products should request `channels` in any `fields` projection before classifying products. Omission from a projection that did not request the field does not establish that the seller omitted its declaration. Existing 3.x property-based inheritance remains supported; this preparation does not replace it with automatic exclusion from discovery or proposal routing. Omission is not a wildcard for every channel in the taxonomy. Declared channels describe buying contexts, not independent evidence of actual delivery or per-channel totals.
The proposed 4.0 change would require an explicit nonempty declaration on the product, removing reliance on omission-based inheritance. Its treatment of missing channel details and sparse projections needs to be specified as part of that change. Buyers that also read 3.x responses still need to preserve the 3.x compatibility behavior.
## Declaring channel support in capabilities
Buyers should call `get_adcp_capabilities` before filtering `get_products`
requests. When present, `portfolio.primary_channels` is the seller's complete
brief-routing channel allowlist, so a buyer may skip the seller when no requested
channel intersects it. Omission means unknown scope, not support for every
channel. A match is not an availability guarantee; call `get_products` to
resolve current inventory and the rest of the brief.
AdCP 3.2 applies the same exhaustive routing meaning to
`portfolio.primary_countries`. Sellers upgrading from 3.1 that populated either
`primary_*` array with only representative values MUST expand it to the complete
brief-routing scope or omit it until they can do so. Empty and duplicate arrays
remain wire-valid in 3.2 for compatibility but produce Canary advisories; 4.0 is
expected to require non-empty, unique declarations. The country array does not
replace `media_buy.execution.targeting` geo capabilities or product
`overlay_support`.
## Migration steps
**1. Audit channel usage**
Find all places your code reads or writes channel values.
**2. Map old to new**
Use the mapping table above to convert each value. Note that `display`, `social`, `ctv`, `podcast`, and `dooh` are unchanged.
**3. Handle multi-mapping**
Where v2 `video` or `audio` maps to multiple v3 channels, classify each product by its distribution context.
**4. Update filters**
If your buyer agent filters by channel, update to the new values.
**5. Update capabilities**
Implement `get_adcp_capabilities` with correct channel declarations.
**6. Test validation**
v3 schema validation will reject old channel values like `video`, `audio`, `native`, and `retail`.
> [card] [Media channel taxonomy](/dist/docs/3.2.8/reference/media-channel-taxonomy)
>
> Full definitions and design rationale for all 20 v3 channels.
***
**Related:** [Pricing](/dist/docs/3.2.8/reference/migration/pricing) | [Geo targeting](/dist/docs/3.2.8/reference/migration/geo-targeting) | [Creatives](/dist/docs/3.2.8/reference/migration/creatives) | [Catalogs](/dist/docs/3.2.8/reference/migration/catalogs) | [Attribution](/dist/docs/3.2.8/reference/migration/attribution) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Migrating to creative transformers (3.1)
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/creative-transformers
Move build-capability discovery and creative pricing off Format fields onto transformers (list_transformers). Additive in 3.1; deprecated Format fields removed at 4.0.
# Migrating to creative transformers (3.1)
> [!NOTE]
>
> AdCP 3.2 uses `get_adcp_capabilities.creative.supported_formats[]` for canonical operation discovery and `list_transformers` for account-scoped transformer discovery. Transformer inputs use canonical `input_formats`; outputs use `output_capability_ids`; builds select `target_capability_id(s)`. The named-format examples below document the 3.1 compatibility path only.
AdCP 3.1 introduces **transformers** — the creative analog of a media-buy product: an agent-offered, account-scoped, selectable unit of build capability (a voice, model, style, or director) with a typed configuration surface and per-account pricing, discovered via [`list_transformers`](/dist/docs/3.2.8/creative/task-reference/list_transformers) and selected with `transformer_id` on [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative).
Because a transformer carries **its own input/output formats and its own pricing**, three things that 3.0 hung on the *format* are now redundant and are deprecated:
* `Format.input_format_ids` / `Format.output_format_ids`
* `Format.pricing_options`
* the `input_format_ids` / `output_format_ids` discovery **filters** on `list_creative_formats`
**Nothing breaks if you do nothing in 3.1.** All four are `deprecated: true` but still validate and still function through the 3.1–3.x line. Act before 4.0. The hazards below are about *silent degradation* over the window, not hard breaks.
## What changed
| Surface | 3.0 | 3.1 | Removed |
| - | - | - | - |
| Build-capability discovery | filter `list_creative_formats` on `input_format_ids` / `output_format_ids`; read `Format.input_format_ids` / `output_format_ids` | discover via `list_transformers` (each transformer declares its own I/O signature) | 4.0 |
| Creative/transform pricing | `Format.pricing_options` (per format) | `transformer.pricing_options` (per transformer; `include_pricing` + `account` on `list_transformers`) | 4.0 |
| `list_creative_formats` `input_format_ids` / `output_format_ids` filters | supported | `deprecated: true` — use `list_transformers` filters + `brief` | 4.0 |
## Migrate
### Format I/O signature → transformer
A transformer declares the formats it accepts and produces directly, so build capability is a property of the *selectable unit*, not a relationship hung on a format.
**Before (3.0)** — a transform format declares what it consumes/produces:
```json test=false theme={null}
{
"format_id": { "agent_url": "https://creative.example", "id": "resize_to_meta" },
"input_format_ids": [{ "agent_url": "https://creative.example", "id": "display_master" }],
"output_format_ids": [{ "agent_url": "https://creative.example", "id": "meta_reels_9x16" }]
}
```
**After (3.1)** — declare a transformer (discovered via `list_transformers`):
```json test=false theme={null}
{
"transformer_id": "resize_to_meta",
"name": "Resize to Meta Reels",
"input_format_ids": [{ "agent_url": "https://creative.example", "id": "display_master" }],
"output_format_ids": [{ "agent_url": "https://creative.example", "id": "meta_reels_9x16" }],
"params": [],
"pricing_options": [ { "pricing_option_id": "per_format", "model": "per_unit", "unit": "format", "unit_price": 0.10, "currency": "USD" } ]
}
```
### Format pricing → transformer pricing
`Format.pricing_options` moves to `transformer.pricing_options` (same `vendor-pricing-option` shape; `per_unit` is typical). The applied option is echoed per-leaf on the `build_creative` response and reconciled via `report_usage`, unchanged.
For multi-output transformers, a pricing option can carry `applies_to_output_format_ids` to scope that rate to specific outputs. An unscoped pricing option is the default for any output. If a build targets an output that matches no scoped option and the transformer has no unscoped default, the agent rejects the build with `UNPRICEABLE_OUTPUT` rather than guessing a price.
### `list_creative_formats` discovery filters → `list_transformers`
Stop filtering `list_creative_formats` on `input_format_ids` / `output_format_ids` to find "what can build X". Use `list_transformers` — filter on its `input_format_ids` / `output_format_ids`, narrow with `brief`, and expand account-scoped option values with `expand_params`.
## What breaks silently if you do nothing
These do not throw — which is exactly why they are the reason this guide exists.
1. **Discovery-read degradation (buyers).** If your buyer/storyboard learns build capability *only* by reading `Format.input_format_ids` / `output_format_ids` or by filtering `list_creative_formats` on them, you keep working against a 3.1 seller but see **progressively emptier results** as sellers stop emitting the deprecated fields and move capability onto transformers. No error — just fewer and fewer options. **The field outlives its data.** Move discovery to `list_transformers`.
2. **Per-output pricing gaps (multi-publisher template sellers).** A template that priced outputs differently can keep that shape with `applies_to_output_format_ids`, but every output needs either a scoped pricing option or an unscoped default. Otherwise builds for unpriced outputs are rejected with `UNPRICEABLE_OUTPUT`.
3. **Fan-out / best-of-N spend under-counting (billing pipelines).** With `max_variants` / `max_creatives`, every produced variant is billed, but only a **trafficked** leaf lazily earns a `creative_id`. Discarded best-of-N leaves are billed via the **inline per-leaf `vendor_cost`** on the `build_creative` response *only* — they never earn a `creative_id` and so never appear in `report_usage`. A pipeline that reconciles spend solely from `report_usage` (the 3.0 invariant "every billed unit reconciles via `creative_id`") will **under-count** by every discarded variant. Ingest the inline per-leaf receipts as the authoritative record for untrafficked leaves. Because that receipt is the sole record, the schema enforces it: whenever a build reports cost (the aggregate `vendor_cost` is present), every produced leaf MUST carry its own `vendor_cost` + `currency`, so a paid build cannot return leaves with no machine-readable cost. Note the boundary: the schema enforces the *internal completeness and consistency* of a reported cost — it cannot tell a genuinely free build (or a legitimately-`0` CPM-deferred leaf) from a paid build that omits the aggregate to under-report. "Aggregate absent" is a trust assertion to reconcile (seller invoice vs. `report_usage` + inline receipts, distinguished by the `pricing_option_id` basis), not proof of zero cost — don't mistake schema-validity for billing-honesty.
## SDK behavior and timeline
| Version | Deprecated fields |
| - | - |
| 3.1 | `deprecated: true`; still emitted and honored. SDKs MUST continue to read them. |
| 3.1–3.x | Honored throughout. New code SHOULD NOT emit them. |
| 4.0+ | SDKs MAY reject. Removed. |
## See also
* [`list_transformers`](/dist/docs/3.2.8/creative/task-reference/list_transformers) — discover transformers, their params, option values, and pricing
* [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) — select a transformer, configure, multiply, refine
* [What's new in 3.1](/dist/docs/3.2.8/reference/whats-new-in-3-1)
# Migrating creatives
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/creatives
Migrate AdCP creatives from v2 to v3. Replaces creative_ids with weighted assignments and assets_required with a unified assets array for format discovery.
# Migrating creatives
> [!NOTE]
>
> This page records the 3.0 migration. For new AdCP 3.2 integrations, use canonical `format_kind` / `format_option_ref`, discover creative operations through `get_adcp_capabilities.creative.supported_formats[]`, and treat `list_creative_formats` plus compound `format_id` as deprecated 3.x compatibility surfaces.
AdCP 3.0 makes three breaking changes to creative handling: the `FormatCategory` enum and format `type` field are removed, weighted creative assignments replace simple ID arrays, and a unified `assets` array replaces `assets_required` for format discovery.
## Format category removal
### What changed
| v2 field | v3 field | Change type |
| - | - | - |
| `type` on format objects (FormatCategory enum) | Removed | Deleted |
| `format_types` filter on `list_creative_formats` / `get_products` | Removed | Deleted |
### Why
The `FormatCategory` enum (`video`, `display`, `audio`, `native`, `social`, `custom`) was a coarse classifier that didn't map well to multi-asset formats. A "video" format might also require display companion banners and text overlays. The enum forced implementors to pick one category for inherently multi-modal formats, which led to inconsistent filtering and discovery gaps.
### Migration
Replace `format_types` filters with `asset_types` (what the format needs) or `format_ids` (exact match):
**v2:**
```json theme={null}
{
"format_types": ["video"]
}
```
**v3 — filter by asset type:**
```json theme={null}
{
"asset_types": ["video"]
}
```
**v3 — filter by exact format ID:**
```json theme={null}
{
"format_ids": [
{ "agent_url": "https://creatives.example.com", "id": "video_preroll_30s" }
]
}
```
`asset_types` returns any format that includes at least one asset of that type — so a video format with companion banners appears in both `["video"]` and `["image"]` results.
***
## Creative assignments
### What changed
| v2 field | v3 field | Change type |
| - | - | - |
| `creative_ids` (string array) | `creative_assignments` (object array) | Replaced |
### Simple migration (equal weights)
**v2:**
```json theme={null}
{
"creative_ids": ["creative_1", "creative_2"]
}
```
**v3 — omit `weight` for equal distribution:**
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/creative-assignment.json",
"creative_id": "creative_1"
}
```
In context of a `create_media_buy` package:
```json theme={null}
{
"creative_assignments": [
{ "creative_id": "creative_1" },
{ "creative_id": "creative_2" }
]
}
```
When `weight` is omitted on all assignments, impressions are distributed equally.
### Weighted assignments
Control what percentage of impressions each creative receives:
```json theme={null}
{
"creative_assignments": [
{ "creative_id": "hero_video", "weight": 60 },
{ "creative_id": "promo_video", "weight": 40 }
]
}
```
Weights are relative — they don't need to sum to 100, but doing so makes intent clear.
### Rotation modes and groups
`rotation_mode` is a package policy carried on each assignment row. All assignments in one package MUST resolve to the same mode; omission resolves to `weighted`, preserving the pre-3.2 behavior above. A seller MUST reject conflicting modes with `VALIDATION_ERROR` before creating or updating the package rather than picking the first row.
| Mode | Selection behavior |
| - | - |
| `weighted` | Select proportionally by `weight`. Omitted weights are equal; `weight: 0` pauses an assignment. This is the default. |
| `even` | Balance delivery across eligible assignments without buyer-supplied weights. |
| `sequential` | Cycle through `sequence_position` in ascending order within each group. Every assignment requires a position. |
| `random` | Make an independent uniform selection from the eligible assignments. |
`group_id` identifies a pool only within its containing package; the same value in another package is unrelated. Assignments without `group_id` belong to the package's default group. In sequential mode, positions start at 1 and MUST be unique within each effective group, so separate groups may reuse the same positions.
Conventional weighted pool (the legacy shape remains valid):
```json theme={null}
{
"creative_assignments": [
{ "creative_id": "host_read_30", "weight": 70 },
{ "creative_id": "produced_spot_30", "weight": 30 }
]
}
```
Sequential podcast storytelling:
```json theme={null}
{
"creative_assignments": [
{
"creative_id": "story_chapter_1",
"rotation_mode": "sequential",
"group_id": "listener_story",
"sequence_position": 1
},
{
"creative_id": "story_chapter_2",
"rotation_mode": "sequential",
"group_id": "listener_story",
"sequence_position": 2
}
]
}
```
`weight` is valid only for the effective `weighted` mode. `sequence_position` is valid only for explicit `sequential` assignments. Package validators additionally enforce effective-mode consistency and position uniqueness because JSON Schema draft-07 cannot compare values across assignment rows.
### Placement targeting
Assign specific creatives to specific placements within a product:
```json theme={null}
{
"creative_assignments": [
{
"creative_id": "hero_video",
"placement_ids": ["homepage_hero"],
"weight": 100
},
{
"creative_id": "sidebar_banner",
"placement_ids": ["article_sidebar"],
"weight": 100
},
{
"creative_id": "fallback_banner",
"weight": 50
}
]
}
```
When `placement_ids` is omitted, the creative runs on all placements in the package. `placement_ids` references `placement_id` values from the product's placements array.
> [!NOTE]
>
> `sync_creatives` does not support `placement_ids`. Use `create_media_buy` or `update_media_buy` for placement-level targeting.
### Creative assignment schema
Each assignment object:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/creative-assignment.json",
"creative_id": "hero_video",
"weight": 60,
"placement_ids": ["homepage_hero"]
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `creative_id` | string | Yes | References a creative from `list_creatives` or `sync_creatives` |
| `weight` | number (0-100) | No | Delivery weight. Omit for equal distribution. |
| `placement_ids` | string\[] | No | Target specific placements. Omit to run everywhere. |
***
## Asset discovery
### What changed
| v2 field | v3 field | Change type |
| - | - | - |
| `assets_required` (string array) | `assets` (object array) | Replaced |
| `preview_image` | `format_card` | Replaced |
### Format assets
**v2** — only listed required asset IDs:
```json theme={null}
{
"format_id": { "agent_url": "https://creatives.example.com", "id": "display_300x250" },
"name": "Standard Banner 300x250",
"assets_required": ["main_image", "headline"]
}
```
**v3** — lists ALL assets with `required` boolean:
```json theme={null}
{
"format_id": { "agent_url": "https://creatives.example.com", "id": "display_300x250" },
"name": "Standard Banner 300x250",
"assets": [
{
"item_type": "individual",
"asset_id": "main_image",
"asset_type": "image",
"required": true,
"requirements": {
"min_width": 300,
"min_height": 250,
"accepted_mime_types": ["image/png", "image/jpeg"]
}
},
{
"item_type": "individual",
"asset_id": "headline",
"asset_type": "text",
"required": true,
"requirements": {
"max_length": 50
}
},
{
"item_type": "individual",
"asset_id": "impression_tracker",
"asset_type": "url",
"required": false,
"requirements": {
"role": "impression_tracker"
}
}
]
}
```
### What the assets array provides
* **Full discovery** — see ALL assets a format supports, not just required ones
* **Type information** — each asset declares its `asset_type` (image, video, text, url, etc.)
* **Requirements** — inline constraints (dimensions, length, MIME types)
* **Optional assets** — trackers, companion banners, and other optional elements are now visible
* **Repeatable groups** — carousel and multi-item formats use `item_type: "repeatable_group"`
### Asset item types
Each entry in the `assets` array has an `item_type` discriminator:
**Individual assets** (`item_type: "individual"`):
```json theme={null}
{
"item_type": "individual",
"asset_id": "main_video",
"asset_type": "video",
"required": true,
"requirements": {
"min_duration_seconds": 15,
"max_duration_seconds": 30,
"accepted_mime_types": ["video/mp4"]
}
}
```
**Repeatable groups** (`item_type: "repeatable_group"`) for carousels and multi-item formats:
```json theme={null}
{
"item_type": "repeatable_group",
"asset_group_id": "card",
"required": true,
"min_count": 2,
"max_count": 10,
"selection_mode": "sequential",
"assets": [
{
"asset_id": "card_image",
"asset_type": "image",
"required": true,
"requirements": {
"min_width": 600,
"min_height": 600,
"aspect_ratio": "1:1"
}
},
{
"asset_id": "card_title",
"asset_type": "text",
"required": true,
"requirements": {
"max_length": 40
}
}
]
}
```
### Format cards (replacing preview_image)
v2's `preview_image` URL is replaced by `format_card`, which uses the creative rendering system:
```json theme={null}
{
"format_card": {
"format_id": {
"agent_url": "https://creatives.example.com",
"id": "format_card_standard"
},
"manifest": {
"format_name": "Standard Banner 300x250",
"preview_url": "https://cdn.example.com/previews/banner_300x250.png"
}
}
}
```
***
## Migration steps
### Format category
**1. Remove format_types filters**
Remove `format_types` from `list_creative_formats` and `get_products` requests.
**2. Replace with asset_types**
Use `asset_types` to filter formats by what assets they accept (e.g., `["video"]`, `["image"]`).
**3. Or use format_ids**
Use `format_ids` for exact format matching when you know the specific formats you need.
**4. Stop reading type field**
Remove any code that reads the `type` field from format objects — it no longer exists in v3.
### Creative assignments
**1. Replace creative_ids**
Replace `creative_ids` arrays with `creative_assignments` object arrays.
**2. Set creative_id**
Set `creative_id` on each assignment object.
**3. Add weights**
Add weights if you need non-equal distribution, otherwise omit `weight`.
**4. Add placement_ids**
Add `placement_ids` if you need placement-level targeting.
**5. Update sync_creatives calls**
These use `creative_assignments` too, but without `placement_ids`.
### Asset discovery
**1. Replace assets_required**
Replace `assets_required` parsing with `assets` array iteration.
**2. Check required boolean**
Check `required` boolean on each asset instead of assuming all listed assets are required.
**3. Use asset_type**
Use `asset_type` to understand what kind of file each asset expects.
**4. Handle item_type**
Check for `"individual"` vs `"repeatable_group"`.
**5. Replace preview_image**
Replace `preview_image` reads with `format_card` rendering.
**6. Validate**
Creative manifests must use exact `asset_id` values as keys.
> [card] [Creative](/dist/docs/3.2.8/creative/index)
>
> Full creative documentation: formats, asset types, manifests, and creative agents.
***
**Related:** [Channels](/dist/docs/3.2.8/reference/migration/channels) | [Pricing](/dist/docs/3.2.8/reference/migration/pricing) | [Geo targeting](/dist/docs/3.2.8/reference/migration/geo-targeting) | [Catalogs](/dist/docs/3.2.8/reference/migration/catalogs) | [Attribution](/dist/docs/3.2.8/reference/migration/attribution) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Cross-role governance enforcement
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/cross-role-governance-enforcement
Prepare governance providers, services, and SDKs for AdCP 3.2 cross-role authorization and outcome reconciliation.
# Cross-role governance enforcement
> [!NOTE]
>
> **Experimental-surface notice.** The implementation may merge during 3.2 development. The beta-to-GA period provides the six-week notice window before production availability. These changes are part of the existing `governance.campaign` experimental feature, including the new `adcp.governance_enforcement` capability.
AdCP 3.2 makes buyer governance enforceable across service roles without disclosing `plan_id` to those services.
## Provider changes
* Resolve transport credentials to an authenticated agent URL on every governance check. Require `caller` to match and never grant plan access or authorization from the request assertion alone.
* Persist the authenticated `sync_plans` caller as the immutable plan owner. Treat absent delegations as owner-only; delegations add scoped non-owner authority and never displace the owner.
* Emit the modern `check_type` response shape. The absent-`check_type` legacy response arm remains accepted during 3.x migration.
* Return `governance_context` only for `approved`; return non-authorizing `consultation_context` only for intent `conditions`.
* Require task-neutral `proposed_commitment` for `update_media_buy` and on intent checks whose task payload carries pricing indirectly; amount `0` explicitly represents a verified no-cost or non-increasing action.
* Allow purchase execution checks before a durable `media_buy_id` exists; require the ID for modification and delivery.
* Bind intent approval to the target service. Require execution checks to authenticate as that preserved audience, keep the intent currency, and narrow rather than widen its authorized amount.
* Send the exact downstream service URL as top-level `target_agent` on every intent check. Keep routing metadata outside `payload`, which must remain the same JSON task-arguments value sent downstream. The JCS hash is serialization-independent; the service adds `governance_context` and may add `context`, then removes those two metadata fields before recomputing it.
* For `update_media_buy`, have the buyer propose a positive-delta ceiling without exposing seller state to governance. The seller computes the actual positive delta from authoritative current state atomically with its revision check and write, enforces the signed ceiling, and sends `execution_commitment` on an online execution check.
* Settle each opaque action binding once, even though intent and execution checks have distinct IDs. Require the outcome reporter to authenticate as the original buyer caller and preserve `purchase_type`. Derive the ledger amount from governance-owned intent or purchase-execution state, validate every reported monetary value, and treat caller amounts as reconciliation evidence only.
* Cache identical `report_plan_outcome` retries by `idempotency_key`; reject key reuse with another payload.
## Service changes
* Advertise task-scoped enforcement only through `adcp.governance_enforcement` and only for behavior actually implemented.
* Resolve the account before deciding whether governance applies; return `ACCOUNT_REQUIRED` when applicability cannot be determined.
* Verify inbound intent tokens. Media services claiming `online_execution_check` additionally perform prepare → check → commit.
* Require critical `authorized_task` and `authorized_payload_hash` claims, and recompute the RFC 8785 JCS/SHA-256 payload binding before every governed side effect.
* Keep cancellations, pauses, deactivations, and pure decreases available; any commitment-increasing part of a mixed update wins over an exemption.
## SDK changes
Implementation trackers:
* [TypeScript SDK #2442](https://github.com/adcontextprotocol/adcp-client/issues/2442)
* [Python SDK #1013](https://github.com/adcontextprotocol/adcp-client-python/issues/1013)
* [Go SDK #432](https://github.com/adcontextprotocol/adcp-go/issues/432)
Regenerate request/response types and update helpers for:
* typed `governance_context` on governed tasks;
* `adcp.governance_enforcement.tasks[]`;
* SDK-normalized discriminated result types or type guards for modern responses, plus the legacy compatibility arm (the wire schema uses conditional validation and does not itself guarantee a generated union);
* `proposed_commitment`;
* top-level intent `target_agent` and whole-request-rooted condition paths;
* `execution_commitment` for seller-side `update_media_buy` execution checks;
* opaque JWS `sub` continuity rather than `sub == plan_id`;
* signed `authorized_commitment` verification against the service-computed price;
* critical protected-header recognition for `authorized_commitment`, `authorized_task`, and `authorized_payload_hash`;
* phase-conditional `planned_delivery.media_buy_id`;
* exact outcome tuple and one-settlement semantics.
Validate generated SDK signers and verifiers against the published [`governance-authorization.json` vectors](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/governance-authorization.json). They cover bit-exact payload hashing and 27 deterministic compact-JWS cases for task, payload, audience, authenticated caller, monetary ceiling, currency, time, replay, signature, and critical-marker behavior. The bundled private component is public test material and MUST NOT be installed as a production trust anchor.
Until an SDK release contains this schema bundle, its generated `check_governance` validators are stale. The training agent deliberately uses passthrough MCP tool schemas with framework request/response validation disabled for this experimental tenant, then validates in the source-aligned handler. Production integrations MUST regenerate or pin a compatible SDK rather than copying that compatibility overlay.
Pin experimental integrations to the matching 3.2 schema bundle until the surface graduates.
## Conformance coverage
The [cross-role governance index](/compliance/latest/universal/governance.yaml)
connects this contract to the executable proof for each service role. It is an
index, not one universal workflow: each service storyboard runs only when the
agent advertises the exact task and mode in
`adcp.governance_enforcement.tasks[]`.
| Service role | Governed task | Capability-gated proof |
| - | - | - |
| Media buy | `create_media_buy` | [signed approval plus tamper rejection](/compliance/latest/protocols/media-buy/scenarios/governance_approved.yaml); agents also claiming `online_execution_check` run the [conditions](/compliance/latest/protocols/media-buy/scenarios/governance_conditions.yaml) and [denied](/compliance/latest/protocols/media-buy/scenarios/governance_denied.yaml) paths |
| Signals | `activate_signal` | [signed activation and persisted-deployment proof](/compliance/latest/specialisms/signal-marketplace/scenarios/governance_approved.yaml), plus [unauthorized paid activation and no-upstream-call proof](/compliance/latest/specialisms/signal-marketplace/scenarios/governance_denied.yaml) |
| Brand rights | `acquire_rights` | [signed grant and persisted-state proof](/compliance/latest/specialisms/brand-rights/scenarios/governance_approved.yaml), plus [unauthorized acquisition and no-grant proof](/compliance/latest/specialisms/brand-rights/scenarios/governance_denied.yaml) |
| Creative | `build_creative` | [signed paid-render artifact proof](/compliance/latest/specialisms/creative-transformers/scenarios/governance_approved.yaml), plus [unauthorized paid render and no-upstream-call proof](/compliance/latest/specialisms/creative-transformers/scenarios/governance_denied.yaml) |
Governance providers and enforcing services remain separate roles. Provider
responses prove verdict semantics; service storyboards prove that signed intent
is checked before a role-specific side effect. Merely returning or echoing
`governance_context` is not enforcement evidence.
# Migrating geo targeting
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/geo-targeting
Migrate AdCP geo targeting from v2 to v3. Replaces implicit US-centric targeting with named systems (Nielsen DMA, postal codes) for global market support.
# Migrating geo targeting
AdCP 3.0 replaces implicit US-centric geo targeting with named systems that support global markets. Metro targeting values are grouped by system, and postal targeting values are grouped by country plus the country-local postal system.
## What changed
| v2 field | v3 field | Change type |
| - | - | - |
| `geo_metros` (string array) | `geo_metros` (system/values objects) | Restructured |
| `geo_postal_codes` (string array) | `geo_postal_areas` (country/system/values objects) | Renamed and restructured |
Fields that didn't change: `geo_countries`, `geo_countries_exclude`, `geo_regions`, `geo_regions_exclude` all remain simple string arrays using ISO codes.
## Metro targeting
**v2** — flat array of codes, assumed to be Nielsen DMAs:
```json theme={null}
{
"targeting": {
"geo_metros": ["501", "602"]
}
}
```
**v3** — codes grouped by system:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/targeting.json",
"geo_metros": [
{ "system": "nielsen_dma", "values": ["501", "602"] }
]
}
```
Each entry specifies a system and the codes within that system. Multiple systems can coexist:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/targeting.json",
"geo_metros": [
{ "system": "nielsen_dma", "values": ["501", "602"] },
{ "system": "uk_itl2", "values": ["UKC1", "UKD3"] }
]
}
```
### Metro systems
| System | Coverage | Example codes |
| - | - | - |
| `nielsen_dma` | US designated market areas | `501` (New York), `602` (Chicago) |
| `uk_itl1` | UK regions | `UKC` (North East), `UKD` (North West) |
| `uk_itl2` | UK sub-regions | `UKC1` (Tees Valley), `UKD3` (Greater Manchester) |
| `eurostat_nuts2` | EU statistical regions | `DE11` (Stuttgart), `FR10` (Ile-de-France) |
| `custom` | Publisher-defined areas | Publisher-specific codes |
Registered metro systems are `nielsen_dma`, `uk_itl1`, `uk_itl2`, `eurostat_nuts2`, and `custom`.
## Postal targeting
**v2** — flat array of codes, assumed to be US ZIP codes:
```json theme={null}
{
"targeting": {
"geo_postal_codes": ["10001", "90210"]
}
}
```
**v3** — renamed to `geo_postal_areas`, codes grouped by country-local system:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/targeting.json",
"geo_postal_areas": [
{ "country": "US", "system": "zip", "values": ["10001", "90210"] }
]
}
```
### Postal systems
| Country | System | Precision | Example codes |
| - | - | - | - |
| `US` | `zip` | 5-digit ZIP | `10001`, `90210` |
| `US` | `zip_plus_four` | ZIP+4 | `10001-1234` |
| `GB` | `outward` | Outward postcode | `SW1`, `EC2` |
| `GB` | `full` | Full postcode | `SW1A 1AA` |
| `CA` | `fsa` | Forward sortation area | `M5V`, `V6B` |
| `CA` | `full` | Full postal code | `M5V 2T6` |
| `DE` | `plz` | Postleitzahl | `10115`, `80331` |
| `FR` | `code_postal` | Code postal | `75001`, `13001` |
| `AU` | `postcode` | Postcode | `2000`, `3000` |
| `ZA` | `postal_code` | Normal postal code | `2196` |
Use `postal_code` for the normal postal code string in countries without a more specific registered local system. Deprecated country-fused aliases such as `us_zip` remain accepted for compatibility and SDK backfill.
Registered country/system pairings are defined in `postal-country-system.json`; the published `postal-system.json` enum remains additive and also contains deprecated country-fused aliases for 3.x compatibility.
## Exclusion targeting
v3 adds `_exclude` variants for metro and postal targeting:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/targeting.json",
"geo_countries": ["US"],
"geo_metros_exclude": [
{ "system": "nielsen_dma", "values": ["501"] }
]
}
```
This targets the entire US except the New York DMA.
## Discovering seller capabilities
Before sending geo targeting, buyers should verify the seller supports the requested systems. Use `get_adcp_capabilities`:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/protocol/get-adcp-capabilities-response.json",
"status": "completed",
"adcp": {
"major_versions": [3],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
},
"supported_protocols": ["media_buy"],
"account": {
"supported_billing": ["operator", "agent"],
"supported_account_currency_modes": ["fixed", "per_media_buy"]
},
"media_buy": {
"execution": {
"targeting": {
"geo_countries": true,
"geo_regions": true,
"geo_metros": {
"nielsen_dma": true
},
"geo_postal_areas": {
"us_zip": true,
"us_zip_plus_four": true,
"US": ["zip", "zip_plus_four"],
"ZA": ["postal_code"]
}
}
}
}
}
```
The `geo_metros` object uses boolean properties to indicate which metro systems are supported. The `geo_postal_areas` object is keyed by country and lists the supported country-local postal systems; during the 3.x migration, sellers SHOULD also emit equivalent deprecated aliases such as `us_zip` where one exists. Buyers and SDKs should normalize both shapes. If you request a system the seller doesn't declare, expect a validation error.
## Full targeting example
A v3 targeting overlay combining geo restrictions:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/targeting.json",
"geo_countries": ["US", "CA"],
"geo_regions": ["US-NY", "US-CA"],
"geo_metros": [
{ "system": "nielsen_dma", "values": ["501", "803"] }
],
"geo_postal_areas": [
{ "country": "US", "system": "zip", "values": ["10001", "10002", "90210"] }
]
}
```
Inclusion fields are combined with AND logic — delivery must match all specified constraints. Exclusion fields (`_exclude` variants) act as AND NOT — delivery must match inclusions and must not match any exclusion.
## Migration steps
**1. Identify geo targeting**
Find all uses of `geo_metros` and `geo_postal_codes`.
**2. Rename field**
`geo_postal_codes` becomes `geo_postal_areas`.
**3. Restructure values**
Wrap metro arrays into `{ "system": "...", "values": [...] }` objects and postal arrays into `{ "country": "...", "system": "...", "values": [...] }` objects.
**4. Choose systems**
For US-only code, use `nielsen_dma` and `country: "US", system: "zip"`. For international, add the appropriate country-local systems.
**5. Verify capabilities**
Call `get_adcp_capabilities` to check what systems each seller supports.
**6. Add exclusions**
If needed, use the new `_exclude` variants for negative targeting.
> [card] [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting)
>
> Full targeting reference: audiences, contextual, geographic, and device targeting.
***
**Related:** [Channels](/dist/docs/3.2.8/reference/migration/channels) | [Pricing](/dist/docs/3.2.8/reference/migration/pricing) | [Creatives](/dist/docs/3.2.8/reference/migration/creatives) | [Catalogs](/dist/docs/3.2.8/reference/migration/catalogs) | [Attribution](/dist/docs/3.2.8/reference/migration/attribution) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Migration guides
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/index
Upgrade paths between AdCP versions: 3.1 to 3.2, 3.0 to 3.1, and v2 to v3, with breaking changes, effort estimates, and deep-dive pages for each area.
# Migration guides
Pick the guide for the version you run today.
| From → To | Current status | Guide | What it covers |
| - | - | - | - |
| **3.1 → 3.2** | 3.2 is the current stable release (`3.2.1`, wire pin `"3.2"`). 3.1 stays supported. | [Migrating from 3.1 to 3.2](/dist/docs/3.2.8/reference/migration/3-1-to-3-2) | Compatibility exceptions, mixed-version request signing, SDK version map, day-one checklists by role, and the full wire-change table |
| **3.0 → 3.1** | 3.1 is the previous supported release. | [3.0 to 3.1 badge checklist](/dist/docs/3.2.8/reference/migration/3-0-to-3-1) | Additive prep for buyers, sellers, agents, SDKs, and compliance workflows |
| **v2 → v3** | v2 reached end of life on August 1, 2026 (UTC). | [Migrating from v2 to v3](#migrating-from-v2-to-v3) (below) | Every breaking change from 2.x to 3.0, with effort estimates |
For the status of every published version, see [Versions & Compatibility](/dist/docs/3.2.8/reference/versions). For the rules that govern what a release may change, see [Versioning & Governance](/dist/docs/3.2.8/reference/versioning).
## Preparing for 4.0
> [!NOTE]
>
> **Running a 3.x agent?** From compliance bundle 3.2.6 on the 3.2 line, and from 3.3 onward, the suite reports which [AdCP 4.0 removals and new requirements](/dist/docs/3.2.8/reference/migration/v4-compatibility) your agent depends on. The checks are advisory throughout 3.x and never fail a 3.x run.
## 3.2 migration guides
> [!NOTE]
>
> **Moving to 3.2?** Start with the [3.1 to 3.2 migration guide](/dist/docs/3.2.8/reference/migration/3-1-to-3-2). If you pinned a 3.2 beta or release candidate, see the [3.2 prerelease history](/dist/docs/3.2.8/reference/3-2-beta).
> [card] [3.1 to 3.2](/dist/docs/3.2.8/reference/migration/3-1-to-3-2)
>
> Compatibility exceptions, mixed-version signing, SDK versions, day-one checklists, and wire changes
> [card] [Targeting-aware discovery](/dist/docs/3.2.8/reference/migration/targeting-aware-discovery)
>
> Move legacy filters and brief constraints into targeting overlays and support declarations
> [card] [Media buy status](/dist/docs/3.2.8/reference/migration/media-buy-status)
>
> Remove the deprecated body-level status and use `media_buy_status` on create/update success
> [card] [Secured asset access](/dist/docs/3.2.8/reference/migration/asset-access)
>
> Replace inline provider credentials with signed URLs or pre-authorized workload identity
> [card] [Cross-role governance](/dist/docs/3.2.8/reference/migration/cross-role-governance-enforcement)
>
> Adopt the experimental task-scoped authorization and outcome contract as one migration
> [card] [Reliable Reporting consumer status](/dist/docs/3.2.8/reference/migration/reliable-reporting-status-loop)
>
> Adopt the opt-in `sync_reporting_status` loop ahead of its active breaking-change notice
## 3.1 badge prep guides
You can stay on 3.0 without breaking compatibility. To claim the 3.1 badge, complete this short prep checklist.
> [card] [3.1 badge checklist](/dist/docs/3.2.8/reference/migration/3-0-to-3-1)
>
> Additive prep for buyers, sellers, agents, SDKs, and compliance workflows
> [card] [Creative transformers](/dist/docs/3.2.8/reference/migration/creative-transformers)
>
> Move build capability discovery and pricing from formats to transformers
## Migrating from v2 to v3
This section covers every breaking change when upgrading from AdCP 2.x to 3.0, with effort estimates and links to detailed migration pages. For new features see [What's new in v3](/dist/docs/3.2.8/reference/whats-new-in-v3); for release-candidate deltas see [prerelease upgrade notes](/dist/docs/3.2.8/reference/migration/prerelease-upgrades); for SDKs see [Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk).
> [!WARNING]
>
> **v2 has been unsupported since 3.0 GA and reached end of life on August 1, 2026 (UTC).** See the [v2 sunset page](/dist/docs/3.2.8/reference/v2-sunset) for the full timeline, AgenticAdvertising.org registry policy, and why v2 is not safe for interoperable production.
> [!NOTE]
>
> **Starting from v2?** See the [v3 readiness checklist](/dist/docs/3.2.8/reference/migration/v3-readiness) for the 8 minimum requirements to pass storyboard testing before working through this full migration.
> [!WARNING]
>
> **Upgrading from rc.3?** The [rc.3 → 3.0 prerelease upgrade notes](/dist/docs/3.2.8/reference/migration/prerelease-upgrades) cover additional breaking changes: capabilities model simplification, `account` required on `update_media_buy`, `preview_creative` schema flattening, `signal_id` required on signals, governance lifecycle changes, and the `pending_activation` status split.
### Migration checklist
Each row is a breaking change. **Effort** indicates the typical work involved:
* **Rename** — Field name changed, same semantics. Find-and-replace.
* **Restructure** — Shape changed (e.g., string → object, single → array). Requires code changes.
* **Remove** — Field existed in v2, removed in v3. Find-and-delete.
* **New requirement** — Didn't exist in v2. Requires new implementation.
| Area | Change | Effort | Details |
| - | - | - | - |
| Channels | `native` removed | Restructure | [Channels migration](/dist/docs/3.2.8/reference/migration/channels) |
| Channels | `video` split into `olv`, `linear_tv`, `cinema` | Restructure | [Channels migration](/dist/docs/3.2.8/reference/migration/channels) |
| Channels | 10 new channels added (including `sponsored_intelligence`) | Rename | [Channels migration](/dist/docs/3.2.8/reference/migration/channels) |
| Pricing | `fixed_rate` → `fixed_price` | Rename | [Pricing migration](/dist/docs/3.2.8/reference/migration/pricing) |
| Pricing | `price_guidance.floor` → `floor_price` | Rename | [Pricing migration](/dist/docs/3.2.8/reference/migration/pricing) |
| Pricing | Price guidance restructured | Restructure | [Pricing migration](/dist/docs/3.2.8/reference/migration/pricing) |
| Creatives | `creative_ids` → `creative_assignments` with weights | Restructure | [Creatives migration](/dist/docs/3.2.8/reference/migration/creatives) |
| Creatives | Asset discovery via `assets` array | New requirement | [Creatives migration](/dist/docs/3.2.8/reference/migration/creatives) |
| Catalogs | `promoted_offerings` → `sync_catalogs` | Restructure | [Catalogs migration](/dist/docs/3.2.8/reference/migration/catalogs) |
| Geo targeting | Flat arrays → system specification required | Restructure | [Geo targeting migration](/dist/docs/3.2.8/reference/migration/geo-targeting) |
| Optimization | `optimization_goal` (single) → `optimization_goals` (array, discriminated union) | Restructure | [Optimization goals migration](/dist/docs/3.2.8/reference/migration/optimization-goals) |
| Brand identity | `brand_manifest` → `brand` ref (`{ domain, brand_id }`) | Restructure | [Brand identity migration](/dist/docs/3.2.8/reference/migration/brand-identity) |
| Capability discovery | `adcp-extension.json` → `get_adcp_capabilities` | Restructure | [Capability discovery](/dist/docs/3.2.8/protocol/get_adcp_capabilities) |
| Signals | Delivery flattening, pricing restructure | Restructure | [Signals migration](/dist/docs/3.2.8/reference/migration/signals) |
| Audiences | `external_id` promoted to required top-level field | Restructure | [Audiences migration](/dist/docs/3.2.8/reference/migration/audiences) |
| Attribution | Integer day counts → `Duration` objects | Restructure | [Attribution migration](/dist/docs/3.2.8/reference/migration/attribution) |
| Products | `buying_mode` required on every `get_products` request | New requirement | [get_products reference](/dist/docs/3.2.8/media-buy/task-reference/get_products) |
| Media buy status | `pending_activation` → `pending_start` | Rename | [Media buys](/dist/docs/3.2.8/media-buy/media-buys) |
| Media buy status | `pending_creatives` added (no creatives assigned yet) | New requirement | [Media buys](/dist/docs/3.2.8/media-buy/media-buys) |
| Task status | Legacy `task_status` and `response_status` fields MUST NOT be emitted alongside v3 `status` — remove both | Remove | [Task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle) |
| Capabilities | `compliance_testing` capability block on `get_adcp_capabilities` | Additive | [Capability discovery](/dist/docs/3.2.8/protocol/get_adcp_capabilities#compliance_testing) |
| Idempotency | `idempotency_key` required on all mutating requests (UUID v4) | New requirement | [Security § Idempotency](/dist/docs/3.2.8/building/by-layer/L1/security) |
| Request signing | RFC 9421 Ed25519 signing profile (optional in 3.0, mandatory under AdCP Verified) | Additive | [Security § Request signing](/dist/docs/3.2.8/building/by-layer/L1/security) |
| Webhook signing | Unified on RFC 9421 profile, baseline-required for sellers; HMAC fallback deprecated (removed in 4.0) | New requirement | [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) |
| Webhook idempotency | `idempotency_key` required on every webhook payload | New requirement | [Webhooks § Reliability](/dist/docs/3.2.8/building/by-layer/L3/webhooks) |
| Governance | `governance_context` is a signed JWS verified via governance agent JWKS | Restructure | [Governance](/dist/docs/3.2.8/governance/campaign) |
| IO approval | `MediaBuy.pending_approval` removed — approval is a task-layer object | Restructure | [Media buy lifecycle](/dist/docs/3.2.8/media-buy/media-buys) |
| Regulatory invariants | GDPR Art 22 / EU AI Act Annex III enforced via schema `if/then` | New requirement | [Governance § Annex III obligations](/dist/docs/3.2.8/governance/annex-iii-obligations) |
> [!WARNING]
>
> `buying_mode` on `get_products` is checked by storyboard testing. `brief` is the baseline mode; sellers that declare `wholesale` or `refine` in capabilities must handle those mode semantics. See the [v3 readiness checklist](/dist/docs/3.2.8/reference/migration/v3-readiness) for details.
### New in v3 — required vs optional
These capabilities are new in v3. None existed in v2, so there's nothing to migrate — but you should know which ones affect your integration.
| Capability | Required? | Who needs it |
| - | - | - |
| Accounts protocol (`sync_accounts`, `list_accounts`) | Required for all buyers — use `sync_accounts` when `require_operator_auth: false` (buyer-declared accounts), `list_accounts` when `true` and the seller exposes an account-id namespace | All buyers — the seller's account model determines which task to call, not whether accounts are needed |
| Brand Protocol (`brand.json`) | Recommended | All buyers — provides brand identity for creative generation |
| Governance (content standards, property lists) | Optional | Buyers who need brand suitability enforcement |
| Sponsored Intelligence | Optional | Buyers working with AI platforms that support conversational handoffs |
| Registry API | Optional | Buyers who want programmatic agent/brand discovery |
| Campaign Governance | Optional | Organizations with compliance or approval workflows |
### Running v2 and v3 side by side
Dual-support is a temporary migration tool, not a supported production posture. Since August 1, 2026, v3-only has been the required configuration — see the [v2 sunset page](/dist/docs/3.2.8/reference/v2-sunset).
During migration, sellers can accept both v2 and v3 traffic and buyers can route to each seller on the correct version:
1. **Check seller capabilities** — Call `get_adcp_capabilities` on each seller. A successful response means the seller supports v3; buyers declare their release via `adcp_version` and sellers advertise accepted releases via `adcp.supported_versions`. Through 3.x, buyers SHOULD also send the deprecated `adcp_major_version`, and sellers MUST continue advertising the deprecated `adcp.major_versions`, for compatibility with older peers. See [version negotiation](/dist/docs/3.2.8/reference/versioning#version-negotiation) for the full flow. A seller that does not respond to `get_adcp_capabilities` is v2-only.
2. **Branch by seller** — Route v3-capable sellers through your v3 integration and v2-only sellers through your existing v2 code.
3. **Migrate incrementally** — Start with the rename changes (pricing fields, channel updates), then tackle structural changes (creative assignments, optimization goals), then adopt new capabilities (accounts, governance) as needed.
### Breaking migrations (v2 → v3.0)
> [card] [Channels](/dist/docs/3.2.8/reference/migration/channels)
>
> `native` removed, `video` split, 10 new channels
> [card] [Pricing](/dist/docs/3.2.8/reference/migration/pricing)
>
> Field renames and price guidance restructure
> [card] [Creatives](/dist/docs/3.2.8/reference/migration/creatives)
>
> Creative assignments with weights and asset discovery
> [card] [Catalogs](/dist/docs/3.2.8/reference/migration/catalogs)
>
> `promoted_offerings` to first-class `sync_catalogs`
> [card] [Geo targeting](/dist/docs/3.2.8/reference/migration/geo-targeting)
>
> System specification for global geo support
> [card] [Optimization goals](/dist/docs/3.2.8/reference/migration/optimization-goals)
>
> Single goal to array with discriminated union
> [card] [Brand identity](/dist/docs/3.2.8/reference/migration/brand-identity)
>
> `brand_manifest` to `brand` ref via `brand.json`
> [card] [Signals](/dist/docs/3.2.8/reference/migration/signals)
>
> Delivery flattening and pricing restructure
> [card] [Audiences](/dist/docs/3.2.8/reference/migration/audiences)
>
> `external_id` promotion to required field
> [card] [Attribution](/dist/docs/3.2.8/reference/migration/attribution)
>
> Integer days to structured `Duration` objects
# Migrating to `media_buy_status` (3.1 → 3.2)
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/media-buy-status
Move from body-level `status` to `media_buy_status` on create_media_buy and update_media_buy success responses. Additive in 3.1; legacy field removed in 3.2; nested status cascade follows in 4.0.
# Migrating to `media_buy_status` (3.1 → 3.2)
> [!NOTE]
>
> The deprecated response-body `status: MediaBuyStatus` existed only during the
> AdCP 3.1 migration window. AdCP 3.2 removes it from create/update success
> schemas. In 3.2, root `status` is exclusively the task-envelope status.
AdCP 3.1 splits two enums that 3.0 collided at the same response root key:
* **Envelope `status`** — TaskStatus (`submitted` / `working` / `input-required` / `completed` / `canceled` / `failed` / `rejected` / `auth-required` / `unknown`). Required from beta.2 ([#4876](https://github.com/adcontextprotocol/adcp/issues/4876)).
* **Body `media_buy_status`** — MediaBuyStatus (`pending_creatives` / `pending_start` / `active` / `paused` / `completed` / `rejected` / `canceled`). **New in 3.1.**
Under MCP flat-on-the-wire serialization both fields share the response root. In 3.0 they were both named `status`; the body-level MediaBuyStatus was silently destroyed when the envelope stamped a TaskStatus at the same path. No validator caught it. 3.1 splits them.
## What changed
| Surface | 3.0 | 3.1 migration window | 3.2 |
| - | - | - | - |
| `create_media_buy` success response | `status` (MediaBuyStatus) at root | `media_buy_status` at root; legacy body `status` marked `deprecated: true` | Legacy body `status` removed; root `status` is TaskStatus only |
| `update_media_buy` success response | Same | Same | Same |
| `get_media_buys` items | `media_buys[].status` (MediaBuyStatus) | Unchanged | Unchanged — renamed to `media_buys[].media_buy_status` in 4.0 ([#4905](https://github.com/adcontextprotocol/adcp/issues/4905)) |
| `get_media_buy_delivery` items | `media_buy_deliveries[].status` (MediaBuyStatus) | Unchanged | Unchanged — renamed in 4.0 ([#4905](https://github.com/adcontextprotocol/adcp/issues/4905)) |
| `core/media-buy.json` | `status` (MediaBuyStatus) | Unchanged | Unchanged — renamed in 4.0 ([#4905](https://github.com/adcontextprotocol/adcp/issues/4905)) |
## Before (3.0)
```json theme={null}
{
"status": "completed",
"media_buy_id": "mb_12345",
"status": "active",
"packages": [...]
}
```
Two keys named `status` collide at the JSON root under MCP flat serialization — the body-level `MediaBuyStatus: 'active'` value is silently destroyed by the envelope `TaskStatus: 'completed'`. No validator catches it.
## After (3.1)
```json theme={null}
{
"status": "completed",
"media_buy_id": "mb_12345",
"media_buy_status": "active",
"packages": [...]
}
```
Two distinct fields. Envelope `status` carries the task-lifecycle state at the root; body `media_buy_status` carries the buy's lifecycle state alongside.
## 3.1 deprecation window (historical)
* **3.1 sellers** SHOULD emit `media_buy_status` on `create_media_buy` and `update_media_buy` success responses. They MAY continue emitting the deprecated top-level `status: MediaBuyStatus` only while serving 3.1.
* **3.1 buyers** MUST prefer `media_buy_status` when present. They MAY fall back to legacy `status` only for a negotiated 3.0 or 3.1 response.
* **3.0 sellers and buyers** continue to work unchanged. No `required[]` swap, no rename, no breakage.
* **Compliance storyboards** assert `path: "media_buy_status"`. A 3.1 seller emitting only the legacy `status` is schema-valid but fails 3.1 storyboard certification. The storyboard is the binding conformance check; the schema `deprecated: true` marker is advisory.
* **Sellers emitting both fields** MUST emit identical values for `media_buy_status` and the deprecated `status`. Divergent emission (e.g., `status: "active", media_buy_status: "paused"`) passes JSON Schema validation but is a conformance violation — 3.1 storyboards enforce equality via `field_value_or_absent` assertions on `status` alongside the canonical `media_buy_status` checks. The `if/then` JSON Schema constraint was evaluated and deferred: the migration window is short, codegen toolchain compat is uncertain, and the storyboard gate is sufficient. See [#4908](https://github.com/adcontextprotocol/adcp/issues/4908).
## SDK behavior during the 3.1 window
In the published 3.1 schema, the legacy `status` field carries `deprecated: true` (JSON Schema 2020-12). It is absent from the 3.2 source schema. Deprecation propagation through 3.1 codegen varies:
| Toolchain | Propagation |
| - | - |
| TypeScript (`json-schema-to-typescript`) | `@deprecated` JSDoc on the field. Reliable. |
| Python (`datamodel-code-generator` v2+) | `deprecated=True` on the `Field(...)` arg. Older pinned versions silently drop it. |
| Go (`quicktype` and similar) | Generally not propagated. |
| `@adcp/client` 3.1+, Python `adcp` SDK, `adcp-go` | Canonical `media_buy_status` is the typed shape SDK users consume. |
If your 3.1 toolchain doesn't surface the deprecation, the storyboard gate is your enforcement signal. Regenerating against 3.2 removes the legacy lifecycle field from create/update success types.
## When the legacy field disappears
* **3.2** ([#4906](https://github.com/adcontextprotocol/adcp/issues/4906)): the deprecated top-level `status: MediaBuyStatus` is **removed** from `CreateMediaBuySuccess` and `UpdateMediaBuySuccess`. After 3.2, top-level `status` on these responses unambiguously carries envelope TaskStatus only. The deprecation window is short by design — the storyboard gate already forces 3.1-conformant sellers off the legacy field.
* **4.0** ([#4905](https://github.com/adcontextprotocol/adcp/issues/4905)): the nested `status` cascade lands — `media_buys[].status` on `get-media-buys-response`, `media_buy_deliveries[].status` on `get-media-buy-delivery-response`, and `status` on `core/media-buy.json` rename to `media_buy_status`. Genuinely breaking (a `required[]` swap), held to the major.
This removal is the narrow same-major compatibility exception ratified in DR-0011 and tracked by [#4906](https://github.com/adcontextprotocol/adcp/issues/4906). The repository records it with a `minor` changeset so it is mechanically released as AdCP 3.2 after the enforced 3.1 deprecation window. The broader nested status cascade remains reserved for 4.0.
## Forward-compatible buyer code
Code that needs to span 3.0, 3.1, and 4.0 sellers:
```js theme={null}
// Never interpret the 3.2+ envelope TaskStatus as a MediaBuyStatus.
const mediaBuyStatus = response.media_buy_status
?? (negotiatedAdcpVersion === '3.0' || negotiatedAdcpVersion === '3.1'
? response.status
: undefined);
const buyLifecycleStatus = mediaBuy.media_buy_status ?? mediaBuy.status;
```
## Related
* [create_media_buy reference](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) — canonical response examples
* [Media buy lifecycle](/dist/docs/3.2.8/media-buy/media-buys/lifecycle) — the MediaBuyStatus state machine
* [Envelope task-status](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle) — TaskStatus semantics
# Migrating optimization goals
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/optimization-goals
Migrate AdCP optimization goals from beta.3 to rc.1. Replaces singular optimization_goal with a multi-goal array using discriminated unions and priority ordering.
# Migrating optimization goals
AdCP 3.0 rc.1 replaces the singular `optimization_goal` object with an `optimization_goals` array. Each goal is a discriminated union on `kind`, supporting multi-goal packages with priority ordering.
## What changed
| beta.3 | rc.1 | Notes |
| - | - | - |
| `optimization_goal` (single object) | `optimization_goals` (array) | Array of discriminated union |
| Implicit single goal | `priority` field | 1 = highest priority |
| One goal type | Two kinds: `metric` and `event` | Discriminated on `kind` field |
| No reach optimization | `reach` metric with `reach_unit` and `target_frequency` | Products declare `supported_reach_units` |
## Goal kinds
Every goal has a `kind` discriminator:
* **`metric`** — Seller-native delivery metrics (clicks, views, reach, engagements, etc.)
* **`event`** — Conversion tracking tied to event sources configured via `sync_event_sources`
### Metric goals
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/optimization-goal.json",
"kind": "metric",
"metric": "clicks",
"target": {
"kind": "cost_per",
"value": 2.50
},
"priority": 1
}
```
Supported metrics: `clicks`, `views`, `completed_views`, `viewed_seconds`, `viewable_rate` (requires `standard`; optional `vendor`), `engagements`, `follows`, `saves`, `profile_visits`, `reach`. `attention_seconds` and `attention_score` are accepted but **deprecated** (slated for removal at next major) — use `kind: "vendor_metric"` with an explicit vendor binding instead.
**How these surface in delivery:** `viewed_seconds` is reported via `viewability.viewed_seconds` (the same `standard` threshold governs both `viewable_rate` and `viewed_seconds`). Vendor-attested metrics — attention, panel-based brand lift, emissions, retail-media partner metrics — flow through the `kind: "vendor_metric"` goal kind on the optimization side and `vendor_metric_values[]` on the delivery side, keyed on `(vendor, metric_id)`. See [`kind: vendor_metric`](/dist/docs/3.2.8/media-buy/conversion-tracking/#kind-vendor_metric) for the goal shape and the three-precondition rejection rule.
Target types:
* `cost_per` — Target cost per metric unit (e.g., \$2.50 CPC)
* `threshold_rate` — Target rate threshold (e.g., 0.02 for 2% CTR)
`viewable_rate` accepts only `threshold_rate` targets, with a value from 0 to 1.
**Vendor shape on legacy and canonical goals.** The legacy goal shape (`core/optimization-goal.json`) carries `vendor` as a `BrandRef`. The canonical 3.2 shape (`core/canonical-optimization-goal.json`) carries it as a `BrandKey`. This applies both to `viewable_rate` and `viewed_seconds` metric goals and to `vendor_metric` goals. When converting a legacy goal to the canonical shape, keep only `domain`, `brand_id`, and `countries`, and drop the other `BrandRef` fields (`industries`, `data_subject_contestation`, `brand_kit_override`). They don't identify a measurement vendor, and the canonical shape rejects them.
### Event goals
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/optimization-goal.json",
"kind": "event",
"event_sources": [
{
"event_source_id": "es_web_pixel",
"event_type": "purchase",
"value_field": "order_total",
"value_factor": 1
}
],
"target": {
"kind": "per_ad_spend",
"value": 4.0
},
"attribution_window": {
"post_click": { "interval": 7, "unit": "days" },
"post_view": { "interval": 1, "unit": "days" }
},
"priority": 2
}
```
Event target types:
* `cost_per` — Target cost per conversion (CPA)
* `per_ad_spend` — Target return on ad spend (ROAS). Requires `value_field`.
* `maximize_value` — Maximize total conversion value. Requires `value_field`.
### Reach goals
Reach is a metric goal with additional fields:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/optimization-goal.json",
"kind": "metric",
"metric": "reach",
"reach_unit": "individuals",
"target_frequency": {
"min": 2,
"max": 5,
"window": { "interval": 7, "unit": "days" }
},
"priority": 1
}
```
`reach_unit` values: `individuals`, `households`, `devices`, `accounts`, `cookies`, `custom`.
`target_frequency` requires at least one of `min` or `max`, plus `window` as a Duration object (e.g., `{"interval": 7, "unit": "days"}` or `{"interval": 1, "unit": "campaign"}`).
## Multi-goal packages
Multiple goals are ordered by `priority` (1 = highest). The seller optimizes for higher-priority goals first, using lower-priority goals as tiebreakers.
**beta.3:**
```json theme={null}
{
"optimization_goal": {
"metric": "clicks",
"target_cpc": 2.50
}
}
```
**rc.1:**
```json theme={null}
{
"optimization_goals": [
{
"kind": "metric",
"metric": "clicks",
"target": { "kind": "cost_per", "value": 2.50 },
"priority": 1
},
{
"kind": "event",
"event_sources": [
{ "event_source_id": "es_web_pixel", "event_type": "purchase" }
],
"target": { "kind": "cost_per", "value": 25.00 },
"priority": 2
}
]
}
```
## Product capabilities
Products declare optimization support via `metric_optimization`:
```json test=false theme={null}
{
"metric_optimization": {
"supported_metrics": ["clicks", "views", "completed_views", "reach"],
"supported_reach_units": ["individuals", "households"],
"supported_view_durations": [6, 15, 30],
"supported_targets": ["cost_per", "threshold_rate"]
},
"max_optimization_goals": 3
}
```
* `supported_metrics` — Which metrics the product can optimize for
* `supported_reach_units` — Required when `reach` is in supported_metrics
* `supported_view_durations` — Seconds for `completed_views` metric
* `supported_viewability_standards` — Viewability standards (`mrc`, `groupm`) for `viewable_rate` goals
* `supported_targets` — Target kinds available. When omitted, only target-less goals (maximize volume) are allowed
* `max_optimization_goals` — Maximum number of goals per package
## Migration steps
**1. Rename the field**
Replace `optimization_goal` (singular) with `optimization_goals` (array) in all request construction code.
**2. Add kind discriminator**
Wrap existing goals with `"kind": "metric"` or `"kind": "event"`. Metric goals use seller-native metrics; event goals reference event sources from `sync_event_sources`.
**3. Restructure targets**
Replace flat target fields (e.g., `target_cpc`) with the discriminated `target` object: `{ "kind": "cost_per", "value": 2.50 }`.
**4. Add priority**
Set `priority: 1` for single-goal packages. For multi-goal packages, assign ascending priority values (1 = highest).
**5. Update response parsing**
When reading optimization goals from responses (e.g., `get_media_buy`), switch on `kind` to determine the goal type before accessing type-specific fields.
**6. Check product capabilities**
Before submitting goals, check `metric_optimization.supported_metrics` and `max_optimization_goals` on the product. Sellers reject unsupported metrics and goals exceeding the limit.
**7. Validate against schema**
Run requests against `optimization-goal.json` schema. The discriminated union enforces the correct fields per kind.
> [card] [Conversion tracking & optimization goals](/dist/docs/3.2.8/media-buy/conversion-tracking/index)
>
> Configure event sources, send conversion events, and optimize delivery goals.
***
**Related:** [Channels](/dist/docs/3.2.8/reference/migration/channels) | [Pricing](/dist/docs/3.2.8/reference/migration/pricing) | [Signals](/dist/docs/3.2.8/reference/migration/signals) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Prerelease upgrade notes
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/prerelease-upgrades
Breaking and additive changes between AdCP 3.0.0 release candidates.
# Prerelease upgrade notes
If you adopted a prerelease version, review the relevant section below before upgrading. If you are migrating from v2, see the [main migration guide](/dist/docs/3.2.8/reference/migration).
## rc.3 → 3.0
### Breaking for rc.3 adopters
| Area | rc.3 | 3.0 | What to do |
| - | - | - | - |
| `idempotency_key` on mutating requests | Optional | **Required** on every mutating request (schema `^[A-Za-z0-9_.:-]{16,255}$`; UUID v4 for Verified). Sellers declare `adcp.idempotency = { supported: true/false }` on capabilities. | Generate fresh key per logical operation. Persist keys across agent instances. Declare `adcp.idempotency` on `get_adcp_capabilities` (sellers). When `supported: true`, handle `IDEMPOTENCY_CONFLICT` and `IDEMPOTENCY_EXPIRED`; conformance probes require a mutated-payload replay to return CONFLICT. When `supported: false`, use natural-key checks instead of blind retries. See [Security § Idempotency](/dist/docs/3.2.8/building/by-layer/L1/security). |
| Webhook signing | HMAC-SHA256 with `push_notification_config.authentication` (required) | RFC 9421 profile (baseline-required for sellers); HMAC fallback available through 3.x via `authentication.credentials` | Publish a signing JWK in your JWKS at `jwks_uri` (referenced from `brand.json` `agents[]`). New signers use `adcp_use: "request-signing"` for webhooks; deprecated `adcp_use: "webhook-signing"` keys remain accepted during the compatibility window. If you want webhook-only key material, publish a second `request-signing` JWK with a distinct `kid`. Drop `push_notification_config.authentication` from new configs; buyers opt into legacy HMAC via `authentication.credentials`. Receivers verify against the sender's JWKS. The entire `authentication` object (HMAC + Bearer) is removed in 4.0. |
| `idempotency_key` on webhook payloads | Not standardized (fragile `(task_id, status, timestamp)` tuple dedup) | **Required** — sender-generated UUID v4 on every payload | Sellers: generate a cryptographically-random UUID v4 per event. Receivers: dedupe on `idempotency_key` with 24h minimum TTL, sender-scoped cache. Schemas affected: `mcp-webhook-payload`, `collection-list-changed-webhook`, `property-list-changed-webhook`, `artifact-webhook-payload`, `revocation-notification`. |
| `revocation-notification.notification_id` | Field name on rights revocation payload | Renamed to `idempotency_key` | Find-and-replace in your rights-revocation receivers. |
| `MediaBuy.pending_approval` status | Present | Removed — approvals are explicit approval tasks | Remove `pending_approval` from media-buy state filters. Consume approval tasks from the task surface. |
| Budget autonomy | `budget.authority_level` enum (`agent_full \| agent_limited \| human_required`) | Removed. Split into `budget.reallocation_threshold` (number) + `plan.human_review_required` (boolean) | Rewrite: `agent_full` → `reallocation_unlimited: true`; `agent_limited` → `reallocation_threshold: `; `human_required` → `human_review_required: true`. Regulated verticals (fair housing, lending, employment, pharmaceutical) enforce `human_review_required: true` via schema `if/then`. |
| `inventory-lists` specialism | Present | Renamed to `property-lists`; `collection-lists` split out as separate specialism | Update specialism claims. Agents that governed collection lists should now claim both `property-lists` and `collection-lists`. |
| Compliance path taxonomy | `/compliance/{v}/domains/` | `/compliance/{v}/protocols/` | Update any internal references to compliance paths. Runner and catalog use `protocols/` exclusively. |
| `governance_context` carrier | Opaque string | Signed JWS | Switch to JWS format. Verify signature via governance agent JWKS (resolved via `sync_governance`). Bind to `sub`, `aud`, `phase`, `exp`. |
| Media buy status | `pending_activation` | Removed — replaced by `pending_creatives` and `pending_start` | Replace `pending_activation` in status filters, comparisons, and state machine logic. Schema: `enums/media-buy-status.json`. See details below. |
| Capabilities model | Redundant boolean gates (`features.content_standards`, `brand.identity`, `trusted_match.supported`, etc.) | Removed — object presence is the signal | Remove boolean capability checks. Test for object presence instead. Schema: `protocol/get-adcp-capabilities-response.json`. See [capabilities migration](#capabilities-model-simplification) below. |
| `reporting_capabilities` | Optional on products | Required on every product | Ensure all products returned from `get_products` include `reporting_capabilities`. Schema: `core/product.json`. |
| `account` on `update_media_buy` | Optional | Required | Pass `account` on all `update_media_buy` calls, matching `create_media_buy` behavior. Schema: `media-buy/update-media-buy-request.json`. |
| `preview_creative` schema | oneOf union | Flat object with `request_type` discriminant | Update request builders to use the flat schema with `request_type` field. Schema: `creative/preview-creative-request.json`. See [preview_creative migration](#preview_creative-schema-flattening) below. |
| `signal_id` on `get_signals` response | Optional on signal items | Required | Ensure all signal items in `get_signals` responses include `signal_id`. Schema: `signals/get-signals-response.json`. |
| `GOVERNANCE_DENIED` error | Not in error code enum | Added as correctable error | Handle `GOVERNANCE_DENIED` in error handling logic. Schema: `enums/error-code.json`. |
| Governance lifecycle | `media_buy_id` as lifecycle correlator | Removed — `governance_context` is sole lifecycle correlator | Replace `media_buy_id` in governance schemas with `governance_context`. Handle `purchase_type` field on `check_governance` and `report_plan_outcome`. Schema: `governance/check-governance-request.json`. See [governance migration](#governance-lifecycle-migration) below. |
| Geo capability fields | `supported_geo_levels`, `supported_metro_systems`, `supported_postal_systems` (from #2143) | Removed — use typed objects (`geo_countries`, `geo_regions`, `geo_metros`, `geo_postal_areas`) | If you adopted the flat array shape from #2143, revert to typed geo objects with `additionalProperties: false`. Schema: `protocol/get-adcp-capabilities-response.json`. |
| `comply_test_controller` schema | oneOf union | Flat object with `scenario` discriminant and if/then validation | Update request builders to use the flat schema with `scenario` field instead of oneOf variants. |
| Compliance testing surface | An interim rc.4 build accepted `"compliance_testing"` as a `supported_protocols` value | Removed before GA. Compliance testing is declared via a top-level `compliance_testing: { scenarios: [...] }` capability block, not via `supported_protocols`. | Remove `"compliance_testing"` from `supported_protocols` if present. Agents implementing `comply_test_controller` add a top-level `compliance_testing: { scenarios: [...] }` block instead. |
| Specialism IDs | `broadcast-platform`, `social-platform`, `property-governance`, `collection-governance` | Renamed/merged: `sales-broadcast-tv`, `sales-social`, `inventory-lists` (merges property + collection governance) | Update specialism claims in `get_adcp_capabilities.specialisms`. See [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog). |
| `audience-sync` parent protocol | Under `governance` | Moved to `media-buy` | If claiming `audience-sync`, add `media_buy` to `supported_protocols`. |
| Sponsored Intelligence scope | `sponsored_intelligence` as a specialism | Promoted to full protocol in `supported_protocols` | Move from `specialisms` to `supported_protocols`. |
### Media buy status migration
`pending_activation` was a single state covering two distinct conditions. It has been split:
| Condition | rc.3 status | 3.0 status |
| - | - | - |
| Buy approved, no creatives assigned | `pending_activation` | `pending_creatives` |
| Buy ready to serve, waiting for flight date | `pending_activation` | `pending_start` |
| Buy is serving | `active` | `active` (unchanged) |
**What to change:**
1. **Status filters** — Replace `pending_activation` with both `pending_creatives` and `pending_start` in `status_filter` arrays on `get_media_buys` and `get_media_buy_delivery`.
2. **Status comparisons** — Any `if (status === 'pending_activation')` needs to branch on which condition you're checking. If you want "not yet serving," check for both `pending_creatives` and `pending_start`. If you want "ready but waiting for flight date," check only `pending_start`.
3. **State machine transitions** — `rejected` is now valid from both `pending_creatives` and `pending_start` (previously only from `pending_activation`). `pending_creatives` → `pending_start` happens when creatives are assigned via `sync_creatives`.
4. **Legacy alias** — `pending` continues to be accepted as an alias for `pending_start` in delivery response status filters.
See the [canonical lifecycle diagram](/dist/docs/3.2.8/media-buy/media-buys#state-machine) for the full state machine.
### Capabilities model simplification
PR #2143 removed redundant boolean capability fields. Object presence now signals support — if you have the object, you have the capability.
**Removed fields and replacements:**
| Removed field | What to do instead |
| - | - |
| `media_buy.reporting` | Use product-level `reporting_capabilities` (now required) |
| `features.content_standards` | Check for `content_standards` object presence |
| `features.audience_targeting` | Check for `audience_targeting` object presence |
| `features.conversion_tracking` | Check for `conversion_tracking` object presence |
| `content_standards_detail` | Renamed to `content_standards` |
| `brand.identity` | Implied by brand protocol support |
| `trusted_match.supported` | Check for `trusted_match` object presence |
| `targeting.device_platform` / `targeting.device_type` | Implied by `media_buy` protocol support |
| `targeting.audience_include` / `targeting.audience_exclude` | Implied by `audience_targeting` presence |
**Before (rc.3):**
```json theme={null}
{
"features": {
"content_standards": true,
"audience_targeting": true
},
"trusted_match": {
"supported": true,
"uid_types": ["email_sha256"]
}
}
```
**After (3.0):**
```json theme={null}
{
"content_standards": { ... },
"audience_targeting": { ... },
"trusted_match": {
"uid_types": ["email_sha256"]
}
}
```
### preview_creative schema flattening
The `preview_creative` request is flattened from a oneOf union to a single object with a `request_type` discriminant. Three modes:
| `request_type` | Required field | Purpose |
| - | - | - |
| `single` | `creative_manifest` | Preview one creative |
| `batch` | `requests` (array, 1-50 items) | Preview multiple creatives |
| `variant` | `variant_id` | Replay a post-flight variant |
**Before (rc.3):**
```json theme={null}
{
"creative_manifest": { "format_id": { ... }, "assets": { ... } }
}
```
**After (3.0):**
```json theme={null}
{
"request_type": "single",
"creative_manifest": { "format_id": { ... }, "assets": { ... } }
}
```
Schema: `schemas/creative/preview-creative-request.json`
### Governance lifecycle migration
`media_buy_id` is removed from governance schemas. `governance_context` is an opaque string that serves as the sole lifecycle correlator across `sync_plans`, `check_governance`, `report_plan_outcome`, and `get_plan_audit_logs`.
**Before (rc.3):**
```json theme={null}
{
"media_buy_id": "mb_456",
"planned_delivery": { ... }
}
```
**After (3.0):**
```json theme={null}
{
"governance_context": "campaign_2024_q4_nova",
"purchase_type": "media_buy",
"planned_delivery": { ... }
}
```
Schema: `schemas/governance/check-governance-request.json`
### context and ext fields
All request and response schemas across governance, collection, property, sponsored-intelligence, and content-standards protocols now include optional `context` and `ext` fields for application metadata and protocol extensions.
### Additive changes in 3.0
* **RFC 9421 request signing profile (optional in 3.0, mandatory under AdCP Verified)** — Ed25519 HTTP Message Signatures with canonicalized covered-component list. Published test vectors at `static/compliance/source/test-vectors/request-signing/`. sf-binary encoding and URL canonicalization pinned for bit-identical canonical inputs. 15-step verification checklist with `keyid` cap-before-crypto.
* **Webhook signing unified on RFC 9421** — Baseline-required for sellers emitting webhooks. Sellers publish a signing JWK in their JWKS at `jwks_uri`; new signers use `adcp_use: "request-signing"` for webhook delivery, while deprecated `webhook-signing` keys remain accepted during the compatibility window. Use a distinct `kid` if you want webhook-only key material. 14-step webhook verifier checklist in the [Security guide](/dist/docs/3.2.8/building/by-layer/L1/security). HMAC-SHA256 remains a legacy fallback through 3.x (the entire `authentication` object is removed in 4.0).
* **Property-list webhook signing defined** — Property-list change deliveries use RFC 9421 `Signature`, `Signature-Input`, and `Content-Digest` headers. The published 3.1 schema required a body-level `signature` without defining an algorithm, signed bytes, or key discovery; 3.2 senders set that deprecated field to the compatibility marker `rfc9421`, while receivers accept any string from an older 3.x sender and ignore it for authentication. Keeping the marker required and unconstrained avoids a 3.x schema break; it is removed in 4.0. Collection-list webhook schema and behavior remain unchanged pending separately versioned work.
* **Required `idempotency_key` on every webhook payload** — Sender-generated UUID v4 across all five webhook payload schemas. Replaces fragile `(task_id, status, timestamp)` dedup. `revocation-notification.notification_id` renamed to `idempotency_key` for protocol-wide consistency.
* **`check_governance` on every spend-commit** — Governance invocation is required at commit, not just at plan approval. Closes the loophole where partial spends could skip governance.
* **Experimental status mechanism** — `status: experimental` marker for fields and tasks in production use but not yet under full stability guarantees. `custom` pricing-model escape hatch on signals.
* **`submitted` branch on `create_media_buy`** — Seller has accepted the payload for processing but has not yet confirmed the order. Distinct from `pending_creatives` and `pending_start`.
* **Time semantics + `activate_signal` idempotency** — Unifies time-field semantics across the protocol. `activate_signal` added to the required-idempotency table.
* **Known limitations + privacy-considerations reference pages** — New `/docs/reference/known-limitations` and `/docs/reference/privacy-considerations`. Platform-agnostic lint prevents vendor-specific language from creeping into the spec.
* **Signed JWS `governance_context`** — Governance decisions are now cryptographically verifiable. Sellers resolve the governance agent's JWKS via `sync_governance` and verify `sub` / `aud` / `phase` / `exp` before honoring the decision.
* **Universal security storyboard** — Every agent runs `/compliance/{version}/universal/security.yaml` (unauth rejection, API key, OAuth/RFC 9728, audience binding). Agents declaring signing also run the `signed_requests` harness.
* **Cross-instance state persistence** — Architecture spec requires persistent state (tasks, media buys, plans, signed artifacts, idempotency keys) across horizontally-scaled instances.
* **Security implementation guide** — New `docs/building/by-layer/L1/security.mdx` documents threat model, three-principal model (brand / operator / agent), and verification paths. Retires ambiguous "principal" terminology.
* **GDPR Art 22 / EU AI Act Annex III as schema invariants** — New registry policy `eu_ai_act_annex_iii`. `requires_human_review` on policies and categories. Schema-level enforcement of `human_review_required: true` for regulated verticals.
* **Operating an Agent guide** — New doc for publishers without engineering teams — three paths: partner, self-host, build.
* **Release cadence policy** — Named cadence: patch monthly, minor quarterly, major annual if needed. v2 EOL August 1, 2026.
* **CHARTER.md** — Formal governance charter published.
* **Collection lists** — Program-level brand safety using distribution identifiers (IMDb, Gracenote, EIDR) for cross-publisher matching. New targeting overlay fields (`collection_list`, `collection_list_exclude`). New genre taxonomy enum.
* **Broadcast TV support** — Ad-ID identifiers, broadcast spot formats (:15, :30, :60), Agency Estimate Number, measurement windows (Live, C3, C7), delivery data completeness (`is_final`, `measurement_window`).
* **Offline reporting delivery** — `reporting_delivery_methods` on capabilities, `reporting_bucket` on accounts, `supports_offline_delivery` on product `reporting_capabilities`. Avro and ORC added as file format options.
* **TMPX exposure tracking** — Country-partitioned identity and macro connectivity for the Trusted Match Protocol execution layer.
* **TMP provider registration** — `provider-registration.json` schema, `GET /health` endpoint, dual discovery models (static config and dynamic API), per-provider latency budget semantics.
* **TMP multi-identity Identity Match** — `identity-match-request` replaces single `user_token` + `uid_type` with an `identities` array (minItems 1, maxItems 3). Router filters per provider and re-signs with RFC 8785 JCS canonicalization; cache key adds `consent_hash`. Adds `rampid_derived` to the `uid-type` enum. Breaking relative to prior pre-release TMP drafts only; TMP remains pre-release in 3.0 and stabilizes in 3.1.0.
* **GOVERNANCE_DENIED error** — New correctable error code for governance-rejected operations.
* **context/ext fields** — Optional `context` and `ext` on all request/response schemas across governance, collection, property, SI, and content-standards protocols.
* **Compliance testing capability** — Agents include a `compliance_testing: { scenarios: [...] }` block in `get_adcp_capabilities` declaring which `comply_test_controller` scenarios they support. The block's presence is the signal — compliance testing is NOT a `supported_protocols` value. Storyboard runners use the block to determine whether deterministic testing steps can be validated.
* **Specialisms + compliance catalog** — Storyboards ship in the protocol at `/compliance/{version}/` (universal + protocols + specialisms + test-kits). New `specialisms` field on `get_adcp_capabilities` with 19 values across 6 protocols. Per-version protocol tarball at `/protocol/{version}.tgz`. See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog).
* **Structured measurement terms** — `measurement_terms` on products and media buys for billing vendor, IVT threshold, and viewability floor negotiation. `cancellation_policy` on guaranteed products. `viewability-standard` enum. `TERMS_REJECTED` error code.
* **Unified vendor pricing** — `pricing_options[]` on `list_creatives`, `build_creative`, `get_creative_features`, and `property-list`. Shared `vendor-pricing-option.json` schema.
* **Per-request version declaration** — `adcp_major_version` on all v3 request schemas. `VERSION_UNSUPPORTED` error code. Multi-version sellers supporting v2 clients must detect v2 payloads by structural cues, not by this field (v2 schemas do not have it).
* **Broadcast forecast schema** — `measurement_source`, `packages`, and `guaranteed_impressions` on `DeliveryForecast`. New `forecast-range-unit` and `forecastable-metric` enums.
* **Broadcast station identifiers** — `station_id` and `facility_id` identifier types. `linear_tv` property type.
* **Brand schema extensions** — Generic `agents` array on `brand.json`. Visual tokens (`border_radius`, `elevation`, `spacing`, extended color roles). Structured font definitions.
* **Per-item error schema** — `sync_creatives`, `sync_catalogs`, and `sync_event_sources` response errors now use `error.json` ref.
* **Property relationship field** — `relationship` on brand.json property definitions (`owned`, `direct`, `delegated`, `ad_network`) for bilateral verification with `adagents.json` delegation types.
* **`sales` agent type restored** — `sales` restored to `brand-agent-type` enum. Sales agents (SSPs, publishers) are distinct from buying agents (DSPs, buyer platforms).
* **Required tasks reference** — New reference page consolidating required, conditional, and optional tasks across all AdCP protocols by agent role.
* **Storyboard validation fixes** — 20+ validation bugs fixed across 11 storyboard files: corrected field paths (`creatives[0].action`, `media_buy_deliveries`, `renders[0].preview_url`), added missing `value:` to `field_value` checks, added `value` property to storyboard validation schema.
***
## rc.1 → rc.2
### Potentially breaking for rc.1 adopters
| Area | rc.1 | rc.2 | What to do |
| - | - | - | - |
| Account auth model | `account_resolution` capability | Removed — `require_operator_auth` now determines account model | Update capability parsing and auth/account branching logic |
| Creative library task boundary | `list_creatives` / `sync_creatives` documented under Media Buy | Creative library operations live in the Creative Protocol | Route library reads/writes through Creative Protocol assumptions, even when a sales agent implements both protocols |
| Sandbox capability discovery | `media_buy.features.sandbox` | `account.sandbox` | Read sandbox support from the account capability block |
| DOOH flat rate parameters | `flat_rate.parameters` without discriminator | `flat_rate.parameters.type: "dooh"` required when parameters are present | Add the discriminator in request builders and validators |
| Deprecated governance task docs | `delete_content_standards`, `get_property_features` documented | Removed | Use `update_content_standards`, property lists, and `get_adcp_capabilities` instead |
### Additive changes in rc.2
* **Creative generation and preview** — `build_creative` adds `include_preview`, `preview_inputs`, `preview_quality`, `preview_output_format`, `quality`, `item_limit`, and multi-format `target_format_ids`. Buyers can now preview inline, choose draft vs production generation, and request multiple output formats in one call.
* **Creative library retrieval** — `build_creative` also supports library retrieval using `creative_id`, optional `concept_id`, `media_buy_id`, `package_id`, and `macro_values`, so ad servers and creative platforms can resolve stored creatives into delivery-ready manifests.
* **Creative capability discovery** — Creative agents can declare `supports_generation`, `supports_transformation`, and `has_creative_library`. `list_creatives` now uses library-oriented fields like `include_snapshot`, `has_served`, and `items`.
* **Product discovery and planning** — `get_products` adds `exclusivity`, `preferred_delivery_types`, and `time_budget`, with `incomplete` in the response. Products may omit `delivery_measurement`, and packages can now carry per-package `start_time` / `end_time`.
* **Compliance and governance** — Creative disclosures add persistence semantics, and campaign governance introduces `sync_plans`, `check_governance`, `report_plan_outcome`, and `get_plan_audit_logs`.
* **Accounts and sandbox ergonomics** — `sync_accounts` adds `payment_terms`, and sandbox now participates in the natural account key for buyer-declared account references.
***
## Need help?
* **Community**: [Slack](/dist/docs/3.2.8/community/joining-slack) — best for quick questions from other implementers
* **Issues**: [GitHub Issues](https://github.com/adcontextprotocol/adcp/issues) — for bugs, spec questions, or migration edge cases
* **Full v2 → v3 migration**: [Migration guide](/dist/docs/3.2.8/reference/migration)
# Migrating pricing
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/pricing
Migrate AdCP pricing from v2 to v3. Covers field renames, the hard constraint vs soft hint separation, and updated pricing option schemas.
# Migrating pricing
AdCP 3.0 renames pricing fields for clarity and separates hard constraints (prices the publisher enforces) from soft hints (historical data to help buyers bid).
## What changed
| v2 field | v3 field | Change type |
| - | - | - |
| `fixed_rate` | `fixed_price` | Renamed |
| `price_guidance.floor` | `floor_price` | Moved to top level |
The `pricing_model`, `currency`, `pricing_option_id`, and `price_guidance` percentiles (`p25`, `p50`, `p75`, `p90`) are unchanged.
## Hard constraints vs soft hints
v3 makes an explicit semantic distinction:
**Hard constraints** — publisher-enforced prices that cause bid rejection if violated:
* `fixed_price` — the exact price per unit (fixed-price deals)
* `floor_price` — minimum acceptable bid (auction pricing)
These are mutually exclusive. A pricing option has either `fixed_price` (guaranteed rate) or `floor_price` (auction with minimum), never both.
**Soft hints** — historical percentiles to help buyers calibrate bids:
* `price_guidance.p25` — 25th percentile of recent winning bids
* `price_guidance.p50` — median of recent winning bids
* `price_guidance.p75` — 75th percentile of recent winning bids
* `price_guidance.p90` — 90th percentile of recent winning bids
## Deal type mapping
These fields map to standard programmatic deal types:
| Deal type | AdCP field | Description |
| - | - | - |
| Programmatic Guaranteed (PG) | `fixed_price` | Fixed CPM, guaranteed delivery |
| Preferred Deal | `fixed_price` | Fixed CPM, non-guaranteed (buyer has first look) |
| Private Marketplace (PMP) | `floor_price` | Auction with minimum bid |
| Open Auction | Neither | No floor or fixed price — open bidding |
PG and Preferred Deals both use `fixed_price`. The distinction between them is in delivery commitment, not pricing — PG guarantees delivery volume while Preferred Deals offer first-look access without volume guarantees.
## Fixed-price deals
**v2:**
```json theme={null}
{
"pricing_option_id": "cpm_usd_fixed",
"pricing_model": "cpm",
"currency": "USD",
"fixed_rate": 25.00
}
```
**v3:**
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpm-option.json",
"pricing_option_id": "cpm_usd_fixed",
"pricing_model": "cpm",
"currency": "USD",
"fixed_price": 25.00
}
```
Rename `fixed_rate` to `fixed_price`. No structural changes.
## Auction pricing
**v2:**
```json theme={null}
{
"pricing_option_id": "cpm_usd_auction",
"pricing_model": "cpm",
"currency": "USD",
"price_guidance": {
"floor": 10.00,
"p50": 15.00,
"p75": 18.00
}
}
```
**v3:**
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpm-option.json",
"pricing_option_id": "cpm_usd_auction",
"pricing_model": "cpm",
"currency": "USD",
"floor_price": 10.00,
"price_guidance": {
"p50": 15.00,
"p75": 18.00
}
}
```
Two changes:
1. `price_guidance.floor` moves to top-level `floor_price`
2. `price_guidance` retains only the percentile hints
## Price guidance object
The v3 `price_guidance` object contains only statistical percentiles:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/price-guidance.json",
"p25": 8.50,
"p50": 15.00,
"p75": 18.00,
"p90": 22.00
}
```
All fields are optional. Publishers include whichever percentiles they can provide.
## Flat-rate pricing
**v2** (DOOH with parameters, no type discriminator):
```json theme={null}
{
"pricing_option_id": "dooh_times_square",
"pricing_model": "flat_rate",
"currency": "USD",
"fixed_rate": 50000.00,
"parameters": {
"duration_hours": 24,
"sov_percentage": 100,
"estimated_impressions": 1500000
}
}
```
**v3:**
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/flat-rate-option.json",
"pricing_option_id": "dooh_times_square",
"pricing_model": "flat_rate",
"currency": "USD",
"fixed_price": 50000.00,
"parameters": {
"type": "dooh",
"duration_hours": 24,
"sov_percentage": 100,
"estimated_impressions": 1500000
}
}
```
Two changes:
1. `fixed_rate` renames to `fixed_price` (same as other pricing models)
2. `parameters` gains a required `"type": "dooh"` discriminator for DOOH inventory
Sponsorship flat_rate options that had no `parameters` in v2 continue to omit it in v3. Note that `fixed_price` is optional on flat-rate options — when absent, the flat-rate is auction-based (uncommon but valid for some DOOH inventory).
## Minimum spend
v3 adds an optional `min_spend_per_package` field to all pricing options:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpm-option.json",
"pricing_option_id": "cpm_usd_premium",
"pricing_model": "cpm",
"currency": "USD",
"floor_price": 15.00,
"min_spend_per_package": 5000.00,
"price_guidance": {
"p50": 22.00,
"p75": 28.00
}
}
```
This lets publishers declare minimum spend requirements per package.
## Transition period handling
During migration, readers may encounter both old and new field names. Consider checking for both:
```javascript test=false theme={null}
const price = option.fixed_price ?? option.fixed_rate;
const floor = option.floor_price ?? option.price_guidance?.floor;
```
v3 writers should only emit the new field names. Old field names (`fixed_rate`, `price_guidance.floor`) are not recognized by v3 schema validation. Remove the v2 fallback once all upstream sellers have migrated to v3 schemas.
## Migration steps
**1. Rename fixed_rate**
Rename `fixed_rate` to `fixed_price` in all pricing options.
**2. Move floor**
Move `floor` from inside `price_guidance` to top-level `floor_price`.
**3. Clean up price_guidance**
Remove `floor` from `price_guidance` objects (only percentiles remain).
**4. Update readers**
Update code to look for new field names. Consider temporary fallback for both during transition.
**5. Test auction bids**
Verify floor enforcement works with the new field location.
**6. Validate against schemas**
Each pricing model has its own schema in `/schemas/3.2.8/pricing-options/`.
> [card] [Media products](/dist/docs/3.2.8/media-buy/product-discovery/media-products)
>
> How products declare pricing options, channels, and capabilities.
***
**Related:** [Channels](/dist/docs/3.2.8/reference/migration/channels) | [Geo targeting](/dist/docs/3.2.8/reference/migration/geo-targeting) | [Creatives](/dist/docs/3.2.8/reference/migration/creatives) | [Catalogs](/dist/docs/3.2.8/reference/migration/catalogs) | [Attribution](/dist/docs/3.2.8/reference/migration/attribution) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Reliable Reporting consumer-status loop
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/reliable-reporting-status-loop
Breaking-change notice and migration guide for sync_reporting_status in Reliable Reporting Core.
> [!WARNING]
>
> **Experimental breaking-change notice published September 12, 2026.** Under
> AdCP's six-week experimental-surface notice policy, the Core requirement
> described here must not appear in an immutable release before October 24,
> 2026\. `3.2.0-rc.2` published the task as opt-in, `3.2.0-rc.3` hardened it, and
> AdCP 3.2 ships it opt-in; making it *required* is what the notice window
> governs. Published `3.2.0-rc.1` remains unchanged.
Reliable Reporting without this loop lets a seller publish its obligation/revision state and
requires a buyer to derive an independent expected-period denominator. It does
not give the buyer a standard way to tell the seller that reporting was absent
or unreadable. A seller can therefore project `healthy` while the buyer's
webhook, exact revision read, or destination access is failing.
AdCP 3.2 closes that loop additively with opt-in
[`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status).
A seller advertises `consumer_status_task` only when the task and readback are
implemented. The requirement itself lands no earlier than the first minor after
the notice window. Both changes remain inside the experimental
`media_buy.reporting_delivery` surface.
## Capability change
The blocks below are excerpts of `media_buy.reporting_delivery` showing only the
fields that change; a real declaration also carries `offerings[]`,
`automated_recovery_window_seconds`, and `status_retention_days`.
Before (`3.2.0-rc.1`):
```json theme={null}
{
"supported": true,
"reliable_reporting_version": "1.0",
"configuration_task": "sync_accounts",
"status_task": "get_reporting_status",
"revision_content_task": "get_media_buy_delivery"
}
```
Opt-in form in AdCP 3.2, and required form no earlier than the first minor
after the notice window:
```json theme={null}
{
"supported": true,
"reliable_reporting_version": "1.0",
"configuration_task": "sync_accounts",
"status_task": "get_reporting_status",
"consumer_status_task": "sync_reporting_status",
"revision_content_task": "get_media_buy_delivery"
}
```
A seller that also commits to an escalation clock advertises the window and the
contact it escalates to. Both are optional, and declaring the window requires
declaring the contact:
```json theme={null}
{
"supported": true,
"reliable_reporting_version": "1.0",
"configuration_task": "sync_accounts",
"status_task": "get_reporting_status",
"consumer_status_task": "sync_reporting_status",
"revision_content_task": "get_media_buy_delivery",
"consumer_mismatch_escalation_seconds": 172800,
"operations_contact": {
"url": "https://status.streamhaus.example/reporting",
"email": "reporting-ops@streamhaus.example"
}
}
```
`operations_contact` is inert human-facing metadata. Agents surface it to an
operator; they never dereference the URL, send protocol traffic to it, or treat
either value as a credential or as evidence of agent identity.
The new field is optional during the notice window. When present, it commits the
seller to the complete task and readback contract below. The first minor after
the notice window, at the earliest, makes the field required for Reliable
Reporting Core. It does not add a buyer
endpoint or webhook: buyers call the seller-hosted task using the same
authenticated transport as other AdCP tasks.
## Seller migration
1. Accept batched immutable consumer status statements with ordinary AdCP
idempotency, atomic current-leaf supersession, bounded per-caller resources,
and caller/account isolation.
2. Validate a missing obligation from the accepted configuration generation,
report definition, and period; do not require a seller-issued obligation ID.
3. Retain superseded status history and include it in
`get_reporting_status(view: "periods")`, pagination totals, and
`changes_after` checkpoints for at least `status_retention_days`. Verify any
supplied seller snapshot ID and timestamp against the scoped snapshot you
actually issued.
4. Compare the current buyer statement with the current seller projection. A
conflict creates a caller-scoped `CONSUMER_STATUS_MISMATCH`; it never rewrites
either party's evidence or contaminates another caller. Carry `opened_at` on
that issue and keep it fixed across re-emissions and severity changes.
5. Apply the stale-`received` grace window. A `received` statement made stale
only by your own restatement is `delayed` until the `created_at` of the
**first** revision that superseded the one the buyer named, plus the
configuration generation's `schedule.delivery_sla`, as exact elapsed time in
UTC — or `automated_recovery_window_seconds` when that SLA resolves to a zero
duration. It is `action_required` after. Later restatements do not restart
the window, and an advertised `consumer_mismatch_escalation_seconds` boundary
takes precedence when the two overlap. Every other conflict —
`obligation_missing`, `revision_missing`, `unreadable`, `content_mismatch` —
is `action_required` immediately.
6. Report `obligation_counts.consumer_status_pending` on the summary view:
obligations past `expected_at + automated_recovery_window_seconds` with no
current status from this caller. Count it and stop. Silence never changes
health, another count, or your `reliability_statistics`.
7. Accept `content_mismatch` with its closed `mismatch_code`. It is a
contract-fact disagreement about the accepted configuration generation, not a
measurement dispute; do not route it into billing variance handling.
8. Optionally advertise `consumer_mismatch_escalation_seconds` with an
`operations_contact`. If you do, an `open` or `acknowledged` issue still
unresolved at `opened_at` plus that window MUST be `action_required` with a
`contact_*` `recommended_action`.
9. Treat `resolved` and `waived` as distinct terminal dispositions. `resolved`
means the consumer superseded the causing statement or your own projection
stopped conflicting. `waived` requires an explicit off-protocol agreement
with the authenticated consumer covering the exact caller/account,
`issue_id`, causing `reporting_status_id`, and diagnosed conflict; never
create it unilaterally. Retire that issue, restore the underlying summary and
period health while retaining the immutable consumer statement, and emit an
offered `reporting.status_changed` recovery transition when health changes.
Only `open` and `acknowledged` issues appear in `issues[]`.
10. Add `consumer_status_task: "sync_reporting_status"` only when every item
above is deployed.
## Buyer migration
1. Continue retaining accepted configuration generations and deriving expected
periods independently.
2. After bounded retries, submit `received`, `obligation_missing`,
`revision_missing`, `unreadable`, or `content_mismatch` for the exact period;
do not wait indefinitely before making failure visible.
3. Meet the posting deadline. Every elapsed expected period needs a current
status by `expected_at + automated_recovery_window_seconds`. If you are still
retrying at that point, post `revision_missing` or `unreadable` and supersede
it later — silence is counted against you in
`obligation_counts.consumer_status_pending` and tells the seller nothing.
4. Send a new immutable statement with explicit supersession whenever status
changes.
5. Re-read within the grace window when a seller restatement makes your
`received` stale. You have until the first superseding revision's
`created_at + delivery_sla` before the mismatch escalates to
`action_required`; a seller that restates again does not buy you more time.
6. Use `content_mismatch` only for contract facts the accepted configuration
generation already fixed — a frozen media buy with no rows, a promised metric
absent, the wrong currency, rows outside the period. A disagreement about
counts belongs to
[billing authority](/dist/docs/3.2.8/media-buy/advanced-topics/billing-authority)
and `makegood_policy`, not to this loop.
7. Before closing the reporting scope, ensure every elapsed expected period has
a current consumer status.
Missing buyer feedback remains unknown and never excuses the seller's reporting
obligation. `received` is Core access evidence only; Reconciled Billing still
uses [`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts)
for materialization evidence, row/control totals, and canonical billing digests.
## Billing authority stays separate
None of this decides whose count governs an invoice. That remains
`measurement_terms.billing_measurement` — see
[Billing Authority](/dist/docs/3.2.8/media-buy/advanced-topics/billing-authority). Current
source reserves an optional `authoritative_party` (`seller` | `consumer`,
default `seller`) on `reporting-delivery-config.json` so the two models can be
unified additively later. **Sellers MUST reject `consumer` with
`UNSUPPORTED_FEATURE`** during configuration validation; no released minor
defines the buyer-deposited revision task it anticipates. Reserving it now means
a future buyer-basis billing feed does not have to break the existing
billing-feed constraints. Tracked in
[#7440](https://github.com/adcontextprotocol/adcp/issues/7440).
> [!NOTE]
>
> **Already emitting `CONSUMER_STATUS_MISMATCH`?** `opened_at` and
> `reporting_status_id` are now required on that issue code. The code itself
> shipped in RC.1's `reporting-status-issue.json` enum, so an RC.1 seller that
> already emits it must add `opened_at` — fixed at first emission, never advanced
> on re-emission — before validating against the
> [3.2 schema](https://adcontextprotocol.org/schemas/3.2.1/core/reporting-status-issue.json).
> No other issue code is affected.
## Verifying the loop
Sellers advertising `consumer_status_task` run the capability-gated
`reporting_consumer_status` storyboard. It uses the
[`reporting_core_lifecycle_probe`](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#reporting_core_lifecycle_probe)
controller fixture, which supplies every boundary the projection depends on:
* `restate_after_received` restates a revision the caller already reported as
`received` and returns the `stale_received_grace_deadline`, so both sides of
the grace boundary are graded live rather than only in a seller's own
integration tests.
* `advance_past_status_deadline` crosses `expected_at +
automated_recovery_window_seconds` without recording any statement, so the
storyboard can check that `obligation_counts.consumer_status_pending` rises,
that it clears on any posted leaf, and that neither transition moves `health`
or any other count.
* `advance_past_escalation` crosses the open issue's `opened_at` plus
`consumer_mismatch_escalation_seconds` while the grace window is still open,
so the precedence rule is graded rather than assumed — and the returned
`issue_id` and `issue_opened_at` prove the window is anchored to the issue
rather than to the poll.
The storyboard also grades each closed `mismatch_code`, rejection of a
`content_mismatch` that omits it, and the advertised `operations_contact`.
Cross-principal non-disclosure still requires an integration test — see
[known limitations](/dist/docs/3.2.8/reference/known-limitations#conformance-and-testing).
# Migrating signals
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/signals
Migrate AdCP signals from beta.3 to rc.1. Covers deliver_to flattening, structured pricing options, and simplified usage reporting fields.
# Migrating signals
AdCP 3.0 rc.1 makes three changes to the Signals Protocol: delivery target flattening, structured pricing options, and usage reporting simplification.
## Deliver-to flattening
The nested `deliver_to` object in `get_signals` requests is replaced by two top-level fields.
| beta.3 | rc.1 | Notes |
| - | - | - |
| `deliver_to.destinations` | `destinations` | Moved to top level |
| `deliver_to.countries` | `countries` | Moved to top level |
**beta.3:**
```json test=false theme={null}
{
"signal_spec": "in-market auto intenders",
"deliver_to": {
"destinations": [
{ "agent_url": "https://dsp.example.com", "seat_id": "seat_123" }
],
"countries": ["US", "CA"]
}
}
```
**rc.1:**
```json test=false theme={null}
{
"signal_spec": "in-market auto intenders",
"destinations": [
{ "agent_url": "https://dsp.example.com", "seat_id": "seat_123" }
],
"countries": ["US", "CA"]
}
```
***
## Pricing options
The legacy `pricing` object (with a single `cpm` field) is replaced by a `pricing_options` array. Each option is a discriminated union on `model`.
| beta.3 | rc.1 | Notes |
| - | - | - |
| `pricing: { cpm: 2.50 }` | `pricing_options[]` | Array of pricing model objects |
| Implicit pricing selection | `pricing_option_id` on `activate_signal` | Explicit buyer commitment |
| No idempotency | `idempotency_key` on `report_usage` | Prevents duplicate billing |
### Three pricing models
**CPM** — Fixed cost per thousand impressions:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/signal-pricing-option.json",
"pricing_option_id": "po_auto_cpm",
"model": "cpm",
"cpm": 2.50,
"currency": "USD"
}
```
**Percent of media** — Percentage of media spend, with optional CPM cap:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/signal-pricing-option.json",
"pricing_option_id": "po_auto_pom",
"model": "percent_of_media",
"percent": 15,
"max_cpm": 5.00,
"currency": "USD"
}
```
**Flat fee** — Fixed charge per reporting period (monthly licensed segments):
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/signal-pricing-option.json",
"pricing_option_id": "po_auto_flat",
"model": "flat_fee",
"amount": 10000.00,
"period": "monthly",
"currency": "USD"
}
```
### Activation with pricing
When activating a signal, pass the selected `pricing_option_id`:
```json test=false theme={null}
{
"signal_agent_segment_id": "luxury_auto_intenders",
"destinations": [
{ "type": "agent", "agent_url": "https://dsp.example.com", "account": { "account_id": "acct_pinnacle" } }
],
"pricing_option_id": "po_auto_cpm"
}
```
***
## Usage reporting
`report_usage` adds `idempotency_key` and removes the `kind` and `operator_id` fields.
| beta.3 | rc.1 | Notes |
| - | - | - |
| `kind` field | Removed | Usage records are self-describing via `signal_agent_segment_id` or `standards_id` |
| `operator_id` field | Removed | Account reference provides operator identity |
| No idempotency | `idempotency_key` | Client-generated UUID prevents duplicate billing on retries |
**rc.1 usage report:**
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/account/report-usage-request.json",
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"reporting_period": {
"start": "2025-03-01T00:00:00Z",
"end": "2025-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_pinnacle_signals" },
"signal_agent_segment_id": "luxury_auto_intenders",
"pricing_option_id": "po_auto_cpm",
"impressions": 4200000,
"media_spend": 21000.00,
"vendor_cost": 2100.00,
"currency": "USD"
}
]
}
```
The `pricing_option_id` in the usage record must match the one passed at activation, allowing the vendor to verify the correct rate was applied.
## Migration steps
**1. Flatten deliver_to**
Move `deliver_to.destinations` and `deliver_to.countries` to top-level fields in `get_signals` requests.
**2. Parse pricing_options array**
Update signal response parsing to read `pricing_options` (array) instead of `pricing` (object). Switch on `model` field to determine the pricing type.
**3. Select pricing at activation**
When calling `activate_signal`, pass the selected `pricing_option_id` from the signal's `pricing_options` array.
**4. Add idempotency_key to report_usage**
Generate a unique key (UUID) for each `report_usage` call. Retries with the same key are idempotent.
**5. Remove kind and operator_id**
Remove `kind` and `operator_id` from usage records. Usage type is determined by the presence of `signal_agent_segment_id` (signals) or `standards_id` (governance).
**6. Track pricing_option_id through lifecycle**
Store the `pricing_option_id` at activation time and pass it in `report_usage` records so the vendor can verify billing.
**7. Validate against schemas**
Run requests against `get-signals-request.json`, `activate-signal-request.json`, and `report-usage-request.json` schemas.
> [card] [Signals Protocol](/dist/docs/3.2.8/signals/overview)
>
> Full reference for signal discovery, activation, usage reporting, and pricing models.
***
**Related:** [Pricing](/dist/docs/3.2.8/reference/migration/pricing) | [Optimization goals](/dist/docs/3.2.8/reference/migration/optimization-goals) | [AdCP 3.0 overview](/dist/docs/3.2.8/reference/whats-new-in-v3)
# Targeting-aware product discovery
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/targeting-aware-discovery
Migrate targeting filters and product-ID assumptions to targeting overlays, future support, sparse resolution, and configured products.
# Targeting-aware product discovery
AdCP 3.2 aligns targeting across discovery and purchase. Buyers provide concrete
delivery constraints in `list_products.criteria.targeting_overlay` or
`request_proposals.criteria.targeting_overlay`, and sellers return configured
products whose pricing and forecasts already account for those constraints.
`get_products.targeting_overlay` remains the compatibility-facade form.
## What changed
* Split discovery tasks accept `criteria.targeting_overlay`; `get_products` accepts the equivalent top-level field.
* Proposal refinements can replace structured discovery criteria without restating inherited fields.
* `required_overlay_support` declares targeting dimensions whose values will be
supplied on packages later.
* Products declare selectable dimensions through `overlay_support`.
* Products disclose non-exact discovery alternatives through sparse
`targeting_resolution.modifications`.
* `request_proposals` and the `get_products` compatibility response confirm
structured hard targeting inferred from natural-language briefs once through
response-root `targeting_resolution.brief_targeting`; `refine_proposals`
places confirmation in the affected `results[]` entry
whenever that interpretation materially affects eligibility, pricing, or forecasting.
* Product discovery and booked packages use lifecycle-specific schemas under
the shared `targeting_resolution` field; demographic package execution moves
to `targeting_resolution.demographics`.
* `product_id` is opaque. Non-custom wholesale IDs remain stable for the same
logical offer within seller and declared cache scope; custom IDs are stable
only within their issuing discovery/refinement lineage.
* `placement_selection` joins property and collection lists as purchased-
inventory targeting inside the overlay.
* Legacy targeting-like product filters are deprecated.
## Filter migration
Coverage and delivery targeting are different requests. Preserve the meaning of
legacy filters when upgrading a seller or buyer; using a newer field does not
authorize changing what the buyer asked for.
| Legacy discovery field | Compact discovery handling |
| - | - |
| `filters.countries` | `criteria.offer_filters.countries` |
| `filters.regions` | `criteria.offer_filters.regions` |
| `filters.metros` | `criteria.offer_filters.metros` (same `{system, code}` entries) |
| `filters.postal_areas` | `criteria.offer_filters.postal_areas` |
| `filters.geo_proximity` | `criteria.offer_filters.geo_proximity` |
| top-level `property_list` | `criteria.offer_filters.property_list` |
| `filters.keywords` | Preserve legacy keyword eligibility in the facade; no automatic delivery-overlay translation. |
| `filters.signal_targeting` | Preserve signal-option eligibility, values, and include/exclude capability in the facade. |
| `filters.required_geo_targeting` | Use `criteria.required_overlay_support` only when the exact dimension, country, and system requirement is representable; otherwise retain legacy evaluation. |
The geographic filters match inventory coverage. They do not require selectable
package targeting and do not scope pricing or forecasts to that geography.
Within one field, entries are alternatives; different filter fields combine
with AND. Keep channel, format, delivery type, pricing, reporting, and other
product characteristics in `criteria.offer_filters` as well. Legacy
`get_products` continues accepting the original field names.
Use `criteria.targeting_overlay` when the buyer actually intends to restrict
delivery, and `criteria.required_overlay_support` when the buyer needs to select
targeting values later. Coverage and an explicit overlay may coexist and are
applied independently. For example, Canadian coverage and US-only delivery can
both be satisfied by a product covering both countries.
For concrete signal delivery selections, use `signal_targeting_groups` with
explicit group operators. Copying a legacy `targeting_mode: "exclude"` into
`targeting_overlay.signal_targeting` does not preserve exclusion, even if the
result validates.
See the [legacy request-preservation contract](https://github.com/adcontextprotocol/adcp/blob/main/specs/legacy-compact-lifecycle-compatibility.md#legacy-request-preservation-on-a-32-seller)
for named formats, inline catalogs, field projections, execution budgets, and
other inputs requiring retained seller logic. Unsupported semantics must be
reported at the original input path before any side effect.
## Briefs versus structured fields
Move any requirement with a structured AdCP representation out of prose and
into that field. For targeting, this means using `targeting_overlay`. Structured
input is more compact, deterministic, and lossless. Briefs remain appropriate
for goals, context, semantic intent, preferences, and requirements without a
structured representation.
Hard targeting stated only in a brief remains binding. Sellers MUST expose the
predicate they inferred once as response-level
`targeting_resolution.brief_targeting` when that structured interpretation
materially affects product eligibility, pricing, or forecasting; otherwise it
remains a best practice. Do not use that field to echo an unchanged structured
overlay.
## Known values versus future selection
Known values are real targeting and participate in forecasts:
```json theme={null}
{
"targeting_overlay": {
"geo_countries": ["US"]
}
}
```
Use future support when the buyer needs package-level control but does not know
the eventual values:
```json theme={null}
{
"required_overlay_support": {
"geo_metros": {
"systems": ["nielsen_dma"]
},
"placement_selection": true,
"property_list": true,
"collection_list": true
}
}
```
This does not request one product per DMA, placement, property, or collection.
It filters to products that allow those dimensions to be selected later.
Operator-specific capabilities remain separate: for example,
`device_platform` and `device_platform_exclude` are independently requested and
disclosed so exclusion support is never inferred from inclusion support.
Requirement `true` matches support `true` or any valid support object. An object
requirement matches support `true` or a support object containing every
requested boolean and array subset. Unrequested fields and numeric seller limits
do not participate. Support guarantees selectability, not inventory or a
value-specific forecast for every later selection. Rediscover with concrete
`targeting_overlay` values when that forecast is required. Fixed prices and
floors remain binding for supported selections; price guidance remains
non-binding.
Products can disclose per-package cardinality without changing the requirement
shape. For example, a buyer can require future country and radius selection:
```json theme={null}
{
"required_overlay_support": {
"geo_countries": true,
"geo_proximity": { "radius": true }
}
}
```
A matching Product can respond with constrained support:
```json theme={null}
{
"overlay_support": {
"geo_countries": { "max_values_per_package": 1 },
"geo_proximity": {
"radius": true,
"max_values_per_package": 5
}
}
}
```
These limits apply to each package field independently. They are not buyer
requirements, value allowlists, inventory guarantees, or cross-package
constraints. Sellers reject an over-limit create or update atomically with
`UNSUPPORTED_FEATURE`. Legacy support `true` remains valid.
Numeric limits are ignored for future-support matching, not for concrete
targeting acceptance. A returned Product's accepted effective targeting must
already satisfy every maximum it discloses. Sellers exclude an over-limit
candidate unless they return a distinct configured Product with a disclosed,
compliant targeting modification.
ISO subdivision support follows the same split but can be country/value aware:
```json theme={null}
{
"targeting_overlay": {
"geo_regions": ["FR-49"]
},
"required_overlay_support": {
"geo_regions_exclude": {
"countries": {
"FR": { "values": ["FR-44", "FR-2A"] }
}
}
}
}
```
The known `FR-49` constraint scopes the returned configured product and
forecast. The exclusion requirement is permission to select either candidate
later; it is not an availability promise for either value. Inclusion and
exclusion are matched independently. Numeric administrative depth is not used
because ISO subdivision categories are not uniform across countries.
## Do not migrate raw ad-server keys
Do not replace legacy targeting-like filters with a `custom`,
`key_value_pairs`, or equivalent generic map. External buyers use typed AdCP
targeting fields, seller-published signal references, and structured inventory
selection. Sellers keep backend key/value compilation private. If a recurring
concept needs protocol support, standardize it as a typed field with explicit
matching and resolution behavior.
## Accepting targeting modifications
Exact acceptance produces no structured-overlay echo. A product with no Product
`targeting_resolution` accepts the discovery overlay exactly, but does not
confirm how prose was interpreted. Brief-derived hard targeting may therefore
produce response-root `targeting_resolution.brief_targeting` on
`request_proposals` or `get_products`, or per-result confirmation on
`refine_proposals`, even when no overlay was sent.
An exact request-specific configured product issued through targeting-aware
discovery still returns `expires_at` (and, on `get_products`, `is_custom: true`);
absence of a resolution echo does not make its price, forecast, or inventory
assumptions permanent. The generic Product schema continues accepting legacy custom
products without `expires_at`; the requirement belongs to this new discovery
flow and to every product that carries `targeting_resolution`.
Canonical products returned by `list_products` and the proposal lifecycle carry
no `is_custom`; `expires_at` identifies request-specific configured offers.
A seller offering an alternative returns only the changed paths. On
`get_products`, the legacy Product also carries `is_custom: true`:
```json theme={null}
{
"product_id": "prod_configured_age_456",
"is_custom": true,
"expires_at": "2026-08-05T12:00:00Z",
"targeting_resolution": {
"modifications": [
{
"operation": "replace",
"path": "/demographics/age",
"applied": {
"min": 25,
"max": 34,
"include_unknown": false
},
"reason": "This product executes seller-defined age intervals."
}
]
}
}
```
Using this `product_id` in a direct `create_media_buy`, or accepting a finalized
proposal that purchases it, accepts the modification. A fresh unsupported
overlay sent directly at creation is still rejected; sellers never store a
knowingly non-equivalent package execution.
## Product identity
Reuse non-custom wholesale IDs for the same logical offer within the seller and
declared `cache_scope`, including across reads and wholesale-feed webhooks.
Feed and pricing versions communicate mutation; retirement or replacement may
end the identity. A binding price, floor, currency, model, or priced
applicability change receives a new `pricing_option_id`; feed events do not
reinterpret an issued option ID. Do not extend wholesale ID stability to custom configured products.
Within the lineage that issued a custom ID, it remains stable for refinement
and purchase and identifies the complete buyable configuration, including
targeting resolution, forecast assumptions, and overlay support. The selected
`(product_id, pricing_option_id)` pair identifies its commercial terms.
The lineage is explicit in referenced `product_id` and `proposal_id` values,
not a transport session. On refine, top-level filters, targeting, and future
support replace prior values when present; omitted values remain bound through
the referenced product. Any changed buyable configuration receives a new ID.
Use the configured `product_id` throughout its discovery/refinement context.
Request-specific products carry `expires_at`. A seller that still recognizes an
expired ID returns `PRODUCT_EXPIRED`; after its expiry tombstone is no longer
retained, or when the ID belongs to another account or lineage,
`PRODUCT_NOT_FOUND` applies. Sellers do not retain tombstones indefinitely and
do not reveal cross-tenant existence through the error choice. Either result requires rediscovery. This
change deliberately does not introduce a second “catalog product” identity that
could be confused with AdCP creative catalogs.
## Placement selection
Placement selection is purchased-inventory targeting:
```json theme={null}
{
"targeting_overlay": {
"placement_selection": {
"mode": "selected",
"placement_refs": [
{
"publisher_domain": "pinnacle-media.example",
"placement_id": "short_video"
}
]
}
}
}
```
Do not use creative assignment refs to purchase placement inventory.
`creative_assignments[].placement_refs` route a creative only within the
already-purchased set. Placement selection is a complete set: products with
fixed `mode: included` placements use the product default and do not advertise
selectable placement support. Placement, property, and collection changes all
use the existing `update_targeting` action.
A selected placement set exactly equal to the product's complete fixed
`mode: included` set is an inherent restatement across discovery, create, and
update. It does not require `overlay_support.placement_selection`; partial
selection still requires a selectable product.
This placement lifecycle supersedes the separate top-level selection proposed
in [issue #6132](https://github.com/adcontextprotocol/adcp/issues/6132). It is
nested in `targeting_overlay` so purchased inventory follows the same
discovery, forecasting, authorization, and readback rules as other targeting.
There is no separate `update_placements` action: a seller advertises
`update_targeting`, and an unavailable action is rejected with
`ACTION_NOT_ALLOWED` and `attempted_action: "update_targeting"`.
On `update_media_buy`, omission has two different meanings:
* Omit `targeting_overlay` to leave all targeting unchanged.
* Supply `targeting_overlay` as the complete desired post-update overlay.
Omitting `placement_selection` from that replacement removes the prior
placement constraint; it does not preserve that nested field.
Invalid placement identities or orphaned creative routing return
`INVALID_REQUEST`; unsupported selection returns `UNSUPPORTED_FEATURE`; and a
selection outside the priced envelope returns `REQUOTE_REQUIRED`. Every
rejection leaves the prior package targeting and assignments unchanged.
## Compatibility window
Release negotiation is the coarse feature gate. There is no separate
`targeting_aware_discovery` capability flag: a seller advertising a 3.2 release
is promising the 3.2 discovery contract, while each product's `overlay_support`
remains authoritative for the dimensions that can be selected later.
Before sending `targeting_overlay` or `required_overlay_support`, a buyer:
1. Reads `get_adcp_capabilities.adcp.supported_versions`.
2. Selects a compatible 3.2 release (normally `"3.2"`) and sends that exact
release-precision value in `adcp_version` (plus `adcp_major_version: 3`
through 3.x).
3. Validates the response against the echoed `adcp_version`.
Absence of `supported_versions`, or a list whose highest compatible release is
3.1 or earlier, is not evidence of targeting-aware discovery. The buyer must
omit the 3.2 fields and use legacy targeting filters or explicit brief prose.
It must not optimistically send unknown fields to a major-only seller because a
legacy implementation may accept and ignore them through an open schema.
A 3.2 seller receiving a 3.1 pin either serves the 3.1 schema and omits 3.2-only
request/response semantics, or returns `VERSION_UNSUPPORTED` when it does not
support 3.1. It never labels a 3.2-shaped response as 3.1.
Sellers preserve legacy coverage and eligibility filters independently of any
explicit overlay. Equality between those fields is not required because they
serve different purposes. Legacy-only requests remain supported through 3.x;
unsupported legacy predicates must be rejected explicitly rather than ignored.
Schema surfaces are available through the v3 alias:
* [`get-products-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-request.json)
* [`targeting-overlay-support.json`](https://adcontextprotocol.org/schemas/3.2.8/core/targeting-overlay-support.json)
* [`targeting-overlay-requirements.json`](https://adcontextprotocol.org/schemas/3.2.8/core/targeting-overlay-requirements.json)
* [`product-targeting-resolution.json`](https://adcontextprotocol.org/schemas/3.2.8/core/product-targeting-resolution.json)
* [`package-targeting-resolution.json`](https://adcontextprotocol.org/schemas/3.2.8/core/package-targeting-resolution.json)
* [`placement-selection.json`](https://adcontextprotocol.org/schemas/3.2.8/core/placement-selection.json)
# v3 readiness checklist
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/migration/v3-readiness
The 8 minimum requirements for seller agents to pass AdCP v3 storyboard testing.
# v3 readiness checklist
AdCP storyboard testing requires v3 protocol support. Agents that only support v2 will fail. This page covers the minimum changes to unblock integration testing with v3 buyers — not the full migration. For the complete list, see the [migration guide](/dist/docs/3.2.8/reference/migration).
> [!WARNING]
>
> Storyboard testing will hard-fail any agent that does not declare v3 support. Complete these 8 items first, then work through the [full migration checklist](/dist/docs/3.2.8/reference/migration). v2 is fully deprecated on August 1, 2026 (UTC) — see the [v2 sunset page](/dist/docs/3.2.8/reference/v2-sunset).
***
## 1. Implement `get_adcp_capabilities`
v3 buyers call this task first to discover what your agent supports. Without it, buyers cannot determine your protocol version, supported channels, pricing models, or features.
This is the single most important change — it's how buyers (and storyboard testing) distinguish v3 agents from v2.
Return at minimum: `major_versions: [3]`, `supported_protocols`, and your `features` object.
> [card] [get_adcp_capabilities reference](/dist/docs/3.2.8/protocol/get_adcp_capabilities)
>
> Task specification and response schema.
***
## 2. Update channel taxonomy
v3 replaces v2's 9 channels with 20 planning-oriented channels. Buyers send v3 channel values — your agent must recognize them.
| Common v2 value | v3 replacement |
| - | - |
| `video` | `olv`, `linear_tv`, or `cinema` |
| `audio` | `radio` or `streaming_audio` |
| `native` | Removed — native inventory is now part of `display` |
| `retail` | `retail_media` |
`display`, `social`, `ctv`, `podcast`, and `dooh` are unchanged.
> [card] [Channel migration](/dist/docs/3.2.8/reference/migration/channels)
>
> Complete mapping table and examples.
***
## 3. Rename pricing fields
Two field renames — same semantics, different names:
| v2 field | v3 field |
| - | - |
| `fixed_rate` | `fixed_price` |
| `price_guidance.floor` | `floor_price` (top-level) |
Buyers validate against v3 schemas. The old field names cause schema validation failures.
> [card] [Pricing migration](/dist/docs/3.2.8/reference/migration/pricing)
>
> Before/after examples and price guidance restructuring.
***
## 4. Support `creative_assignments`
`creative_ids` (string array) is replaced by `creative_assignments` (object array) with delivery weighting and placement targeting.
```json theme={null}
// v2
{ "creative_ids": ["cr_001", "cr_002"] }
// v3
{ "creative_assignments": [
{ "creative_id": "cr_001", "weight": 70 },
{ "creative_id": "cr_002", "weight": 30 }
]
}
```
> [card] [Creatives migration](/dist/docs/3.2.8/reference/migration/creatives)
>
> Weighted assignments, placement targeting, and asset discovery.
***
## 5. Accept `brand` ref instead of `brand_manifest`
Buyers pass brand identity as a reference (`{ domain, brand_id }`) instead of an inline manifest. Your agent resolves brand data from `brand.json` or the registry at execution time.
```json theme={null}
// v2
{ "brand_manifest": { "name": "Acme", "logo": "..." } }
// v3
{ "brand": { "domain": "acme.example.com", "brand_id": "acme_main" } }
```
> [card] [Brand identity migration](/dist/docs/3.2.8/reference/migration/brand-identity)
>
> BrandRef schema, resolution flow, and migration steps.
***
## 6. Handle `buying_mode` on `get_products`
`buying_mode` is now required on every `get_products` request. `brief` is the baseline mode for curated product discovery. If your agent declares `wholesale` or `refine` in `media_buy.buying_modes`, it must handle those mode semantics as well.
> [card] [get_products reference](/dist/docs/3.2.8/media-buy/task-reference/get_products)
>
> Full request schema including buying_mode.
***
## 7. Remove `buyer_ref` — use `idempotency_key`
v3 removes `buyer_ref`, `buyer_campaign_ref`, and `campaign_ref` from all requests and responses. Seller-assigned `media_buy_id` and `package_id` are now the only canonical identifiers.
If your agent relied on `buyer_ref` for deduplication, use the new `idempotency_key` field instead. `idempotency_key` (UUID v4) is **required** on every mutating request — agents MUST reject requests that omit it with `INVALID_REQUEST`, and MUST return `IDEMPOTENCY_CONFLICT` when a key is reused with a different payload. See the [idempotency implementation guide](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency) for normative semantics.
If your agent used `buyer_ref` for internal tracking or correlation (e.g. mapping to campaign IDs, session traces, or UI state), use the `context` field instead. `context` is an opaque object echoed unchanged in every response and webhook — agents must never parse or act on it. For `create_media_buy` package correlation, put per-package tracking in `packages[i].context` (for example `context.buyer_ref`), not deprecated top-level `buyer_ref`; 3.1+ sellers MUST echo `product_id` on explicit package responses, and package context remains the fallback for legacy sellers that do not.
| v2 field | v3 replacement |
| - | - |
| `buyer_ref` | Removed — use `media_buy_id` (seller-assigned) |
| `buyer_campaign_ref` | Removed |
| `campaign_ref` | Removed |
| `buyer_ref` as implicit dedup | Explicit `idempotency_key` on mutating requests |
| `buyer_ref` as correlation / tracking | `context` (opaque, echoed unchanged) |
```json theme={null}
// v2 — buyer provides their own ref
{ "buyer_ref": "camp-2024-q3", "start_time": "..." }
// v3 — seller-assigned ID, explicit idempotency, context for tracking
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"context": { "campaign": "camp-2024-q3", "trace_id": "abc-123" },
"start_time": "..."
}
```
For package-level line-item correlation, keep the buy-level context separate from each package's fallback correlation handle:
```json test=false theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440001",
"context": {
"internal_campaign_id": "camp-2024-q3"
},
"brand": {
"domain": "example-brand.test"
},
"packages": [
{
"product_id": "prod_weekday_display",
"pricing_option_id": "cpm_usd_auction",
"format_option_refs": [
{ "scope": "product", "format_option_id": "display_image_300x250" }
],
"budget": 12000,
"context": {
"buyer_ref": "line-001"
}
},
{
"product_id": "prod_weekend_video",
"pricing_option_id": "cpm_usd_auction",
"format_option_refs": [
{ "scope": "product", "format_option_id": "video_hosted_30s" }
],
"budget": 18000,
"context": {
"buyer_ref": "line-002"
}
}
],
"start_time": "2026-07-01T00:00:00Z",
"end_time": "2026-07-31T23:59:59Z"
}
```
***
## 8. Implement `sync_accounts`
v3 buyers establish billing relationships before placing buys. Your agent must accept `sync_accounts` calls and return an account reference that buyers include on subsequent requests.
> [card] [Accounts Protocol](/dist/docs/3.2.8/accounts/overview)
>
> Account provisioning, lifecycle, and the sync_accounts task.
***
## After these 8 items
Once these are in place, run storyboard testing against your agent. The existing tracks (products, media buy, creative) validate v3 schemas in detail and will surface any remaining field-level issues.
For the complete migration — including geo targeting, optimization goals, signals, audiences, and attribution — see the [full migration guide](/dist/docs/3.2.8/reference/migration).
# What's New in AdCP 3.1
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/whats-new-in-3-1
Adopter overview of AdCP 3.1 — distributed brand.json, dependency-impact webhooks, wholesale feed mirroring, release-precision version negotiation, brand response signing, canonical creative formats, vendor-attested measurement, action discovery, and more. Additive over 3.0; use wire pin 3.1 for the stable release.
> [!NOTE]
>
> **Status: 3.1 is released and maintained.** AdCP 3.2 is the current minor (see [What's new in AdCP 3.2](/dist/docs/3.2.8/reference/whats-new-in-3-2)); 3.1 is the supported previous minor, wire pin `adcp_version: "3.1"`. The 3.0 line remains supported for existing integrations pinned to `"3.0"`.
AdCP 3.1 is a minor release. Every 3.1 change is **additive** over 3.0: new fields are optional, no required field was removed, no shape changed in a way that breaks a 3.0-conformant client. **No breaking changes for 3.0-conformant agents.** To adopt 3.1, pin production traffic to `"3.1"` after confirming the agent advertises that value in `supported_versions`. For implementation prep, use the [3.0 to 3.1 migration guide](/dist/docs/3.2.8/reference/migration/3-0-to-3-1).
This page is the curated adopter overview for the 3.1 minor release. Need the full 3.1 change list, per-PR detail, or migration tables? Use [Release Notes § Version 3.1.0](/dist/docs/3.2.8/reference/release-notes#version-3-1-0), the authoritative version record, and [Migrating from 3.0 to 3.1](/dist/docs/3.2.8/reference/migration/3-0-to-3-1), the role-based upgrade checklist. For long-form normative reference, follow the link on each headline below.
> [!NOTE]
>
> **Looking for the major v2 → v3 changes instead?** See [What's New in AdCP 3](/dist/docs/3.2.8/reference/whats-new-in-v3). This page covers the 3.0 → 3.1 minor delta only.
## Final 3.1 feature set
If you only need the stable 3.1 shape, read this list first:
* **Versioning and validation.** Release-precision `adcp_version` pins, stable wire value `"3.1"`, `supported_versions` advertisement, envelope echo, and version-scoped verification badges.
* **Brand trust.** Distributed `brand.json`, sub-brand self-publishing through `brand_refs[]`, typed brand constraints, authorized operator scoping, and required signed responses for `verify_brand_claim` / `verify_brand_claims`.
* **Signals and product targeting.** Enriched signal definitions, `SignalRef`, wholesale signal enumeration, product-scoped `included_signals`, selectable `signal_targeting_options`, grouped buy-time `signal_targeting_groups`, and clarified owned-vs-marketplace conformance.
* **Wholesale feed mirroring.** Conditional fetch tokens, public/account `cache_scope`, product and signal wholesale-feed webhooks, and repair-by-read semantics for storefronts, registries, and federated marketplaces.
* **Creative formats.** Canonical `format_kind` declarations, publisher format catalogs, `v1_format_ref` dual-emission, hosted audio/video `duration_ms_exact` plus one-sided `duration_ms_range`, published-post references, and video placement semantics.
* **Creative generation.** `list_transformers`, account-scoped transformer selection, strict typed `config`, catalog and variant fan-out, advisory evaluator ranking over `creative-feature-result[]`, spend controls, content macros, free-text params, and per-output pricing receipts.
* **Media-buy operations.** Dependency impairments, buyer-visible `webhook_activity[]`, action discovery, proposal-lifecycle cleanup, currency-scoped product discovery, sponsored/social placement fields, and SI availability status.
* **Measurement and billing.** Vendor-attested `vendor_metric` goals, reach-window semantics, `viewability.viewed_seconds`, windowed delivery recovery, finality flags on delivery and usage, and out-of-band creative billing declarations.
* **Runtime hardening.** Mutation idempotency and read-envelope tolerance, `IDEMPOTENCY_IN_FLIGHT`, open error-code decoding with recovery classification, auth error split, credential-in-payload rejection, webhook operation-id echo, and flat MCP envelope tolerance.
* **SDK and compliance readiness.** Named schemas for code generators, async-response refs, intentionally open payload markers, capability-gated storyboard coverage, packaged compliance bundle closure, and drift checks for release artifacts.
## Why upgrade
3.1 is the production-hardening release. 3.0 shipped the protocol surface — discovery, buy lifecycle, signals, creative library, brand identity. 3.1 closes the operational gaps that surfaced when real agents started running buys against real publishers:
* **You can debug your webhooks now.** Buyer agents inspect their own recent delivery fires via `webhook_activity[]` on `get_media_buys` — HTTP status, fire time, idempotency_key — instead of guessing why their gateway returned 5xx.
* **You can see why a buy is impaired.** When a creative gets pulled, an audience is suspended, a catalog item is withdrawn, or an event source goes quiet, the buy's `health` flips to `impaired` and `impairments[]` lists every offline dependency with its package_ids and remediation hint. Both as a snapshot on `get_media_buys` and as a push fire via `notification-type: impairment`.
* **You can mirror wholesale product feed and wholesale signals feed without burning bandwidth.** Conditional-fetch tokens (`if_wholesale_feed_version` — ETag-style), wholesale enumeration on signals (symmetric with products), and account-level wholesale feed webhooks let storefronts, federated marketplaces, and registries hold an up-to-date local replica of every connected agent's buyable products and signals without re-fetching unchanged feed payloads on every poll. Two-layer cache model (`cache_scope: "public" | "account"`) means most accounts dedupe into a single shared cache.
* **You can compose seller-offered signals on media products.** Products can declare `included_signals` for bundled/planned signal metadata, `signal_targeting_allowed` for package-level signal selection, optional inline `signal_targeting_options` for product-specific menus and pricing, and `signal_targeting_rules` for include/exclude/grouping limits. Buyers apply selections through grouped `targeting_overlay.signal_targeting_groups`, while wholesale products can omit inline options and use `get_signals` as the selectable signal feed.
* **You can bind goals to vendor-attested measurement.** Optimization goals can now reference `(vendor, metric_id)` pairs from real measurement vendors (DV, IAS, Adelaide, TVision, Lumen, Kantar, Upwave, Scope3, etc.) — not vendor-agnostic strings the seller can interpret however they want. The measurement-vendor catalog discovery surface itself is experimental in 3.1 (`measurement.core`).
* **Brand verification responses are attestable.** `verify_brand_claim` and `verify_brand_claims` now return a required `signed_response` payload-envelope JWS so downstream partners can retain and verify the brand's answer without relying on transport-session context.
* **You can pin a release and stop fighting drift.** Release-precision `adcp_version` (`"3.1"` for the stable release) on every request; sellers advertise their full `supported_versions` set and echo what they actually served. SDK constructor pins are now a real thing.
* **Sub-brands self-publish.** A brand can publish its own canonical `brand.json` on its own domain while the corporate house declares ownership via a portfolio pointer — same reciprocal pattern as IAB's `ads.txt` / `sellers.json`.
* **Creative formats have a canonical vocabulary.** 12 canonical `format_kind` values + a publisher catalog discovery surface + a projection-ref mechanism. Creative agents also advertise buildable canonical outputs through `creative.supported_formats[]`; targetable entries SHOULD include stable `capability_id` values for `build_creative` routing.
* **Hosted audio/video durations use one range vocabulary.** `duration_ms_range` now covers bounded and one-sided ranges (`[null, 60000]` for "up to 60s", `[15000, null]` for "at least 15s"); fixed slots should use `duration_ms_exact`. No separate min/max duration fields were added.
* **You can discover and select creative transformers.** A new `list_transformers` task surfaces the account-scoped, agent-offered build units — voices, models, styles — the creative analog of media-buy products, with an `expand_params` mode that returns the enumerable option values (e.g. your configured voices) on the same tool. `build_creative` selects one with `transformer_id`, configures it with a typed `config` bag (strict validation — unknown keys and out-of-range values are rejected with field-attributed errors; vendor knobs go in `ext`), and fans out across catalog items (`max_creatives`) and alternatives (`max_variants` + `variant_axis`, with `keep_mode` advisory). A new `BuildCreativeVariantSuccess` response member carries per-variant manifests, recommendation/rank, and a per-leaf pricing receipt. Pricing moves onto the transformer (`pricing_options` `per_unit`), settled via `report_usage`.
* **Video and audio inventory can declare execution semantics.** Products and placements can declare OpenRTB-aligned `video_placement_types` and `audio_distribution_types` so buyers can distinguish instream/accompanying/interstitial/standalone video and music streaming/FM-AM broadcast/podcast/catch-up/web-radio audio without changing buyer-facing channels.
* **Verification badges are version-scoped.** Public 3.1 badge issuance can run alongside active 3.0 badges; buyers pinned to a release read the matching badge version.
* **Action discovery and proposals are mechanical.** Products advertise `allowed_actions[]`; media buys carry `available_actions[]`; proposals use `proposal_status` to say whether finalize is still required before `create_media_buy(proposal_id)`.
* **Billing has finality.** Row-level `is_final` + `finalized_at` on delivery; matching `final` + `finalized_at` + `measurement_window` on `report_usage`. Buyers know when the number stops moving and can reconcile invoices.
Plus a long tail of error-code clarity, auth tightening, idempotency rules, TMP IdentityMatch upgrades, and `adagents.json` scaling work — see the headline list below.
## At a glance
| Area | 3.0 | 3.1 |
| - | - | - |
| **`brand.json`** | Inline `brands[]` under a single house document | Distributed: brands self-publish on their own domains; houses declare ownership via `brand_refs[]`; mutual-assertion trust; typed `trademarks[]` |
| **Brand verification** | brand.json discovery only | `verify_brand_claim` / `verify_brand_claims` — federated authoritative verification with required `signed_response` payload-envelope JWS evidence |
| **Dependency impact** | No protocol surface for "a resource the buy depends on went offline" | `media_buy.health` + `impairments[]` snapshot; `notification-type: impairment` webhooks; `propagation_surfaces` capability; `impairment.coherence` compliance invariant |
| **Webhook foundation** | Specced per-feature | One persistent-channel contract: snapshot/log duality, `notification_id` typed at envelope, per-account + per-resource subscription model |
| **Webhook observability** | No buyer-side delivery visibility | `webhook_activity[]` on `get_media_buys` — buyers self-service debug their own missed fires |
| **Wholesale feed mirroring** | Re-fetch wholesale on every poll to detect changes | ETag-style `wholesale_feed_version` / `if_wholesale_feed_version` conditional fetch on `get_products` / `get_signals`; `cache_scope` (public/account) on every response for two-layer cache layering |
| **Wholesale signals** | `get_signals` required `signal_spec` or deprecated `signal_ids` — no protocol-conformant way to enumerate the full priced signals feed | `discovery_mode: "wholesale"` symmetric with `get_products buying_mode: "wholesale"`; paginated full wholesale signals feed enumeration with `signal_ref` identity and `pricing_options[]` populated |
| **Signal identity** | `SignalId` / `signal_id.source` (`catalog` or `agent`) was the primary signal identity shape | `SignalRef` / `signal_ref.scope` is canonical: `data_provider` for provider-published adagents.json signals, `signal_source` for source-native signals, and `product` for product-local media-buy options. Legacy `signal_id` remains accepted during the migration window |
| **Product signal metadata** | `data_provider_signals` mixed legacy bundled metadata with no selectable package-level signal surface | `data_provider_signals` is deprecated. Use `included_signals` for non-selectable bundled/planned signals and `signal_targeting_options` for selectable product-scoped signal options with pricing, activation handles, defaults, and grouping hints |
| **Package signal targeting** | No grouped buy-time surface for seller-offered named signals; storefronts overloaded audience fields or brief text | `targeting_overlay.signal_targeting_groups`: top-level `operator: "all"` with child `any` include groups and `none` exclusion groups. Product `signal_targeting_rules` declares selection mode, direct vs seller-planned resolution, and group limits |
| **Wholesale feed webhooks** | None | Account-level webhooks registered via `sync_accounts.accounts[].notification_configs[]` carry `product.*` / `signal.*` / `wholesale_feed.bulk_change` change payloads with `applies_to.scope`; standard webhook signing and SSRF guards apply |
| **Creative formats** | Format-by-name with per-publisher variants | 12 canonical `format_kind` values + publisher catalog discovery (`adagents.json formats[]`) + `v1_format_ref` for dual emission + size flexibility (fixed / multi-size / responsive); creative agents advertise buildable outputs in `creative.supported_formats[]` and SHOULD include `capability_id` on targetable entries |
| **Hosted audio/video duration constraints** | Fixed durations or closed ranges only | `duration_ms_exact` for fixed slots; `duration_ms_range` for bounded and one-sided ranges such as `[null, 60000]` or `[15000, null]`; `[null, null]` is invalid |
| **Creative transformers** | `build_creative` built to a target format; render knobs implicit; format-attached `Format.input_format_ids` / `output_format_ids` / `pricing_options` | `list_transformers` discovers account-scoped build units (voices/models/styles) with an `expand_params` option-enumeration mode; `build_creative` selects one via `transformer_id`, takes a strictly-validated typed `config`, and fans out with `max_creatives` (per-catalog-item) + `max_variants`/`variant_axis` + advisory `keep_mode`; new `BuildCreativeVariantSuccess` member returns per-variant manifests, recommendation/`rank`, and per-leaf pricing receipts; rate lives on `transformer.pricing_options` (`per_unit`), settled via `report_usage`. The shipped `BuildCreativeSuccess` / `BuildCreativeMultiSuccess` are unchanged |
| **Version negotiation** | Integer `adcp_major_version` per request | Release-precision `adcp_version` (e.g. `"3.1"` for the stable release) + `adcp.supported_versions` advertisement + envelope echo. Integer field remains as backwards-compatible legacy |
| **Optimization goals** | `event` + `metric` kinds, vendor-agnostic | New `vendor_metric` kind — bind goals to vendor-attested metrics; `vendor_metric_optimization` per-product capability; three-precondition rejection rule |
| **Capability declarations** | Per-protocol basics | New: `media_buy.buying_modes` for wholesale products, `signals.discovery_modes` for wholesale signals, `wholesale_feed_versioning`, `wholesale_feed_webhooks`, `supported_optimization_metrics`, `supported_target_kinds`, `media_buy.frequency_capping`, `media_buy.propagation_surfaces`, `creative.bills_through_adcp`, `capabilities.idempotency.in_flight_max_seconds` |
| **Video and audio execution discovery** | Video and audio products relied on free-text descriptions, placement names, or overloaded channels | `video_placement_types` and `audio_distribution_types` on products, placements, and `get_products.filters` using AdCP-native names for OpenRTB `video.plcmt` and `audio.feed` values |
| **Currency-scoped discovery** | Buyers could filter budget currency but not the currencies they can transact in for media product pricing | `pricing_currencies` on `get_products.filters`; sellers match product-level `pricing_options`, prune returned product pricing options to requested currencies, and exclude products whose mandatory product-scoped signal charges are not satisfiable in those currencies |
| **Delivery reporting** | `reach` without window semantics; viewability is rate only | `reach_window` (cumulative / period / rolling); `viewability.viewed_seconds`; windowed pull recovery via `time_granularity` + `include_window_breakdown` |
| **Billing surface** | Authority via `billing_measurement`; no finality marker | Row-level `is_final` + `finalized_at` on delivery; `final` + `finalized_at` + `measurement_window` on `report_usage`; `creative.bills_through_adcp` capability + `BILLING_OUT_OF_BAND` error |
| **Action discovery** | No structured action vocabulary on buys/products | `allowed_actions[]` on Product (advisory template); `available_actions[]` on `get_media_buys` / `create_media_buy` / `update_media_buy`; proposal executability comes from `proposal_status`, not action-mode hacks |
| **Auth + security** | Single `AUTH_REQUIRED` error; no transport-channel rule | `AUTH_REQUIRED` split into `AUTH_MISSING` (correctable) + `AUTH_INVALID` (terminal); `CREDENTIAL_IN_ARGS` rejects credentials in request payload; request-signing `protocol_methods_*` namespace |
| **Idempotency** | Per-call replay only | Rule 9 (concurrent retries) + Rule 10 (downstream reconciliation); `IDEMPOTENCY_IN_FLIGHT` error code; `capabilities.idempotency.in_flight_max_seconds` |
| **Async envelope** | Two-shape submitted envelope for create-style tasks | Three-shape envelope extended to `sync_audiences` |
| **TMP IdentityMatch** | Basic request/response | `serve_window_sec` frequency-cap data flow; `seller_agent_url` required on request; optional `package_ids` |
| **`adagents.json`** | Authoritative-only discovery | Managed-network scale (20 MB cap + `publisher_domains[]` compact form); ads.txt `managerdomain` fallback; tightened `revoked_publisher_domains[]` semantics |
| **Schema housekeeping** | — | Named reusable schemas for SDK generators; `x-adcp-hoist` opt-in marker; `x-adcp-open-payload` marker for intentionally open JSON payload fields; open-string compliance scenarios; `allowed_values` on text-asset-requirements; `vast_tracker` + `daast_tracker` asset types; optional `currency`/`total_budget` on create/update responses |
| **Compliance suite** | Per-tool scenarios | Capability-gated scenarios for `frequency_cap_enforcement`, `per_creative_attribution`, `metric_mode`, ROAS, `audience_buy_flow`, `event_dedup_flow`, `performance_buy_flow`, and `product_signal_targeting`; storyboard `requires` runtime gate; `comply_test_controller` sandbox gate; version-scoped badge evidence; packaged-reference validation for public compliance bundles |
### Capability-slot migration note
When using SDK helpers such as `definePlatform`, keep unsupported capability slots absent from `get_adcp_capabilities`. A missing slot is an honest scope boundary: storyboards and local test vectors targeting that slot should grade `not_applicable`, not failed.
Current runners grade a path targeting an undeclared slot as `not_applicable`. A runner that dispatches that path and reports an implementation failure is not applying the capability declaration correctly.
## Headline features
### Distributed `brand.json` — sub-brands self-publish
A brand can now publish its **own** canonical `brand.json` on its own domain while the corporate house declares ownership via a portfolio pointer (`brand_refs[]`). The hierarchy stays one level deep — only houses declare ownership. Trust resolves via mutual assertion: both sides reciprocate. Identity attributes (logos, colors, tone, tagline) trust on the leaf's TLS alone; relationship trust (governance propagation, billable inclusion) gates on the reciprocal entry.
Same shape as IAB's `ads.txt` / `sellers.json` / `app-ads.txt` reciprocal-publication pattern, applied to brand identity. Plus: typed `trademarks[]` with optional `status`, `license_type`, `licensor_domain`, `countries`, `nice_classes` (cross-industry disambiguation). Compliance fields resolve strictest-of (brand-level can tighten, never weaken) while identity fields stay brand-wins.
→ Normative spec: [`brand.json` § Distributed publishing](/dist/docs/3.2.8/brand-protocol/brand-json#distributed-publishing) · PR [#4505](https://github.com/adcontextprotocol/adcp/pull/4505)
### `verify_brand_claim` / `verify_brand_claims` — federated brand verification
Two new brand-protocol tasks let partners ask a brand authoritatively whether a claim belongs to it: a brand agent published at the brand's own domain, queried by anyone who needs to verify trademark ownership, ad-creative claims, or asset rights. Federated by design — every brand agent answers for its own brand only. Reframes the email-based self-healing SHOULD from #4505 as a richer pull-based DRM-for-brand-identity surface.
RC4 locks the trust envelope: successful `verify_brand_claim` and `verify_brand_claims` responses require `signed_response`, a payload-envelope JWS over the canonical task-body response. The signature binds the answer to the designated task, resolved brand tenant, responding agent URL, caller/request hash, and `iat`/`exp` freshness window. Verifiers resolve the key with `adcp_use: "response-signing"` and reject any mismatch between the unsigned response fields and `signed_response.payload.response`.
→ Spec: [Brand Protocol § verify_brand_claim](/dist/docs/3.2.8/brand-protocol/tasks/verify_brand_claim) · [Security § Designated-task response signing](/dist/docs/3.2.8/building/by-layer/L1/security#designated-task-response-signing) · PRs [#4540](https://github.com/adcontextprotocol/adcp/pull/4540), [#4603](https://github.com/adcontextprotocol/adcp/pull/4603), [#5192](https://github.com/adcontextprotocol/adcp/pull/5192)
### Dependency-impact webhooks and snapshot coherence
When a resource a media buy depends on transitions to an offline state — an audience suspended, a creative suspended/rejected post-approval, a catalog item withdrawn, an event source quiet, a property depublished — buyers see it through two parallel surfaces:
* **Snapshot.** `media_buy.health` flips from `ok` to `impaired`; `media_buy.impairments[]` lists every offline resource with its package_ids, transition, reason_code, and remediation hint. The next `get_media_buys` read shows current truth.
* **Log.** `notification-type: impairment` webhooks fire with `notification_id = impairment_id` and the same payload shape, configured via `push_notification_config`.
Either path is complete; buyers reconcile via the snapshot when push and pull disagree. Sellers declare which surfaces they use via `capabilities.media_buy.propagation_surfaces` (`["snapshot"]`, `["webhook"]`, `["snapshot", "webhook"]`, or `["out_of_band"]`). The `impairment.coherence` compliance invariant grades the contract end-to-end (forward, inverse, and health-iff rules; relaxes on terminal-status buys).
→ Spec: [Media Buy Lifecycle § Health & impairments](/dist/docs/3.2.8/media-buy/media-buys/lifecycle#health-impairments) · [Snapshot and log contract](/dist/docs/3.2.8/protocol/snapshot-and-log) · RFC #2853 · PRs #4588, #4601, #4677, #4685, #4690
### Webhook foundation + buyer-side delivery visibility
3.1 codifies one persistent-channel contract for every push surface: snapshot is authoritative, push is at-least-once and unordered, dedupe via `idempotency_key`, correlate state via `notification_id` (now typed at the envelope level on `mcp-webhook-payload.json`), replay = re-read the snapshot. Future webhook RFCs reference the foundation instead of re-deriving it. The subscription model extends to per-account so creative-library-level events (creative state changes) fire even when no media buy directly references the creative.
For production debugging, buyers can opt-in to `webhook_activity[]` on `get_media_buys` — recent fires for the buys they see, with HTTP status, fire time, and `idempotency_key`. No more black-box "the publisher fired but my gateway returned 5xx and I can't see it." Pure self-service: buyers debug their own integration without operator round-trips.
→ Spec: [Snapshot and log contract](/dist/docs/3.2.8/protocol/snapshot-and-log) · [Webhooks § Persistent channel contract](/dist/docs/3.2.8/building/by-layer/L3/webhooks#persistent-channel-contract) · RFC #4582 · PRs #4601, #4701, #4730
### Wholesale feed mirroring — conditional fetch, wholesale signals, webhooks
Three companion proposals let consumers (storefronts, federated marketplaces, registries, agency brand stacks) maintain a near-real-time local mirror of every connected AdCP agent's buyable wholesale product feed and wholesale signals feed without burning bandwidth on per-poll wholesale fetches. Independent and complementary — agents MAY adopt any subset; consumers fall back to wholesale polling against agents that don't.
Terminology: this section uses **wholesale feed** for seller-side products and signals from `get_products` / `get_signals`. It is distinct from `sync_catalogs`, which uploads buyer-provided campaign input feeds to a seller account.
* **Conditional fetch (`if_wholesale_feed_version`).** Every `get_products` / `get_signals` response returns an opaque `wholesale_feed_version` token. Pass it back on the next call and the seller MAY short-circuit with `unchanged: true` — no product or signal payload, no per-page diff. ETag/HTTP semantics. Optional companion `pricing_version` for sellers that move rate cards independently of structural metadata; `if_pricing_version` requires `if_wholesale_feed_version` (schema-enforced via `dependencies`). Backward-compatible: pre-v3.1 agents that ignore the tokens just return full payloads.
* **Wholesale signals (`discovery_mode: "wholesale"`).** Callers can omit `signal_spec` / `signal_refs` / deprecated `signal_ids` and enumerate a signals agent's full priced signals feed, paginated. Symmetric with `get_products` `buying_mode: "wholesale"`, closing the gap that previously forced storefronts and marketplaces into hacky probe queries to mirror the signals feed.
* **Wholesale feed webhooks.** Account-level webhooks registered through `sync_accounts.accounts[].notification_configs[]` emit `product.{created,updated,priced,removed}`, `signal.{created,updated,priced,removed}`, and `wholesale_feed.bulk_change` notifications. Each webhook carries `core/wholesale-feed-webhook.json`: the actual changed product/signal payload or bulk-change summary, the post-change `wholesale_feed_version`, and `applies_to.scope` for cache invalidation. There is no polling event task; consumers repair missed or distrusted pushes through `get_products` / `get_signals`.
**Cache layering is the load-bearing design choice.** Every response declares `cache_scope: "public" | "account"` (schema-required — the safety property of the two-layer cache depends on it). When the request had no `account`, MUST be `"public"`. When the request had `account`, the seller declares `"public"` (this account prices off the rate card — buyer dedupes with the unauthenticated view) or `"account"` (custom overrides — buyer caches under the account key). Most accounts at most sellers price off the public layer, so a consumer holding N account caches typically dedupes into one public cache + a small number of overlays. Events carry `applies_to.scope` (with optional `account_ids[]`) so consumers invalidate the right cache layer — public events cascade to all overlays; account events touch only the named overlays. Sellers MAY downgrade an account from `"account"` back to `"public"` by returning a public-scope response on a previously-account-scoped tuple, signalling "this account no longer has overrides; drop the overlay."
**Security posture is honest.** The advisory-payload framing makes explicit that re-verifying a feed event against `get_products` / `get_signals` defends against transport tampering only — a compromised agent operator re-confirms its own lie. Operator-compromise defense lives in the existing trust anchors that gate spend (signed `create_media_buy` response, `adagents.json` pinned signing keys for marketplace-signal provenance), with content-signing of feed events deferred to the 4.0 R-1 root-of-trust track. Treat events as cheap mirror invalidation, not as the basis for any decision that commits dollars or authority.
Capability declarations: `wholesale_feed_versioning` (conditional fetch + `pricing_version_separate` + `cache_scope_account`), `wholesale_feed_webhooks` (webhook change payloads), `media_buy.buying_modes` and `signals.discovery_modes` (wholesale support). Agents that advertise `product.*` webhook events must also advertise wholesale `get_products`; agents that advertise `signal.*` events must also advertise wholesale `get_signals`; `wholesale_feed.bulk_change` must name only a feed family backed by one of those repair paths. JSON Schema for the webhook envelope at `core/wholesale-feed-webhook.json`, wrapping `core/wholesale-feed-event.json` (discriminated on event_type with 9 branches + `appliesTo` / `removalReason` `$defs`).
→ Spec: [Wholesale feed webhooks](https://github.com/adcontextprotocol/adcp/blob/main/specs/wholesale-feed-webhooks.md) · [`get_products` § Wholesale feed versioning](/dist/docs/3.2.8/media-buy/task-reference/get_products#wholesale-feed-versioning) · [`get_products` § Cache layering](/dist/docs/3.2.8/media-buy/task-reference/get_products#cache-layering) · [`get_signals` § Wholesale signals feed](/dist/docs/3.2.8/signals/tasks/get_signals#wholesale-signals-feed) · PRs [#4761](https://github.com/adcontextprotocol/adcp/pull/4761) (conditional fetch), [#4762](https://github.com/adcontextprotocol/adcp/pull/4762) (wholesale signals), [#4763](https://github.com/adcontextprotocol/adcp/pull/4763) (feed webhooks), [#4767](https://github.com/adcontextprotocol/adcp/pull/4767) (cluster implementation)
### Product-scoped signal targeting — included vs selectable signals
3.1 adds a product-scoped signal targeting contract for seller-offered signals on media buys. This closes the gap between broad signal discovery and the actual package-level buy surface:
* **`included_signals`** describes signals already bundled into, included in, or seller-planned into a product. These are descriptive product metadata, not buyer-selectable controls.
* **`data_provider_signals` is deprecated.** It remains for compatibility as legacy bundled metadata, but new implementations use `included_signals` for non-selectable signals and `signal_targeting_options` for selectable ones.
* **`signal_targeting_allowed`** tells buyers the product has a package-level `signal_targeting_groups` surface. The default is false.
* **`signal_targeting_options`** is the inline selectable menu when the product needs product-specific pricing, activation handles, defaults/fixed selections, grouping hints, or a brief/refine-selected subset. Wholesale products can omit this field and use `get_signals` as the selectable feed.
* **`signal_targeting_rules`** declares the product-specific composition contract: direct targeting vs seller-planned resolution, optional/required/fixed selection, min/max counts, and grouping limits. This belongs on the product because a single seller may route products through different ad servers or planning layers.
Buyers apply selected signals with `packages[].targeting_overlay.signal_targeting_groups`. The portable baseline is intentionally simple: top-level `operator: "all"` with child `operator: "any"` groups for includes and child `operator: "none"` groups for exclusions. For binary signals, the signal expression uses `value: true`; exclusion is represented by the parent `none` group, not by `value: false`.
Signal identity is also normalized. New payloads use `signal_ref`:
* `scope: "data_provider"` + `data_provider_domain` + `signal_id` for signals defined in a provider's published adagents.json signals.
* `scope: "signal_source"` + `signal_source_url` + `signal_id` for source-native signals not published in upstream adagents.json signals.
* `scope: "product"` + `signal_id` for product-local options meaningful only inside the selected product/package context.
Legacy `SignalId` / `signal_id.source` remains accepted during the minor-version migration window, including on `get_signals`, audience selectors, legacy flat signal targeting, and wholesale signal events, but `SignalRef` is the canonical shape for new clients. Legacy flat `targeting_overlay.signal_targeting` remains schema-valid but deprecated; new package-level composition uses `signal_targeting_groups`.
→ Spec: [Product discovery § Signal targeting](/dist/docs/3.2.8/media-buy/product-discovery/media-products#signal-targeting) · [Targeting § signal_targeting_groups](/dist/docs/3.2.8/media-buy/advanced-topics/targeting#signal_targeting_groups) · [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) · PR [#5009](https://github.com/adcontextprotocol/adcp/pull/5009)
### Canonical creative formats — live, 12 canonicals, backwards-compatible
* **Published-post reference creatives.** Existing social/publisher posts are represented as canonical `video_hosted`, `image`, or `native_in_feed` formats with `asset_source: "publisher_owned_reference"` and a `published_post` slot. Products can declare `required_connections[]` for downstream platform grants such as advertiser account and publisher identity connections. Missing or expired grants use `AUTHORIZATION_REQUIRED` with `error.details.missing_connections[]`; recoverable dependency loss moves creatives to `suspended` rather than policy rejection. Catalog-driven retail media remains `sponsored_placement` with `source_catalog`.
Live in 3.1, additive over 3.0. Products carry `format_options[]`: a list of `ProductFormatDeclaration` entries with a `format_kind` discriminator from the canonical enum. **12 canonicals:** `image`, `html5`, `display_tag`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_daast`, `image_carousel`, `native_in_feed`, `responsive_creative`, `sponsored_placement`, `agent_placement`. The enum also includes `custom` as the escape hatch for adopter-defined shapes that do not fit the canonicals. Three canonicals (`sponsored_placement`, `responsive_creative`, `agent_placement`) plus `custom` are tagged **experimental** within the framework; the remaining canonicals are non-experimental. The promotion queue for new canonicals is tracked in [#3666](https://github.com/adcontextprotocol/adcp/issues/3666).
**Backwards compatibility.** The `format_ids` path remains supported in 3.1, is deprecated beginning in AdCP 3.2, and is removed in AdCP 4.0. `ProductFormatDeclaration` carries an optional `v1_format_ref: [{agent_url, id}]` array so canonical declarations link to one or more named formats — sellers can dual-emit during the 3.x migration window. SDKs treat the enum as **open at parse time**: unknown future canonicals don't fail validation; SDKs may surface a local routing status such as `declared_only`, but that status is not a 3.1 wire field.
**Publisher catalogs.** `list_creative_formats(publisher_domain="…")` returns the publisher's authoritative format list by reading `/.well-known/adagents.json formats[]`, falling back to the AAO community mirror, then to agent-derived. Response carries `source: "publisher" | "aao_mirror" | "agent_derived"` so buyers know which tier produced the list.
**Size flexibility.** Display canonicals declare size in three modes: fixed (`width`+`height`), multi-size (`sizes: [{w,h}]` — mirrors OpenRTB `banner.format[]`), or responsive (`min_width`/`max_width`/`min_height`/`max_height`). Mutually exclusive.
**Hosted audio/video duration ranges.** `audio_hosted` and `video_hosted` use `duration_ms_exact` for fixed-duration slots and `duration_ms_range` for bounded or one-sided ranges. Either endpoint of `duration_ms_range` MAY be `null`: `[null, 60000]` means "up to 60 seconds" and `[15000, null]` means "at least 15 seconds". `[null, null]` is invalid, and `duration_ms_exact` takes precedence if both duration fields are present.
→ Spec: [Canonical formats](/dist/docs/3.2.8/creative/canonical-formats) · PRs [#3307](https://github.com/adcontextprotocol/adcp/pull/3307), [#4770](https://github.com/adcontextprotocol/adcp/pull/4770), [#5323](https://github.com/adcontextprotocol/adcp/pull/5323)
### Creative transformers — discover build capability, select, fan out, variant
3.1 introduces **transformers**: the creative analog of media-buy products. A transformer is an agent-offered, account-scoped, selectable unit of build capability — a voice, a model, a style, a director — with a typed configuration surface and per-account pricing. The set is account-specific and dynamic (your configured voices aren't a global enum), so discovery flows agent → buyer the same way `get_products` surfaces account-scoped inventory.
* **`list_transformers`** is the new discovery surface. It returns the transformers a creative agent offers for your account, each with `input_format_ids` / `output_format_ids`, a typed param schema, and (with `include_pricing`) a `per_unit` rate card. Its `expand_params` mode returns the account-scoped enumerable option values for a param — your actual configured voices, for example — on the same tool, instead of forcing you to hold a stale local list. Offered only by agents that set `creative.supports_transformers: true` in `get_adcp_capabilities`.
* **`build_creative` selects and configures a transformer.** Pass `transformer_id` to pick one — the target format(s) MUST be a subset of its `output_format_ids` — and a typed `config` bag keyed to the transformer's params. Validation is strict: the agent MUST reject unknown keys and out-of-range values with field-attributed errors; vendor-specific knobs go in `ext`.
* **Two fan-out axes.** `max_creatives` is the item/catalog axis: N distinct creatives, one per catalog item ("5 of 150" sampling) — distinct from `item_limit`, which caps the items used *within* one creative. `max_variants` (default 1) produces alternatives per creative along a `variant_axis` (`voice` | `theme` | `best_of_n` | `transformer_config` | `custom`, with optional `values[]` and `label`). `keep_mode` (`keep_all` | `keep_one` | `keep_some`) is advisory. Resolutions and quality levels are the **format** axis (`target_format_ids`), not variants.
* **New `BuildCreativeVariantSuccess` response member** (`oneOf` member 3 of 6) carries `creatives[]`, each `{ build_creative_id, catalog_item_ref?, variants[] }`; each variant is `{ build_variant_id, creative_manifest, variant_axis_value?, recommended, rank?, ... }` with a per-leaf pricing receipt (`pricing_option_id` + `vendor_cost` + `currency` + `consumption`). When the build reports cost (the aggregate `vendor_cost` is present), every produced leaf carries its own `vendor_cost` + `currency` (schema-enforced). Top-level `items_total` / `items_returned` plus an aggregate `vendor_cost`. The shipped `BuildCreativeSuccess` / `BuildCreativeMultiSuccess` are **unchanged**.
* **Best-of-N is variants + `keep_mode` + `recommended`/`rank`.** `build_variant_id` is its own namespace — never reuse `preview_id` (preview renders) or served `variant_id` (delivery). You **pay for all produced variants** (`per_unit` × N); keeping is a client act of trafficking the chosen `build_variant_id`(s). A kept variant lazily earns a `creative_id` (added to the library / first trafficked) which flows to `report_usage`. Per-**format** generation is atomic; per-**item** (catalog fan-out) is non-atomic.
* **Evaluator ranking reuses creative-feature discovery.** Agents with `creative.supports_evaluator: true` use the existing `get_adcp_capabilities.governance.creative_features` catalog as the evaluator feature-discovery surface. `rank_by`, `feature_requirement`, and `variants[].eval.features[]` all refer to that same feature vocabulary; `evaluator_id` is a pre-provisioned account preset, not an ID from that catalog. `feature_agent.agent_url` selects an allowlisted external scoring path and `feature_id` disambiguates the requested feature subject to the seller's accepted-verifier entry. Sellers SHOULD echo external judge usage per leaf with fields such as `eval.calls_used` / `eval.seconds_used` when `agent_url` evaluation runs under an `eval_budget`.
* **Pricing moves onto the transformer.** The rate lives on `transformer.pricing_options` (`per_unit`), echoed inline as a per-leaf receipt on `build_creative`, and settled via `report_usage`. `Format.pricing_options` is **deprecated** in favor of `transformer.pricing_options`.
> [!WARNING]
>
> **Deprecations (3.1, removed in 4.0).** `Format.input_format_ids`, `Format.output_format_ids`, and `Format.pricing_options`, plus the `input_format_ids` / `output_format_ids` filters on `list_creative_formats`, are deprecated and all redirect to `list_transformers`. SDKs honor them through 3.1–3.x; they are removed at 4.0. Migrate format-attached input/output/pricing reads to `list_transformers`. Full migration (incl. the discovery-degradation, per-output-pricing, and best-of-N spend hazards): [Migration › Creative transformers](/dist/docs/3.2.8/reference/migration/creative-transformers).
→ Spec: [`list_transformers`](/dist/docs/3.2.8/creative/task-reference/list_transformers) · [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) · [`get_adcp_capabilities` § creative features / evaluator support](/dist/docs/3.2.8/protocol/get_adcp_capabilities)
### Release-precision version negotiation — pin your release
Every request and response now carries `adcp_version` (release-precision: `"3.1"` for the stable release); sellers advertise their full `supported_versions` set on `get_adcp_capabilities` and echo the release they actually served at the envelope root. SDKs pin via a constructor option (`adcpVersion: "3.1"` JS, `adcp_version="3.1"` Python, `WithAdcpVersion("3.1")` Go) and emit both the new string and the integer `adcp_major_version` mirror for compatibility with sellers that only read the legacy field. The integer remains functional through all of 3.x — additive ship, no required changes for 3.0-conformant agents. `VERSION_UNSUPPORTED` is typed with `error.data.supported_versions[]` echoed so retry doesn't require an out-of-band lookup.
→ Spec: [Versioning § Version negotiation](/dist/docs/3.2.8/reference/versioning#version-negotiation) · PR [#3493](https://github.com/adcontextprotocol/adcp/pull/3493)
### Vendor-attested measurement — `vendor_metric` goals + per-product capabilities
Optimization goals now support a third `kind: "vendor_metric"` shape — bind goals to vendor-attested metrics like attention (DV, IAS, Adelaide, TVision, Lumen), panel-based brand lift (Kantar, Upwave, Cint), emissions (Scope3, Good-Loop), and retail-media partner metrics. Closes the gap where 3.0's vendor-agnostic enum values like `attention_seconds` were meaningless without a vendor binding.
Sellers declare per-product `vendor_metric_optimization` with `supported_metrics[]` (the `(vendor, metric_id)` pairs the bidding stack can steer toward). A three-precondition rejection rule on goal acceptance — discovery, capability, reporting coherence — ensures the goal is steerable AND reportable end-to-end. Plus seller-level `supported_optimization_metrics` and `supported_target_kinds` on `conversion_tracking` for capability-gated compliance scenarios.
The measurement-vendor catalog that defines `measurement.metrics[]` is experimental in 3.1. Vendors implementing it must declare `measurement.core` in `experimental_features`; buyers should treat catalog discovery as a 3.x experimental surface until measurement tasks and compliance storyboards are frozen.
→ Spec: [Optimization goals § `vendor_metric` kind](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting#vendor-metric-goals) · PRs [#4668](https://github.com/adcontextprotocol/adcp/pull/4668), [#4669](https://github.com/adcontextprotocol/adcp/pull/4669), [#4649](https://github.com/adcontextprotocol/adcp/pull/4649)
### Delivery reporting — `reach_window`, `viewed_seconds`, windowed pulls
Three additive surfaces close reporting gaps. **`reach_window`** declares the measurement window for `reach` and `frequency` (cumulative / period / rolling) — buyers MUST NOT sum reach across rows without it. **`viewability.viewed_seconds`** reports average in-view duration per measurable impression, the reporting-side counterpart to the `viewed_seconds` optimization goal. **Windowed pull recovery** on `get_media_buy_delivery` accepts `time_granularity` + `include_window_breakdown: true`, returning `windows[]` slices shape-aligned with `reporting_webhook` payloads at the same granularity — a buyer who missed a webhook fire reconstructs identical data by polling. Capability-scoped via `reporting_capabilities.windowed_pull_granularities`; sellers can honestly declare asymmetric webhook-vs-pull frequencies.
→ Spec: [Delivery metrics reference](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) · PRs [#4618](https://github.com/adcontextprotocol/adcp/pull/4618), [#4601](https://github.com/adcontextprotocol/adcp/pull/4601)
### Billing surface — authority, finality, and out-of-band
Two complementary changes close the billing-grade reporting story. **Authority + finality flags:** `get_media_buy_delivery` responses now carry row-level `is_final` + `finalized_at` on `media_buy_deliveries[*]` and on each `by_package[*]` — buyers know when a number stops moving and is safe for invoice reconciliation. Symmetric on `report_usage`: each usage record carries `final` (default `true`), `finalized_at`, and `measurement_window`. **`bills_through_adcp` + `BILLING_OUT_OF_BAND`:** creative agents declare via `capabilities.creative.bills_through_adcp` whether they bill on-protocol or out-of-band (flat license, SaaS, bundled enterprise — CM360 is the canonical case). Buyers pre-filter; sellers in out-of-band mode reject `report_usage` calls with the new `BILLING_OUT_OF_BAND` error rather than silently accepting.
→ Spec: [Billing measurement](/dist/docs/3.2.8/media-buy/advanced-topics/accountability#billing-measurement) · [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) · PRs [#4735](https://github.com/adcontextprotocol/adcp/pull/4735), [#4561](https://github.com/adcontextprotocol/adcp/pull/4561)
### Action discovery — `allowed_actions` and `available_actions`
Structured action vocabulary for buy lifecycle mutations. Products advertise `allowed_actions[]` as an advisory template (which mutations the product *generally* supports, with `modes[]` and `allowed_statuses[]`). Media buys carry `available_actions[]` on `get_media_buys` / `create_media_buy` / `update_media_buy` responses — the current set of valid mutations for *this* buy in its current state. Buyers pre-flight which mutations are valid instead of issuing a call and getting `INVALID_STATE`. Finer-grained values added to `media-buy-valid-action` enum; legacy coarse values retained through 3.x for backwards compat (removed in 4.0).
3.1 removes the pre-GA `requires_proposal` action mode. Proposal lifecycle now has one path: `proposal_status` says whether finalization is required; `finalize` is seller commitment to firm pricing/terms/hold; `create_media_buy(proposal_id)` is buyer acceptance/execution. If an `update_media_buy` request exceeds the current quoted envelope, sellers return `REQUOTE_REQUIRED` instead of modeling a proposal-required action mode. Buyers with cached prerelease action metadata containing `requires_proposal` must discard it and re-read the current product or buy action surface. 3.1 does not define an amendment-quote artifact for updates.
→ Spec: [Media Buy Lifecycle § Action discovery](/dist/docs/3.2.8/media-buy/media-buys/lifecycle#action-discovery) · [Product discovery § Proposals](/dist/docs/3.2.8/media-buy/product-discovery/media-products#proposals) · PR [#4514](https://github.com/adcontextprotocol/adcp/pull/4514)
### Auth + security tightening
Four complementary changes: **`AUTH_REQUIRED` split** into `AUTH_MISSING` (correctable — retry with credentials) and `AUTH_INVALID` (terminal — credentials presented and rejected; rotate or escalate; do NOT auto-retry). Recovery classifications now match operator reality. **`CREDENTIAL_IN_ARGS`** new error code: sellers MUST reject requests that smuggle buyer-principal credentials into the task payload instead of the transport authentication channel — closes a prompt-injection exfiltration surface. **Request-signing `protocol_methods_*` namespace** — RFC 9421 signing scope tightened to the AdCP method surface only. **`comply_test_controller` sandbox gate** — every controller call MUST carry `account.sandbox: true` and the seller MUST verify against its persisted account record, not trust the field. Defense-in-depth boundary between sandbox and production.
→ Spec: [Error handling § Recovery Classification](/dist/docs/3.2.8/building/by-layer/L3/error-handling#recovery-classification) · PRs [#3739](https://github.com/adcontextprotocol/adcp/pull/3739), [#4057](https://github.com/adcontextprotocol/adcp/pull/4057), [#4326](https://github.com/adcontextprotocol/adcp/pull/4326), [#4382](https://github.com/adcontextprotocol/adcp/pull/4382)/[#4392](https://github.com/adcontextprotocol/adcp/pull/4392)
### Idempotency — Rules 9 + 10 + `IDEMPOTENCY_IN_FLIGHT`
Two new rules close production-edge cases. **Rule 9 (concurrent retries):** when a buyer retries before the original call has produced a cached response, the seller MAY return `IDEMPOTENCY_IN_FLIGHT` (new error code) instead of blocking — useful when the first call invokes a slow downstream system (SSP, ad server, payment provider). Buyers MUST treat it as transient and MUST NOT mint a fresh `idempotency_key`. **Rule 10 (downstream reconciliation):** explicit guidance on how buyers reconcile when an `IDEMPOTENCY_EXPIRED` response arrives and they have evidence the original succeeded — perform a natural-key check (e.g., `get_media_buys` by `context.internal_campaign_id`) before generating a fresh key. **`capabilities.idempotency.in_flight_max_seconds`** new capability — seller declares how long an in-flight call can take so buyers tune retry pacing.
→ Spec: [Calling an agent § Idempotency](/dist/docs/3.2.8/protocol/calling-an-agent) · PRs [#4402](https://github.com/adcontextprotocol/adcp/pull/4402), [#4409](https://github.com/adcontextprotocol/adcp/pull/4409)
### TMP IdentityMatch upgrades
Three additive changes: **`serve_window_sec`** new required field on responses (1–300 seconds) — router caches the eligibility decision for this many seconds before re-querying. Replaces the prior `ttl_sec` framing with frequency-cap-data-flow-aware semantics. **`seller_agent_url`** now required on requests so the router can route the decision back to the originating seller. **`package_ids`** moved from required to optional — routers can ask "is this user eligible at all?" without enumerating packages.
→ Spec: [TMP IdentityMatch implementation](/dist/docs/3.2.8/trusted-match/identity-match-implementation) · PRs [#4070](https://github.com/adcontextprotocol/adcp/pull/4070), [#3687](https://github.com/adcontextprotocol/adcp/pull/3687)
### `adagents.json` — managed-network scale, manager-domain fallback, revocation semantics
Three production-scale improvements. **Managed-network scale:** authoritative `adagents.json` now caps at 20 MB; managers publishing large agent networks switch to a compact `publisher_domains[]` form that lists owned domains without inlining every property. **Manager-domain fallback:** when a publisher's authoritative `adagents.json` is absent, crawlers fall back to the `managerdomain` declared in `ads.txt` — closes the discovery gap for S3 / CloudFront-hosted publishers that can't return a 404 directly. **Revocation semantics:** `revoked_publisher_domains[]` is now strictly time-bound — revocation is a published fact with a discoverable timestamp, not a silent removal. Tightens trust propagation across the managed network.
→ Spec: [`adagents.json` reference](/dist/docs/3.2.8/governance/property/adagents) · PRs [#4504](https://github.com/adcontextprotocol/adcp/pull/4504), [#4173](https://github.com/adcontextprotocol/adcp/pull/4173), [#4536](https://github.com/adcontextprotocol/adcp/pull/4536)
### Compliance suite — capability-gated scenarios
Capability-gated storyboard scenarios let sellers run *only* what they claim. New scenarios for `frequency_cap_enforcement`, `per_creative_attribution`, `metric_mode` + ROAS (using a `contains:` matcher), `audience_buy_flow`, `event_dedup_flow`, and `performance_buy_flow` (capability-gated CPA buys). Plus a new `requires` runtime gate on Storyboards that conditions execution on declared capabilities — no more all-or-nothing scenarios. The full set is enumerated on the [Compliance catalog](/dist/docs/3.2.8/building/verification/compliance-catalog).
**Late pre-GA compliance update:** money-moving seller specialisms now exercise baseline `sync_governance` registration before spend-committing flows: `sales-guaranteed`, `sales-non-guaranteed`, `sales-broadcast-tv`, `sales-catalog-driven`, `sales-social`, and the generative seller flow under `creative-generative`. This does not make every seller governance-aware; `governance-aware-seller` remains the opt-in claim for `check_governance` consultation and propagation. Existing pre-GA sellers claiming these specialisms must implement `sync_governance` registration and reject payloads with more than one `governance_agents` entry to remain conformant in 3.1 grading.
**Compliance packaging closure:** packaged compliance artifacts are now self-contained. Webhook receiver envelope vectors live under the versioned compliance tree, and release validation fails when authored vector/test-kit references do not resolve inside the packaged `/compliance/{version}/` bundle or protocol tarball. Signal conformance is also split by obligation: `signal-owned` and the baseline signals protocol are discovery-only (`get_signals`), while `signal-marketplace` requires `activate_signal`.
→ Spec: [Compliance catalog](/dist/docs/3.2.8/building/verification/compliance-catalog) · PRs [#4312](https://github.com/adcontextprotocol/adcp/pull/4312), [#4642](https://github.com/adcontextprotocol/adcp/pull/4642), [#4664](https://github.com/adcontextprotocol/adcp/pull/4664), [#4722](https://github.com/adcontextprotocol/adcp/pull/4722), [#4727](https://github.com/adcontextprotocol/adcp/pull/4727), [#4731](https://github.com/adcontextprotocol/adcp/pull/4731), [#5187](https://github.com/adcontextprotocol/adcp/pull/5187)
### Final-spec clarifications (WG-review batch)
Normative tightenings landed as the spec settled through prerelease validation. Mostly low-risk — adopters who'd already inferred reasonable defaults will continue working — but worth knowing about because the 3.1 grader checks them.
* **`PROPOSAL_NOT_FOUND` error code** (#4043). Completes the proposal-lifecycle error catalog (alongside `PROPOSAL_EXPIRED` and `PROPOSAL_NOT_COMMITTED`). Sellers MUST return it when a referenced `proposal_id` isn't recognized — wrong tenant, evicted from cache, or never finalized. Recovery: correctable.
* **Forward-compatible `error.code` decoding** (#4227). Receivers MUST treat `error.code` as an **open enum** — decode unknown codes without rejecting, classify recovery from `error.recovery`, default to `transient` when an unknown code omits recovery, and keep that fallback bounded. AdCP 3.1 senders SHOULD populate `error.recovery` on every error; 3.2 makes it a producer MUST. Unblocks additive-in-patch for error codes on future maintenance lines without breaking pinned-version receivers.
* **`get_products` key tolerance** (#4399). Closes a wrapper gap where optional envelope fields were rejected before a nominal read tool could run. Sellers MUST accept keyed calls. AdCP 3.2 makes the read/mutation boundary explicit: a guaranteed side-effect-free synchronous arm may ignore the key. Buyers SHOULD supply a key whenever the request may create a task or change observable state, and sellers declaring `adcp.idempotency.supported: true` MUST apply replay before the effect. Legacy `get_products` keeps the field optional throughout 3.x.
* **MCP tool wrappers MUST tolerate envelope fields** (#4399). The protocol envelope (`status`, `context_id`, `context`, `task_id`, `timestamp`, `replayed`, `adcp_error`, `governance_context`, `idempotency_key`) on MCP requests now goes through the wrapper layer instead of being rejected as "unexpected fields." Closes a wrapper-layer bug where adopters had to omit envelope fields to call MCP successfully.
* **MCP serialization normalization** (#2911). Drops `payload.required` from the protocol-envelope schema; adds the `context` field at envelope level; clarifies the flat-sibling MCP wire shape (envelope and body fields at the root, no nested `payload:` key). Adopters who'd implemented the de-facto flat shape are unaffected.
* **Idempotency replay returns historical snapshot** (#4371). When a buyer retries a stateful create call (e.g., `create_media_buy`) within the replay window, the seller MUST return the **historical snapshot** of state-tracking fields (`status`, `confirmed_at`, etc.) — not the current state. Otherwise an at-most-once retry mutates the response from underneath the buyer.
* **`refine[]` finalize-exclusivity + multi-finalize atomicity** (#4107). `get_products` `refine[]` semantics tightened: when any entry uses `action: "finalize"`, every entry in the array MUST be proposal-scoped with `action: "finalize"`; sellers reject mixes of finalize and non-finalize refinement with `INVALID_REQUEST`. Multi-finalize across multiple proposals is allowed only when the seller can guarantee atomic commit across every named proposal. Sellers that cannot guarantee that atomicity MUST reject the multi-finalize array with `MULTI_FINALIZE_UNSUPPORTED` (preferred) or `INVALID_REQUEST`, and buyers can then sequence single-proposal finalize calls if they accept the looser commit guarantee.
* **`pending_creatives` status disambiguation** (#4196). The description now explicitly states buyer action is required — sellers awaiting creative sync MUST surface what's missing (creative count, deadline) in the response message rather than just emitting the status enum value. Clarifies adopter-facing UX without changing the wire shape.
* **`notices` advisory channel on runner-output-contract** (#4418). Storyboard runners surface non-failure advisories (e.g., "agent still advertises a deprecated specialism, but the storyboard passed") through a structured `notices[]` field on the run output. Replaces ad-hoc `skip.detail` prose carrying advisory text — unparseable for graders and dashboards.
* **Governance body-level `status` renamed** (#4897). `check_governance` response: `status` → `verdict` (enum unchanged: `approved` / `denied` / `conditions`). `report_plan_outcome` response: `status` → `outcome_state` (enum unchanged: `accepted` / `findings`). `get_plan_audit_logs` entries cascade: `entries[].status` → `entries[].verdict` for consistency. Frees the top-level `status` key for the envelope task-status under MCP flat-on-the-wire serialization (#4876, #2911). Migration: rename the property in every emitter and consumer of these three response shapes; values do not change. Governance is an experimental surface per `x-status`, so this is a sanctioned 3.1 wire-shape adjustment ahead of GA.
* **Media-buy body-level `status` collision — additive-deprecate** (#4895). `create_media_buy` and `update_media_buy` success responses gain a new top-level `media_buy_status` field. The legacy top-level `status: MediaBuyStatus` form is marked `deprecated: true` and removed in **3.2** (#4906); compliance storyboards already require the new field. Nested `status` on `get-media-buys-response`, `get-media-buy-delivery-response`, and `core/media-buy.json` are out of scope here and addressed in the **4.0** cascade (#4905). Full migration: [Migration › `media_buy_status`](/dist/docs/3.2.8/reference/migration/media-buy-status).
* **Proposal lifecycle, signal privacy metadata, and measurement locks.** `proposal_status` is the per-proposal source of truth, `supports_proposals` is a conformance grading declaration, `finalize` is seller commitment, and `create_media_buy(proposal_id)` is buyer execution. The pre-GA `requires_proposal` action mode is removed in favor of `REQUOTE_REQUIRED` for updates outside the quoted envelope; buyers with cached prerelease action metadata containing `requires_proposal` must invalidate it and re-read the relevant product or buy surface. Signal definitions do not declare Global Privacy Control support, and projected `consent_basis` / `art9_basis` values on `get_signals` rows remain provider-declared signal-definition posture. The measurement catalog remains experimental and agents implementing it declare `measurement.core` in `experimental_features`.
→ Full batch shipped as one commit: PR [#4796](https://github.com/adcontextprotocol/adcp/pull/4796) (`4c124545f1`). See per-issue links for the full prose.
### Misc schema additions
**`media_buy.frequency_capping` capability declaration** (#4670) — seller declares which frequency-cap surfaces it honors.
**SDK generation ergonomics** (#5168) — common inline object and array item shapes now have stable core schema names so SDKs do not invent local wrapper names. `x-adcp-open-payload` marks intentionally open JSON payload fields for generators that need to preserve open maps rather than collapsing them into closed typed models.
**Open compliance scenario strings** (#5168) — `comply_test_controller.scenario`, `list_scenarios.scenarios[]`, and `compliance_testing.scenarios[]` are `string` rather than a closed enum; SDKs SHOULD parse them as strings and MAY layer known-value helpers locally. SDKs that previously generated a literal union for these fields should widen to `string` and keep default handling for unknown scenario names.
**`x-adcp-hoist` opt-in marker** (#4630) — canonically-shared object schemas declare themselves as hoistable into shared types. **`allowed_values` on text-asset-requirements** (#4333) — closed-set text assets (CTA, etc.) declare the allowed values so buyers can constrain generation. **`vast_tracker` + `daast_tracker` asset types** (#3051) — video and audio tracker assets. **Optional `currency` + `total_budget`** on `create_media_buy` / `update_media_buy` success responses (#4417). **Async envelope to `sync_audiences`** (#4571) — three-shape submitted envelope (Success / Error / Submitted) extended from create-style tasks.
→ See [Release Notes § Version 3.1.0](/dist/docs/3.2.8/reference/release-notes#version-3-1-0) for the per-PR detail.
## Adopter action
| If you are… | What you need to do |
| - | - |
| A 3.0-conformant production agent | Nothing required to remain on 3.0 — 3.1 changes are additive and a 3.0 client keeps working. When you are ready to claim 3.1, bump your SDK pin to `"3.1"` to pick up the new fields and emit `adcp_version` for forward-compatibility with future minors. |
| A buyer running production campaigns | Bump your SDK and pass `adcpVersion: "3.1"` on construction after the seller advertises `"3.1"` in `supported_versions`. Implement `webhook_activity[]` reads when you suspect a missed fire. Read `media_buy.health` + `impairments[]` on every `get_media_buys` poll. Implement the `impairment.coherence` invariant in your reconciliation pipeline. |
| A seller running production buys | Surface `media_buy.health` + `impairments[]` whenever a referenced resource transitions offline. Declare `capabilities.media_buy.propagation_surfaces` honestly. Implement `webhook_activity[]` so buyers can debug their integration end-to-end without operator round-trips — buyer self-service is integration-friction reduction, not seller charity. Mark `is_final` on every delivery row so buyers know when to reconcile. |
| A seller claiming money-moving specialisms | Implement `sync_governance` on the account surface, register one governance agent per account using the brand/operator account reference, and reject registrations with multiple `governance_agents` entries. `check_governance` calls are still only required when also claiming `governance-aware-seller`. |
| A brand agent implementing `verify_brand_claim` or `verify_brand_claims` | Return `signed_response` on every success response. Publish a per-brand `adcp_use: "response-signing"` JWK, keep unsigned response fields byte-equivalent to `signed_response.payload.response`, and retain bulk audit evidence with the original request and result index. |
| A seller using proposals or action discovery | Route proposal execution from `proposal_status`, not `supports_proposals` or action modes. Do not emit `requires_proposal`; use `REQUOTE_REQUIRED` when an update exceeds the quoted envelope and the buyer must rediscover terms or create a separate buy. |
| A buyer with cached prerelease `action_mode: "requires_proposal"` values | Treat the cached value as unknown. Do not map it to `requires_approval`; that mode is an asynchronous human-approval gate and has no proposal artifact. If the cached value was used for proposal executability, re-read the proposal through `get_products` and branch on `Proposal.proposal_status`: `draft` means finalize first, `committed` is ready for `create_media_buy(proposal_id)`. If it came from product `allowed_actions[]` or buy `available_actions[]`, invalidate that cached action metadata and re-read the current product or buy action surface. |
| A prerelease 3.1 signals adopter that previously saw `data_subject_rights.gpc_honored` | Remove the field from signal-level rights routing. 3.1 does not declare Global Privacy Control support on signal definitions; GPC remains a serve-time publisher/bidstream concern. Use provider policy, registry disclosures, and CCPA/state-law opt-out routing such as `ccpa_opt_out_url` for implementation guidance, but do not infer GPC handling from `data_subject_rights`. |
| A sub-brand team that wants self-publish authority | Stand up `/.well-known/brand.json` at your own domain as a Brand Canonical Document. Declare `house_domain: ""`. Ask the parent house team to reciprocate via `brand_refs[]`. |
| A consumer maintaining a wholesale product feed and wholesale signals feed mirror (storefront, federated marketplace, registry) | Bootstrap via `get_products buying_mode: "wholesale"` and/or `get_signals discovery_mode: "wholesale"`; persist the returned `wholesale_feed_version` + `cache_scope`. On subsequent polls send `if_wholesale_feed_version` and skip the full payload when the seller responds `unchanged: true`. If the agent declares `wholesale_feed_webhooks.supported`, register change webhooks through `sync_accounts.accounts[].notification_configs[]`; apply the webhook payload to the mirror and track `applies_to.scope` to invalidate the right cache layer (public vs. account overlay). Handle `wholesale_feed.bulk_change` or missed pushes by re-reading `get_products` / `get_signals`. |
| A signals agent | Declare `signals.discovery_modes: ["brief", "wholesale"]` to expose your full priced signals feed for mirroring. Return `cache_scope` on every response (REQUIRED — schema-enforced). Pre-3.1 callers without `discovery_mode` continue to get brief-mode behavior. If you only claim `signal-owned`, `get_signals` discovery is enough; claim `signal-marketplace` only when you also implement `activate_signal`. |
| A sales / signals agent serving wholesale feed mirrors at scale | Declare `wholesale_feed_webhooks.supported: true` and support webhook registration through `sync_accounts.accounts[].notification_configs[]`, with standard account-level webhook signing, endpoint proof-of-control before activation, SSRF guards, account/caller authorization checks, and the notification-config fan-out cap. Keep `event_types[]` consistent with declared repair reads: `product.*` requires wholesale `get_products`, `signal.*` requires wholesale `get_signals`. The webhook emitter MUST include the actual changed product/signal payload or bulk-change summary and apply the same per-caller scope filter as your wholesale task at event-emission time — multi-tenant agents that can't reliably scope events per-principal MUST NOT declare the capability. |
| A measurement vendor (attention, brand lift, emissions, retail) | Publish your experimental `measurement.metrics[]` catalog at your AdCP agent and declare `experimental_features: ["measurement.core"]`. Sellers declaring `vendor_metric_optimization` per product can now bind optimization goals to your `(vendor, metric_id)` pairs. |
| A creative agent | Declare `capabilities.creative.bills_through_adcp` honestly. If you bill out of band, reject `report_usage` calls with `BILLING_OUT_OF_BAND` rather than silently accepting. |
| A creative agent offering transformers | Declare `creative.supports_transformers: true` and serve `list_transformers` (including the `expand_params` option-enumeration mode). On `build_creative`, validate the typed `config` strictly — reject unknown keys and out-of-range values with field-attributed errors, route vendor knobs through `ext`, and verify each target format is a subset of the transformer's `output_format_ids`. Return `BuildCreativeVariantSuccess` with per-leaf pricing receipts when fanning out across catalog items or variants. Move rate cards from `Format.pricing_options` to `transformer.pricing_options` and settle through `report_usage`. |
| A seller or creative agent declaring hosted audio/video formats | Use `duration_ms_exact` for fixed-duration slots and `duration_ms_range` for bounded or one-sided ranges. `[null, 60000]` means "up to 60 seconds"; `[15000, null]` means "at least 15 seconds"; `[null, null]` is invalid. Do not add separate bare min/max duration fields. |
| Maintaining SDK fixtures, compliance mirrors, or release packaging | Keep compliance vector and test-kit references inside the packaged `/compliance/{version}/` tree. Treat missing bundle-relative references as release blockers. |
| An SDK author | Pin `published_version` to the published 3.1 artifact you bundle; emit `adcp_version` (release-precision string) plus `adcp_major_version` (integer mirror); normalize semver values to release-precision before wire emission (`"3.1.0"` → `"3.1"`); surface `VERSION_UNSUPPORTED` as a typed error rather than auto-downshifting. |
## Migration
**Bottom line: no breaking changes; additive only; you should bump.**
All 3.1 changes are **additive** over 3.0. New fields are optional, no required field was removed, and no shape changed in a way that breaks a 3.0-conformant client. A buyer running against a 3.1 seller without upgrading their SDK keeps working — they just won't see the new fields. A seller running 3.0 schemas against a 3.1 buyer keeps working — the buyer's new fields are silently ignored.
But the new surfaces solve real production problems, and the longer you stay on 3.0 the more you're operating without the production-hardening 3.1 added: webhook delivery debug, dependency-impact observability, billing finality flags, action discovery, vendor-attested measurement, release-precision negotiation. **Bump as soon as your SDK is ready.**
The one publisher-visible behavior change is on `brand.json` `trademarks[]`: free-text `status` / `countries` values now validate against typed enum / ISO 3166-1 alpha-2 — non-conforming values surface as schema errors. If your `trademarks[]` published unrestricted free text, normalize the values before claiming 3.1.
Prerelease 3.1 adopters should also update prerelease-only integrations: brand verification success responses now require `signed_response`; proposal/action code must remove the temporary `requires_proposal` action mode and use `REQUOTE_REQUIRED` for update repricing; buyers with cached `requires_proposal` values must invalidate and re-read the relevant proposal, product, or buy surface rather than mapping them to `requires_approval`; signal definitions do not declare Global Privacy Control support; `signal-owned` conformance is discovery-only while `signal-marketplace` remains the activation claim; hosted audio/video declarations should use one-sided `duration_ms_range` rather than separate bare min/max fields; and measurement catalog discovery remains experimental behind `measurement.core`. These were prerelease cleanup items before GA, not 3.0 breaking changes.
**Validator obligation for 3.1 SDKs.** The wholesale feed mirroring work tightens one shape within 3.1: `cache_scope` is schema-required on every `get_products` / `get_signals` response (the safety property of the two-layer cache depends on it — see [Cache layering](/dist/docs/3.2.8/media-buy/task-reference/get_products#cache-layering)). Pre-3.1 sellers correctly omit the field and remain conformant to their declared version. SDKs that validate strictly against the 3.1 schema MUST select the validator based on the server-declared `adcp_version` (the same release-precision mechanism 3.1 ships in version negotiation): for responses with `adcp_version` starting `3.0`, the 3.1 `cache_scope`-required constraint MUST be relaxed. This is a tightening within 3.1, not a 3.0 break — but SDKs that hardcode the 3.1 schema without version-pinned validation will reject correct 3.0 traffic. Version-pinned validation is the right pattern for every 3.x→3.(x+1) tightening; cache_scope is the first time it's load-bearing.
For the per-PR detail, see [Release Notes § Version 3.1.0](/dist/docs/3.2.8/reference/release-notes#version-3-1-0). For the version-negotiation cadence and the 3.1 → 3.2 → 4.0 timeline, see [Versioning & Governance § Migration timeline](/dist/docs/3.2.8/reference/versioning#migration-timeline).
# What's new in AdCP 3.2
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/whats-new-in-3-2
AdCP 3.2 is GA: agents run media with the full power of the platform (shared budgets, cost controls, outcome planning), Reliable Reporting, clean-room data collaboration, and a compact lifecycle with 71–94% smaller tool schemas.
# What's new in AdCP 3.2
> [!NOTE]
>
> **AdCP 3.2 is generally available** (published 2026-09-30). The release artifact is `3.2.1` and the wire pin is `adcp_version: "3.2"`. The number `3.2.0` was never released ([why](/dist/docs/3.2.8/reference/release-notes#why-the-first-stable-release-is-3-2-1)). 3.1 stays supported for integrations pinned to `"3.1"`, and nothing forces you to migrate.
3.1 made agents safe to operate. 3.2 makes the deal between them explicit. A buyer can move from a brief to seller-authored plans, negotiate typed terms, hold inventory, accept one exact snapshot, and run the campaign without either agent guessing which kind of change is happening. Reports the seller owes can no longer silently disappear.
This page is the adopter overview. The complete record is [Release Notes § Version 3.2.1](/dist/docs/3.2.8/reference/release-notes#version-3-2-1), and the role-based checklist is [Migrating from 3.1 to 3.2](/dist/docs/3.2.8/reference/migration/3-1-to-3-2).
> [card] [Try the proposal lifecycle](https://agenticadvertising.org/chat?prompt=Walk%20me%20through%20the%20AdCP%203.2%20proposal%20lifecycle%20against%20the%20constrained-seller%20training%20profile.%20Show%20the%20alternatives%2C%20pause%20before%20finalizing%20a%20hold%2C%20then%20pause%20again%20before%20accepting%20it.)
>
> Ask Addie to walk you through discovery, negotiation, the hold, and acceptance, with a confirmation step at each gate. No membership or setup needed.
> [card] [Build it](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk)
>
> `@adcp/sdk@14.0.0` and Python `adcp==8.0.0` ship alongside `3.2.1` and embed it.
> [card] [Adopt it](/dist/docs/3.2.8/reference/migration/3-1-to-3-2)
>
> Add the compact tools one at a time while your 3.1 traffic keeps working.
## Why 3.2 matters
3.1 made agents safe to operate. **3.2 lets them run real media with the full power of the platforms they buy on, and prove what ran.**
1. **Platform power.** Social and other self-optimizing platforms can take one shared budget, optimize it natively against the buyer's cost controls, and plan to an outcome before the buy.
2. **Reliable Reporting.** The reporting pipeline is part of the protocol, so a missing report shows up as missing (experimental).
3. **Data collaboration.** Products declare how your audience data can reach them, including clean rooms and dataset shares (experimental).
4. **Compact lifecycle.** One small tool per step of a buy, with MCP schemas 71–94% smaller: fewer tokens and less to implement.
5. **Trust you can check.** AI-generated content is declared, do-not-run lists are honored, measurement says who measured it, and rights grants carry verifiable attestations (experimental).
| If you are… | What changes for you |
| - | - |
| **A buyer or agency** | Hand a platform one budget with the cost caps, cost targets, or ROAS targets you care about, and ask what an outcome will cost before you buy. See which reports you are owed and when one is late or missing. Proposals, holds, and one accepted snapshot keep the agreed terms on record. |
| **A seller or platform** | Sell the way your platform works: optimize a shared budget natively against the buyer's cost controls, state what a product needs before it can run (event source, app catalog, page or profile), and declare how audience data reaches you, including clean rooms. Declare exchange, retail media, streaming TV, and DOOH specialisms, and report on your own reporting clock. |
| **An agent or SDK builder** | Seven task-specific tools replace overloaded modes, with MCP schemas 71–94% smaller than the 3.1 facades. You also get exact version negotiation, required error recovery, body-bound signing with published test vectors, and conformance that extends to buyer and orchestrator agents through preview specialisms. |
Adopting 3.2 has a short list of requirements, and the stable-surface exceptions to 3.x compatibility are recorded in one place: [3.2 exceptions to 3.x compatibility](/dist/docs/3.2.8/reference/versioning#3-2-exceptions-to-3-x-compatibility). The two with the widest impact are `media_buy_status` on create and update success, and RFC 8941 encoding for request signatures.
## The 3.2 feature set
* **Compact commercial lifecycle.** `list_products`, `request_proposals`, `refine_proposals`, `decline_proposals`, `buy_products`, `accept_proposal`, and `control_media_buy`.
* **Targeting that survives execution.** One model from discovery to readback, including age and demographic bases, named places, subdivisions, browser families, property exclusions, exact `null`-clear semantics, and daypart time zones.
* **Frequency management.** A MediaBuy-level cap counted across every package, structured product cap constraints, and a post-purchase cap-update action.
* **Budgets, bidding, and pricing.** Seller-optimized shared budgets with separately declared package controls, a `bidding` block, hard daily caps, atomic total-budget changes, revenue-share pricing, creative rotation, and a shared MediaBuy `name`.
* **Planning.** Ask which dates are available, or which budget reaches a target outcome.
* **Reliable Reporting 1.0 (experimental).** Reporting obligations, immutable revisions, health, managed delivery, reconciled receipts, and a buyer-to-seller consumption-status loop.
* **Delivery reporting and measurement.** Metric narrowing, sortable and paginated breakdowns, delivery by format, time-based views, a `viewable_rate` goal, first-party measurement disclosure, and dates on the seller's reporting timezone.
* **Accounts and principals.** Operator reconciliation, account time zones and currency, change notifications, an experimental account change feed, and an experimental authenticated-principal layer.
* **Seller specialisms and channels.** `sales-dooh` (stable), `sales-exchange`, `sales-retail-media`, and `sales-streaming-tv` (preview). DOOH, OOH, radio, audio VAST, CTV experiences, and programmed channels.
* **Creative.** Canonical formats as the default path, revision and served-variant identity, representation sets, tracker execution contracts, VAST 4.3 and validation, localization, and pixel density.
* **Trust and runtime.** Required `error.recovery`, body-bound signing, a published signing-error vocabulary, non-authoritative MCP sessions, durable idempotency ledgers, and portable attestations.
* **Conformance.** Preview buyer and orchestrator specialisms, a buyer-orchestrator certification track, owner-selectable Legacy and Strict Spec grading, and 3.2 request-signing vectors.
## 3.1 to 3.2 by the numbers
| Published surface | 3.1.0 | 3.2.1 | Change |
| - | -: | -: | -: |
| Manifested tools | 64 | 78 | +15 added, 1 webhook payload removed from the manifest |
| Specialisms | 21 | 31 | +10 |
| Standard error codes | 92 | 120 | +28 |
| Source JSON Schema files | 648 | 1,017 | +369 |
| Compliance YAML files | 137 | 237 | +100 |
Seven of the new tools are the compact lifecycle. The rest are principal, reporting, account change-feed, notification-configuration, and governance-adjustment tasks.
The corpus grew, but each operation got lighter. The compact tools stop pulling every legacy mode, inline creative, and provenance branch into each call. Comparing the 3.1 bundled request and response schemas with the 3.2 MCP `2026-07-28` media-buy pairs:
| Comparable operation | 3.1 compatibility pair | 3.2 compact pair | Reduction |
| - | -: | -: | -: |
| Proposal planning | \~3.0 MB (`get_products`) | \~0.89 MB (`request_proposals`) | 71% |
| Direct purchase | \~2.8 MB (`create_media_buy`) | \~0.60 MB (`buy_products`) | 78% |
| Proposal acceptance | \~2.8 MB (`create_media_buy`) | \~0.37 MB (`accept_proposal`) | 87% |
| Operational control | \~4.4 MB (`update_media_buy`) | \~0.25 MB (`control_media_buy`) | 94% |
These are schema artifact sizes, not request-body sizes or latency. The model-context profile presents input-only schemas; response schemas stay available to SDKs and validators.
## Headline features
### A media buy you can audit: the compact lifecycle
Each tool marks one business boundary:
| Boundary | What becomes true |
| - | - |
| `list_products` | Published offers are listed, and the read has no side effects. |
| `request_proposals` | The seller has authored non-binding plan snapshots from the brief. |
| `refine_proposals` with `revise` | A new immutable snapshot records the changed terms without rewriting history. |
| `refine_proposals` with `finalize` | The exact terms are committed, and inventory is held until `expires_at`. |
| `decline_proposals` | The buyer's feedback is recorded, and the proposal can no longer execute. |
| `buy_products` | A published offer is purchased directly. |
| `accept_proposal` | The held snapshot becomes an accepted MediaBuy: a new buy, an amendment, or a negotiated cancellation. |
| `control_media_buy` | Delivery changes inside the accepted envelope, guarded by the current revision. |
Proposals carry typed `commercial_terms` and an RFC 8785 `terms_digest`. That gives buyers one recovery rule: use `control_media_buy` inside the accepted terms, and request a new snapshot for anything that changes them. Sellers advertise the subset they serve in `media_buy.lifecycle_tools`. When that field is absent, use the 3.x facades (`get_products`, `create_media_buy`, `update_media_buy`), which stay available throughout 3.x.
The contract ends at acceptance. `accept_proposal` does not standardize invoicing, payment rails, FX, makegoods, or disputes. The [3.3 commercial-completion workstream](https://github.com/adcontextprotocol/adcp/issues/7064) covers what comes after. See [Proposal negotiation](/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation).
### Targeting and frequency that survive execution
* **Discovery.** Buyers put known values in `targeting_overlay` and use `required_overlay_support` for values they will choose later. Sellers price and forecast against the effective targeting and disclose material interpretation in `targeting_resolution`. Package readback echoes the exact committed targeting, including `placement_selection` and `collection_selection`.
* **New dimensions.** Basis-aware age and portable demographic predicates, named places (`geo_places`), country-aware ISO subdivisions, browser families, device-platform exclusion, `property_list_exclude`, and BCP 47 language ranges. Daypart runs on inventory-local time or one named IANA zone.
* **Clearing a dimension.** On request-only inputs, omitting a dimension inherits or preserves it, a value replaces it, and `null` clears it.
* **Frequency.** A root `frequency_cap` on the MediaBuy counts once across every package. Sellers advertise it through `media_buy.aggregate_frequency_capping`, and products opt in through `media_buy_support`. Products with limited package caps declare them in `overlay_support.frequency_cap_support`. The `update_media_buy_frequency_cap` action changes or clears the root cap after purchase.
* **No persistent identifier, no cap.** A product that declares no persistent identifier (`Product.identity.persistent_identifier`, experimental feature `media_buy.product_identity`) must reject capped purchases instead of accepting them without enforcement.
See [Targeting-aware product discovery](/dist/docs/3.2.8/reference/migration/targeting-aware-discovery).
### Budgets, bidding, pricing, and planning
* **Shared budgets, honestly declared.** A seller can optimize one shared `total_budget` across packages under the buyer's goals. `media_buy.features.seller_optimized_budget` covers only that core contract plus media-buy-level pacing. Package budget caps, minimum-spend targets, and package pacing are separate capabilities (`seller_optimized_package_budgets`, `seller_optimized_min_spend_targets`, `seller_optimized_package_pacing`). A seller that lacks one rejects that control with `UNSUPPORTED_FEATURE` instead of dropping it. Core sellers must accept omitted or `even` pacing and may reject `asap` or `front_loaded`, and must not coerce them to `even`.
* **Say which allocation you mean.** Omitting `budget_allocation` still means fixed package budgets, but buyer agents should send `{"mode": "fixed"}` or a `seller_optimized` block explicitly, and ask the principal when the instruction is ambiguous.
* **Caps and bidding.** `daily_budget_cap` is always hard, and one `budget_cap_timezone` defines the day. Total-budget changes are atomic. A `bidding` block separates the objective from automatic bidding, manual bids, ceilings, and ROAS controls.
* **Pricing and controls.** `revenue_share` pricing applies a `commission_rate` to settled `commissionable_value`. Package creative rotation can be weighted, even, sequential, or random. A shared MediaBuy `name` gives both sides one trafficking label. Structured warnings and durable indicators flag risks that need buyer attention.
* **Declines.** Sellers can say why a request was declined with a coarse `decline_reason`, without exposing private thresholds.
* **Planning.** `offer_filters.availability_horizon` answers "which dates can I run?" `criteria.outcome_target` answers "what budget reaches 10,000 clicks?", or, with an optional `cost_per`, "what can I get at 3 or less per click on a 5,000 budget?"; the seller answers with a cost control never below the ask. Both are capability-gated, and availability answers are snapshots, never holds.
* **Products that say what they need before you buy (experimental).** Products can declare `execution_requirements`: the event source, catalog (including `app`), or downstream connection a package needs before `create_media_buy` succeeds. The declaration is the same for every account, and an unmet requirement is rejected with `VALIDATION_ERROR` pointing at the binding. Sellers opt in with `media_buy.execution_requirements` in `experimental_features`; per-account readiness is planned for 3.3.
### Reliable Reporting 1.0: missing data becomes visible
For every reporting period a seller owes, the buyer can see whether it is waiting, healthy, delayed, or needs action; whether an official revision exists; and whether that revision is correct even when it has zero rows. A missing obligation can't drop out of the seller's own denominator.
| Tier | What it adds |
| - | - |
| **Core** | Obligations derived from the schedule, immutable revisions, explicit adjustments, and health, read through `get_reporting_status`. A polling-only seller can implement it. |
| **Managed Delivery** | Durable file, dataset-share, and warehouse deliveries bound to exact revisions, destinations, retention, and revocation. |
| **Reconciled Billing** | Authenticated consumer receipts (`sync_reporting_receipts`) and canonical content agreement. It does not create or settle invoices. |
The buyer closes the loop with `sync_reporting_status`, reporting what it received, missed, could not read, or disputes as a `content_mismatch`. The buyer owes a status by `expected_at + automated_recovery_window_seconds`, and a missed status never changes seller health. A seller restatement gets a re-read grace window before it escalates.
Reliable Reporting is experimental, discovered through `media_buy.reporting_delivery` with `reliable_reporting_version: "1.0"`. `sync_reporting_status` is opt-in in 3.2 and becomes required Core in the next eligible minor, no earlier than October 24, 2026. See [Implementing Reliable Reporting Core](/dist/docs/3.2.8/media-buy/reporting-core-implementation-guide) and the [status-loop migration](/dist/docs/3.2.8/reference/migration/reliable-reporting-status-loop).
### Delivery reporting and measurement buyers can act on
* **Ask for what you need.** `requested_metrics` narrows a `get_media_buy_delivery` response. Breakdowns become negotiable (`limit`, `sort_by`, `sort_direction`), echo the sort they applied, disclose truncation, and page with cursors.
* **New cuts.** `by_format` reports delivery per canonical `format_kind`. `time_based_views` separates play-time from in-view counting. Leaf metrics such as `quartile_100` and `viewable_rate` can be committed and sorted.
* **Optimize for viewability.** `viewable_rate` is a metric optimization goal. It requires a viewability `standard` (`mrc` or `groupm`) and accepts an optional measurement `vendor`. The `views` goal means content views as defined in delivery metrics (the CPV-billable quantity), not viewable impressions.
* **Dates on the seller's clock.** Delivery dates and `daily_breakdown[].date` are calendar dates in the products' `reporting_capabilities.timezone`, and `reporting_period.timezone` echoes the zone applied. A dated or windowed (`time_granularity`) request that spans more than one reporting timezone is rejected with `VALIDATION_ERROR`.
* **Know who measured it.** `vendor_relationship` (`first_party`, `affiliated`, or `third_party`) discloses seller-owned measurement. `measurable_plays` gives DOOH, cinema, and place-based channels a real denominator.
* **Report at the right grain.** Demographic and spot-level (as-run) delivery, delivery by property, collection, and placement, and currency at media-buy or package grain. The response-wide `aggregated_totals` is deprecated.
### Seller specialisms and channels
| Specialism | Status | For |
| - | - | - |
| `sales-dooh` | Stable | Non-guaranteed digital out-of-home venue and screen inventory |
| `sales-exchange` | Preview | Exchanges and SSPs: floors, bid guidance, auction-priced buys, auction transparency |
| `sales-retail-media` | Preview | Retail media networks: catalog sync, keyword sponsored search, item availability |
| `sales-streaming-tv` | Preview | CTV and streaming: VAST sync, household frequency caps, household reach |
Underneath the specialisms:
* **DOOH.** Structured slot, loop, resolution, and motion attributes, with duration-weighted share of voice.
* **Static OOH (experimental).** Posting periods, modeled impressions, and proof of posting.
* **Audio.** The `audio_vast` canonical format, `nielsen_audio` demographic notation, and loudness constraints.
* **CTV.** Experience profiles for menu, pause, screensaver, overlay, squeezeback, and in-scene ads, built on existing canonical formats.
* **Programmed channels.** FAST, virtual linear, and syndicated audio streams become first-class `kind: "channel"` collections with verified owner-sold carriage.
See the [compliance catalog](/dist/docs/3.2.8/building/verification/compliance-catalog#choosing-a-sales-specialism).
### Accounts, principals, and change visibility
* **Operator changes.** `sync_accounts` can rekey an account's operator identity with revision checks. Former keys return `ACCOUNT_MOVED` instead of creating duplicates.
* **Account settings.** Sellers declare account time zones and currency modes.
* **Cache invalidation.** `capabilities.changed` and `account.status_changed` tell caches when to refresh.
* **Account change feed (experimental).** `list_account_changes` is an optional, capability-gated feed of material changes to a shared account, including changes made outside your own calls. It ships as experimental feature `account.change_feed` while [RFC #6810](https://github.com/adcontextprotocol/adcp/issues/6810) is open.
* **Authenticated principals (experimental).** `sync_principal` and `get_principal` hold a caller's standing relationship with a seller: caller-level webhooks with a one-call kill switch, reusable reporting destinations, and declarations of which async versions, signing algorithms, and experimental features the caller can consume. Principal configuration never grants advertiser-account authority. Follow the buyer-side flow in [Set up your buyer agent with a seller](/dist/docs/3.2.8/accounts/principal-registration-walkthrough).
### Creative: one traceable path from brief to replay
Canonical formats are the authoring and discovery path. Creative agents advertise `creative.supported_formats[].capability_id` and `operations`, and products expose the formats they accept in `format_options[]`. For a generative campaign, one identity chain runs from brief to format selection, build, pre-flight preview, assignment, live delivery, and post-flight replay:
* **Revision identity.** Buyer-authored, immutable revision identity follows a creative through sync, review, library readback, and delivery attribution.
* **Served-variant identity.** Makes post-flight preview replay unambiguous.
* **Representation sets and paired redirects.** Say exactly what gets delivered.
* **Tracker execution contracts.** Tell buyers, before spend, which pixel, VAST, and DAAST trackers will fire.
* **VAST.** VAST 4.3, three validation levels (`structural`, `document`, `wrapper`), and three VAST error codes catch unplayable tags before serve time.
3.2 also adds pixel-density and rendition sets, materialized localization on a shared BCP 47 primitive, opt-in async preview with `quality_used`, structured accessibility rejection detail, synthetic-depiction provenance, and buyer-pushed catalog item suppression. `list_creative_formats` remains only for compatibility; exact plural `format_ids` fields are deprecated for removal in 4.0.
### Trust and runtime hardening
* **Errors.** Every 3.2 error carries `error.recovery`, and `retry_after` is an integer. Classification comes before retry: a delay never makes a `correctable` or `terminal` error retryable. 28 new standard codes and versioned error-recovery vectors let SDKs pin behavior.
* **Request integrity.** Request signing stays optional in 3.x. A 3.2 signing endpoint covers `content-digest` on every body and encodes values as RFC 8941 `sf-binary`. A published signing-error vocabulary lets SDKs classify failures without guessing, and 3.2 request-signing vectors let a `covers_content_digest: "required"` verifier grade checklist steps 2–12. Signing becomes required for spend-committing operations in 4.0.
* **Sessions and replay.** Verifiers derive identity and authorization from each request, never from `Mcp-Session-Id`. Idempotency ledgers outlive the resources they create, and `COMMITTED_RESOURCE_PURGED` reports writes committed before their resource was purged.
* **Evidence.** Portable, reference-first attestations back audience evidence, rights grants, and runtime signal quality. OAuth discovery consistency is graded. Product and signal agents can declare `anonymous_discovery`.
* **Transports.** Compact MCP `2026-07-28` schemas, a 128 KiB MCP interoperability target, the A2A 1.0 profile extension, and cross-transport async identity rules.
### Conformance that grades both sides of the trade
* **Buyer and orchestrator agents** get their own preview specialisms: `buyer-discovery`, `buyer-activation`, `buyer-negotiation`, `buyer-monitoring`, `buyer-recovery`, and `orchestrator-multi-agent`. Together they form a buyer-orchestrator compliance track with three certification levels. Preview specialisms can be claimed, and the runner reports a `preview` result instead of a verified pass or fail.
* **Capability-scoped grading.** Storyboards resolve against what an agent actually advertises, and fixture gaps grade as not applicable instead of failing.
* **Grading profiles.** Verified-agent owners can choose Legacy or Strict Spec grading.
* **Badges.** 3.2 badges are issued once hosted grading moves to the `3.2.1` compliance bundle, graded against `3.2.1` with a `"3.2"` advertisement and response echo; prerelease runs are diagnostic only. See [AAO Verified](/dist/docs/3.2.8/building/verification/aao-verified).
* **Reference agent.** The public training agent answers `"3.2"` and moves to the `3.2.1` bundle with `@adcp/sdk@14.0.0`.
## Experimental surfaces in 3.2
Experimental surfaces in 3.2 include campaign governance (`governance.campaign`), Trusted Match (`trusted_match.core`), audience activation (`media_buy.audience_activation`), product identity (`media_buy.product_identity`), execution requirements (`media_buy.execution_requirements`), Reliable Reporting (`media_buy.reporting_delivery`), principals (`protocol.principal`), the account change feed (`account.change_feed`), measurement (`measurement.core`, `measurement.gateway`), the static OOH delivery block, and the `seller_rendered_stateful_display` and `coordinated_placements` canonical formats. The full registry is in [experimental status](/dist/docs/3.2.8/reference/experimental-status).
To use them, inspect `experimental_features` and pin an exact release. 3.2 carries announced breaking changes for two of them:
* **Governance.** Task-scoped enforcement, intent-only conditions, and new required delivery-observation fields. See the [cross-role governance migration](/dist/docs/3.2.8/reference/migration/cross-role-governance-enforcement).
* **Trusted Match.** Publisher authentication, provider-attributed key-values, and `macros` renamed to `creative_data`.
See the [release notes](/dist/docs/3.2.8/reference/release-notes#experimental-surface-changes) and the [experimental-status contract](/dist/docs/3.2.8/reference/experimental-status).
## What to change when you adopt 3.2
| If you are… | Before advertising or sending `"3.2"` |
| - | - |
| Any seller or service | Advertise `"3.2"` only when you serve it, and echo it on responses. Populate `error.recovery` on every error. Declare only the capabilities and specialisms you implement. |
| A buyer | Gate compact tools and optional fields on capabilities. Don't infer 3.2 support from a major-only declaration. Send `budget_allocation` explicitly. |
| A media-buy implementer | Use `media_buy_status` on create and update success. Root `status` is the task-envelope state. If you declare `seller_optimized_budget`, declare the package-control sub-capabilities you honor. |
| A signing implementation | Require `content-digest` coverage and RFC 8941 `sf-binary` values on 3.2 signing endpoints. The endpoint, not the request pin, selects the profile. |
| An MCP server or verifier | Never derive identity or task ownership from `Mcp-Session-Id`. |
| A delivery-reporting implementer | Emit currency at media-buy or package grain, stop producing new `aggregated_totals`, and report dates on your reporting timezone with `reporting_period.timezone`. |
| A creative implementation | Discover through `format_options[]` and `creative.supported_formats[]`. Isolate named-format conversion. |
| An SDK maintainer | Generate from the signed `3.2.1` tarball and publish an exact support statement. |
**SDKs.** TypeScript `@adcp/sdk@14.0.0` (npm `latest`) and Python `adcp==8.0.0` ship alongside `3.2.1` and embed it. Go and Java support for final 3.2 is planned as a follow-up. Both 3.2 SDK lines still call and serve 3.0 and 3.1 peers.
## Start here
1. Follow [Migrating from 3.1 to 3.2](/dist/docs/3.2.8/reference/migration/3-1-to-3-2).
2. Pick an SDK in [Choose your SDK](/dist/docs/3.2.8/building/by-layer/L4/choose-your-sdk).
3. Run your agent against the `3.2.1` compliance bundle. See [Validate your agent](/dist/docs/3.2.8/building/verification/validate-your-agent).
4. Use the [Release Notes](/dist/docs/3.2.8/reference/release-notes#version-3-2-1) for the full record, or the [3.2 prerelease history](/dist/docs/3.2.8/reference/3-2-beta) if you pinned a beta or RC.
# AdCP 3.0
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/reference/whats-new-in-v3
What's new in AdCP 3.0: brand identity and rights, creative workflow upgrades, governance, sponsored intelligence, collections and installments, 20 media channels, and migration guides from v2.
AdCP 3.0 expands the protocol beyond media buying into brand identity, governance, media planning, and conversational brand experiences.
> [!WARNING]
>
> **v2 is unsupported as of 3.0 GA and fully deprecated on August 1, 2026 (UTC).** See the [v2 sunset page](/dist/docs/3.2.8/reference/v2-sunset) for the timeline and AAO registry policy.
## At a glance
| Area | v2.x | v3.x |
| - | - | - |
| **Protocol scope** | Media Buy, Signals, Creative | Adds Brand Protocol, Governance, Sponsored Intelligence (experimental) |
| **Brand identity** | No standard mechanism | `brand.json` + community brand registry |
| **Governance** | No brand suitability protocol | Property lists, content standards, campaign governance, policy registry, and brand calibration |
| **Sponsored Intelligence** (experimental) | No conversational brand protocol | Consent-first brand sessions in AI assistants |
| **Accounts Protocol** | No formal account model | Named protocol layer: `sync_accounts`, `list_accounts`, `report_usage`, brand registry-grounded identity |
| **Catalogs** | `promoted_offerings` creative asset | First-class `sync_catalogs` task with 13 catalog types |
| **Media planning** | Products only | Proposals with budget allocations + delivery forecasts |
| **Brand rights** | No licensing protocol | `get_rights`, `acquire_rights`, `update_rights` with HMAC-authenticated webhooks — shipping [experimental](/dist/docs/3.2.8/reference/experimental-status) in 3.0 |
| **Visual guidelines** | No structured brand visuals | `visual_guidelines` on `brand.json` for generative creative systems |
| **Creative workflows** | Basic build / preview / sync separation | Inline preview, multi-format `build_creative`, library retrieval, quality tiers, and catalog `item_limit` |
| **Creative libraries** | Media Buy-centric creative reads/writes | `list_creatives` / `sync_creatives` as Creative Protocol operations plus `supports_generation`, `supports_transformation`, and `has_creative_library` discovery |
| **Creative governance** | No creative evaluation protocol | `get_creative_features` for security scanning, quality, content categorization |
| **Disclosure matching** | Position-only disclosure handling | Position + persistence-aware disclosure matching (`continuous`, `initial`, `flexible`) |
| **Collections and installments** | No content programming model | `collections` on products with distribution IDs, installment lifecycle, break-based inventory |
| **Planning ergonomics** | No `time_budget`, `preferred_delivery_types`, `exclusivity`, or per-package flights | `time_budget` + `incomplete`, `preferred_delivery_types`, `exclusivity`, optional `delivery_measurement`, and package-level `start_time` / `end_time` |
| **Channel model** | 9 channels | 20 planning-oriented channels (including `sponsored_intelligence`) with broadcast TV support (creative identifiers, measurement windows, spot formats) |
| **Capability discovery** | Agent card extensions | Runtime `get_adcp_capabilities` task |
| **Sandbox discovery** | Mixed capability locations | `require_operator_auth` for auth model, `account.sandbox` for sandbox support, sandbox in natural account references |
| **Creative assignment** | Simple ID arrays | Weighted assignments with placement targeting |
| **Geo targeting** | Implicit US-centric | Explicit named systems (global) |
| **Keyword targeting** | No keyword support | `keyword_targets` with match types and bid prices |
| **Optimization** | Single optimization goal | Multi-goal `optimization_goals` array with metric and event types |
| **Delivery reporting** | Aggregate delivery only | Opt-in dimension breakdowns (geo, device, audience, placement, keyword) |
| **Signal pricing** | Simple CPM | Structured pricing models: CPM, percent of media, flat fee, per-unit, and `custom` escape hatch for non-standard constructs |
| **Device targeting** | No form-factor targeting | `device_type` (desktop, mobile, tablet, ctv, dooh, unknown) distinct from `device_platform` (OS) |
| **Proximity targeting** | No point-based geo targeting | `geo_proximity` with travel time, radius, and GeoJSON methods |
| **Refinement** | Free-text with `proposal_id` | Typed change-request array with seller acknowledgment |
| **Error handling** | Unstructured errors | `recovery` field (transient, correctable, terminal) + 18 standard error codes |
| **AI provenance** | No provenance model | `provenance` object with IPTC source types, C2PA references, regulatory disclosures |
| **Creative compliance** | No compliance on briefs | `required_disclosures`, `prohibited_claims`, disclosure positions |
| **Agent ergonomics** | Full payloads on every call | `fields` projection, opt-in breakdowns, pre-flight capability filtering |
| **Signal lifecycle** | Activate only | `activate` / `deactivate` action on `activate_signal` |
***
## New capabilities
### Trust surface: idempotency, request signing, and signed governance
3.0 makes agent-to-agent transactions safe for real money by turning three operational disciplines into first-class protocol primitives.
**`idempotency_key` is required on every mutating request.** Buyers generate a fresh key per logical operation — the schema requires `^[A-Za-z0-9_.:-]{16,255}$`; AdCP Verified additionally requires a cryptographically-random UUID v4. Sellers declare dedup semantics on `get_adcp_capabilities` as either `adcp.idempotency = { supported: true, replay_ttl_seconds: <1h–7d, 24h recommended> }` or `{ supported: false }`. When `supported: true`, replay is safe: the seller returns `replayed: true` on exact replay, `IDEMPOTENCY_CONFLICT` when the same key accompanies a different payload, and `IDEMPOTENCY_EXPIRED` after the TTL. **When `supported: false`, sending an `idempotency_key` is a no-op — naive retries double-process**, and buyers MUST use natural-key checks (e.g., `get_media_buys` plus request context such as `context.internal_campaign_id` or package context such as `context.buyer_ref`) before retrying spend-committing operations. Clients MUST NOT assume a default; a seller missing this block is non-compliant. Since `supported: true` is a trust-bearing claim, conformance runners probe it with a deliberate payload-mutation replay — sellers claiming support MUST pass this probe before the declaration is considered verified.
**RFC 9421 HTTP Message Signatures are optional in 3.0 and mandatory under AdCP Verified.** Agents sign mutating requests with Ed25519 over a canonicalized covered-component list (method, target URI, `content-digest`, protocol-level fields). The spec pins sf-binary encoding and URL canonicalization so independent implementations produce bit-identical canonical inputs. A 15-step verification checklist defines the seller's path: `alg` allowlist, `keyid` cap-before-crypto (defense against unbounded verification), JWKS resolution via SSRF-validated fetch, `jti` replay dedup, audience binding. Published test vectors at `static/compliance/source/test-vectors/request-signing/` let implementers validate correctness offline.
**Webhooks are signed under the same RFC 9421 profile — baseline-required for sellers.** Webhook authentication unifies on the AdCP 9421 profile as a symmetric variant of request signing: the seller signs outbound webhook requests with a key published in its JWKS at `jwks_uri` (discoverable via `brand.json` `agents[]`). New signers use `adcp_use: "request-signing"` for webhook delivery; deprecated `adcp_use: "webhook-signing"` keys remain accepted during the compatibility window. Operators that want webhook-only key material publish a distinct `request-signing` `kid`. No shared secret crosses the wire. The buyer verifies the signature using the seller's JWKS. A 14-step webhook verifier checklist — documented in the [Security guide](/dist/docs/3.2.8/building/by-layer/L1/security) — covers trust-anchor scoping, downgrade-and-injection resistance, and per-keyid replay dedup (100K per keyid, 10M aggregate); verification failures return typed reason codes defined there. HMAC-SHA256 remains a legacy fallback through 3.x (opt-in via `push_notification_config.authentication.credentials`); the entire `authentication` object is removed in 4.0.
**Every webhook payload carries a required `idempotency_key`.** Webhooks use at-least-once delivery, so receivers must dedupe. Every webhook payload — MCP, collection-list changes, property-list changes, content-standards artifacts, rights revocations — carries a sender-generated, cryptographically-random UUID v4 `idempotency_key` stable across retries of the same event. Same name and format as the request-side field. Predictable keys allow pre-seeding a receiver's dedup cache to suppress legitimate events, so sellers MUST generate keys from a cryptographic source.
**`governance_context` is a signed JWS.** When a governance agent approves a plan it returns a JWS — not an opaque string — signed with the governance agent's key. The buyer echoes it in the media-buy envelope. Sellers verify the signature using the governance agent's JWKS (resolved via `sync_governance`) and bind decisions to a specific buyer, plan, phase, and time without a round-trip. Stale or forged decisions are rejected at the transport layer. When a governance agent is configured on the plan, sellers MUST invoke `check_governance` before committing budget and MUST reject a spend-commit lacking a valid `governance_context` with `PERMISSION_DENIED`.
**The compliance runner validates all of this.** Every agent runs `/compliance/{version}/universal/security.yaml` regardless of which protocols or specialisms it claims — covering unauthenticated rejection, API key enforcement, OAuth discovery per RFC 9728, and audience binding. Agents that declare signing run the `signed_requests` and `signed_webhooks` harnesses: positive flows, tampering (header injection, body mutation, timestamp skew), replay (`jti` reuse), and the `keyid`-cap-before-crypto path. Runner output is a structured, verifiable `runner-output.json` artifact with a hash chain over the test-kit corpus so tampering is detectable.
**Cross-instance state persistence is now a spec requirement.** Agent state — tasks, media buys, plans, signed artifacts, idempotency keys — MUST be persistent across horizontally-scaled instances. In-memory-only state is non-compliant for production.
See the [Security implementation guide](/dist/docs/3.2.8/building/by-layer/L1/security) for the full threat model, principal roles (brand / operator / agent), and step-by-step verification paths.
> [card] [Security implementation](/dist/docs/3.2.8/building/by-layer/L1/security)
>
> Threat model, signing profile, verification paths, and the universal security storyboard.
***
### Specialisms and storyboard-driven compliance
Storyboards — scripted compliance scenarios that agents must pass — now live in the protocol at `/compliance/{version}/`, alongside schemas and task definitions. Agents declare two things in `get_adcp_capabilities`:
* **`supported_protocols`** — broad domain claims (`media_buy`, `creative`, `signals`, `governance`, `brand`, `sponsored_intelligence`). Each commits the agent to the domain's baseline storyboard.
* **`specialisms`** — 19 narrow capability claims across the 6 domains. Examples: `sales-guaranteed`, `sales-broadcast-tv`, `creative-generative`, `property-lists`, `signal-marketplace`, `brand-rights`. Each rolls up to one parent protocol.
Compliance runs have three tiers: **universal** storyboards every agent runs (capability discovery, schema validation, error compliance), **domain baselines** for each declared protocol, and **specialism storyboards** for each narrow claim. A per-version protocol tarball at `/protocol/{version}.tgz` lets clients bulk-sync schemas, storyboards, and examples in one request.
> [!NOTE]
>
> **AdCP Verified is self-attested in 3.0.** Agents run the storyboard suite and publish a signed `runner-output.json` with a hash chain over the test-kit corpus. AgenticAdvertising.org does not audit the output or gate issuance — the Verified stamp means "this agent published passing runner output," not "an auditor confirmed the claim." Verifying parties (buyers, integrators, regulators) can re-run any claim against the referenced storyboards and compare output hashes.
>
> The compliance runner and the storyboards are themselves software shipping at 3.0 — they have bugs, coverage gaps, and in a few places they encode our best guess at spec intent where the working group is still refining the exact rule. When an implementer sees a storyboard failure, three things are possible: their agent has a bug, the storyboard has a bug, or the spec is ambiguous. All three are legitimate issues to file.
>
> **Why 3.0 began as self-attested rather than audited:** at the 3.0 launch, the reference implementations AgenticAdvertising.org operated — the training agent and the JavaScript, Python, and Go SDKs — did not yet pass the new storyboard suite cleanly. Self-attestation was the bridge while the runner, storyboards, and implementations converged. For the current verification profiles, evidence rules, and registry behavior, see [AgenticAdvertising.org Verified](/dist/docs/3.2.8/building/verification/aao-verified); historical launch-era pass counts are intentionally not carried forward as current status.
> [card] [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog)
>
> Full index of domains and specialisms with status flags and storyboard sources.
***
### Brand Protocol
Buy-side identity through `/.well-known/brand.json`. Just as publishers use `adagents.json` to declare properties and authorized agents, brands use `brand.json` to declare their identity, brand hierarchy, and authorized operators.
| Sell side | Buy side |
| - | - |
| Publisher | **House** (corporate entity) |
| Property | **Brand** (advertising identity) |
| `adagents.json` | **`brand.json`** |
Four variants: **House Portfolio** (full brand hierarchy inline), **Brand Agent** (dynamic via MCP), **House Redirect** (sub-brand to house domain), and **Authoritative Location** (hosted URL).
Given any domain, the protocol resolves to a canonical brand:
```
shoes.novabrands.example.com
-> fetch /.well-known/brand.json
-> { "house": "novabrands.example.com" }
-> fetch novabrands.example.com/.well-known/brand.json
-> search brands[] for property matching "shoes.novabrands.example.com"
-> Result: { house: "novabrands.example.com", brand_id: "nova_athletics" }
```
**Use cases:** creative generation (resolve domain to brand identity), brand verification (check `authorized_operators`), reporting roll-up (group campaigns by house).
> [card] [Brand Protocol](/dist/docs/3.2.8/brand-protocol)
>
> Full specification including brand.json variants, resolution flow, and brand identity.
***
### Brand rights lifecycle
Three tasks for licensing and usage rights between brands and content owners:
| Task | Purpose |
| - | - |
| `get_rights` | Discover available rights for a brand's content |
| `acquire_rights` | Request and negotiate rights acquisition |
| `update_rights` | Modify active rights (extend, restrict, revoke) |
Rights include generation credentials (API keys or tokens for accessing licensed content), creative approval webhooks (HMAC-SHA256 authenticated callbacks when creatives are submitted for review), and revocation notifications. The protocol distinguishes actionable rejections (fix and resubmit) from final rejections (do not retry).
Structured `visual_guidelines` on `brand.json` complement rights by giving generative creative systems structured rules for on-brand asset production: photography style, graphic elements, composition, motion, logo placement, colorways, type scale, and restrictions.
> [card] [Brand rights](/dist/docs/3.2.8/brand-protocol/tasks/get_rights)
>
> Task reference for rights discovery, acquisition, and management.
***
### Collections and installments
Products can now reference persistent content programs — podcasts, TV series, YouTube channels — via `collections`, which follows the same publisher-scoped selector pattern as `publisher_properties`. Collections are declared in the publisher's `adagents.json` and products reference them by publisher domain and collection ID. Buyers resolve full collection objects from `adagents.json`. Collections include distribution identifiers for cross-seller matching, installment lifecycle states (scheduled, tentative, live, postponed, cancelled, aired, published), break-based ad inventory configuration, talent linking to `brand.json`, and international content rating systems.
Shows support relationships (spinoff, companion, sequel, prequel, crossover) and derivative content (clips, highlights, recaps) for comprehensive content modeling.
> [card] [Collections and installments](/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments)
>
> Full specification including collection schemas, installment lifecycle, and break-based inventory.
***
### Registry API
The AgenticAdvertising.org registry provides a public REST API for resolving brands and properties, discovering agents, and validating authorization. Most endpoints require no authentication.
| Capability | Endpoint | Description |
| - | - | - |
| Brand resolution | `/api/brands/resolve` | Resolve domain to canonical brand |
| Property resolution | `/api/properties/resolve` | Resolve publisher domain to property info |
| Agent discovery | `/api/registry/agents` | List registered agents with capabilities |
| Authorization check | `/api/registry/validate/property-authorization` | Real-time authorization validation |
| Search | `/api/search` | Search across brands, publishers, and properties |
| Community brands | `/api/brands/save` | Contribute brand data (auth required) |
The registry complements the protocol: resolve entities via the REST API, then transact via MCP/A2A tasks.
> [card] [Registry API](/dist/docs/3.2.8/registry)
>
> Complete endpoint reference with authentication and rate limits.
***
### Proposals and delivery forecasts
Publishers can return **proposals** alongside products — structured media plans with percentage-based budget allocations that buyers can execute directly via `create_media_buy`. Proposals encode publisher expertise, replacing ad-hoc product lists with actionable buying strategies. They can be refined through session continuity — subsequent `get_products` calls within the same session carry conversation history.
**Delivery forecasts** attach to proposals and allocations. Each forecast contains budget points with metric ranges (low/mid/high), showing how delivery scales with spend. Three forecast methods: **`estimate`** (rough approximation), **`modeled`** (predictive models), **`guaranteed`** (contractually committed). Forecasts can predict delivery metrics (impressions, reach, GRPs) and outcomes (purchases, leads, app installs). TV and radio forecasts use `demographic_system` and `demographic` for GRP-based planning.
> [card] [Proposals and forecasting](/dist/docs/3.2.8/media-buy/product-discovery/media-products#proposals)
>
> Complete documentation including budget curves, CTV, retail media, and broadcast audio examples.
***
### Accounts
> [!TIP]
>
> **Migrating from v2?** Accounts are entirely new in v3 — there is no v2 equivalent to migrate from. Start with [Accounts and Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) for the setup guide.
Formal billing relationships between buyers and sellers via `sync_accounts`.
**Four entities:**
| Entity | Question | How identified |
| - | - | - |
| **Brand** | Whose products are advertised? | House domain + brand_id via `brand.json` |
| **Account** | Who gets billed? | [Account reference](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) — `account_id` from `list_accounts` or natural key |
| **Operator** | Who operates on the brand's behalf? | Domain (e.g., `acmeagency.example.com`) |
| **Agent** | What software places buys? | Authenticated session |
**Two billing models:** `operator` (operator or brand buying direct is invoiced) and `agent` (agent consolidates billing). **Two trust models:** agent-trusted (default, agent declares brands/operators) and operator-scoped (seller requires operator-level credentials).
**Workflow:** `get_adcp_capabilities` -> `sync_accounts` -> `get_products` with `account` -> `create_media_buy` with `account`.
> [card] [Accounts Protocol](/dist/docs/3.2.8/accounts/overview)
>
> Accounts Protocol overview: identity verification, billing models, and settlement.
***
### Catalogs
First-class catalog lifecycle with `sync_catalogs`. Thirteen catalog types: structural (`offering`, `product`, `inventory`, `store`, `promotion`) and industry-vertical (`hotel`, `flight`, `job`, `vehicle`, `real_estate`, `education`, `destination`, `app`). Vertical types have canonical item schemas drawn from Google Ads, Meta, LinkedIn, and Microsoft feed specs.
Formats declare what catalogs they need via `catalog_requirements`. Creatives reference synced catalogs by `catalog_id` instead of embedding items in assets. Catalogs declare `conversion_events` and `content_id_type` for attribution alignment.
> [card] [Catalogs](/dist/docs/3.2.8/creative/catalogs)
>
> Complete documentation including catalog types, sync workflow, format requirements, and conversion events.
***
### Capability discovery
`get_adcp_capabilities` replaces both `adcp-extension.json` and the MCP agent card with runtime capability discovery. It returns supported protocols, account billing models, portfolio information, targeting systems, and governance features — all schema-validated.
> [!WARNING]
>
> **Agent cards and `adcp-extension.json` are no longer needed.** Buyers discover sellers through `adagents.json` and call `get_adcp_capabilities` at runtime. If your v2 integration reads capability data from agent card extensions, switch to `get_adcp_capabilities`.
> [card] [get_adcp_capabilities](/dist/docs/3.2.8/protocol/get_adcp_capabilities)
>
> Full task reference with request/response schemas.
***
### Governance Protocol
Brand suitability and inventory curation. Governance agents manage **property lists** (curated sets of properties for targeting or exclusion) and **content standards** (brand suitability policies with per-category block/allow rules). Buyers pass property lists to `get_products` for filtered inventory discovery, and use `calibrate_content` for collaborative alignment between brand and governance agent. Governance agents can enforce `provenance_required` on creative policy and support third-party AI content verification via the `verification` array on provenance claims.
Campaign governance extends this with plan-level policy and budget enforcement via `sync_plans`, `check_governance`, `report_plan_outcome`, and `get_plan_audit_logs`. Governance agents can operate in `audit`, `advisory`, or `enforce` mode, validate seller-side actions against delegated authority, and resolve standardized policies through the shared [policy registry](/dist/docs/3.2.8/governance/policy-registry).
**Art 22 / Annex III as schema invariants.** For regulated verticals (credit, insurance pricing, recruitment, housing), AdCP 3.0 enforces mandatory human oversight at the protocol layer, not in deployer policy PDFs. `policy_categories` intersecting `fair_housing | fair_lending | fair_employment | pharmaceutical_advertising` makes `plan.human_review_required: true` a schema requirement — buyers cannot opt out. Governance agents MUST escalate every action on such plans regardless of budget. See [Annex III & Art 22 obligations](/dist/docs/3.2.8/governance/annex-iii-obligations).
> [card] [Governance Protocol](/dist/docs/3.2.8/governance/overview)
>
> Full specification including property lists, content standards, and calibration.
***
### Sponsored Intelligence Protocol
Conversational brand experiences in AI assistants. SI defines how AI assistants invoke brand agents for rich engagement (text, voice, UI components) without breaking the conversational flow. Sessions follow a consent-first model: user expresses interest, grants consent, then the brand agent engages conversationally with optional transaction handoff.
> [!NOTE]
>
> **Experimental.** Sponsored Intelligence is part of AdCP 3.0 as an experimental surface (feature id `sponsored_intelligence.core`) — session lifecycle, UI components, identity/consent, and capability negotiation may change between 3.x releases with at least 6 weeks' notice. Sellers implementing SI MUST declare `sponsored_intelligence.core` in `experimental_features`. See [experimental status](/dist/docs/3.2.8/reference/experimental-status) for the full contract and the [3.1.0 roadmap](https://github.com/adcontextprotocol/adcp/issues/2201) for planned changes.
> [card] [SI Chat Protocol](/dist/docs/3.2.8/sponsored-intelligence/si-chat-protocol)
>
> Full specification including session lifecycle, implementing agents, and implementing hosts.
***
### Published signal definitions for data providers
Data providers can publish signal definitions via `adagents.json` `signals[]`, following the same pattern as publishers declaring properties.
| Publishers | Data providers |
| - | - |
| Declare **properties** | Declare **signals** |
| Use `property_ids` / `property_tags` | Use `signal_ids` / `signal_tags` |
| Buyers verify via `publisher_domain` | Buyers verify via `data_provider_domain` |
Signals now have explicit `value_type` (binary, categorical, numeric) with typed targeting, and structured `signal_id` objects that reference the data provider's published definitions.
> [card] [Data provider guide](/dist/docs/3.2.8/signals/data-providers)
>
> Complete implementation guide for publishing signal definitions.
***
## rc.1 to rc.2 highlights
This page covers the full v2 → v3 shift. If you already adopted `3.0.0-rc.1`, these are the most important rc.2 changes to review before upgrading.
### Creative workflow and library changes
`build_creative` now supports inline preview (`include_preview`), multi-format output (`target_format_ids`), quality tiers, catalog-driven `item_limit`, and library retrieval using `creative_id` with optional `concept_id`, `media_buy_id`, `package_id`, and `macro_values`. `preview_creative` also adds quality control. Creative library operations are now explicitly Creative Protocol tasks: `list_creatives` and `sync_creatives` live with the rest of the creative lifecycle, and capability discovery adds `supports_generation`, `supports_transformation`, and `has_creative_library` so buyers can route requests intentionally.
### Planning, accounts, and sandbox refinements
`account_resolution` is removed; buyers now use `require_operator_auth` to determine the auth model and initial account-reference shape. Sandbox support moves to `account.sandbox`, and sandbox can participate in the natural account key for buyer-declared account flows. Product discovery adds `preferred_delivery_types`, `exclusivity`, and `time_budget`, with `incomplete` in responses when the seller cannot finish within the requested budget. Packages and product allocations can now carry per-package `start_time` / `end_time`, and `delivery_measurement` becomes optional on products.
### Compliance and governance refinements
Creative compliance now includes disclosure persistence semantics in addition to position and duration, allowing formats to declare which persistence modes they can enforce. Campaign governance also lands in rc.2 with `sync_plans`, `check_governance`, `report_plan_outcome`, and `get_plan_audit_logs`, plus `governance_context` for canonical plan extraction. `sync_governance` provides a dedicated task for syncing governance agent endpoints to accounts, replacing the previous approach of embedding `governance_agents` on `sync_accounts` and `list_accounts` requests.
For the exhaustive rc.2 change list, see the [Release Notes](/dist/docs/3.2.8/reference/release-notes#version-300-rc2) and [CHANGELOG.md](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md#300-rc2).
***
## rc.3 to 3.0 highlights
> [!NOTE]
>
> **Upgrading from rc.3?** See [rc.3 → 3.0 prerelease upgrade notes](/dist/docs/3.2.8/reference/migration/prerelease-upgrades) for the breaking changes table, before/after examples, and migration steps.
### Specialisms and compliance catalog
Storyboards move into the protocol at `/compliance/{version}/` with a new `specialisms` field on `get_adcp_capabilities`. 21 specialisms roll up to 6 domains; four 3.1 archetypes ship with `status: preview`. See the [Compliance Catalog](/dist/docs/3.2.8/building/verification/compliance-catalog). Renames: `broadcast-platform` → `sales-broadcast-tv`, `social-platform` → `sales-social`. Merge: `property-governance` + `collection-governance` → `inventory-lists`. Promotion: `sponsored_intelligence` specialism → full protocol.
### Capabilities model simplification
The capabilities model is streamlined for 3.0: redundant boolean gates are removed. If a `content_standards` object exists in `get_adcp_capabilities`, the agent supports content standards — no separate boolean needed.
`reporting_capabilities` is now required on every product. Geo capability fields remain typed: `geo_countries` is boolean; `geo_regions` accepts its legacy boolean or a country/value-aware object; and `geo_metros` and `geo_postal_areas` use structured objects. Region inclusion and exclusion may be declared independently.
See the [prerelease upgrade notes](/dist/docs/3.2.8/reference/migration/prerelease-upgrades#capabilities-model-simplification) for the full list of removed fields and migration steps.
### Governance across purchase types
Campaign governance extends beyond media buys to cover brand rights licensing, signal activation, and creative services — any purchase where budget or policy rules apply. `governance_context` replaces `media_buy_id` as the identifier that ties governance actions together across a campaign's lifecycle. A `purchase_type` field on `check_governance` and `report_plan_outcome` distinguishes the governed activity.
### GOVERNANCE_DENIED error and schema consistency
`GOVERNANCE_DENIED` is added to the standard error codes with correctable recovery, enabling governance-rejected operations to return structured errors. All request/response schemas across governance, collection, property, sponsored-intelligence, and content-standards protocols gain optional `context` and `ext` fields for application metadata and protocol extensions. `signal_id` is now required on signal items in `get_signals` responses. The `comply_test_controller` schema is flattened from a oneOf union to a flat object with `scenario` discriminant.
### Per-request version declaration
All request schemas now include `adcp_version` (release-precision, e.g., `"3.1"`), allowing v3 buyers to declare which release their payloads conform to. Sellers validate against their advertised `adcp.supported_versions` array on `get_adcp_capabilities` and echo `adcp_version` at the envelope root on every response. Unsupported releases return `VERSION_UNSUPPORTED`. When omitted, sellers default to their highest supported version.
3.1 also retains `adcp_major_version` (integer) as a backwards-compatible legacy field, but release-precision `adcp_version` is the primary wire field going forward. See [Version negotiation](/dist/docs/3.2.8/reference/versioning#version-negotiation) for the negotiation contract, migration timeline, and SDK pinning examples.
Note: both fields are v3-only — v2 clients cannot set either (the fields do not exist in v2 schemas). Multi-version sellers detect v2 payloads by structural cues (missing `buying_mode`, `fixed_rate` vs `fixed_price`, `geo_postal_codes` vs `geo_postal_areas`, etc.) rather than by these fields.
### Collection lists
Collection lists extend brand safety from properties to content programs. Like property lists, collection lists are curated sets — but they target shows, series, and other content programs across platforms using distribution identifiers (IMDb, Gracenote, EIDR) for cross-publisher matching.
New targeting overlay fields `collection_list` and `collection_list_exclude` enable both inclusion and exclusion targeting. A new genre taxonomy enum normalizes genre classification across buyers and sellers.
> [card] [Collection lists](/dist/docs/3.2.8/governance/collection/tasks/collection_lists)
>
> Task reference for collection list creation and management.
### Broadcast TV support
Linear TV sellers can now fully participate in AdCP. This release adds the protocol primitives that distinguish broadcast from digital:
* **Broadcast creative identifiers** — `industry_identifiers` on creative assets and manifests, with `creative-identifier-type` enum (`ad_id`, `isci`, `clearcast_clock`, `idcrea`). Broadcast creatives carry the traffic or clearance identifier used by the relevant workflow, which ties spots to rotation instructions and traffic systems.
* **Broadcast spot formats** — Reference formats for :15, :30, and :60 spots. Video file only — no VAST, no impression trackers, no clickthrough URLs. The absence of tracker asset slots in a format signals that third-party pixel tracking is not supported.
* **Agency Estimate Number** — `agency_estimate_number` on media buys and packages. The financial reference that links broadcast orders to agency media plans and billing.
* **Measurement windows** — `measurement_windows` on `reporting_capabilities` for Live, C3, and C7 maturation. `measurement_window` on `billing_measurement` declares which window the guarantee is reconciled against.
* **Delivery data completeness** — `is_final` and `measurement_window` on per-package delivery data. Buyers know whether numbers are provisional or closed, and which measurement window they represent. Applies to any channel with maturing data (broadcast, podcast, long-tail content).
> [card] [Broadcast TV](/dist/docs/3.2.8/creative/channels/broadcast)
>
> Channel guide covering spot formats, creative identifiers, measurement windows, and how broadcast differs from CTV.
### Structured measurement terms
Guaranteed buys gain a formal negotiation surface: `measurement_terms` defines billing measurement vendor, IVT threshold, and viewability floor. Sellers declare defaults on products, buyers propose overrides at `create_media_buy`, sellers accept/reject/adjust. A `cancellation_policy` schema declares notice periods and penalties for guaranteed products.
### Unified vendor pricing
Pricing models extend from signals to creative, governance, and property list agents. Creative agents return `pricing_options[]` on `list_creatives` and `build_creative` responses. Property lists carry `pricing_options[]`. All vendor pricing uses a shared `vendor-pricing-option.json` schema (cpm, percent_of_media, flat_fee).
### Offline reporting delivery
Sellers can declare offline reporting delivery methods (SFTP, S3, GCS, Azure Blob) in `get_adcp_capabilities` via `reporting_delivery_methods`. Accounts specify a `reporting_bucket` for file delivery. Products declare `supports_offline_delivery` in `reporting_capabilities`. File formats include CSV, JSON, Parquet, Avro, and ORC.
### Trusted Match Protocol extensions
TMP gains a provider registration schema (`provider-registration.json`) formalizing provider endpoints, capabilities, lifecycle status (active/inactive/draining), and per-provider timeout budgets. A `GET /health` endpoint enables router-side health monitoring. TMPX adds exposure tracking with country-partitioned identity resolution and macro connectivity.
Identity Match requests now accept an `identities` array (1-3 tokens per request) instead of a single `user_token` + `uid_type` pair. Publishers send every identity token they have; buyers resolve on whichever graph matches. The router filters `identities` per provider (minimum-necessary-data) and re-signs before forwarding — the forwarded set must be a subset of what the publisher sent. RFC 8785 JCS canonicalization is used for both signature and cache-key derivation, and `consent_hash` partitions the cache by consent state. `rampid_derived` is added to the `uid-type` enum.
TMP remains pre-release in 3.0. The stable surface is targeted for 3.1.0.
### Brand schema extensions
`brand.json` gains a generic `agents` array for declaring brand-associated agents, visual tokens (`border_radius`, `elevation`, `spacing`, extended color roles), and structured font definitions with `weight`, `style`, `stretch`, `optical_size`, and `usage` fields.
### Required tasks reference
A new [Required tasks by protocol](/dist/docs/3.2.8/protocol/required-tasks) reference page consolidates required, conditional, and optional tasks across all AdCP protocols by agent role — a single page to verify your implementation covers the minimum surface.
### Experimental surfaces
AdCP 3.0 ships a core of stable surfaces under the [3.x stability guarantees](/dist/docs/3.2.8/reference/versioning#3x-stability-guarantees), plus four surfaces that are part of the core protocol but not yet frozen. These surfaces are being co-developed with design partners — **OpenAds, Scope3, Yahoo, ONX, and Triton Digital** — running them in production engagements that shape the graduation path. Experimental surfaces carry `x-status: experimental` in their schemas, and sellers implementing them declare the feature id in `experimental_features` on `get_adcp_capabilities`. They may change between 3.x releases with at least 6 weeks' notice.
| Surface | Feature id | Why experimental |
| - | - | - |
| [Brand rights lifecycle](/dist/docs/3.2.8/brand-protocol/tasks/get_rights) | `brand.rights_lifecycle` | Legal-construct surface added late in the 3.0 cycle. First enterprise deployments will expose edge cases in partial rights, sublicensing, revocation, and dispute resolution. |
| [Campaign governance](/dist/docs/3.2.8/governance/campaign/specification) | `governance.campaign` | Multi-party governance semantics (approval conflicts, audit provenance, tie-breaking under Embedded Human Judgment) are not yet settled. |
| [Trusted Match Protocol](/dist/docs/3.2.8/trusted-match/) | `trusted_match.core` | Privacy architecture will evolve with regulator engagement; TMPX exposure tokens, country-partitioned identity, and Offer creative data are expected to change. |
| [Sponsored Intelligence](/dist/docs/3.2.8/sponsored-intelligence/overview) | `sponsored_intelligence.core` | Conversational brand experiences are a new advertising model. Session lifecycle, UI components, identity/consent object shape, and capability negotiation are expected to evolve as first-party AI hosts and brand agents integrate. |
The experimental label is deliberately scoped — everything else in 3.0 follows the normal 6-month deprecation notice. See [experimental status](/dist/docs/3.2.8/reference/experimental-status) for the full contract, graduation criteria, and client guidance.
### Signal pricing: custom escape hatch
Vendor pricing gains a `custom` model alongside `cpm`, `percent_of_media`, `flat_fee`, and `per_unit`. Requires a human-readable `description` and a structured `metadata` object. Buyers SHOULD route custom pricing through operator review before commitment — automatic selection is not recommended.
Motivation: performance kickers, tiered volume, hybrid (flat + CPM), and outcome-shared pricing are already appearing in the field. Shipping the escape hatch now avoids retrofit pain when real deployments hit a construct the enumerated models cannot express. Structured metadata keeps the model machine-inspectable without a schema change per new pattern.
***
## Breaking changes
### Media channel taxonomy
v2's 9 channels are replaced by 20 planning-oriented channels. Five channels carried over unchanged (`display`, `social`, `ctv`, `podcast`, `dooh`). The remaining four are split, removed, or renamed.
> [!WARNING]
>
> All code that reads or writes channel values must be updated.
| v2 channel | v3 channel(s) | Notes |
| - | - | - |
| `display` | `display` | Unchanged |
| `video` | `olv`, `linear_tv`, `cinema` | Split by distribution context (`ctv` was already separate in v2) |
| `audio` | `radio`, `streaming_audio` | Split by distribution (`podcast` was already separate in v2) |
| `native` | Removed | Use format-level properties instead |
| `social` | `social` | Unchanged |
| `ctv` | `ctv` | Unchanged |
| `podcast` | `podcast` | Unchanged |
| `dooh` | `dooh` | Unchanged |
| `retail` | `retail_media` | Renamed for clarity |
New channels in v3 (no v2 equivalent): `search`, `linear_tv`, `radio`, `streaming_audio`, `ooh`, `print`, `cinema`, `email`, `gaming`, `retail_media`, `influencer`, `affiliate`, `product_placement`, `sponsored_intelligence`.
> [!NOTE]
>
> The `gaming` channel covers intrinsic in-game ads, rewarded video, and playable ads. Rewarded video in gaming apps could also be classified as `olv` — use `gaming` when the inventory comes from a gaming budget.
> [card] [Channels deep dive](/dist/docs/3.2.8/reference/migration/channels)
>
> Complete mapping guide with examples for each v2 channel, multi-channel products, and capability discovery.
***
### Pricing option field renames
v3 separates **hard constraints** (publisher-enforced prices) from **soft hints** (historical percentiles). `fixed_rate` becomes `fixed_price`, and `price_guidance.floor` moves to top-level `floor_price`.
| v2 field | v3 field | Notes |
| - | - | - |
| `fixed_rate` | `fixed_price` | Renamed for clarity (it's a price, not a rate) |
| `price_guidance.floor` | `floor_price` | Moved to top level as hard constraint |
These fields map to standard deal types: `fixed_price` corresponds to Programmatic Guaranteed (PG) and Preferred Deals, while `floor_price` corresponds to Private Marketplace (PMP) auctions. Open auction inventory omits both fields.
> [card] [Pricing deep dive](/dist/docs/3.2.8/reference/migration/pricing)
>
> Fixed-price vs auction examples, price guidance schema, flat-rate pricing, minimum spend, and transition period handling.
***
### Creative assignments with weighting
`creative_ids` string arrays are replaced by `creative_assignments` objects that support delivery weighting and placement targeting.
| v2 field | v3 field |
| - | - |
| `creative_ids` (string array) | `creative_assignments` (object array with `creative_id`, `weight`, `placement_ids`) |
> [card] [Creatives deep dive](/dist/docs/3.2.8/reference/migration/creatives)
>
> Weighted assignments, placement targeting, asset discovery with the unified `assets` array, repeatable groups, and format cards.
***
### Geo targeting with named systems
Metro and postal targeting values now carry explicit system information, supporting global markets. Metro values are grouped by system using `{ "system": "...", "values": [...] }` objects; native postal values use `{ "country": "...", "system": "...", "values": [...] }`.
| v2 field | v3 field |
| - | - |
| `geo_metros` (string array) | `geo_metros` (system/values objects) |
| `geo_postal_codes` (string array) | `geo_postal_areas` (country/system/values objects) |
v3 also adds `geo_metros_exclude` and `geo_postal_areas_exclude` for negative targeting (e.g., target the US except the New York DMA).
> [card] [Geo targeting deep dive](/dist/docs/3.2.8/reference/migration/geo-targeting)
>
> Metro and postal system reference tables, exclusion targeting, capability discovery, and a full targeting example.
***
### Other targeting changes
v3 adds several targeting fields beyond geo:
| Field | Description |
| - | - |
| `daypart_targets` | Time-of-day and day-of-week targeting windows |
| `age_restriction` | Age-gating for restricted content |
| `device_platform` | Operating system targeting (iOS, Android, Windows, tvOS, etc.) |
| `device_type` | Device form factor targeting (desktop, mobile, tablet, ctv, dooh, unknown) |
| `language` | Content language targeting |
| `keyword_targets` / `negative_keywords` | Keyword targeting for search and retail media with match types (broad, phrase, exact) and per-keyword bid prices |
| `device_type_exclude` | Negative device form factor targeting |
| `geo_proximity` | Point-based proximity targeting via travel time isochrones, radius, or GeoJSON geometry |
These fields are optional additions — they don't replace any v2 fields.
***
### Unified asset discovery
Formats now use an `assets` array with `required` boolean instead of `assets_required`. See the [creatives deep dive](/dist/docs/3.2.8/reference/migration/creatives#asset-discovery).
***
### Catalogs replace promoted_offerings
The `promoted_offerings` creative asset type and `promoted_offering` string field are removed. Catalogs are now first-class protocol objects with their own sync lifecycle (`sync_catalogs`), format-level requirements (`catalog_requirements`), and conversion event alignment.
| v2 field | v3 replacement |
| - | - |
| `promoted_offerings` (creative asset) | `catalogs` field on creative manifest |
| `promoted_offering` (string on media-buy) | Removed — use `brand` + `brief` |
| `promoted_offering` (string on creative-manifest) | Removed — use `catalogs` field |
> [card] [Catalogs deep dive](/dist/docs/3.2.8/reference/migration/catalogs)
>
> Before/after examples, sync_catalogs workflow, catalog_requirements discovery, and migration checklist.
***
### Brand identity unification
Inline `brand_manifest` objects are replaced by brand references (`BrandRef`). Task schemas reference brands by `{ domain, brand_id }` instead of passing manifests inline. Brand data is resolved from `brand.json` or the registry at execution time.
| v2/beta field | v3 rc.1 field |
| - | - |
| `brand_manifest` (inline object) | `brand` (`{ domain, brand_id }`) |
Affects: `get_products`, `create_media_buy`, `build_creative`, and property list schemas.
> [card] [Brand identity deep dive](/dist/docs/3.2.8/reference/migration/brand-identity)
>
> BrandRef schema, resolution flow, before/after examples, and migration steps.
***
### Product delivery forecasts
`estimated_exposures` is replaced by a structured `forecast` field using the `DeliveryForecast` type.
| v2/beta field | v3 rc.1 field |
| - | - |
| `estimated_exposures` (integer) | `forecast` (DeliveryForecast with time periods, metric ranges, methodology) |
***
### Proposal refinement via buying mode
`proposal_id` is removed from the `get_products` request. Refinement now uses `buying_mode: "refine"` with a typed `refine` array of change-requests (see [typed refinement](#typed-refinement-with-seller-acknowledgment)). A2A conversation continuity uses native `contextId`; MCP continuity, when offered, belongs to the transport session rather than an AdCP request-body field.
Proposal execution via `create_media_buy` with `proposal_id` is unchanged.
| v2/beta field | v3 rc.1 field |
| - | - |
| `proposal_id` on `get_products` request | Removed — use `buying_mode: "refine"` |
***
### Optimization goals redesign
`optimization_goal` (singular object) is replaced by `optimization_goals` (array). Each goal is a discriminated union on `kind`:
| v2/beta field | v3 rc.1 field |
| - | - |
| `optimization_goal` (single object) | `optimization_goals` (array) |
| Implicit single goal | `priority` field for multi-goal ordering |
Two goal kinds:
* **`metric`** — Seller-native delivery metrics (clicks, views, reach, engagements, etc.) with `cost_per` or `threshold_rate` targets
* **`event`** — Conversion tracking with `event_sources` array and optional `value_field`/`value_factor`
> [card] [Optimization goals deep dive](/dist/docs/3.2.8/reference/migration/optimization-goals)
>
> Goal kinds, reach optimization, multi-goal priority, product capabilities, and migration steps.
***
### Signals pricing restructure
The legacy `pricing: { cpm }` object on signals is replaced by a structured `pricing_options` array with three pricing models.
| v2/beta field | v3 rc.1 field |
| - | - |
| `pricing.cpm` (number) | `pricing_options[]` (array of pricing model objects) |
Three models: `cpm`, `percent_of_media` (with optional `max_cpm`), `flat_fee`.
> [card] [Signals deep dive](/dist/docs/3.2.8/reference/migration/signals)
>
> Pricing models, deliver_to flattening, usage reporting, and migration steps.
***
### Signals deliver_to flattening
The nested `deliver_to` object in `get_signals` request is replaced with two top-level fields.
| v2/beta field | v3 rc.1 field |
| - | - |
| `deliver_to.destinations` | `destinations` (top-level) |
| `deliver_to.countries` | `countries` (top-level) |
***
### AudienceMember external_id required
`external_id` is promoted from a uid-type enum value to a required top-level field on AudienceMember. Every member must have a buyer-assigned stable identifier plus at least one matchable identifier.
> [card] [Audiences deep dive](/dist/docs/3.2.8/reference/migration/audiences)
>
> Before/after examples, uid-type changes, sync_audiences usage, and migration steps.
***
### Typed refinement with seller acknowledgment
`refine` is redesigned from a nested object with `overall`/`products`/`proposals` to a flat typed array. Each entry is discriminated by `scope`:
| v2/beta field | v3 rc.1 field |
| - | - |
| `refine.overall` (string) | `{ "scope": "request", "ask": "..." }` array entry |
| `refine.products[].product_id` | `{ "scope": "product", "product_id": "..." }` |
| `refine.proposals[].proposal_id` | `{ "scope": "proposal", "proposal_id": "..." }` |
| `refine.products[].notes` | `ask` field |
Product and proposal entries use the prefixed id field (`product_id`, `proposal_id`) matching AdCP's id naming convention throughout the protocol. `action` is optional on product and proposal entries and defaults to `"include"` — orchestrators only need to set it explicitly for `"omit"`, `"more_like_this"` (product), or `"finalize"` (proposal).
Sellers respond with `refinement_applied` — a positionally-matched array where each entry reports `status` (`applied`, `partial`, `unable`) and optional `notes`. Entries echo the matching id field (`product_id` / `proposal_id`) for cross-validation.
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442061",
"buying_mode": "refine",
"refine": [
{ "scope": "request", "ask": "more video, less display" },
{ "scope": "product", "product_id": "prod_video_premium", "ask": "add 16:9 format" },
{ "scope": "product", "product_id": "prod_display_ros", "action": "omit" },
{ "scope": "proposal", "proposal_id": "prop_balanced_v1", "action": "finalize" }
]
}
```
**Seller migration note.** The shape change is breaking for sellers as well as buyers. Sellers that return `refinement_applied` MUST now echo `scope` and the matching id field (`product_id` for product scope, `proposal_id` for proposal scope) — the pre-rename `{status, notes}`-only entries are rejected by the tightened response schema. Missing `action` on incoming refine entries MUST be treated as `action: "include"`, not as a parse error. Re-issue your seller tests against the 3.0 request schema to catch any orchestrator code still emitting the generic `id` field — the validator now rejects it with `must NOT have additional properties`.
> [card] [Refinement deep dive](/dist/docs/3.2.8/media-buy/product-discovery/refinement)
>
> Change-request types, seller acknowledgment, and before/after examples.
***
### Creative assignments restructured
`SyncCreativesRequest.assignments` changed from a `{ creative_id: package_id[] }` map to a typed array with explicit fields.
| v2/beta field | v3 rc.1 field |
| - | - |
| `assignments` (object map) | `assignments` (array of `{ creative_id, package_id, weight, placement_ids }`) |
***
### Signals account and field consistency
Two consistency changes to signals schemas:
| v2/beta field | v3 rc.1 field |
| - | - |
| `account_id` (string) on `get_signals` and `activate_signal` | `account` (AccountReference object) |
| `deployments` on `activate_signal` | `destinations` (renamed for consistency with `get_signals`) |
***
### Package catalogs as array
| v2/beta field | v3 rc.1 field |
| - | - |
| `catalog` (single Catalog object) on Package | `catalogs` (array of Catalog refs) |
***
### Brand tone structured format
Brand `tone` is now an object type only — string format is removed. Structured tone includes `voice`, `attributes`, `dos`, and `donts` fields. Existing string values should migrate to `{ "voice": "" }`.
| v2/beta field | v3 rc.2 field |
| - | - |
| `tone` (string or object) | `tone` (object: `{ voice, attributes, dos, donts }`) |
***
### Account resolution removed
`account_resolution` capability field is removed. `require_operator_auth` now determines the auth model and account reference style: `true` means account-id namespaces (discover via `list_accounts` when exposed, pass `account_id`), `false` means buyer-declared accounts (declare via `sync_accounts`, pass natural key).
| v2/beta/rc.1 field | v3 rc.2 field |
| - | - |
| `account_resolution` capability | Removed — use `require_operator_auth` |
***
### Privacy and consent
AdCP does not define its own consent framework. Privacy signals (TCF 2.0, GPP, US Privacy String) should be passed via the brief's `ext` field or through transport-level headers. Sellers that require consent signals should declare this in `get_adcp_capabilities` using the extension mechanism.
***
## Removed in v3
| Removed | Replacement |
| - | - |
| `adcp-extension.json` agent card | `get_adcp_capabilities` task |
| `list_authorized_properties` task | `get_adcp_capabilities` portfolio section |
| `assets_required` in formats | `assets` array with `required` boolean |
| `preview_image` in formats | `format_card` object |
| `creative_ids` in packages | `creative_assignments` array |
| `geo_postal_codes` | `geo_postal_areas` |
| `fixed_rate` in pricing | `fixed_price` |
| `price_guidance.floor` | `floor_price` (top-level) |
| `promoted_offerings` asset type | `catalogs` field on creative manifest |
| `promoted_offering` on media-buy | Removed — use `brand` + `brief` |
| `promoted_offering` on creative-manifest | `catalogs` field |
| `brand_manifest` (inline object) | `brand` ref (`{ domain, brand_id }`) |
| `estimated_exposures` on Product | `forecast` (DeliveryForecast) |
| `proposal_id` on `get_products` request | Transport-native continuity (A2A `contextId`; MCP transport session) |
| `refine` object with `overall`/`products`/`proposals` | `refine` array of typed change-requests |
| `creative_brief` on `build_creative` request | `brief` asset type in manifest `assets` map |
| `supports_brief` capability | `supports_compliance` |
| `creative-brief-ref.json` schema | Deleted — briefs are now asset types |
| `deployments` on `activate_signal` | `destinations` |
| `account_id` (string) on signals tasks | `account` (AccountReference) |
| `report_usage.kind` and `report_usage.operator_id` | Removed |
| `catalog` (singular) on Package | `catalogs` (array) |
| `account_resolution` capability | `require_operator_auth` determines account model |
| `X-Dry-Run` HTTP header | `sandbox: true` on account reference |
| `X-Test-Session-ID` HTTP header | Removed — sandbox accounts provide test isolation |
| `X-Mock-Time` HTTP header | Removed |
| `delete_content_standards` task | Archive via `update_content_standards` instead |
| `get_property_features` task | Property list filters + `get_adcp_capabilities` for feature discovery |
| `tone` as string on brand.json | Object only: `{ voice, attributes, dos, donts }` |
| `FormatCategory` enum / `type` on formats | Filter by `asset_types` or `format_ids` instead |
| `broadcast-platform` specialism | Renamed to `sales-broadcast-tv` |
| `social-platform` specialism | Renamed to `sales-social` |
| `property-governance` + `collection-governance` specialisms | Merged into `inventory-lists` |
| `sponsored_intelligence` specialism | Promoted to full protocol in `supported_protocols` |
***
## Migration checklists
> [accordion] All implementations
>
> These breaking changes affect anyone reading or writing AdCP data:
>
> * [ ] Update channel enum values to [new taxonomy](/dist/docs/3.2.8/reference/migration/channels)
> * [ ] Rename `fixed_rate` -> `fixed_price` in [pricing options](/dist/docs/3.2.8/reference/migration/pricing)
> * [ ] Move `price_guidance.floor` -> `floor_price` ([pricing details](/dist/docs/3.2.8/reference/migration/pricing))
> * [ ] Replace `creative_ids` with [`creative_assignments`](/dist/docs/3.2.8/reference/migration/creatives)
> * [ ] Add system specification to [metro/postal targeting](/dist/docs/3.2.8/reference/migration/geo-targeting)
> * [ ] Rename `geo_postal_codes` -> `geo_postal_areas`
> * [ ] Handle new `geo_metros_exclude` and `geo_postal_areas_exclude` fields
> * [ ] Update format parsing to use [`assets` array](/dist/docs/3.2.8/reference/migration/creatives#asset-discovery)
> * [ ] Replace `preview_image` reads with [`format_card`](/dist/docs/3.2.8/reference/migration/creatives#format-cards-replacing-preview_image) rendering
> * [ ] Replace `list_authorized_properties` calls with `get_adcp_capabilities` portfolio
> * [ ] Remove `promoted_offerings` from creative manifest assets and replace with [`catalogs` field](/dist/docs/3.2.8/reference/migration/catalogs)
> * [ ] Remove `promoted_offering` string from media buy and creative manifest objects
> * [ ] Update `optimization_goal` to [`optimization_goals`](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting) (array of discriminated union)
> * [ ] Handle `external_id` as required field on AudienceMember
> * [ ] Replace `brand_manifest` with `brand` ref (`{ domain, brand_id }`) in all task calls
> * [ ] Replace `estimated_exposures` reads with `forecast` (DeliveryForecast) on products
> * [ ] Remove `proposal_id` from `get_products` requests — use session continuity for refinement
> * [ ] Update `refine` from object to typed array with `scope` discriminator
> * [ ] Handle `recovery` field on errors for retry/correction logic
> * [ ] Update `catalog` to `catalogs` (array) on packages
> * [ ] Update signals `account_id` to `account` (AccountReference)
> * [ ] Rename signals `deployments` to `destinations`
> * [ ] Pass `buying_mode` (now required) on `get_products`
> * [ ] Move `creative_brief` to `brief` asset type in manifest `assets` map
> * [ ] Handle `report_usage` without `kind` and `operator_id` fields
> * [ ] Update `SyncCreativesRequest.assignments` from object map to typed array
> * [ ] Migrate brand `tone` from string to object format (`{ voice, attributes, dos, donts }`)
> * [ ] Remove `account_resolution` reads — use `require_operator_auth` instead
> * [ ] Read sandbox support from `account.sandbox` instead of `media_buy.features.sandbox`
> * [ ] Remove `X-Dry-Run`, `X-Test-Session-ID`, and `X-Mock-Time` header handling — use `sandbox: true` on account references instead
> * [ ] Add `type: "dooh"` inside `flat_rate.parameters` when DOOH parameters are provided
> * [ ] Treat `list_creatives` and `sync_creatives` as Creative Protocol operations
> * [ ] Remove `delete_content_standards` calls — archive via `update_content_standards`
> * [ ] Remove `get_property_features` calls — use property list filters
> * [ ] Remove `format_types` / `type` filters — use `asset_types` or `format_ids` instead
> * [ ] Validate all requests/responses against v3 schemas
> [accordion] Seller agents (publishers, SSPs, networks)
>
> Update all data structures to v3 format (channels, pricing, geo targeting), then implement new capabilities:
>
> * [ ] Implement `get_adcp_capabilities` task (including `account` capabilities)
> * [ ] Remove `adcp-extension.json` from agent card
> * [ ] Implement `sync_accounts` for account provisioning
> * [ ] Return proposals with delivery forecasts from `get_products` when applicable
> * [ ] Support property list filtering in `get_products` if integrating with governance agents
> * [ ] Handle catalogs synced via [`sync_catalogs`](/dist/docs/3.2.8/reference/migration/catalogs) with approval workflow
> * [ ] Declare `metric_optimization` capabilities on products
> * [ ] Declare `reporting` capabilities in `get_adcp_capabilities` for dimension breakdowns
> * [ ] Support `reporting_dimensions` parameter on `get_media_buy_delivery`
> * [ ] Return `refinement_applied` array when processing `refine` requests
> * [ ] Implement `rejected` status and `rejection_reason` on media buys
> * [ ] Support `fields` projection parameter on `get_products`
> * [ ] Declare `supported_pricing_models` in `get_adcp_capabilities`
> * [ ] Support `time_budget` on `get_products` and return `incomplete` when work cannot finish in budget
> * [ ] Declare sandbox support in `account.sandbox`, not `media_buy.features.sandbox`
> * [ ] Stop checking for `X-Dry-Run` header — honor `sandbox: true` on account references instead
> * [ ] Support `preferred_delivery_types`, `exclusivity`, optional `delivery_measurement`, and package-level `start_time` / `end_time`
> [accordion] Buyer agents and orchestrators (DSPs, agencies, brands)
>
> Update all requests and response handling to v3 format, then integrate new capabilities:
>
> * [ ] Resolve brands via [`brand.json`](/dist/docs/3.2.8/brand-protocol) before placing buys
> * [ ] Call `sync_accounts` to establish billing relationships
> * [ ] Update to call `get_adcp_capabilities` for runtime discovery
> * [ ] Evaluate proposals and delivery forecasts when returned by sellers
> * [ ] Use the [Registry API](/dist/docs/3.2.8/registry) for brand/property resolution and agent discovery
> * [ ] Pass property lists to filter inventory when working with governance agents
> * [ ] Invoke SI sessions when connecting users with brand agents
> * [ ] Sync catalogs via [`sync_catalogs`](/dist/docs/3.2.8/reference/migration/catalogs) before submitting creatives
> * [ ] Add `conversion_events` to catalogs for attribution tracking
> * [ ] Update `optimization_goal` to `optimization_goals` array in `create_media_buy`
> * [ ] Pass `pricing_option_id` when activating signals with pricing options
> * [ ] Use `reporting_dimensions` for dimension breakdowns in delivery reporting
> * [ ] Handle `refinement_applied` response for typed refinement feedback
> * [ ] Use `recovery` field on errors for automated retry/correction
> * [ ] Use `fields` projection on `get_products` for efficient discovery
> * [ ] Handle `rejected` status on media buys
> * [ ] Use `action: "deactivate"` on `activate_signal` for campaign cleanup
> * [ ] Integrate `get_rights` / `acquire_rights` for licensed content campaigns
> * [ ] Handle `visual_guidelines` from `brand.json` for creative generation
> * [ ] Read `require_operator_auth` and `account.sandbox` when choosing account and sandbox flows
> * [ ] Handle `time_budget` / `incomplete` for bounded-latency product discovery
> * [ ] Use creative capability flags (`supports_generation`, `supports_transformation`, `has_creative_library`) to route build vs library workflows
> * [ ] Submit plans to governance agents via `check_governance` when campaign governance is in use
> [accordion] Signals agents (data providers, measurement vendors)
>
> Update schema references from v2 to v3. Signals Protocol doesn't use media channels in its core model.
>
> * [ ] Update schema references from v2 to v3
> * [ ] Ensure `get_adcp_capabilities` returns `major_versions: [3]`
> * [ ] Return structured `signal_id` objects in `get_signals` responses
> * [ ] Include `value_type` field in signal responses
> * [ ] Support `signal_ids` parameter in `get_signals` requests for ID-based lookup
> * [ ] Update from legacy `pricing` to structured `pricing_options` array
> * [ ] Handle top-level `destinations`/`countries` instead of nested `deliver_to`
> * [ ] Add `idempotency_key` support to `report_usage`
> * [ ] Support `action: "deactivate"` on `activate_signal`
> * [ ] Include `categories` and `range` metadata in signal entries
> * [ ] Update `account_id` to `account` (AccountReference)
> * [ ] Rename `deployments` to `destinations`
> [accordion] Data providers (new in v3)
>
> Publish signal definitions via `adagents.json`. See [Data Provider Guide](/dist/docs/3.2.8/signals/data-providers).
>
> * [ ] Create published signal definitions in `/.well-known/adagents.json`
> * [ ] Define signals with `id`, `name`, `value_type`, and optional metadata
> * [ ] Add `signal_tags` for grouping and efficient authorization
> * [ ] Authorize signals agents using `signal_ids` or `signal_tags` authorization types
> * [ ] Validate the file using AdAgents.json Builder
> [accordion] Creative agents (creative management, DCO providers)
>
> Support new asset discovery and integrate brand identity. The `FormatCategory` enum and format `type` field are removed in v3 — filter formats by `asset_types` or `format_ids` instead.
>
> * [ ] Support `assets` array with `required` boolean (replaces `assets_required`)
> * [ ] Replace `preview_image` with `format_card` rendering
> * [ ] Resolve brand identity via `brand.json` for on-brand creative generation
> * [ ] Support `catalog` field on creative manifests (replaces [`promoted_offerings`](/dist/docs/3.2.8/reference/migration/catalogs) asset)
> * [ ] Declare `catalog_requirements` on formats that render catalog items
> * [ ] Update schema references from v2 to v3
> * [ ] Support `provenance` object on creative manifests and assets
> * [ ] Support `brief` and `catalog` as asset types in the `assets` map
> * [ ] Handle `compliance.required_disclosures` on creative briefs
> * [ ] Check format `supported_disclosure_positions` compatibility
> * [ ] Declare `supports_compliance` in capabilities (replaces `supports_brief`)
> * [ ] Handle `visual_guidelines` from `brand.json` for on-brand asset generation
> * [ ] Support `include_preview`, `target_format_ids`, `quality`, and `item_limit` on `build_creative`
> * [ ] Support library retrieval via `creative_id` and declare `supports_generation`, `supports_transformation`, `has_creative_library`
> * [ ] Implement `list_creatives` and `sync_creatives` as Creative Protocol operations
> * [ ] Support `quality` parameter on `preview_creative`
> * [ ] Declare disclosure persistence support via format `disclosure_capabilities`
> [accordion] Brands (new in v3)
>
> Establish machine-readable brand and operator identity. See [brand.json specification](/dist/docs/3.2.8/brand-protocol/brand-json).
>
> * [ ] Host `/.well-known/brand.json` on your domain
> * [ ] Declare brand portfolio, properties, and authorized operators
> * [ ] Optionally provide brand data (logos, colors, fonts, tone) inline in `brand.json` or via brand agent
> * [ ] Add `visual_guidelines` to `brand.json` for generative creative systems
> * [ ] Implement `get_rights` / `acquire_rights` / `update_rights` if licensing content
> * [ ] Register in the [community brand registry](/dist/docs/3.2.8/registry) if not hosting `brand.json`
> [accordion] Governance agents (new in v3)
>
> Implement brand suitability capabilities. See [Governance Protocol](/dist/docs/3.2.8/governance).
>
> * [ ] Implement property list tasks (`create_property_list`, `get_property_list`, etc.)
> * [ ] Implement content standards tasks (`create_content_standards`, `calibrate_content`, etc.)
> * [ ] Implement `get_adcp_capabilities` with `governance` in `supported_protocols`
> * [ ] Implement `provenance_required` enforcement on creative policy
> * [ ] Support `verification` results from AI detection services
> * [ ] Implement `get_creative_features` for creative evaluation
> * [ ] Declare `creative_features` in `get_adcp_capabilities`
> * [ ] Implement campaign governance tasks (`sync_plans`, `check_governance`, `report_plan_outcome`, `get_plan_audit_logs`) when offering plan-level governance
> [accordion] Sponsored Intelligence agents (new in v3 — experimental)
>
> Implement conversational brand experiences. SI ships in 3.0 as an [experimental surface](/dist/docs/3.2.8/reference/experimental-status) (`sponsored_intelligence.core`) — session lifecycle, UI components, and capability negotiation may change between 3.x releases with 6 weeks' notice. Sellers MUST declare `sponsored_intelligence.core` in `experimental_features`. See [SI Chat Protocol](/dist/docs/3.2.8/sponsored-intelligence/si-chat-protocol).
>
> * [ ] Implement SI session tasks (`si_initiate_session`, `si_send_message`, `si_terminate_session`)
> * [ ] Implement `get_adcp_capabilities` with `sponsored_intelligence` in `supported_protocols` and `sponsored_intelligence.core` in `experimental_features`
***
## Getting help
* **Community**: [Slack](/dist/docs/3.2.8/community/joining-slack)
* **Issues**: [GitHub Issues](https://github.com/adcontextprotocol/adcp/issues)
* **Support**: [support@adcontextprotocol.org](mailto:support@adcontextprotocol.org)
# Specification Guidelines
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/spec-guidelines
AdCP specification guidelines: type naming rules, discriminated union patterns, field naming conventions, and style standards for writing protocol spec pages.
# AdCP Specification Guidelines
This document outlines design principles and rules for maintaining the AdCP specification. These guidelines help ensure consistency, clarity, and ease of implementation across different programming languages.
## Type Naming Principles
### No Reused Type Names
**RULE**: Never use the same enum name or field name to represent different concepts, even in different contexts.
**Why**: Type generators (TypeScript, Python, Go, etc.) create collisions when the same name appears with different values or semantics. This forces downstream users to use awkward workarounds like aliasing or deep imports.
**Example of the problem**:
```json theme={null}
// ❌ BAD: Multiple "Type" enums with different meanings
// asset-type.json
{ "type": "string", "enum": ["image", "video", "html"] }
// format.json
{ "type": "string", "enum": ["audio", "video", "display"] }
// Result: Python generates Type, Type1, Type2 or uses alphabetical first-wins
```
**Solution**: Use semantic, domain-specific names:
```json theme={null}
// ✅ GOOD: Distinct enum names for different concepts
// asset-content-type.json
{ "type": "string", "enum": ["image", "video", "html"] }
// pricing-model.json
{ "type": "string", "enum": ["cpm", "cpc", "fixed"] }
// Result: Python generates AssetContentType and PricingModel
```
### Semantic Field Names
Field names should describe **what** they represent, not generic categories.
**Examples**:
* ✅ `asset_content_type` - Clear: describes what content the asset contains
* ❌ `type` - Ambiguous: type of what?
* ❌ `asset_type` - Better, but could conflict with other type fields
### Ratio Field Names: `_rate` vs `_percentage`
**RULE**: Name a **measured ratio** `_rate`. Name a **configured share** of a budget, allocation or target `_percentage`.
A rate is read off the world: it is an observed outcome over an observed population, and no one chooses its value. A percentage is set by somebody and then enforced.
**Examples**:
* ✅ `viewable_rate`, `completion_rate`, `match_rate`, `engagement_rate`, `new_to_brand_rate` — measured
* ✅ `allocation_percentage`, `spend_percentage`, `sov_percentage`, `max_spend_percentage` — configured
* ❌ `approval_percentage` for the share of submitted conversions an advertiser approved — that is measured, so it is `approval_rate`
* ❌ `allocation_rate` for a budget split the buyer chose — that is set, so it is `allocation_percentage`
**Why**: the two are already used this way across the schema corpus, consistently enough that implementers infer the rule and rely on it. Writing it down turns a habit into a contract and prevents the split from eroding — `coverage_rate` and `coverage_percentage` currently both exist, which is the kind of drift an unwritten convention permits.
**Out of scope**: the rule governs ratios of a population. Prices expressed as a proportion (`commission_rate`, `flat_rate`, `effective_rate`) and per-unit-time rates (`frame_rate`, `sampling_rate`, `speaking_rate`) keep `_rate` whether or not anybody configures them, and `threshold_rate` names the optimization goal kind that targets a measured rate.
**Applying it to an existing field** is a breaking rename and is out of scope for this rule; the guidance binds new fields.
### Enum Consolidation
When the same concept appears in multiple places with different subsets:
1. **Create a single canonical enum** with all possible values
2. **Reference that enum** in all schemas using `$ref`
3. **Document subset expectations** in field descriptions when needed
**Example**:
```json theme={null}
// enums/asset-content-type.json - Single source of truth
{
"$id": "/schemas/v3/enums/asset-content-type.json",
"type": "string",
"enum": ["image", "video", "audio", "text", "html", "javascript", ...]
}
// brand.json - References full enum
{
"asset_type": {
"$ref": "/schemas/v3/enums/asset-content-type.json",
"description": "Type of asset. Note: Brand manifests typically contain basic media assets (image, video, audio, text)."
}
}
// list-creative-formats-request.json - References full enum
{
"asset_types": {
"type": "array",
"items": {
"$ref": "/schemas/v3/enums/asset-content-type.json"
}
}
}
```
**Benefits**:
* Type generators produce single, consistent types
* API allows filtering/specifying any valid value
* Adding new values is non-breaking
* Documentation clarifies typical usage without restricting capability
## Specialist Module Naming
### Core Principle
Specialist module names must reflect the **technical capability** being taught — what practitioners verify, resolve, or operate — not the business or marketing category.
A module titled "Brand" is ambiguous: does it teach brand-safety policy, brand-identity schema validation, or brand-campaign strategy? A module titled "Brand Identity & Verification" tells a developer exactly what they will learn to do.
### Naming Consistency
The module name must be consistent across all four surfaces where it appears:
1. **Page title** — the `title:` frontmatter in the module's `.mdx` file
2. **Badge** — the `adcp_specialist_*` credential suffix (e.g., `adcp_specialist_signals`)
3. **Sidebar navigation** — the `sidebarTitle:` frontmatter
4. **Specialist overview table** — the row in the certification overview page
If any of these diverge, implementers looking at one surface form a different mental model than those reading another. Keep all four in sync.
### Good vs. Bad Names
| Avoid | Prefer | Why |
| - | - | - |
| Brand | Brand Identity & Verification | "Brand" reads as marketing; the module teaches schema validation and identity resolution |
| Ads | Creative Asset Management | "Ads" is too broad; the module covers creative formats, asset pipelines, and approval flows |
| Data | Signals & Audience Activation | "Data" is generic; the module teaches signal discovery, privacy controls, and activation loops |
### Naming Checklist
Before proposing a new specialist module:
* [ ] Does the name describe the technical workflow, not the business domain?
* [ ] Would a developer unfamiliar with AdCP understand what the module teaches from the name alone?
* [ ] Is the name consistent across page title, badge, sidebar, and overview table?
* [ ] Does the badge suffix (`adcp_specialist_*`) read naturally in a credential context?
## Enum Design
### Enum File Structure
All enums should live in `/schemas/3.2.8/enums/` with descriptive names:
```
/schemas/v3/enums/
asset-content-type.json # What IS this asset?
pricing-model.json # How is this PRICED?
media-buy-status.json # What STATE is the buy in?
```
### Enum Naming Convention
* Use **noun phrases** that describe what's being categorized
* Use **kebab-case** for filenames
* Generated type names use **PascalCase** (AssetContentType, PricingModel)
* Avoid generic terms like "type", "kind", "status" without qualifiers
### When to Create a New Enum
Create a dedicated enum file when:
* Values are reused across multiple schemas
* Values represent a closed set of options
* The concept is fundamental to the protocol
* Type safety would benefit implementers
### Enum membership — when to add a value
Adding a value to an *existing* enum is a curation decision, not a default. An enum is a curated roster of real, shared semantics — not a registry of every vendor or integration. A value earns membership when **all** hold:
* **Published** — it names an externally-documented concept with a stable definition, not a per-buyer or per-integration shape.
* **Natively supported** — at least one real implementer handles it directly, without bespoke per-value mapping (for a `feed_format`, the seller parses it natively without `feed_field_mappings`).
* **Shared demand** — it is relevant across more than one producer **and** more than one consumer (a shared dialect, not branding for a single bilateral integration).
A material **dialect** of an existing value earns its own value only when its differences would make the parent value's consumer mis-handle it — a renamed primary key, composite-encoded fields, or a field the parent treats as optional but the dialect requires. Cosmetic or additive-optional differences do not; use the parent value. When a concept fails these tests, model it through the schema's existing extension path (`custom` + a mapping, or `ext`) rather than minting an enum value.
This is distinct from [Platform Agnosticism](#platform-agnosticism): a `feed_format` value legitimately names a vendor's *published spec* (the value **is** the spec), whereas platform-agnosticism forbids a vendor-specific *version of a general concept*.
**Worked example — `feed_format` ([#3456](https://github.com/adcontextprotocol/adcp/issues/3456)).** `tiktok_shop`, `pinterest_catalog`, and `openai_product_feed` qualify: published, Google-Merchant-Center-derived feed dialects that real sellers parse natively, each with deltas a strict GMC parser would mis-handle. A feed without a published, natively-parsed spec uses `custom` + `feed_field_mappings`.
## Field Design
### Discriminated Unions
When objects can have multiple shapes, always use explicit discriminator fields:
```json theme={null}
{
"oneOf": [
{
"type": "object",
"properties": {
"delivery_type": { "type": "string", "const": "url" },
"url": { "type": "string" }
},
"required": ["delivery_type", "url"]
},
{
"type": "object",
"properties": {
"delivery_type": { "type": "string", "const": "inline" },
"content": { "type": "string" }
},
"required": ["delivery_type", "content"]
}
]
}
```
This enables proper type narrowing in TypeScript and pattern matching in other languages.
### Avoiding Over-Specific Subsets
Don't artificially restrict enum values in request schemas unless there's a technical reason:
* ❌ Limit `asset_types` filter to 7 values "because most people only use these"
* ✅ Allow all asset content types - let users filter by anything
If certain values are uncommon, document that in the description but don't prevent their use.
## Schema References
### When to Use \$ref
Use `$ref` for:
* Enum values (always)
* Core data models used in multiple places
* Complex nested objects used repeatedly
Don't use `$ref` for:
* Simple inline objects used only once
* Request-specific parameters
* Highly contextual structures
### Reference Paths
All `$ref` paths should be absolute from schema root:
```json theme={null}
// ✅ GOOD: Absolute path
"$ref": "/schemas/v3/enums/asset-content-type.json"
// ❌ BAD: Relative path
"$ref": "../../enums/asset-content-type.json"
```
## Platform Agnosticism
**RULE**: Normative schema **field names** MUST NOT represent a specific vendor's version of a general concept. Platform-specific fields belong under `ext.{vendor}`.
**Why**: AdCP is a protocol, not a platform. A field named `google_campaign_id` or `ttd_line_id` at the top level of a schema bakes one vendor's data model into the spec and creates lock-in. The protocol is credible as an open standard only to the extent that its normative field surface is vendor-neutral.
**How**: Vendor-specific fields belong in the `ext.{vendor}` namespace (schema: `/schemas/core/ext.json`, source: `static/schemas/source/core/ext.json`). `ext` is `additionalProperties: true` — the namespacing is a convention enforced by review, not by JSON Schema.
```json theme={null}
// ❌ BAD: vendor name in a normative field (a general concept dressed up as a vendor)
{
"google_campaign_id": "abc123"
}
// ✅ GOOD: vendor-specific under ext
{
"ext": {
"gam": { "campaign_id": "abc123" }
}
}
```
### External system identifiers
Names that reference **canonical external identifier spaces** are legitimate in both field names and enum values. The distinction is not "does it contain a vendor token" but "does it represent *that vendor's version of something the protocol already has a general concept for*":
* `google_campaign_id` (bad) — a vendor-specific ID for a concept the protocol already models (`media_buy_id`). Move to `ext.gam`.
* `apple_podcast_id` (legitimate) — a canonical identifier for a specific Apple Podcasts item. There is no general concept to map to; the Apple Podcasts namespace is *the* namespace.
* `nielsen_dma` (legitimate) — the industry-standard geographic division, not "Nielsen's version of geography."
Existing examples of legitimate patterns:
* Distribution-platform identifier types: `amazon_music_id`, `roku_channel_id` in `distribution-identifier-type.json` (enum values)
* Feed formats: `google_merchant_center`, `facebook_catalog` in `brand.json` (enum values) — widely-adopted open interchange formats implemented by many third parties
* Measurement/data identifiers: `nielsen_dma` in `get-adcp-capabilities-response` (field name)
* Platform IDs: `apple_podcast_id`, `apple_id` (field names)
The rule to apply: if the name asks "which vendor-equivalent version of something AdCP models?" (bad — use `ext`), reject; if the name asks "which externally-defined system/format/identifier space?" (legitimate), allow. When allowing a field name, add it to `tests/check-platform-agnostic.cjs` `FIELD_ALLOWLIST` with a one-line justification. When allowing an enum value, add it to `ENUM_VALUE_ALLOWLIST` with a path-qualified entry and a one-line justification.
### Reviewer checklist
* Reject a new top-level or request/response field whose name is `{vendor}_{general_concept}` (e.g., `google_campaign_id`, `ttd_line_id`).
* Accept an enum value naming an externally-defined system, format, or identifier space.
* Vendor names in **example blocks** (email addresses, sample IDs) are fine.
* When uncertain, ask: "Is this field or value representing *one vendor's version of something the protocol already has a general concept for*?" If yes, it belongs under `ext.{vendor}`.
## Reserved SDK-Internal Keys
**RULE**: The top-level key `ctx_metadata` is reserved on AdCP resource objects as an adapter-internal round-trip cache for state that an SDK or platform adapter needs to carry across calls but that buyers MUST NOT see or rely on. Adapters MUST strip `ctx_metadata` from any payload before wire egress. When the key was present and non-empty at strip time, adapters MUST emit a warning-level log entry so operators can detect accidental key collisions with custom adapter code. (An empty or absent `ctx_metadata` is silent — only a non-empty value triggers the warning.)
**Why**: Platform adapters (e.g. Google Ad Manager, Kevel, custom seller infrastructure) often need to associate adapter-internal identifiers — GAM ad-unit IDs, key-value pairs, placement IDs — with AdCP resources that the buyer-facing SDK returns. The reference Prebid `salesagent` Python implementation uses an `implementation_config` JSON column on its Product model for exactly this purpose. Without a reserved name, every SDK invents its own (`implementation_config`, `_internal`, `sdk_state`, etc.); a fourth SDK then collides with one of them, or two SDKs converging on the same name produce ambiguous semantics. One reserved name removes the coordination problem.
**Scope**: The reservation applies to AdCP resource objects whose schemas declare `additionalProperties: true` — including `Product`, `MediaBuy`, `Package`, `Creative`, `AudienceSegment`, `Signal`, and `RightsGrant`. The reservation travels with the resource wherever it appears: top-level in a response envelope, nested inside another resource (e.g. `Package` inside `MediaBuy`), or inside an array of resources (e.g. each element of `products: Product[]`). Adapters MUST strip the key from every occurrence before egress, not just the outermost one.
`PropertyList` and `CollectionList` declare `additionalProperties: false` and are out of scope until a follow-up PR widens those schemas; until then, adapters needing round-trip state for those resources should track it out-of-band.
**Distinction from neighboring conventions**:
* `ext.{vendor}` — vendor-namespaced, **buyer-visible**, travels on the wire. Use for vendor-specific data the buyer should see (e.g. `ext.gam.line_item_id`).
* `context` / `context_id` — caller-echoed correlation data, also wire-visible. Despite the prefix-match, `ctx_metadata` is not a sub-namespace of these — they are unrelated concepts and travel on different layers.
* `ctx_metadata` — **adapter-internal only**, MUST be stripped before egress, never reaches the buyer.
**Adapter conformance**:
```
1. Read ctx_metadata from inbound resource (publisher → SDK direction).
2. Carry it in adapter-local state.
3. Before serializing the resource for wire egress (SDK → buyer direction):
a. Remove the ctx_metadata key.
b. If the key was present and non-empty, emit a warning-level log:
"stripping reserved ctx_metadata before egress on "
4. Buyer-facing surfaces MUST NOT expose ctx_metadata in any documentation,
typed shape, or example.
```
**Reviewer checklist**:
* Reject any spec, schema, or example that promotes `ctx_metadata` as a buyer-readable field.
* Reject any SDK contribution that surfaces `ctx_metadata` in a buyer-facing typed return.
* Accept SDK code that reads/writes `ctx_metadata` as adapter-internal state, provided the egress-strip + warning-log path is in place.
## Breaking Changes
### What Constitutes a Breaking Change
**Major version bump required**:
* Removing enum values
* Renaming fields
* Changing field types
* Making optional fields required
* Removing fields entirely
**Minor version bump allowed**:
* Adding new enum values (append-only)
* Adding new optional fields
* Clarifying descriptions
* Adding new tasks/endpoints
### Migration Strategy
When making breaking changes:
1. **Create v2 directory**: `/schemas/3.2.8/`
2. **Maintain v1**: Keep old schemas functional
3. **Document migration**: Provide before/after examples
4. **Deprecation period**: Support both versions for defined period
## JSON Schema Conventions
### Dialect roadmap
AdCP 3.x source schemas remain JSON Schema draft-07. The 3.2 build generates a
JSON Schema 2020-12 projection under `/schemas/{version}/mcp/2026-07-28/` for
MCP tool declarations. Projected `outputSchema` files preserve canonical
validation semantics. Projected `inputSchema` files are intentionally
permissive discovery hints: unconditional object surfaces are flattened, while
strict-host-incompatible root combinators are omitted and enforced by canonical
draft-07 validation at call time. Do not author 2020-12-only validation behavior
in 3.x source schemas.
AdCP 4.0 will move the canonical source dialect directly to JSON Schema
2020-12. Contract tightening such as selective `unevaluatedProperties: false`
belongs to that major-version migration. It must not be introduced by the 3.2
projection generator.
### Nullable Scalars
For AdCP 3.x draft-07 schemas, encode nullable scalar fields as a JSON Schema
type union:
```json theme={null}
{ "type": ["string", "null"] }
```
Use the same pattern for nullable numbers, integers, booleans, and mixed scalar
value buckets. Do not introduce OpenAPI-style `nullable: true` in source
schemas; it is not part of JSON Schema Draft 07 and creates inconsistent SDK
projection rules.
Nullable enums must include `null` in both the `type` union and the `enum` value
set:
```json theme={null}
{
"type": ["string", "null"],
"enum": ["active", "paused", null]
}
```
Nullability and presence are separate in JSON Schema Draft 07:
* `type: ["string", "null"]` means the field may be `null` when it is present.
* The enclosing object's `required` array controls whether the field must be present.
* Optional nullable fields therefore have three states: omitted, present with `null`,
and present with a scalar value.
* Required nullable fields have two states: present with `null` or present with a
scalar value.
When omission and explicit `null` carry different semantics, state that distinction
in the field description so SDK generators do not collapse the cases.
## Testing Schemas
All schema changes must:
1. ✅ Validate with JSON Schema Draft 07
2. ✅ Pass example data through validation
3. ✅ Generate types successfully (Python, TypeScript)
4. ✅ Update documentation to match
5. ✅ Include an `adcontextprotocol` changeset describing the schema change
## Review Checklist
Before merging schema changes, verify:
* [ ] No duplicate enum names across different files
* [ ] No ambiguous field names (like bare "type")
* [ ] All enums referenced via `$ref`, not inline
* [ ] Breaking changes use proper versioning
* [ ] Documentation updated to match schemas
* [ ] Examples validate against new schemas
* [ ] Type generation tested
* [ ] `adcontextprotocol` changeset created with proper version bump
## Philosophy
**"The schema is the spec"**
Documentation should reflect what's in schemas, but schemas are the source of truth. When documentation and schemas diverge, schemas win. This means:
* Write clear, detailed descriptions in schemas
* Use semantic names that are self-documenting
* Design for type generation, not just validation
* Think about developer ergonomics across languages
**"Make the right thing easy"**
Good schema design guides implementers toward correct usage:
* Use discriminators so type checkers catch mistakes
* Use semantic names so code reads clearly
* Consolidate enums so generators produce clean types
* Restrict where necessary, but don't over-restrict
## Questions?
When in doubt about schema design decisions:
1. Check existing patterns in `/schemas/3.2.8/`
2. Consider impact on type generation
3. Ask: "Will this name collision cause issues?"
4. Prefer specificity over brevity
5. Document rationale in this file for future reference
# get_account_financials
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/accounts/tasks/get_account_financials
get_account_financials returns spend summaries, credit balances, payment status, and invoice history for operator-billed AdCP accounts. Requires account_financials capability.
Query financial status for an operator-billed account — spend summary, credit or prepay balance, payment status, and invoice history. This gives budget-aware agents the context they need to make spend decisions without leaving the protocol.
`get_account_financials` is only available when the seller declares `account_financials: true` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). It applies to **operator-billed accounts** only. For agent-billed accounts, the agent's own billing system is the source of truth.
**Response Time**: \~1s.
**Request Schema**: [`/schemas/3.2.8/account/get-account-financials-request.json`](https://adcontextprotocol.org/schemas/3.2.8/account/get-account-financials-request.json)
**Response Schema**: [`/schemas/3.2.8/account/get-account-financials-response.json`](https://adcontextprotocol.org/schemas/3.2.8/account/get-account-financials-response.json)
## Quick start
Check remaining credit before launching a campaign:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
const result = await testAgent.getAccountFinancials({
account: { account_id: "acc_acme_001" },
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
if ("errors" in result.data && result.data.errors) {
throw new Error(`Operation failed: ${JSON.stringify(result.data.errors)}`);
}
const { spend, credit, payment_status } = result.data;
console.log(`Spent: $${spend?.total_spend} this period`);
if (credit) {
console.log(`Available credit: $${credit.available_credit} of $${credit.credit_limit}`);
}
if (payment_status === "past_due") {
console.log("Warning: payment is past due — campaigns may be paused");
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.get_account_financials(
account={"account_id": "acc_acme_001"},
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
print(f"Spent: ${result.spend.total_spend} this period")
if hasattr(result, 'credit') and result.credit:
print(f"Available credit: ${result.credit.available_credit} of ${result.credit.credit_limit}")
if getattr(result, 'payment_status', None) == 'past_due':
print("Warning: payment is past due — campaigns may be paused")
asyncio.run(main())
```
## Request parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | object | Yes | [Account reference](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) — by `account_id` or natural key (`brand` + `operator` + optional `sandbox`). Must be an operator-billed account. |
| `period` | object | No | Date range for spend summary: `start` and `end` as ISO 8601 dates. Defaults to the current billing cycle if omitted. |
## Response
**Success response:**
Returns financial data for the account. Only `account`, `currency`, `period`, and `timezone` are guaranteed — everything else depends on what the seller exposes.
| Field | Description |
| - | - |
| `account` | Account reference, echoed from the request. |
| `currency` | ISO 4217 currency code for all monetary amounts. |
| `period` | Actual period covered (`start`, `end`). May differ from requested period if adjusted to billing cycle boundaries. |
| `timezone` | IANA timezone of the seller's billing day boundaries (e.g., `America/New_York`). All dates in the response are calendar dates in this timezone. It may differ from `Account.timezone`, reporting timezone, or a feature-specific cap timezone; use this explicit value for financial periods. |
| `spend` | Spend summary: `total_spend` (amount in `currency`) and optional `media_buy_count`. |
| `credit` | Present for credit-based accounts. Contains `credit_limit`, `available_credit`, and optional `utilization_percent` (0-100). |
| `balance` | Present for prepay accounts. Contains `available` balance and optional `last_top_up` (`amount`, `date`). |
| `payment_status` | `current`, `past_due`, or `suspended`. |
| `payment_terms` | Payment terms in effect: `net_15`, `net_30`, `net_45`, `net_60`, `net_90`, or `prepay`. |
| `invoices` | Array of recent invoices: `invoice_id`, `amount`, `status` (`draft`, `issued`, `paid`, `past_due`, `void`), optional `period`, `due_date`, `paid_date`. |
**Error response:**
* `errors` -- Array of operation-level errors. No financial data is present.
**Note:** Responses use discriminated unions -- you get either financial data OR `errors`, never both.
## Common scenarios
### Budget check before campaign launch
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
const financials = await testAgent.getAccountFinancials({
account: { account_id: "acc_acme_001" },
});
if (!financials.success || "errors" in financials.data) {
throw new Error("Could not check financials");
}
const campaignBudget = 15000;
const { credit } = financials.data;
if (credit && credit.available_credit < campaignBudget) {
console.log(
`Insufficient credit: $${credit.available_credit} available, ` +
`$${campaignBudget} needed. ` +
`Credit utilization: ${credit.utilization_percent}%`
);
} else {
console.log("Budget check passed — proceeding with campaign");
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
financials = await test_agent.simple.get_account_financials(
account={"account_id": "acc_acme_001"},
)
if hasattr(financials, 'errors') and financials.errors:
raise Exception("Could not check financials")
campaign_budget = 15000
credit = getattr(financials, 'credit', None)
if credit and credit.available_credit < campaign_budget:
print(
f"Insufficient credit: ${credit.available_credit} available, "
f"${campaign_budget} needed. "
f"Credit utilization: {credit.utilization_percent}%"
)
else:
print("Budget check passed — proceeding with campaign")
asyncio.run(main())
```
### Prepay balance monitoring
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
const financials = await testAgent.getAccountFinancials({
account: {
brand: { domain: "acme-corp.com" },
operator: "acme-corp.com",
},
});
if (!financials.success || "errors" in financials.data) {
throw new Error("Could not check financials");
}
const { balance } = financials.data;
if (balance && balance.available < 2000) {
console.log(
`Low balance warning: $${balance.available} remaining. ` +
`Consider topping up before launching new campaigns.`
);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
financials = await test_agent.simple.get_account_financials(
account={
"brand": {"domain": "acme-corp.com"},
"operator": "acme-corp.com",
},
)
if hasattr(financials, 'errors') and financials.errors:
raise Exception("Could not check financials")
balance = getattr(financials, 'balance', None)
if balance and balance.available < 2000:
print(
f"Low balance warning: ${balance.available} remaining. "
f"Consider topping up before launching new campaigns."
)
asyncio.run(main())
```
## Error handling
| Error Code | Description | Resolution |
| - | - | - |
| [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) | Account uses agent billing — financials not available from seller | Query your own billing system for agent-billed accounts |
| `UNSUPPORTED_FEATURE` | Seller doesn't have financial data for this account or period | Verify `account_financials` capability is `true` |
| [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found) | Account does not exist or is not accessible | Check account reference or re-sync |
## Next steps
* [list_accounts](/dist/docs/3.2.8/accounts/tasks/list_accounts) -- Discover accounts and check their status
* [get_adcp_capabilities](/dist/docs/3.2.8/protocol/get_adcp_capabilities) -- Check `account_financials` before calling this task
* [Accounts and agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) -- Billing models and account references
# list_account_changes
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/accounts/tasks/list_account_changes
list_account_changes reads the durable ordered feed of material changes to authoritative state on one shared advertiser account.
`list_account_changes` returns material changes to AdCP-visible state on one
account, including changes made outside the observing buyer's calls. Use it
after a snapshot bootstrap, after receiving `account.change_recorded`, or for
an account-level audit of state transitions.
> [!NOTE]
>
> **Experimental.** The account change feed (`list_account_changes`, the `account.change_recorded` webhook, the `account.change_feed` capability block on [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities), and the [`CURSOR_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-cursor-expired) error code) is part of AdCP 3.2 as an experimental surface. [RFC #6810](https://github.com/adcontextprotocol/adcp/issues/6810) is still open, so the surface may change between 3.x releases with at least 6 weeks' notice. Sellers implementing any part of it MUST declare `account.change_feed` in `experimental_features`. See [experimental status](/dist/docs/3.2.8/reference/experimental-status) for the full contract.
The feed is optional and appears only when
`get_adcp_capabilities.account.change_feed.supported` is `true` and
`experimental_features` contains `account.change_feed`.
## What the feed covers
For every resource type the seller advertises, a material committed change
must both appear here and be reflected on its authoritative read, regardless
of whether it originated through AdCP, a seller operator or system, another
authorized principal, or a connected platform.
The feed describes control-plane changes: creation, configuration, lifecycle,
relationships, reporting corrections, and deletion markers. It excludes
reads, failed operations, dry runs, exact idempotency replays, delivery counter
increments, raw audience members, raw events, catalog item bodies, and webhook
delivery attempts.
For the complete coverage matrix and rationale, see the
[account change feed design spec](https://github.com/adcontextprotocol/adcp/blob/main/specs/account-change-feed.md).
## Request
**Request schema:** [`account/list-account-changes-request.json`](https://adcontextprotocol.org/schemas/3.2.8/account/list-account-changes-request.json)
| Field | Required | Description |
| - | - | - |
| `account` | Yes | Exactly one account reference. |
| `cursor` | No | Opaque checkpoint from an earlier call under the same principal, authorization epoch, account, and filters. Mutually exclusive with `starting_position`. |
| `starting_position` | No | `earliest` (intentional completeness-first default) or `latest`. Use `latest` before a snapshot bootstrap. |
| `resource_types` | No | Exact resource-type filter. The cursor is bound to the normalized filter. |
| `max_results` | No | 1–100 changes; default 50. |
Acquire a high-water checkpoint before reading several snapshots:
```json theme={null}
{
"adcp_version": "3.2",
"account": { "account_id": "acc_luma_shared" },
"starting_position": "latest",
"max_results": 100
}
```
## Response
**Response schema:** [`account/list-account-changes-response.json`](https://adcontextprotocol.org/schemas/3.2.8/account/list-account-changes-response.json)
| Field | Description |
| - | - |
| `changes` | Oldest-first material change records. |
| `cursor` | Checkpoint after the scanned high-water. Always present, even on an empty tail page. |
| `has_more` | Whether more retained matching records were available when the page was generated. |
| `available_since` | Current retention boundary for this caller and account. |
| `generated_at` | Seller time for the page and coverage watermarks. |
| `source_coverage` | Optional per-account connected-source status and mechanically evaluable freshness. A connected source reporting `current` supplies `last_successful_sync_at` and `stale_after_seconds`. |
Each change record names the changed resource, action, server-derived origin,
optional changed paths and revision, and an allowlisted read-only
`repair.task` hint. It deliberately does not include full before/after values.
```json theme={null}
{
"changes": [
{
"change_id": "chg_01K38G7X8ZGX9T4F1Q5W6Y2M3N",
"recorded_at": "2026-08-24T11:58:04Z",
"resource": {
"type": "creative",
"account_id": "acc_luma_shared",
"resource_id": "cr_8421"
},
"action": "updated",
"origin": {
"kind": "connected_platform",
"connection_id": "conn_social_primary"
},
"changed_paths": ["/name", "/assets/0"],
"repair": { "task": "list_creatives" }
}
],
"cursor": "opaque-checkpoint",
"has_more": false,
"available_since": "2026-05-26T00:00:00Z",
"generated_at": "2026-08-24T12:00:00Z"
}
```
## Cursor contract
Cursor order, not timestamps, defines the total order. Appends never reorder
prior pages. A filtered empty page still advances across scanned nonmatching
records, so persist every returned cursor.
A cursor is scoped to the authenticated principal, resolved account, and
normalized filters. Do not move it between credentials or filter sets. Sellers
MUST reject a principal, account, or filter mismatch with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) at
`cursor`; applying new filters at an old position could permanently skip
history.
The cursor also binds an authorization-scope epoch. If visible resources for
the principal expand or contract, the seller returns [`CURSOR_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-cursor-expired) with
`details.reason: "authorization_scope_changed"`. Rebootstrap snapshots so
changes skipped under the old visibility cannot become an invisible gap.
Sellers retain changes for at least 90 days. An expired cursor returns
[`CURSOR_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-cursor-expired); it never silently restarts. Recovery is to obtain a new
`latest` checkpoint, rebuild all authoritative snapshots, then drain changes
after the checkpoint.
## Race-free bootstrap
1. Register `account.change_recorded` through [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts#account-change-feed-notifications).
2. Obtain C0 with `starting_position: "latest"`.
3. Enumerate [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts), [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys), [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives), financials,
delivery, and other advertised reads for the account. Include all lifecycle
statuses and exhaust every page.
4. Drain changes after C0. Locally allowlist `repair.task`, construct and
validate the read request from the authenticated account and `resource`
identity, then invoke it. Never dispatch feed-supplied task arguments.
5. Persist the returned cursor and repeat after each signed notification.
6. Poll periodically so a missed webhook does not create a gap.
The webhook's optional `through_cursor` is only a target watermark. Do not
install it without reading all intervening pages.
## Change granularity
The feed contains at least one record per independently repairable identity.
Several package or assignment changes may coalesce under their media buy when
[`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) repairs the complete changed closure; changes to independent
creatives require separate records. Records from one operation may share
`batch_id`, but retain independent `change_id` values and notifications.
For seller-mediated mutations, snapshot and records commit atomically. For an
external platform, records commit with the seller's ingestion of the observed
change. A pass-through authoritative read may lead the feed only within the
source's declared `stale_after_seconds` freshness bound.
## Shared-account example
Suppose a connected platform changes `cr_8421` while the buyer is idle. The
seller records the creative revision, makes it visible on [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives),
appends the account change, and then fires `account.change_recorded`. The buyer
drains from its cursor and rereads `list_creatives`; it does not treat the
webhook payload as the creative document.
This is the same flow for a seller operator changing a campaign budget or
another authorized buyer pausing a package. Account visibility is based on
current authorization, not on which principal created the resource.
## Relationship to `webhook_activity`
`webhook_activity[]` answers whether a webhook delivery was attempted. This
feed answers which material business-state changes were recorded. A change can
exist even when a webhook is missed; one change can also have several delivery
attempts. Never use the transport log as account history.
# list_accounts
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/accounts/tasks/list_accounts
list_accounts returns all advertiser accounts an authenticated agent can operate on an AdCP vendor agent. Works across media buy, signals, governance, and creative protocols.
Returns all accounts the authenticated agent can operate on this vendor agent. Use this to discover existing accounts, check status changes on pending accounts, and recover the exact account reference expected on protocol operations.
Account visibility is source-neutral: the seller MUST return every account the
authenticated caller can operate, including pre-existing accounts created or
managed through seller and connected-platform surfaces. `list_accounts` is not
limited to relationships first provisioned through [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts).
For upstream-managed account namespaces, `list_accounts` is not optional discovery polish; it is the namespace discovery contract. The upstream platform owns the accessible account set, so buyers MUST resolve an explicit `account_id` before the first account-scoped request. If the authenticated credential can access more than one account, the seller MUST expose `list_accounts`; if it can access exactly one account, the seller SHOULD expose `list_accounts` returning that singleton so SDKs can auto-select it and still send `{ "account_id": "..." }` on required-account calls. [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) provisioning does not create account-id accounts in 3.0.x unless a future explicit capability declares that mode; if `sync_accounts` is exposed on these sellers today, use it only for settings updates against an account already identified by `account_id`.
`list_accounts` works across all vendor protocols — media buy agents, signals agents, governance agents, and creative agents all return accounts through this same task.
**Response Time**: \~1s.
**Request Schema**: [`static/schemas/source/account/list-accounts-request.json`](https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/source/account/list-accounts-request.json)
**Response Schema**: [`/schemas/3.2.8/account/list-accounts-response.json`](https://adcontextprotocol.org/schemas/3.2.8/account/list-accounts-response.json)
## Quick Start
List all accounts this agent can operate:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { ListAccountsResponseSchema } from "@adcp/sdk";
const result = await testAgent.listAccounts({});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = ListAccountsResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
for (const account of validated.accounts) {
console.log(`${account.account_id}: ${account.name} (${account.status})`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.list_accounts()
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for account in result.accounts:
print(f"{account.account_id}: {account.name} ({account.status})")
asyncio.run(main())
```
## Request Parameters
All parameters are optional. An empty request returns all accounts visible to
the authenticated caller. Use `account` when re-reading one known account by
seller-assigned `account_id` or by the complete buyer-declared natural key.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | object | No | Exact account filter. Pass `{ "account_id": "..." }` after seller/storefront discovery, or the complete natural key (`brand`, `operator`, and optional `operator_unit`, `currency`, buyer-selected `timezone`, and `sandbox`) for buyer-declared accounts. The seller returns only matching accounts visible to the authenticated caller. |
| `status` | string | No | Filter by account status: `active`, `pending_approval`, `rejected`, `payment_required`, `suspended`, or `closed`. |
| `sandbox` | boolean | No | When true, return only sandbox accounts. When false, return only production accounts. Omit to return both. Primarily used with account-id namespaces where sandbox accounts are pre-existing test accounts on the platform. |
| `include_webhook_activity` | boolean | No | When true, request recent webhook delivery attempts for each returned account in `webhook_activity[]`. |
| `webhook_activity_limit` | integer | No | Maximum number of `webhook_activity[]` records to return per account when `include_webhook_activity` is true. Default 50, max 200. |
| `pagination` | object | No | Pagination cursor for large account sets. |
## Response
| Field | Description |
| - | - |
| `accounts` | Array of account objects (see below) |
| `errors` | Array of errors, if the request failed |
| `pagination` | Pagination cursor for the next page, if more results exist |
**Each account includes:**
| Field | Description |
| - | - |
| `account_id` | Seller/storefront identifier. Use it on protocol tasks when the seller declares an account-id namespace. It is distinct from `operator_unit.id`, which belongs to the buyer-side operator. May be absent when `status: "rejected"`. |
| `name` | Vendor agent's display name for the account |
| `brand` | Brand reference: `domain`, optional `brand_id`, and optional commercial-identity `countries[]`. Countries are not delivery targeting. |
| `operator` | Operator domain. Always present — when the brand operates directly, `operator` equals the brand's domain. |
| `operator_unit` | Optional operator-owned unit. `id` is stable identity; `name` is mutable display metadata. |
| `revision` | Current account optimistic-concurrency revision. Sellers advertising `account.identity_updates.supported: true` always return it; pass it in the next [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) settings update. |
| `identity_change` | Pending or rejected desired operator identity. While present, `operator` and `operator_unit` remain the current canonical identity. Poll until the change applies or is rejected. |
| `currency` | Optional immutable account currency. When present, media buys on the account must use it. |
| `timezone` | Immutable operational timezone for the account. It is the default for account-scoped calendar behavior unless a feature explicitly declares another timezone basis. |
| `status` | Current account state: `active`, `pending_approval`, `rejected`, `payment_required`, `suspended`, or `closed` |
| `billing` | Billing model in effect: `operator` or `agent` |
| `account_scope` | How the seller scoped this account: `operator`, `brand`, `operator_brand`, or `agent`. See [account scope](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-scope). |
| `payment_terms` | Payment terms agreed for this account: `net_15`, `net_30`, `net_45`, `net_60`, `net_90`, or `prepay`. Binding for all invoices when the account is active. |
| `governance_agents` | Governance agent endpoints registered on this account. Present when governance agents have been configured via [`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance). |
| `reporting_delivery_configs` | Experimental caller-visible resolved durable reporting configuration states, including setup/readiness, destination binding, immutable generation, and deactivation cutoff. Another caller's configurations are never returned. |
| `setup` | Present when `status: "pending_approval"`. Contains `url` for completing setup and `message` explaining what's needed. |
| `authorization` | Optional. The calling agent's scope grant for this account — `allowed_tasks`, `field_scopes`, `scope_name`, `read_only`. Applies to every vendor agent type (media-buy, signals, governance, creative, brand) — the Accounts Protocol surface is shared. Vendor agents that support scope introspection SHOULD populate this; media-buy sales agents claiming the `attestation_verifier` standard scope MUST populate it. Absence means the vendor agent does not advertise introspectable scope for this account; callers MUST NOT infer access from absence and fall back to error-driven discovery via the RBAC error codes. See [Caller authorization](/dist/docs/3.2.8/accounts/overview#caller-authorization) for the full shape and semantics. |
| `notification_configs` | Account-level webhook subscribers registered via [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts#account-level-webhook-subscriptions). Each entry carries `subscriber_id`, `url`, `event_types[]`, and `active`. Present when the account has any persisted subscribers. `subscriber_id` is the account-scoped logical key; re-registering the same subscriber replaces that subscriber's config. `authentication.credentials` is omitted on every entry (write-only). Use this surface to verify what's active after a sync, audit fan-out across multiple subscribers, and detect drift between buyer-side expectations and seller-side persisted state. `account.status_changed` subscribers repair by rereading this account; `account.change_recorded` subscribers drain [`list_account_changes`](/dist/docs/3.2.8/accounts/tasks/list_account_changes) and invoke each record's repair task. |
| `webhook_activity` | Optional recent webhook delivery attempts for this account, returned when `include_webhook_activity: true` and the seller exposes the debug log. Omitted means unsupported or not requested; `[]` means supported but no retained fires; non-empty records are most recent first. |
For buyer-declared accounts, `list_accounts` MUST return the current canonical natural-key fields needed to use the account again. A stateless buyer can therefore take `brand`, `operator`, `operator_unit`, `currency`, buyer-selected `timezone`, and `sandbox` from the response and send the same shape as `account` on a later task. `operator_unit.name` may change without changing which account the key identifies. A requested identity in `identity_change` is not a usable account reference until it becomes canonical.
### Single-publisher cardinality
A seller serving exactly one publisher entity MAY return that entity as the sole account on `list_accounts` responses, regardless of calling principal. The *"Direct advertiser with single account"* example in [`list-accounts-response.json`](https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/source/account/list-accounts-response.json) is canonical for this case — a single-element `accounts[]` with no `pagination` envelope at all.
Pagination conformance requiring `pagination.has_more: true` does not apply when:
* `pagination` is absent entirely (canonical single-account shape), or
* `pagination.total_count` is present and ≤ 1
Runners SHOULD grade pagination-walk phases as `not_applicable` in either case. This pattern is conformant; the spec carries no `minItems` constraint on `accounts[]` and the single-account example is normative.
## Common Scenarios
### Poll until account becomes active
After [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) returns `pending_approval`, poll until the account is ready:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { ListAccountsResponseSchema } from "@adcp/sdk";
async function waitForAccount(targetAccountId, maxAttempts = 20) {
for (let i = 0; i < maxAttempts; i++) {
const result = await testAgent.listAccounts({ status: "active" });
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = ListAccountsResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("accounts" in validated) {
const account = validated.accounts.find(a => a.account_id === targetAccountId);
if (account) {
console.log(`Account active: ${account.account_id}`);
return account;
}
}
// Wait 30 seconds before polling again
await new Promise(resolve => setTimeout(resolve, 30_000));
}
throw new Error(`Account ${targetAccountId} did not become active`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def wait_for_account(target_account_id: str, max_attempts: int = 20):
for _ in range(max_attempts):
result = await test_agent.simple.list_accounts(status='active')
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
account = next(
(a for a in result.accounts if a.account_id == target_account_id),
None
)
if account:
print(f"Account active: {account.account_id}")
return account
await asyncio.sleep(30)
raise Exception(f"Account {target_account_id} did not become active")
```
### Reconcile account status webhooks
After receiving `account.status_changed`, re-read the account snapshot. The webhook tells you which account changed; `list_accounts` is the source of truth for the current status, setup hints, billing terms, and authorization.
The [seller-mediated account provisioning walkthrough](/dist/docs/3.2.8/accounts/provisioning-walkthrough#observe-and-reconcile-resolution) shows this invalidation-and-repair pattern in context.
```javascript theme={null}
async function handleAccountStatusWebhook(req, res) {
if (!verifyWebhookSignature(req)) return res.status(401).end();
const fire = req.body; // account-status-changed-webhook
if (await alreadyProcessed(fire.idempotency_key)) return res.status(200).end();
const result = await testAgent.listAccounts({
account: { account_id: fire.account_id },
include_webhook_activity: true,
webhook_activity_limit: 20
});
const account = result.accounts[0];
await reconcileAccount(account);
await markProcessed(fire.idempotency_key);
return res.status(200).end();
}
```
### Filter active accounts only
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { ListAccountsResponseSchema } from "@adcp/sdk";
const result = await testAgent.listAccounts({ status: "active" });
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = ListAccountsResponseSchema.parse(result.data);
if ("accounts" in validated) {
for (const account of validated.accounts) {
console.log(`${account.account_id}: ${account.name} — billing: ${account.billing}`);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.list_accounts(status='active')
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for account in result.accounts:
print(f"{account.account_id}: {account.name} — billing: {account.billing}")
asyncio.run(main())
```
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found) | No accounts found for this agent | Run [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) first to establish a buying relationship |
## Next Steps
* [sync_accounts](/dist/docs/3.2.8/accounts/tasks/sync_accounts) — Sync advertiser accounts with a seller
* [sync_governance](/dist/docs/3.2.8/accounts/tasks/sync_governance) — Sync governance agents to accounts
* [Accounts and agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) — Billing models, trust models, and authorized operators
* [Brand protocol](/dist/docs/3.2.8/brand-protocol/brand-json) — How vendor agents resolve brand identity from the brand's `domain`
# report_usage
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/accounts/tasks/report_usage
report_usage sends consumption data to AdCP vendor agents after campaign delivery — impressions served, signals queried, governance checks run — so vendors can track revenue and verify billing.
Reports how a vendor's service was consumed after campaign delivery. Called by orchestrators to inform a vendor agent (signals, governance, creative) what was used so the vendor can track earned revenue and verify billing. It is also used against the sales agent itself when a media buy names the buyer or a measurement vendor as the billing authority.
Each usage record is self-contained — it carries its own `account` and `media_buy_id`. A single request can span multiple accounts and campaigns.
**Response Time**: \~1s.
**Response Schema**: [`/schemas/3.2.8/account/report-usage-response.json`](https://adcontextprotocol.org/schemas/3.2.8/account/report-usage-response.json)
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `idempotency_key` | string | Recommended | Client-generated unique key for this request (UUID recommended). If a request with the same key has already been accepted, the server returns the original response without re-processing. Prevents duplicate billing on retries. |
| `reporting_period` | object | Yes | `start` and `end` as ISO 8601 date-time in UTC. Applies to all records in the request. |
| `usage` | UsageRecord\[] | Yes | One or more usage records. |
### Usage Record Fields
Each record requires `account`, `vendor_cost`, and `currency`. Additional fields depend on the vendor type:
| Field | Type | Required | Description |
| - | - | - | - |
| `account` | [AccountRef](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) | Yes | Account for this record — by `account_id` or `{ brand, operator }`. |
| `vendor_cost` | number | Yes | Amount owed to the vendor for this record, in `currency` |
| `currency` | string | Yes | ISO 4217 currency code |
| `pricing_option_id` | string | Vendor: Yes | Pricing option from the vendor's discovery response ([`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals), [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives), [`list_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/list_content_standards), [`list_property_lists`](/dist/docs/3.2.8/governance/property/tasks/property_lists#list_property_lists)) or execution response ([`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative)). The vendor uses this to verify the correct rate was applied. |
| `impressions` | number | Signals: Yes | Impressions delivered |
| `media_spend` | number | percent_of_media: Yes | Media spend for percent-of-media cost verification |
| `media_buy_id` | string | Revenue share: Yes | Media buy whose selected package pricing is being reconciled. |
| `conversions` | number | No | Number of attributed conversion events. Optional analytics context for revenue share. |
| `conversion_value` | number | No | Total attributed conversion value. Optional analytics context; not the revenue-share billing basis. |
| `commissionable_value` | number | Revenue share: Yes | Settled attributed value eligible for commission. The seller verifies `vendor_cost = round_currency(commissionable_value × commission_rate)`. |
| `signal_agent_segment_id` | string | Signals: Yes | Signal identifier from `get_signals` |
| `creative_id` | string | Creative: Yes | Creative identifier from `build_creative` or `list_creatives`. Links usage to a specific creative for billing verification. A `build_creative` variant leaf earns a `creative_id` only when trafficked/added to the library — discarded best-of-N or fan-out variants are never reported here; their charge is the inline per-leaf `vendor_cost` on the `build_creative` response (the authoritative record for untrafficked leaves). |
| `build_variant_id` | string | No | When the reported `creative_id` was promoted from a specific `build_creative` variant leaf but differs from that source id, carry the source `build_variant_id` for reconciliation. On the canonical path where `creative_id` is the kept `build_variant_id`, omit this field. |
| `property_list_id` | string | Property lists: Yes | Property list identifier from `list_property_lists`. Links usage to a specific property list for billing verification. |
For revenue-share records, `pricing_option_id` identifies the agreed rate and commission basis. `currency` must match the selected option, and `vendor_cost` must not exceed the package's commission budget.
## Response
| Field | Description |
| - | - |
| `accepted` | Number of usage records successfully stored |
| `errors` | Validation errors for individual records. Partial acceptance is valid — accepted records are stored even when some fail. |
## Examples
### Signal usage — single campaign
```json Request theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"reporting_period": {
"start": "2025-03-01T00:00:00Z",
"end": "2025-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_pinnacle_signals" },
"signal_agent_segment_id": "luxury_auto_intenders",
"pricing_option_id": "po_lux_auto_cpm",
"impressions": 4200000,
"media_spend": 21000.00,
"vendor_cost": 2100.00,
"currency": "USD"
}
]
}
```
```json Response theme={null}
{
"accepted": 1
}
```
### Creative usage — ad server with CPM pricing
```json Request theme={null}
{
"idempotency_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reporting_period": {
"start": "2026-03-01T00:00:00Z",
"end": "2026-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_acme_creative" },
"creative_id": "cr_88201",
"pricing_option_id": "po_video_cpm",
"impressions": 2400000,
"vendor_cost": 1200.00,
"currency": "USD"
}
]
}
```
```json Response theme={null}
{
"accepted": 1
}
```
### Multi-account batch
A single request spanning two campaigns across two accounts:
```json theme={null}
{
"idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"reporting_period": {
"start": "2025-03-01T00:00:00Z",
"end": "2025-03-31T23:59:59Z"
},
"usage": [
{
"account": { "account_id": "acct_pinnacle_signals" },
"signal_agent_segment_id": "luxury_auto_intenders",
"pricing_option_id": "po_lux_auto_cpm",
"impressions": 2100000,
"vendor_cost": 1050.00,
"currency": "USD"
},
{
"account": { "account_id": "acct_nova" },
"signal_agent_segment_id": "eco_conscious_shoppers",
"pricing_option_id": "po_eco_cpm",
"impressions": 800000,
"vendor_cost": 400.00,
"currency": "USD"
}
]
}
```
### Partial acceptance
If some records fail validation, the response identifies how many were accepted:
```json theme={null}
{
"accepted": 1,
"errors": [
{
"code": "INVALID_PRICING_OPTION",
"message": "pricing_option_id 'po_unknown' does not exist on this account",
"field": "usage[1].pricing_option_id"
}
]
}
```
## Retry Safety
Always include `idempotency_key` in production usage. If a request times out or returns a network error, retry with the same key — the server will return the original result without double-counting.
An idempotent replay is transparent: the server returns the original response unchanged and does not emit a `DUPLICATE_REQUEST` error or advisory.
Generate a fresh UUID per request, not per usage record. If you need to report additional records for the same period, submit a new request with a new key.
## Reporting cadence
Report at regular intervals — monthly at minimum. For campaigns with significant spend, weekly reporting gives vendor agents timely visibility into earned revenue.
Report upon campaign completion to close out the final period.
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found) | Account reference in a usage record not found or not accessible | Verify via [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts); re-run [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) if needed |
| [`INVALID_USAGE_DATA`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-usage-data) | A usage record has missing or invalid fields | Check required fields for your vendor type |
| [`INVALID_PRICING_OPTION`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-pricing-option) | `pricing_option_id` not found on this account | Verify `pricing_option_id` from the vendor's discovery response |
## Next Steps
* [sync_accounts](/dist/docs/3.2.8/accounts/tasks/sync_accounts) — Sync advertiser accounts with a seller before reporting
* [Accounts Protocol](/dist/docs/3.2.8/accounts/overview) — How account establishment and settlement fit together
* [Accounts and agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) — Billing hierarchy and operator model
# sync_accounts
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/accounts/tasks/sync_accounts
sync_accounts provisions buyer-declared accounts or updates settings on existing accounts with an AdCP seller agent.
Sync advertiser accounts with a seller for one or more advertiser/operator relationships, or update settings on existing accounts when the seller exposes that mode. A buyer-declared account's natural key describes the advertiser object the seller should provision: a brand, the countries where that advertiser identity applies, the operator, an optional operator-owned unit, an optional fixed currency, an optional buyer-selected immutable timezone, and whether the account is a sandbox.
`sync_accounts` is used across all seller protocols: media buy agents, signals agents, governance agents, and creative agents. In provisioning mode it declares the buyer's intent — the seller provisions or links accounts internally. Use provisioning mode for buyer-declared accounts (`require_operator_auth: false`) and use natural keys (`brand` + `operator`) on subsequent requests. Sellers MAY echo an `account_id` as an internal handle, but they MUST continue accepting the natural-key `AccountRef` for accounts provisioned this way. For account-id namespaces, discover seller-assigned account IDs via [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) or out-of-band onboarding; `sync_accounts` provisioning for account-id namespaces is out of scope unless a future explicit capability declares that mode. If such a seller exposes `sync_accounts` today, use only settings-update mode keyed by `account_id`.
For a complete `pending_approval` flow — capability discovery, human setup, durable status notification, authoritative repair, and first spend — see [Provision a seller-mediated account](/dist/docs/3.2.8/accounts/provisioning-walkthrough).
**Response Time**: \~1s. Account provisioning is synchronous; credit and legal review may require human action (indicated by `status: "pending_approval"` with a `setup.url`).
**Request Schema**: [`/schemas/3.2.8/account/sync-accounts-request.json`](https://adcontextprotocol.org/schemas/3.2.8/account/sync-accounts-request.json)
**Response Schema**: [`/schemas/3.2.8/account/sync-accounts-response.json`](https://adcontextprotocol.org/schemas/3.2.8/account/sync-accounts-response.json)
## Quick start
Sync a single advertiser account and check the resulting status:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAccountsResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncAccounts({
accounts: [
{
brand: { domain: "acme-corp.com" },
operator: "acme-corp.com",
billing: "operator",
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAccountsResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
for (const account of validated.accounts) {
console.log(`${account.brand.domain}: ${account.status}`);
if (account.status === "pending_approval" && account.setup?.url) {
console.log(` Complete setup at: ${account.setup.url}`);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_accounts(
accounts=[
{
"brand": {"domain": "acme-corp.com"},
"operator": "acme-corp.com",
"billing": "operator",
},
],
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for account in result.accounts:
print(f"{account.brand['domain']}: {account.status}")
if account.status == 'pending_approval' and hasattr(account, 'setup') and account.setup:
print(f" Complete setup at: {account.setup.url}")
asyncio.run(main())
```
## Request parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `accounts` | array | Yes | Array of account entries to sync (see below). |
| `delete_missing` | boolean | No | When true, accounts previously synced by this agent but not in this request are deactivated. Scoped to the authenticated agent. Default: `false`. |
| `dry_run` | boolean | No | When true, preview what would change without applying. Default: `false`. |
| `push_notification_config` | object | No | Webhook for async notifications when account status changes (e.g., `pending_approval` transitions to `active`). |
**Account entry fields:**
| Field | Type | Required | Description |
| - | - | - | - |
| `account` | object | Settings update | Existing account to update, selected by `account_id` or its current natural key. Its presence selects settings-update mode and prevents provisioning side effects. |
| `revision` | integer | With `operator_identity` | Expected current account revision in settings-update mode. It is required for identity changes and optional for existing non-identity settings updates. Sellers reject stale revisions atomically with [`CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflict). Obtain it from [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) or the latest `sync_accounts` result. |
| `operator_identity` | object | No | Complete desired operator identity in settings-update mode. Requires `account.identity_updates.supported: true`. Omit this field to leave identity unchanged; include it without `operator_unit` to remove the current unit. |
| `destination_billing_entity` | object | Operator-billed domain handoff | Complete staged billing identity for the destination operator. Required when changing `operator` on an account with `billing: "operator"`; otherwise absent. It is write-only while approval is pending and does not replace the canonical `billing_entity` until the handoff applies. |
| `brand` | object | Provisioning | Brand reference identifying the advertiser. Only its BrandKey fields — `domain`, optional `brand_id`, and the canonicalized ISO 3166-1 alpha-2 `countries[]` set — participate in account identity. Countries qualify commercial identity; they do not target delivery. The existing 3.x task still accepts broader BrandRef fields for compatibility, but mutable/per-call fields such as `industries`, `data_subject_contestation`, and `brand_kit_override` never affect lookup or upsert identity. New producers should send only BrandKey fields. |
| `operator` | string | Provisioning | Domain of the entity operating on the brand's behalf (e.g. `pinnacle-media.com`). When the brand operates directly, set to the brand's domain. Verified against the brand's `authorized_operators` in brand.json. |
| `operator_unit` | object | No | Operator-owned business unit, agency seat, or buying-platform account. `id` is the stable operator-assigned identifier and participates in the natural key; optional `name` is mutable display metadata and does not. This is not the seller's `account_id`. |
| `currency` | string | No | Immutable ISO 4217 transaction currency when the seller's advertiser object is currency-bound. Check `account.supported_account_currency_modes`: include `currency` for `fixed`; omit it for `per_media_buy`. If an older 3.x seller omits that capability, its currency model is not discoverable and must be established out of band. A supplied currency participates in the natural key and every media buy on the account must use it. |
| `timezone` | string | Conditional | Immutable operational timezone. Check `get_adcp_capabilities.account.timezone`: include one of `supported_timezones` when mode is `account_fixed` and selection is `buyer_selected`; omit it for `seller_fixed` or `seller_assigned`. A supplied timezone participates in the natural key. The seller echoes the effective timezone on `sync_accounts` and `list_accounts`. |
| `billing` | string | Provisioning | Who the seller invoices for this buyer–storefront account relationship: `operator`, `agent`, or `advertiser`. Check [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) for `supported_billing`. The seller must accept the requested invoiced party exactly or reject the request. This field does not choose a payment rail, clearing intermediary, or per-media-buy settlement route; AdCP payment and settlement remain out of protocol. Sellers MAY additionally reject a seller-wide supported value when the calling buyer agent's commercial relationship does not permit it. See [`BILLING_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-supported), [`BILLING_NOT_PERMITTED_FOR_AGENT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-permitted-for-agent), [Buyer-agent identity](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#buyer-agent-identity), and [Billing and Account Setup](/dist/docs/3.2.8/building/by-layer/L3/error-handling#billing-and-account-setup). |
| `billing_entity` | object | No | Structured business entity details for the account's current invoiced party. Contains `legal_name` (required), plus optional `vat_id`, `tax_id`, `registration_number`, `address`, `contacts`, and `bank`. Bank details are write-only — included in requests but never echoed in responses. Do not use this field to stage a destination operator during a handoff; use `destination_billing_entity`. See [billing entity and invoice recipient](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#billing-entity-and-invoice-recipient). |
| `payment_terms` | string | No | Payment terms for this account: `net_15`, `net_30`, `net_45`, `net_60`, `net_90`, or `prepay`. The seller must either accept these terms or reject the account — terms are never silently remapped. When omitted, the seller applies its default terms. |
| `sandbox` | boolean | No | When true, set up a sandbox account with no real platform calls or billing. Only applicable to buyer-declared accounts (`require_operator_auth: false`). For account-id namespaces, sandbox accounts are pre-existing test accounts discovered via [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) or supplied out-of-band. |
| `notification_configs` | array | No | Account-level webhook subscribers for events that outlive any single media buy: creative lifecycle notifications, account status changes, and wholesale feed change webhooks. Omit to leave existing subscribers unchanged; send `[]` to remove all subscribers; send a full array to replace. Entries are keyed by account-scoped `subscriber_id`; an existing `subscriber_id` is upserted, and persisted IDs absent from the sent array are removed. |
| `reporting_delivery_configs` | array | No | Experimental caller/account-owned durable reporting desired state. Each entry selects one atomic capability `offering_id` and its exact `report_definition_id`, chooses `delivery_only` or `consumer_receipt` reconciliation, and creates an immutable semantic `(delivery_config_id, delivery_config_version)` generation; only lifecycle intent may change in place. Billing uses `consumer_receipt`. Omit to preserve the caller's set; send `[]` to deactivate it. Destination coordinates are secret-free, and a caller-scoped immutable `destination_ref` may be reused across separately authorized accounts. See [`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status). |
**Natural key**: The tuple `(brand, operator, operator_unit.id, currency, timezone, sandbox)` identifies the advertiser object in the seller system, with `currency` present only for fixed-currency accounts and `timezone` present only for buyer-selected account-fixed timezones. Within `brand`, only `domain`, `brand_id`, and canonicalized `countries[]` participate. Country order has no semantic meaning; send unique uppercase codes in lexical order for stable keys and signatures. `operator_unit.name` and all mutable BrandRef fields are outside identity, so changing display or per-call metadata does not create a new account.
For example, the following key identifies Nova's NL/DE advertiser object, operated through Pinnacle's EMEA seat and fixed to EUR. Adding `sandbox: true` identifies a separate test account.
```json theme={null}
{
"brand": {
"domain": "nova-athletics.example",
"countries": ["DE", "NL"]
},
"operator": "pinnacle-media.example",
"operator_unit": {
"id": "seat_emea_01",
"name": "EMEA"
},
"currency": "EUR"
}
```
The natural key is the buyer-declared account reference. A numeric or opaque `account_id` is instead a seller/storefront identifier: discover it with `list_accounts` (or receive it out of band) and do not substitute an operator's buying-platform account ID into that field.
### Reconciling operator identity
When a buyer discovers that an existing account has the wrong operator domain or operator unit, it MUST identify the existing account through settings-update mode. Sending the corrected natural key as a new provisioning entry does not communicate replacement intent and can legitimately identify a second account.
`operator_identity` is a complete desired value, not a patch:
* Omit `operator_identity` to leave the operator identity unchanged.
* Include the same `operator` and `operator_unit.id` with a different `name` to update display metadata.
* Omit `operator_unit` inside `operator_identity` to remove the current unit.
* Change `operator_unit.id`, add a unit, or remove one to rekey the same account within the operator.
* Change `operator` to request an inter-entity operator-domain handoff. The seller MUST place this transition into approval; it cannot apply directly from buyer assertion alone. Before applying it, the seller MUST verify that the authenticated caller can administer the current account, obtain verified brand authorization for the destination operator, and confirm that the destination operator accepts the handoff. A passive or caller-supplied `authorized_operators` value is not sufficient without the seller's normal verification of the brand-controlled source.
```json theme={null}
{
"idempotency_key": "identity-update-018f24c0-65d1-7c3a",
"accounts": [
{
"account": { "account_id": "acc_nova_pinnacle" },
"revision": 7,
"operator_identity": {
"operator": "pinnacle-media.example",
"operator_unit": {
"id": "east-coast",
"name": "East Coast"
}
}
}
]
}
```
Identity reconciliation changes the same advertiser account; it is never provisioning or merging. The seller MUST resolve exactly one existing account, reject a target-key collision with [`ACCOUNT_IDENTITY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-identity-conflict), preserve `account_id`, historical media buys, reporting continuity, and other account-scoped history, and apply no identity change if it cannot preserve that continuity. `currency`, `sandbox`, and brand identity remain immutable through this field.
An intra-operator unit change stays within the existing account authority boundary. An operator-domain handoff crosses that boundary and therefore has additional rules:
* The canonical operator, billing, and grants remain unchanged while approval is pending.
* When `billing: "operator"`, the request MUST include a complete `destination_billing_entity`. This staged value is write-only while approval is pending; the account response continues to return the current canonical `billing_entity`. The seller MUST re-run its commercial approval for the destination entity, payment terms, and credit state, then switch canonical operator and billing identity together. It MUST NOT expose or apply the destination billing identity early or silently associate the former operator's billing identity with the destination.
* At the atomic switch, grants scoped to the former operator MUST be revoked unless independently authorized for the continuing principal. The destination operator receives only explicitly approved grants. Brand- or buyer-agent grants that remain independently valid MAY be preserved.
* A seller that cannot complete those transitions without breaking account or resource continuity MUST reject or keep the request pending; it MUST NOT partially rekey the account.
Every persisted account mutation increments its integer `revision`. Buyers MUST pass the latest observed `revision` with `operator_identity`; the seller MUST compare it atomically with the write and return `CONFLICT` without side effects on mismatch. Dry runs, validation failures, reads, and exact idempotency replays do not increment it.
An immediately applied intra-operator update returns the new canonical `operator` and `operator_unit`. An operator-domain change always returns the current canonical fields plus `identity_change.status: "pending_approval"`; `list_accounts` exposes the same state. Approval atomically performs the authorized identity, billing, and grant transition and clears `identity_change`. Rejection retains the canonical fields, discards the staged destination billing identity, and exposes `identity_change.status: "rejected"` with a reason. Each disposition increments `revision`.
A new `operator_identity` request submitted with the current revision replaces an earlier pending or rejected request and increments the revision. To cancel a pending request without changing the canonical identity, submit the current canonical `operator_identity` with the current revision; the seller clears `identity_change`, discards any staged destination billing identity, and increments the revision. A stale request returns `CONFLICT` without replacing or clearing the existing state. Exact idempotency replays return the original result without another revision increment.
After a rekey, the seller MUST tombstone the former natural key while the account or any account-scoped historical resource is retained. An authorized caller using that former key receives [`ACCOUNT_MOVED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-moved) with `details.current_account`; the seller MUST NOT provision a second account from it. Callers without access to the current account receive [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found) so the redirect does not become a cross-tenant existence oracle.
With `dry_run: true`, the seller performs the same account resolution, revision, collision, authorization, and continuity checks but persists nothing and leaves the revision unchanged. Each identity-update result includes `identity_change_preview`:
* `would_apply` means an intra-operator update can apply immediately.
* `would_require_approval` means an operator-domain handoff would enter approval.
* `blocked` identifies continuity, authorization, billing, grant, or active-resource blockers in `blockers`.
The preview's `impacts[]` records whether account ID, media buys, reporting, approval, billing, and grants would be preserved, revalidated, revoked and regranted, or block the change. A natural-key collision returns `ACCOUNT_IDENTITY_CONFLICT` and a blocked preview. Dry-run results may use `action: "updated"` to describe the change that would occur or `action: "failed"` for a blocker; the top-level `dry_run: true` and `identity_change_preview` make clear that no mutation occurred. Dry runs MUST NOT return a persisted `identity_change`.
## Response
**Success response:**
Returns an `accounts` array with per-account results. Individual accounts may be pending, rejected, or failed even when the operation succeeds.
**Error response:**
* `errors` -- Array of operation-level errors (auth failure, service unavailable). No `accounts` array is present.
**Note:** Responses use discriminated unions -- you get either `accounts` OR `errors`, never both.
**Per-account fields:**
| Field | Description |
| - | - |
| `account` | Present only on settings-update-mode results, echoed from the request's `account` field. Anchors this row's identity via `account_id` or natural key in place of `brand`/`operator` — including on `action: "failed"` results, where the account may not resolve to a brand/operator tuple at all. See [Two modes](#two-modes-provisioning-vs-settings-update). |
| `brand` | Current canonical brand. Object with `domain`, optional `brand_id`, and optional `countries[]`. Present on provisioning-mode results. |
| `operator` | Current canonical operator domain. While an identity change is pending or rejected, this remains the current value. |
| `operator_unit` | Current canonical operator unit. `id` is stable identity; `name` is display metadata. |
| `revision` | Current optimistic-concurrency revision. Return it from identity-update-capable sellers and pass it on the next settings update. |
| `identity_change` | Pending or rejected desired operator identity. Canonical identity remains in `operator` and `operator_unit`. |
| `identity_change_preview` | Dry-run-only disposition and resource-impact preview. Canonical identity and revision remain unchanged. |
| `currency` | Fixed account currency, echoed when supplied. |
| `name` | Seller's display name for the account. |
| `action` | What happened: `created`, `updated`, `unchanged`, or `failed`. |
| `status` | Current state of the account (see [Account status](#account-status)). Required except when `action: "failed"`, where the seller may not know a lifecycle state to report. |
| `billing` | Billing model applied. Matches the requested value. |
| `billing_entity` | Current canonical business entity for the invoiced party. During a pending operator-domain handoff, this remains the current entity; the staged `destination_billing_entity` is write-only. Sellers may add verified fields, but bank details are always omitted. |
| `account_scope` | How the seller scoped this account: `operator` (shared across brands for this operator), `brand` (shared across operators for this brand), `operator_brand` (dedicated to this operator+brand pair), or `agent` (agent-scoped account shared across declared brand/operator pairs). See [account scope](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-scope). |
| `setup` | Present when `status: "pending_approval"`. Contains `url` for completing credit or legal setup, `message` explaining what's needed, and optional `expires_at`. |
| `rate_card` | Seller-assigned rate card identifier (when applicable). |
| `payment_terms` | Payment terms agreed for this account: `net_15`, `net_30`, `net_45`, `net_60`, `net_90`, or `prepay`. When the account is active, these are the binding terms for all invoices. |
| `credit_limit` | Maximum outstanding balance as `{amount, currency}`. |
| `errors` | Per-account errors. Required and non-empty when `action: "failed"`; absent otherwise. |
| `warnings` | Non-fatal notices. |
| `sandbox` | Whether this is a sandbox account, echoed from the request. Only present for buyer-declared accounts. |
| `notification_configs` | Optional. Current persisted account-level webhook subscribers after applying the request. Present on `created`, `updated`, and `unchanged` results when the request included `notification_configs` or the account already has persisted subscribers. Each entry carries `subscriber_id`, `url`, `event_types[]`, and `active`; `authentication.credentials` is omitted (write-only). |
| `authorization` | Optional. The calling agent's scope grant for this account — `allowed_tasks`, `field_scopes`, `scope_name`, `read_only`. Applies to every vendor agent type (media-buy, signals, governance, creative, brand) — the Accounts Protocol surface is shared. Present on `created`, `updated`, and `unchanged` results; omitted on `failed` results. Vendor agents that support scope introspection SHOULD populate this; media-buy sales agents claiming the `attestation_verifier` standard scope MUST populate it. Absence means the vendor agent does not advertise introspectable scope; callers MUST NOT infer access from absence. See [Caller authorization](/dist/docs/3.2.8/accounts/overview#caller-authorization) for the full shape. |
### Account status
| Status | Meaning | Next step |
| - | - | - |
| `active` | Ready to use | Use [account reference](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) in protocol operations |
| `pending_approval` | Seller reviewing | Human may need to visit `setup.url` to complete credit or legal process. Poll [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) for updates. |
| `rejected` | Seller declined the request | Review rejection reason in `warnings`, adjust and retry, or contact seller |
| `payment_required` | Credit limit reached or funds depleted | Add funds or increase credit limit. Route spend to other accounts. |
| `suspended` | Was active, now paused | Contact seller to resolve |
| `closed` | Was active, now terminated | -- |
### Async notifications
When `push_notification_config` is provided and the seller returns `pending_approval`, the seller sends a webhook notification when the account status changes (e.g., approved → `active`, declined → `rejected`).
For provisioning requests, the notification payload includes the `(brand, operator)` natural key so the buyer can correlate it to the original sync request. When the seller also returns a seller-assigned `account_id`, the notification includes it as a convenience handle; buyers still follow the seller's declared account-reference model for subsequent calls.
```json theme={null}
{
"brand": { "domain": "nova-brands.com", "brand_id": "glow" },
"operator": "pinnacle-media.com",
"status": "active",
"account_id": "acc_glow_001"
}
```
If the buyer did not provide `push_notification_config`, poll [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) to check for status changes.
## Two modes: provisioning vs. settings-update
Each per-account entry uses one of two key shapes, never both:
* **Provisioning mode** — flat `brand` + `operator` + `billing` at the entry root. The seller provisions or upserts accounts. Used for buyer-declared accounts (`require_operator_auth: false`). This is the shape AdCP 3.0 shipped with. Sellers MAY echo an `account_id`, but the natural-key `AccountRef` remains valid for subsequent calls.
* **Settings-update mode** — `account` (an [AccountRef](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references)) at the entry root, with `brand`/`operator`/`billing` absent. The seller updates the account's settable state — no provisioning side effects. Used for account-id namespaces only when the seller exposes settings updates through this task; upstream-managed accounts are discovered via [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts), while seller-defined account IDs may be supplied out-of-band. Buyer-declared account sellers MAY also accept this mode for settings updates against accounts they previously provisioned.
Schema enforces the exclusivity via `oneOf` — sending both shapes on the same entry is a validation error. Sellers that don't implement settings-update mode reject `account`-keyed entries with [`UNSUPPORTED_PROVISIONING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-provisioning); sellers that don't provision through `sync_accounts`, including account-id namespaces, reject natural-key provisioning entries with the same code.
The response result row mirrors the request's discriminator, and the two identity shapes are mutually exclusive: a settings-update-mode result echoes `account` instead of `brand`/`operator`, since an account-id-namespace seller frequently has no buyer-declared brand/operator tuple to return at all. This also makes `action: "failed"` settings-update results representable — for example, an `account_id` the seller cannot reach has no brand/operator tuple to resolve, and the row's identity is carried entirely by the echoed `account` instead. `status` is required on every non-failed result, but optional on `failed` results: some failures still know the account's lifecycle state (e.g. a rejected identity change on an otherwise-reachable account), while others — like this one — do not, and sellers MUST NOT invent a value; `errors` is required instead:
```json theme={null}
{
"account": { "account_id": "acct-social-unreachable" },
"action": "failed",
"errors": [
{ "code": "ACCOUNT_NOT_FOUND", "message": "Account does not exist or is not accessible to the authenticated agent." }
]
}
```
## Account-level webhook subscriptions
`notification_configs[]` carries account-level webhook subscribers for creative lifecycle and assignment changes, `indicators.changed`, account status, wholesale feed changes, and future account-anchored events.
Indicator and assignment subscriptions are prospective: activation or reactivation does not replay conditions that were already current. After activation, buyers establish a complete baseline through [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) before relying on later invalidations: enumerate known media-buy IDs or request every media-buy status and follow pagination to exhaustion, without an indicator filter. The optional bounded [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) projection is not sufficient to prove complete state.
`account.status_changed` is the durable account lifecycle event. Use it for status transitions after the initial `sync_accounts` result, such as `pending_approval → active`, `pending_approval → rejected`, `active → payment_required`, `active → suspended`, recovery back to `active`, or terminal `closed`. It is not a replacement for the one-shot `push_notification_config` on this task: that channel can report the async result of the original provisioning operation, while `notification_configs[]` subscribers outlive the task.
Before relying on durable account lifecycle webhooks, read `get_adcp_capabilities.account.notifications`. Sellers that declare `supported: true` accept `account.status_changed` registrations here, name `sync_accounts` as the registration task, and name [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) as the repair read. Sellers that omit the capability or declare `supported: false` MUST reject `account.status_changed` registrations instead of silently storing a subscriber that will never fire.
### Account change feed notifications
`account.change_recorded` is the generic wake-up for the optional durable
[`list_account_changes`](/dist/docs/3.2.8/accounts/tasks/list_account_changes) feed. It
covers committed material changes from every origin within the seller's
advertised resource coverage, including seller surfaces, connected platforms,
seller automation, and other authorized principals. Before accepting this
event type, the seller MUST advertise
`get_adcp_capabilities.account.change_feed.supported: true` and list the
[experimental](/dist/docs/3.2.8/reference/experimental-status) feature id
`account.change_feed` in `experimental_features`.
Each feed record produces one logical fire for every active subscriber that
requested `account.change_recorded`. The fire's `notification_id` equals the
record's `change_id`. The payload is only an invalidation: receivers drain from
their own persisted cursor and then invoke the record's repair task. Its
optional `through_cursor` is a target watermark, never a checkpoint to install
without reading intervening pages. Existing specialized notifications may
overlap this generic fire.
For these event types, "wholesale feed" means the seller's buyable wholesale product and signals feeds returned by [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) or [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals); it is not the buyer-provided feeds managed by [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs).
Permitted in **both** provisioning and settings-update modes. Declarative semantics:
* Omit `notification_configs` to leave the account's existing subscribers unchanged.
* Send `notification_configs: []` to remove every subscriber on that account.
* Send a non-empty array to replace the account's current set with the submitted set.
Within one account, `subscriber_id` is the stable logical key. Re-sending an existing `(account_id, subscriber_id)` with a different `url`, `event_types`, `authentication`, or `active` value replaces that subscriber's active config rather than creating a duplicate. The seller MUST NOT merge the submitted array with persisted state: persisted subscribers whose `subscriber_id` does not appear in the sent array are removed. Paused entries (`active: false`) are subject to the same replacement semantics; to preserve a paused subscription, re-include it with `active: false` in the sent array. Duplicate `subscriber_id` values within the same submitted array are invalid. The replacement is account-scoped; the same `subscriber_id` MAY be reused on a different account.
If any entry in the submitted replacement set fails validation or activation proof, the seller rejects that account entry with `action: "failed"` and leaves the account's previous `notification_configs[]` set unchanged. Sellers MUST NOT partially apply a replacement set and silently drop only the failed subscriber.
Each entry has:
* `subscriber_id` — buyer-supplied identifier, unique within the account; echoed on every fire so multi-subscriber accounts can route by endpoint
* `url` — HTTPS endpoint URL. Sellers MUST complete an endpoint activation challenge or equivalent proof-of-control before treating a new or changed active subscriber as active.
* `event_types[]` — types the subscriber wants. Only account-anchored types are permitted (today: `creative.status_changed`, `creative.assignment_changed`, `indicators.changed`, `creative.purged`, `account.status_changed`, `account.change_recorded`, `product.created`, `product.updated`, `product.priced`, `product.removed`, `signal.created`, `signal.updated`, `signal.priced`, `signal.removed`, `wholesale_feed.bulk_change`). Sellers MUST reject any media-buy-anchored type (`scheduled`, `final`, `delayed`, `adjusted`, `window_update`, `impairment`) or agent-anchored type (`capabilities.changed`) as a per-account validation failure with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) or [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) in `accounts[].errors[]`, and `error.field` MUST point at the invalid `event_types` entry.
* `product_payload_view` — `canonical` for a [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) mirror or `legacy` for the 3.x `get_products` shape. Omission defaults to `legacy`; valid only when a product event is selected.
* `authentication` (optional) — legacy Bearer or HMAC-SHA256. Omit to use the default RFC 9421 webhook profile. When present, the same signed-registration downgrade-resistance rules as `push_notification_config.authentication` apply. Credentials are write-only — sellers omit them on reads.
* `active` (default `true`) — set `false` to pause a subscriber without removing the registration. Sellers MAY skip only the outbound proof challenge while `active: false`; they MUST still enforce HTTPS parsing, hostname normalization, and reserved-range rejection on write. Paused subscribers MUST NOT receive fires until reactivated. Reactivation MUST repeat full SSRF validation with connect pinning plus proof-of-control for any tuple without current valid proof.
### Endpoint proof of control
Before persisting or echoing an entry as `active: true`, the seller MUST validate the URL, apply the SSRF rules in [Webhook URL validation](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-url-validation-ssrf), and prove that the receiver controls the endpoint.
Proof is required when there is no current valid proof for the tuple `(account_id, subscriber_id, normalized url, authentication mode/credential binding, normalized event_types)`. Changing the subscriber ID, normalized URL, authentication mode/credential binding, or `event_types[]` requires fresh proof before the new set can become active. The challenge POST itself MUST be signed with the seller's RFC 9421 webhook profile key even when the candidate config selects legacy delivery auth. New signers use `adcp_use: "request-signing"`; deprecated `webhook-signing` keys remain accepted during the compatibility window. The receiver MUST verify the RFC 9421 signature and MUST reject the challenge unless `account_id`, `subscriber_id`, `seller_agent_url`, `delivery_auth`, and `event_types` match the pending registration. The signature's covered `@target-uri` MUST equal the exact normalized candidate URL, and its `expires` parameter binds the challenge expiry.
The standard challenge is an HTTPS POST to the candidate `url` with a JSON body containing `type`, `challenge`, `account_id`, `subscriber_id`, `seller_agent_url`, `delivery_auth`, and `event_types`. The canonical schemas are [`webhook-challenge.json`](https://adcontextprotocol.org/schemas/3.2.8/core/webhook-challenge.json) and [`webhook-challenge-response.json`](https://adcontextprotocol.org/schemas/3.2.8/core/webhook-challenge-response.json).
```json theme={null}
{
"type": "webhook.challenge",
"challenge": "example-challenge-token-000000000000",
"account_id": "acct_123",
"subscriber_id": "buyer-primary",
"seller_agent_url": "https://seller.example/adcp",
"delivery_auth": { "mode": "rfc9421" },
"event_types": ["creative.status_changed"]
}
```
The receiver proves control by returning HTTP `2xx` with a JSON body containing exactly one echo field:
```json theme={null}
{ "challenge": "example-challenge-token-000000000000" }
```
Sellers MUST also accept the backward-compatible alias:
```json theme={null}
{ "token": "example-challenge-token-000000000000" }
```
The challenge value MUST be cryptographically random, single-use, and scoped to the registration tuple. The RFC 9421 `expires` parameter is the challenge expiry; receivers MUST reject expired challenges, and sellers MUST reject echoes received after that instant. A failed, non-`2xx`, malformed, mismatched, expired, replayed, or timed-out challenge means proof failed. Sellers SHOULD use the same outbound fetch caps as SSRF validation (10 second connect and 10 second read) and SHOULD make at most one initial challenge POST on the `sync_accounts` critical path. A seller MAY retry one transient network failure before returning if it uses the same challenge value and still completes within its request budget; otherwise the buyer retries by re-sending `sync_accounts`.
On proof failure, the seller returns a per-account failure with `action: "failed"`, `errors[].code: "VALIDATION_ERROR"` (or `INVALID_REQUEST` for malformed URLs), and `error.field` pointing at `accounts[i].notification_configs[j].url`. The previous persisted subscriber set remains unchanged. `dry_run: true` MUST NOT send network challenges; an `active: true` echo in a dry-run result previews the requested post-proof state and does not assert that proof already exists.
### Account status payload
When an account's lifecycle status changes after the initial `sync_accounts` response, sellers fire `account.status_changed` to active subscribers whose `event_types[]` includes that value.
```json theme={null}
{
"idempotency_key": "whk_01K18GM0Z7J3Q6WBH7DYK2R4VM",
"notification_id": "acctchg_acc_glow_20260719T100712Z",
"notification_type": "account.status_changed",
"fired_at": "2026-07-19T10:07:15Z",
"subscriber_id": "account-lifecycle",
"account_id": "acc_glow_pending",
"previous_status": "pending_approval",
"status": "payment_required",
"observed_at": "2026-07-19T10:07:12Z",
"reason_code": "setup_required",
"setup": {
"message": "Complete advertiser billing setup.",
"expires_at": "2026-07-30T00:00:00Z"
}
}
```
The payload is an invalidation signal. It intentionally omits the full account document and `setup.url`; setup URLs are often single-use or sensitive and should not be fanned out to every subscriber. Receivers SHOULD re-run [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) for `account_id` and reconcile from the fresh account snapshot.
`notification_id` is stable per `(account_id, previous_status, status, observed_at)`. Retries and re-emissions of the same transition reuse it under a new `idempotency_key`; a later transition cycle receives a new `notification_id`.
Example — register a buyer-side endpoint plus an audit bus on an account-id namespace account:
```json theme={null}
{
"idempotency_key": "f2c4b7d9-6789-49bc-defa-2345678901bc",
"accounts": [
{
"account": { "account_id": "acc_acme_pinnacle" },
"notification_configs": [
{
"subscriber_id": "buyer-primary",
"url": "https://buyer.example/webhooks/adcp/creative",
"event_types": ["creative.status_changed", "creative.purged"],
"active": true
},
{
"subscriber_id": "audit-bus",
"url": "https://audit.buyer.example/adcp/ingest",
"event_types": ["creative.status_changed", "creative.purged"],
"active": true
}
]
}
]
}
```
Example — register a wholesale feed mirror subscriber for wholesale product and signal changes:
```json theme={null}
{
"idempotency_key": "a8af8cf1-89bd-41f3-b27d-7ee7e9f8d2e4",
"accounts": [
{
"account": { "account_id": "acc_acme_pinnacle" },
"notification_configs": [
{
"subscriber_id": "wholesale-feed-sync",
"url": "https://buyer.example/webhooks/adcp/wholesale-feed",
"event_types": [
"product.created",
"product.updated",
"product.priced",
"product.removed",
"signal.created",
"signal.updated",
"signal.priced",
"signal.removed",
"wholesale_feed.bulk_change"
],
"active": true
}
]
}
]
}
```
Example — register an account lifecycle subscriber:
```json theme={null}
{
"idempotency_key": "ee1343bb-7449-4d33-a2c1-c9cc0c75d0f4",
"accounts": [
{
"account": { "account_id": "acc_acme_pinnacle" },
"notification_configs": [
{
"subscriber_id": "account-lifecycle",
"url": "https://buyer.example/webhooks/adcp/accounts",
"event_types": ["account.status_changed"],
"active": true
}
]
}
]
}
```
Governance agents registered via [`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance) are **not** implicitly subscribed to these webhooks. If your governance agent should also receive creative-lifecycle fires, register its URL as a separate `notification_configs[]` entry — explicit, auditable, with its own `event_types[]` filter.
Verify applied state via [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) — the response carries the current persisted `notification_configs[]` per account with credentials redacted. `sync_accounts` also echoes the current sanitized set on `created`, `updated`, and `unchanged` results when the request included `notification_configs` or any persisted subscribers already exist.
Wholesale feed notifications are registered here, not through a separate subscription task. The webhook body is [`wholesale-feed-webhook.json`](https://adcontextprotocol.org/schemas/3.2.8/core/wholesale-feed-webhook.json): it carries a canonical product replacement for `list_products` subscribers (or the legacy Product view for `get_products` subscribers), signal changes, or a bulk-change summary plus the post-change `wholesale_feed_version`. Sellers MUST apply the same per-subscriber authorization and scope predicate used by the corresponding wholesale read before emitting each webhook. For a detected gap, repair with the mirror's last applied version; for uncertain or bulk state, omit the conditional token and replace from `list_products` / `get_signals`. See [wholesale_feed_webhooks](/dist/docs/3.2.8/protocol/get_adcp_capabilities#wholesale_feed_webhooks) for capability declaration and event semantics.
## Common scenarios
### Agency syncing multiple brands
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAccountsResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncAccounts({
accounts: [
{
brand: { domain: "nova-brands.com", brand_id: "spark" },
operator: "pinnacle-media.com",
billing: "operator",
},
{
brand: { domain: "nova-brands.com", brand_id: "glow" },
operator: "pinnacle-media.com",
billing: "operator",
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAccountsResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
for (const account of validated.accounts) {
if (account.status === "active") {
console.log(`Ready: ${account.brand.domain}/${account.brand.brand_id} → ${account.status}`);
} else if (account.status === "pending_approval") {
console.log(`Setup required for ${account.brand.brand_id}: ${account.setup?.url}`);
// Poll list_accounts until status becomes active
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_accounts(
accounts=[
{
"brand": {"domain": "nova-brands.com", "brand_id": "spark"},
"operator": "pinnacle-media.com",
"billing": "operator",
},
{
"brand": {"domain": "nova-brands.com", "brand_id": "glow"},
"operator": "pinnacle-media.com",
"billing": "operator",
},
],
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for account in result.accounts:
if account.status == 'active':
print(f"Ready: {account.brand['domain']}/{account.brand.get('brand_id')} → {account.status}")
elif account.status == 'pending_approval':
print(f"Setup required for {account.brand.get('brand_id')}: {account.setup.url}")
# Poll list_accounts until status becomes active
asyncio.run(main())
```
### Direct brand purchase
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAccountsResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncAccounts({
accounts: [
{
brand: { domain: "acme-corp.com" },
operator: "acme-corp.com",
billing: "operator",
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAccountsResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
const account = validated.accounts[0];
if (account.status === "active") {
console.log(`Ready: ${account.brand.domain} — ${account.status}`);
} else if (account.status === "pending_approval") {
console.log(`Setup required: ${account.setup?.url}`);
// Poll list_accounts until status becomes active
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_accounts(
accounts=[
{
"brand": {"domain": "acme-corp.com"},
"operator": "acme-corp.com",
"billing": "operator",
},
],
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
account = result.accounts[0]
if account.status == 'active':
print(f"Ready: {account.brand['domain']} — {account.status}")
elif account.status == 'pending_approval':
print(f"Setup required: {account.setup.url}")
# Poll list_accounts until status becomes active
asyncio.run(main())
```
### Handling rejection
When a seller declines a request, the account entry has `status: "rejected"`:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAccountsResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncAccounts({
accounts: [
{
brand: { domain: "acme-corp.com", brand_id: "clearance" },
operator: "acme-corp.com",
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAccountsResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
for (const account of validated.accounts) {
if (account.status === "rejected") {
console.log("Account request was rejected");
if (account.warnings?.length) {
console.log(`Reason: ${account.warnings.join(", ")}`);
}
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_accounts(
accounts=[
{
"brand": {"domain": "acme-corp.com", "brand_id": "clearance"},
"operator": "acme-corp.com",
},
],
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for account in result.accounts:
if account.status == 'rejected':
print("Account request was rejected")
warnings = getattr(account, 'warnings', None)
if warnings:
print(f"Reason: {', '.join(warnings)}")
asyncio.run(main())
```
## Error handling
| Error Code | Description | Resolution |
| - | - | - |
| [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found) | Referenced account does not exist or is not accessible | Check `account_id` or re-sync |
| [`ACCOUNT_MOVED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-moved) | A former natural key was used after the account was rekeyed | Replace the stale reference with `error.details.current_account`, refresh through [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts), and retry with a fresh idempotency key |
| [`CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflict) | Submitted `revision` is stale | Re-read `list_accounts`, reconcile, and retry with the current revision |
| [`ACCOUNT_IDENTITY_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-identity-conflict) | Desired natural key already belongs to another account | Choose a different operator identity or retain the current identity; do not retry the same desired identity unchanged |
| [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) | Seller does not advertise the requested identity change in `account.identity_updates.supported_changes` | Leave identity unchanged or use a seller-supported transition |
| [`BILLING_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-supported) | Seller-wide capability gate (`supported_billing` does not include the value) or per-account-relationship gate; see [Billing and Account Setup](/dist/docs/3.2.8/building/by-layer/L3/error-handling#billing-and-account-setup) | Check [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) for `supported_billing`, adjust or omit `billing`; inspect `error.details.scope` to disambiguate capability vs account scope |
| [`BILLING_NOT_PERMITTED_FOR_AGENT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-billing-not-permitted-for-agent) | Seller-wide capability accepts the value, but the calling buyer agent's commercial relationship does not (e.g., passthrough-only — no payments relationship); see [Buyer-agent identity](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#buyer-agent-identity) | Retry with `error.details.suggested_billing` (typically `operator`) when present; when absent, surface to a human — the agent cannot extend its own commercial relationship |
| [`PAYMENT_TERMS_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-payment-terms-not-supported) | Seller does not accept the requested payment terms | Omit `payment_terms` to accept the seller's default, or negotiate offline |
| [`ACCOUNT_PAYMENT_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-payment-required) | Account has an outstanding balance requiring payment | Resolve outstanding balance or route to another account |
| [`ACCOUNT_SUSPENDED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-suspended) | Account is suspended | Contact seller to resolve |
| [`BRAND_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-brand-required) | Billable operation attempted without brand reference | Include `brand` in the request |
## Next steps
* [list_accounts](/dist/docs/3.2.8/accounts/tasks/list_accounts) -- Poll for status changes on pending accounts
* [sync_governance](/dist/docs/3.2.8/accounts/tasks/sync_governance) -- Sync governance agents to accounts
* [Accounts and agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) -- Billing models, trust models, and authorized operators
* [Brand protocol](/dist/docs/3.2.8/brand-protocol/brand-json) -- How seller agents resolve brand identity from the `brand.domain`
* [get_adcp_capabilities](/dist/docs/3.2.8/protocol/get_adcp_capabilities) -- Discover `supported_billing` and `require_operator_auth` before syncing accounts
# sync_governance
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/accounts/tasks/sync_governance
sync_governance syncs governance agent endpoints to specific accounts. The seller persists these agents and calls them via check_governance during media buy lifecycle events.
Sync the governance agent endpoint for specific accounts. The seller persists the agent and calls it via [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) during media buy lifecycle events. Each account entry pairs an [account reference](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) with exactly one governance agent, supporting both account-id namespaces (`account_id`) and buyer-declared accounts (`brand` + `operator`).
An account binds to one governance agent that owns the full lifecycle. Authorization, delivery monitoring, and compliance are phases of the same evaluation against one plan, not specialisms held by separate authorities; specialist review (legal, brand safety, category) composes inside the governance agent rather than across multiple registrations. `governance_agents` is an array with `maxItems: 1` because the array shape is the shape 3.0 shipped with — the constraint is load-bearing and not a staging post toward loosening. The envelope's `governance_context` is singular below this layer; relaxing the cap would require a coordinated wire-shape change that is not planned. See [One governance agent per account](/dist/docs/3.2.8/governance/campaign/specification#one-governance-agent-per-account).
This uses **replace semantics** — each call replaces any previously registered agent on the specified accounts. Accounts not included in the request keep their existing configuration.
## Seller acceptance of governance agents
Sellers may publish seller-wide advisory criteria at `adcp.governance_enforcement.accepted_governance_agents` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). `any_of[]` is a typed union: a candidate is acceptable when it satisfies at least one matcher.
* `agent_url` matches one explicit HTTPS endpoint.
* `verification` requires a fresh result from the named HTTPS registry for the declared agent role, AdCP version, allowed verification modes, and maximum result age.
URL matchers use the shared [AdCP URL canonicalization rules](/dist/docs/3.2.8/reference/url-canonicalization), not raw string equality. They match the exact canonical endpoint; redirects, DNS aliases, and candidate assertions do not expand an allowlist. A verification matcher is satisfied only by a deterministic result from the seller-configured trusted registry. The candidate cannot nominate the registry, and its self-described role or verification state is never evidence. Registry resolution uses HTTPS, no redirects or forwarded credentials, public-network address checks, DNS pinning through connection, bounded responses, and authenticated registry records. If the registry or verification service cannot be resolved, the seller returns [`GOVERNANCE_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-governance-unavailable); it does not guess or silently turn an availability problem into rejection.
The capabilities declaration is seller-wide preflight guidance. The response to `sync_governance` is authoritative for each account because account contracts, jurisdictions, and product access may narrow the criteria. Verification evidence is evaluated for freshness at binding time and pinned to the accepted binding. Later capability or registry drift does not silently revoke or redirect an existing binding; an explicit account resynchronization creates a new decision. If the submitted agent does not satisfy the applicable criteria, the account result is `failed` with [`GOVERNANCE_AGENT_NOT_ACCEPTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-governance-agent-not-accepted). A seller may return either opaque details (`{"disclosure":"opaque"}` plus an optional local `rejection_ref`) or disclosed details containing the parsed HTTPS origin and authoritative criteria. The disclosed arm uses `attempted_agent_origin`, never the submitted URL: userinfo, path, query, and fragment are stripped after parsing. Buyers reconciling a disclosed rejection against their `any_of[]` matcher list should compare full matcher entries, not origins — an `agent_url` matcher may include a path and therefore be narrower than the disclosed origin. The seller MUST NOT persist or contact a rejected endpoint and MUST NOT echo credentials or a raw candidate URL in responses, logs, or error details.
Acceptance matchers MUST express objective operational, security, interoperability, or compliance requirements. A seller MUST NOT use a URL allowlist or verification criterion to exclude a functionally equivalent governance provider merely as commercial leverage. Sellers SHOULD prefer verification criteria over enumerating providers when the registry can express the requirement deterministically.
Absence of `accepted_governance_agents` means the seller does not restrict governance-agent identity through this mechanism and accepts any otherwise valid binding. Adding or changing a declaration does not retroactively invalidate existing bindings; the seller applies it when a buyer next binds or replaces an agent. Account-specific criteria returned on a failed sync override the advisory capability for that attempt.
**Response Time**: \~1s.
**Request Schema**: [`/schemas/3.2.8/account/sync-governance-request.json`](https://adcontextprotocol.org/schemas/3.2.8/account/sync-governance-request.json)
**Response Schema**: [`/schemas/3.2.8/account/sync-governance-response.json`](https://adcontextprotocol.org/schemas/3.2.8/account/sync-governance-response.json)
## Quick Start
Sync the governance agent for an account-id namespace account:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncGovernanceResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncGovernance({
accounts: [
{
account: { account_id: "acct-social-001" },
governance_agents: [
{
url: "https://governance.pinnacle-media.com",
authentication: {
schemes: ["Bearer"],
credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
]
}
]
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncGovernanceResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
for (const entry of validated.accounts) {
if (entry.status === "synced") {
console.log(`${JSON.stringify(entry.account)}: ${entry.governance_agents.length} agent registered`);
} else {
console.log(`${JSON.stringify(entry.account)}: failed — ${JSON.stringify(entry.errors)}`);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_governance(
accounts=[
{
"account": {"account_id": "acct-social-001"},
"governance_agents": [
{
"url": "https://governance.pinnacle-media.com",
"authentication": {
"schemes": ["Bearer"],
"credentials": "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
]
}
]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for entry in result.accounts:
if entry.status == "synced":
print(f"{entry.account}: {len(entry.governance_agents)} agent registered")
else:
print(f"{entry.account}: failed — {entry.errors}")
asyncio.run(main())
```
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `accounts` | array | Yes | Per-account governance agent entries. Each pairs an account reference with governance agents for that account. |
**Each account entry:**
| Field | Type | Required | Description |
| - | - | - | - |
| `account` | object | Yes | [Account reference](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references): `{account_id}` for account-id namespaces or `{brand, operator}` for buyer-declared accounts. |
| `governance_agents` | array | Yes | Governance agent endpoint for this account. Array with exactly one entry (`minItems: 1`, `maxItems: 1`). |
**The governance agent:**
| Field | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | HTTPS endpoint URL for the governance agent. |
| `authentication` | object | Yes | Credentials the seller presents when calling this agent. Contains `schemes` (array with one auth scheme) and `credentials` (token, min 32 characters). |
## Response
**Success response:**
Returns an `accounts` array with per-account results. Individual entries may fail even when the operation succeeds.
| Field | Description |
| - | - |
| `account` | Account reference, echoed from request. |
| `status` | `"synced"` or `"failed"`. |
| `governance_agents` | Governance agents now active on this account. Reflects persisted state. Only present when `status: "synced"`. |
| `errors` | Per-account errors. Only present when `status: "failed"`. |
For [`GOVERNANCE_AGENT_NOT_ACCEPTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-governance-agent-not-accepted), `errors[].details` conforms to `error-details/governance-agent-not-accepted.json`. It never contains authentication credentials.
**Error response:**
`errors` array with operation-level errors (auth failure, service unavailable). No `accounts` array is present.
## Authorization
The seller MUST verify that the authenticated agent has authority over each referenced account before persisting governance agents. Requests referencing accounts the agent does not own MUST return a `failed` status with an error for those entries.
## Common Scenarios
### Different governance agents per account
A single `sync_governance` call can register a distinct agent per account — each account still binds to exactly one agent, but accounts on the same call need not share it.
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncGovernanceResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncGovernance({
accounts: [
{
account: { account_id: "acct-social-001" },
governance_agents: [
{
url: "https://governance.pinnacle-media.com",
authentication: {
schemes: ["Bearer"],
credentials: "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
]
},
{
account: { account_id: "acct-social-002" },
governance_agents: [
{
url: "https://governance.acme-buyer.com",
authentication: {
schemes: ["Bearer"],
credentials: "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
}
]
}
]
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncGovernanceResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
for (const entry of validated.accounts) {
console.log(`${JSON.stringify(entry.account)}: ${entry.status}`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_governance(
accounts=[
{
"account": {"account_id": "acct-social-001"},
"governance_agents": [
{
"url": "https://governance.pinnacle-media.com",
"authentication": {
"schemes": ["Bearer"],
"credentials": "gov-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
]
},
{
"account": {"account_id": "acct-social-002"},
"governance_agents": [
{
"url": "https://governance.acme-buyer.com",
"authentication": {
"schemes": ["Bearer"],
"credentials": "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
}
]
}
]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for entry in result.accounts:
print(f"{entry.account}: {entry.status}")
asyncio.run(main())
```
### Buyer-declared accounts (brand + operator)
```json Request theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/account/sync-governance-request.json",
"idempotency_key": "e5b9f2c3-1234-48a0-1234-56789012345e",
"accounts": [
{
"account": {
"brand": { "domain": "nova-brands.com", "brand_id": "spark" },
"operator": "pinnacle-media.com"
},
"governance_agents": [
{
"url": "https://governance.pinnacle-media.com",
"authentication": {
"schemes": ["Bearer"],
"credentials": "gov-token-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}
}
]
}
]
}
```
### Rotate governance agent credentials
Call `sync_governance` again with updated `authentication`. Replace semantics means the new credentials overwrite the previous configuration.
### Migrating from pre-3.1 multi-agent registration
Earlier drafts of 3.0 allowed up to 10 governance agents per account with per-agent `categories`. 3.1 constrains `governance_agents` to exactly one entry and removes `categories`. Buyers that registered more than one agent against the previous shape MUST collapse to a single agent on their next `sync_governance` call; the seller's persisted state is replaced. The new request schema rejects more than one agent outright, so no "mixed-mode" window exists.
**Buyer-side collapse decision.** Which of the previously-registered agents becomes the single agent is a buyer-internal decision — the protocol does not rank or recommend. Typical paths: (a) keep the agent with the broadest policy coverage (usually the budget/spend-authority agent) and fold specialist logic (legal, brand safety, regulatory review) into it as internal workflow; (b) deploy a new "front-door" governance agent that fans out to the previous specialists internally, and register only that agent; (c) keep the agent that was always the de facto governance surface and fold the others' specialist review into it as internal workflow without re-registering them. Surface the internal decomposition to auditors via `categories_evaluated` and `findings[].details` on check responses so the audit trail retains what each internal reviewer contributed.
**Seller-side.** Sellers MAY, on first boot under the new schema, collapse previously-persisted multi-agent state to the first entry (ordered by original sync position) and log the migration to their audit trail. Sellers SHOULD surface a clear error to buyers whose next `sync_governance` call attempts to re-register multiple agents, pointing at this migration guidance.
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found) | Referenced account does not exist or is not accessible | Verify account reference via [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) or [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) |
| `UNAUTHORIZED` | Agent does not have authority over the referenced account | Check that you are authenticated as an agent with access to this account |
## Next Steps
* [Sell-side governance boundaries](/dist/docs/3.2.8/governance/sell-side-governance) — Understand governance-agent acceptance as a seller binding constraint, not shared campaign authority
* [list_accounts](/dist/docs/3.2.8/accounts/tasks/list_accounts) — Discover accounts and their current governance agents
* [sync_accounts](/dist/docs/3.2.8/accounts/tasks/sync_accounts) — Provision or link advertiser accounts
* [check_governance](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) — How sellers call governance agents during media buy events
* [Accounts and agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) — Account models, billing, and trust
# Accessibility
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/accessibility
AdCP accessibility support lets formats declare WCAG conformance levels and requires accessible assets like alt text and captions.
AdCP supports accessibility at two levels: formats declare the conformance level of their rendered output, and assets carry the metadata needed to achieve it.
## How It Works
Accessibility in advertising creatives depends on who controls the rendering:
* **Format-rendered creatives** (image + headline + CTA): The format controls the output. It can guarantee contrast ratios, keyboard navigation, and ARIA landmarks — it just needs the right inputs from the creative (alt text for images, captions for video, etc.).
* **Opaque creatives** (HTML bundles, JavaScript tags): The format can't inspect or modify the content. The asset must self-declare its accessibility properties.
AdCP handles both cases through the format's `accessibility` object and per-asset-type accessibility metadata.
## Format Accessibility
Formats declare their accessibility posture through the `accessibility` object:
### `accessibility.wcag_level`
The WCAG conformance level that creatives produced by this format will meet. Values: `A`, `AA`, `AAA`.
For format-rendered creatives, this is a guarantee from the format. For opaque creatives, this reflects the level the format requires assets to self-certify to.
### `accessibility.requires_accessible_assets`
When `true`, all assets with accessibility-relevant fields must include those fields. This is the enforcement mechanism — it tells validation to treat optional accessibility fields as required.
```json theme={null}
{
"format_kind": "image",
"params": {
"width": 300,
"height": 250,
"accessibility": { "wcag_level": "AA", "requires_accessible_assets": true },
"slots": [
{ "asset_group_id": "image_main", "asset_type": "image", "required": true },
{ "asset_group_id": "headline", "asset_type": "text", "required": true }
]
}
}
```
This format guarantees WCAG AA output and requires `alt_text` on the image asset (because `alt_text` is marked as an accessibility field on the image asset type).
## Asset Accessibility Fields
Each asset type defines which of its fields are accessibility-relevant using the `x-accessibility` schema marker. These fields are always optional by default, but become required when the format sets `accessibility.requires_accessible_assets: true`.
### Inspectable Assets
These assets provide structured data that the format uses to render accessibly.
| Asset Type | Accessibility Fields | Purpose |
| - | - | - |
| **Image** | `alt_text` | Alternative text for screen readers |
| **Video** | `captions_url` | URL to captions file (WebVTT, SRT) |
| | `transcript_url` | URL to text transcript |
| | `audio_description_url` | URL to audio description track |
| **Audio** | `transcript_url` | URL to text transcript |
**Example** — video asset in a manifest for an accessible format:
```json theme={null}
{
"creative_id": "brand_video_001",
"format_kind": "video_hosted",
"assets": {
"video_file": {
"url": "https://cdn.example.com/video.mp4",
"width": 1920,
"height": 1080,
"duration_ms": 30000,
"captions_url": "https://cdn.example.com/video.vtt",
"transcript_url": "https://cdn.example.com/video-transcript.txt",
"audio_description_url": "https://cdn.example.com/video-ad.mp3"
}
}
}
```
### Opaque Assets
HTML and JavaScript assets are black boxes — the format can't inspect their rendering. These assets carry an `accessibility` object with self-declared properties.
| Field | Type | Description |
| - | - | - |
| `alt_text` | string | Text alternative describing the creative content |
| `keyboard_navigable` | boolean | Creative can be fully operated via keyboard |
| `motion_control` | boolean | Respects `prefers-reduced-motion` or provides pause/stop controls |
| `screen_reader_tested` | boolean | Creative has been tested with screen readers |
**Example** — HTML creative with accessibility declarations:
```json theme={null}
{
"creative_id": "rich_media_001",
"format_kind": "html5",
"assets": {
"creative_html": {
"content": "...",
"version": "HTML5",
"accessibility": {
"alt_text": "Interactive product carousel showing summer collection",
"keyboard_navigable": true,
"motion_control": true,
"screen_reader_tested": true
}
}
}
}
```
Self-declared accessibility is a trust claim. Platforms may independently validate these properties — that is outside the scope of the protocol.
## Structured Rejection Details
When a creative agent or seller performs an accessibility check and rejects a
creative, it uses the existing `CREATIVE_REJECTED` code with
`recovery: "correctable"`. For backward compatibility, the top-level `field`
identifies the first failing asset in JSONPath-lite form. The optional
`error.details` object may conform to the experimental
[`accessibility-violation.json`](https://adcontextprotocol.org/schemas/3.2.1/error-details/accessibility-violation.json)
shape and batch every failure in `violations[]`:
```json theme={null}
{
"code": "CREATIVE_REJECTED",
"message": "Creative fails the required accessibility level",
"field": "creative_manifest.assets.hero_image",
"recovery": "correctable",
"details": {
"violations": [
{
"pointer": "/creative_manifest/assets/hero_image",
"criterion": "1.4.3",
"criterion_source": "WCAG21",
"required_level": "AA",
"failure_kind": "contrast_ratio_insufficient",
"remediation": "For normal-sized text, increase contrast to at least 4.5:1; evaluate WCAG exceptions separately."
}
]
}
}
```
`criterion` and `criterion_source` identify the external requirement without
freezing an AdCP-owned WCAG corpus. Portable consumers use that pair after
validating the details schema. `failure_kind` is a bounded diagnostic vocabulary;
vendor extensions use an `x_` prefix. `remediation` remains untrusted advisory
text. This shape does not activate an accessibility policy by itself and is
distinct from `error.issues[]`, which is reserved for JSON Schema validation
output.
To stay within the transport error safety limit, producers include at most four
complete violations and keep the complete serialized error at or below 4096
bytes. When additional failures or remediation text are omitted, they set
`details.truncated: true`. Producers omit whole extra violations or remediation
text rather than truncating an RFC 6901 pointer token.
Pointers use RFC 6901 and are always rooted at the complete task request, like
the protocol's core error pointers. They are not rooted at the nested creative
manifest. Thus `build_creative` uses paths such as
`/creative_manifest/assets/hero_image`, while a batched `sync_creatives` request
uses paths such as `/creatives/0/assets/hero_image`. The top-level `error.field`
projects the first violation into the same request-rooted path using JSONPath-lite
notation (for example `creative_manifest.assets.hero_image`).
When `build_creative` receives only `creative_id` and resolves the manifest from
the creative library, the failing asset has no request path. In that case each
violation uses `/creative_id` and top-level `error.field` is `creative_id`.
Criterion and remediation fields preserve diagnostic detail, but the
request-rooted pointer intentionally cannot identify a nested stored asset.
`/creative_id` is attribution only and MUST NOT be interpreted as a nested
mutation path.
### Third-Party Tags
VAST and DAAST assets wrap video and audio delivered by third parties. They carry accessibility fields alongside their existing tag properties.
| Asset Type | Accessibility Fields |
| - | - |
| **VAST** | `captions_url`, `audio_description_url` |
| **DAAST** | `transcript_url` |
### Assets Without Accessibility Fields
Some asset types don't produce standalone rendered content and have no accessibility fields. When a format sets `accessibility.requires_accessible_assets: true`, these are effectively no-ops:
* **Text** — rendered by the format
* **Markdown** — rendered by the format
* **CSS** — styles, not content
* **URL** — links, not rendered content
* **Webhook** — server-side
## Discovering Accessible Formats
Buyers inspect canonical declarations returned in product `format_options[]` or creative-agent `supported_formats[]` and filter them client-side by declared accessibility constraints:
```json theme={null}
const accessible = product.format_options.filter(option =>
["AA", "AAA"].includes(option.params.accessibility?.wcag_level) &&
option.params.slots.some(slot => slot.asset_type === "image")
);
```
This selects formats that claim at least WCAG AA conformance and include an image slot. Accessibility claims remain declaration-specific and should be substantiated by the renderer or required asset metadata.
## Implementation Notes
**Enforcement is application-level.** The `x-accessibility` marker is a JSON Schema extension keyword. Standard JSON Schema validators ignore it — enforcement of `accessibility.requires_accessible_assets` must be implemented in application code that scans asset schemas for `x-accessibility: true` fields and validates their presence.
**For format implementers:**
* Set `accessibility.wcag_level` only when you can substantiate the claim — through your own rendering guarantees or by requiring accessible assets
* If your format renders from structured inputs, ensure your rendering pipeline meets the declared WCAG level (contrast, keyboard nav, ARIA)
* If your format wraps opaque assets, `accessibility.requires_accessible_assets: true` ensures the inputs carry the right declarations
**For creative producers:**
* When submitting to a format with `accessibility.requires_accessible_assets: true`, include all accessibility fields for your asset types
* For opaque assets, test accessibility properties before declaring them
* Provide captions and transcripts as separate hosted files, not embedded in the asset
* Select the recovery class only from `code` and `recovery`. After validating
`details` against `accessibility-violation.json`, portable tooling may group
diagnostics by (`criterion_source`, `criterion`); `failure_kind` refines the
display but does not select the recovery class.
* Treat pointers as untrusted references into an immutable copy of the original
request. Resolve them without mutation, require an allowlisted creative asset
location, and present the validated criterion to controlled repair logic or a
human. Never execute a pointer directly as a property-write path, never treat
`/creative_id` as an asset path, and never pass raw details or remediation text
to an LLM as instructions.
## Related Documentation
* [Creative Formats](/dist/docs/3.2.8/creative/formats) — Format structure and requirements
* [Asset Types](/dist/docs/3.2.8/creative/asset-types) — Asset specifications and payload schemas
* [Creative Manifests](/dist/docs/3.2.8/creative/creative-manifests) — Pairing assets with formats
* [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) — Creative-agent capability discovery
# AI creative for campaign teams
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/ai-creative-overview
AI creative in AdCP lets campaign teams write a brief and get production-ready ads generated across formats without learning the protocol.
AI creative in AdCP means you write a brief and an AI agent handles production. It generates ads from your direction, adapts them across formats, and can personalize them at serve time. You stay in control of the brand. The AI does the heavy lifting.
This page explains how it works in terms you already use.
## How it works
The workflow mirrors what you do with a production team, except the team is an AI agent.
### 1. Write the brief
You describe what you want in plain language, the same way you'd brief a creative team.
*"Create a holiday promotion for our outdoor gear line. Earth tones, active lifestyle imagery. Headline should emphasize the limited-time offer."*
The brief can include a message (what to say), brand identity assets (logos, colors, fonts), and constraints (tone of voice, topics to avoid). The more specific you are, the better the output.
### 2. Review concepts
The AI generates options. You see previews — rough concepts for direction, or polished versions for stakeholder review. Browse them the way you'd review comps from a production studio.
You control the quality level:
* **Draft mode** gives you fast, rough concepts for exploration. Think tissue session.
* **Production mode** gives you polished, client-ready output. Think final comps.
### 3. Iterate
Give feedback in the language you'd use with any creative team.
*"Make the headline more urgent."*
*"Try a warmer color palette."*
*"Keep the layout but swap in the lifestyle photo instead of the product shot."*
The AI revises and returns updated previews.
### 4. Approve and traffic
Lock in the final creative. It gets synced to your campaigns — assigned to media buys, matched to placements, ready to serve.
### 5. Monitor what actually ran
After launch, review what the AI served. Every variant, every context. Full audit trail. If the AI personalized headlines per audience, you can see each version and how it performed.
## Quality control
AI creative has two separate quality dimensions. Understanding both prevents surprises.
**Concept quality** is about the creative itself. Draft mode produces fast, rough ideas — useful when you're exploring directions and don't need pixel-perfect output. Production mode produces finished work suitable for client review and launch. You choose which mode based on where you are in the process.
**Preview quality** is about how you view the output. Quick thumbnails let you scan many options fast. Full-fidelity renders show exactly how the ad will look at final size and resolution. These are independent of concept quality — you can get a high-fidelity render of a draft concept, or a quick thumbnail of a production-ready piece.
Think of it as the difference between a tissue session (rough concepts, fast iteration) and a final presentation (polished work, high-res mockups).
## Brand safety
Four layers keep your brand protected throughout the process.
**The brief itself.** Your creative direction sets the boundaries. Specify tone, topics to include, topics to avoid, and any do's and don'ts. The AI works within these constraints.
**Brand identity.** Logos, color palettes, typography, and brand guidelines are provided as structured assets. The AI references them during generation, not just as suggestions but as requirements.
**Pre-launch review.** Before anything goes live, preview what the AI will generate. Review concepts, test edge cases, and approve the system before it serves a single impression.
**Post-launch audit.** After launch, see every variant that was actually served. Not a summary — the actual creative outputs, with context about when and where each ran.
## What to expect
AI-generated ads work differently from traditional production in a few important ways.
**Previews are representative, not exact.** Because the AI can generate per-impression (adapting to context, audience, or placement), a pre-launch preview shows you what the AI *will* generate, not the one fixed ad it will serve. The preview is accurate to the brief and brand identity, but the live campaign may produce variations.
**Conversational formats need guardrail testing.** If your ad includes an interactive chatbot or conversational element, test the boundaries. What happens when someone asks about a competitor? What if they ask an off-topic question? Pre-launch review should include these scenarios.
**You approve the system, not every individual ad.** With traditional creative, you approve each finished ad. With AI creative, you approve the combination of brief, brand identity, and guardrails that the AI uses to generate ads. This is what makes personalization at scale possible — and why getting the brief and guardrails right matters more than reviewing every output.
## Protocol terms in agency language
| What you call it | What AdCP calls it |
| - | - |
| Creative brief | `message` or `assets.brief` in `build_creative` |
| Comp / mockup | Preview from `preview_creative` |
| Ad unit spec sheet | Creative manifest |
| Production studio | Creative agent |
| Placement size | Format (e.g., `display_300x250`) |
| Trafficking | `sync_creatives` or inline attachment on `create_media_buy` |
| Campaign report (variant-level) | `get_creative_delivery` |
## Next steps
When you're ready to go deeper:
* **See it in action** -- The [Creative protocol overview](/dist/docs/3.2.8/creative) follows a strategist from brief to delivery across CTV, display, and social
* **Technical workflow** -- [Generative creative](/dist/docs/3.2.8/creative/generative-creative) walks through the API step by step
* **Library management** -- [Creative libraries and concepts](/dist/docs/3.2.8/creative/creative-libraries) covers organizing and syncing assets
* **CTV and video** -- [CTV and connected TV](/dist/docs/3.2.8/creative/channels/ctv) covers SSAI/CSAI delivery, companion ads, and VAST tags
* **Multi-agent orchestration** -- [Multi-agent creative orchestration](/dist/docs/3.2.8/creative/multi-agent-orchestration) covers distributing creatives across sellers
* **Brand safety details** -- [Sales agent creative capabilities](/dist/docs/3.2.8/creative/sales-agent-creative-capabilities) explains guardrails and inline creative management
* **Learning** -- The [certification program](/dist/docs/3.2.8/learning/overview) teaches AdCP through interactive modules with Addie
# Asset Types
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/asset-types
AdCP asset types define standardized properties for images, video, text, audio, tags, and tracking URLs used in creative formats.
> **Canonical-formats readers**: this page describes asset types and their payload shapes — the same in v1 and the canonical-formats path. For how assets map to canonical-format slots via `asset_group_id`, see [canonical-formats](/dist/docs/3.2.8/creative/canonical-formats) and the [migration guide](/dist/docs/3.2.8/creative/canonical-formats-migration). v1 uses `asset_id` + `asset_role`; canonical formats use `asset_group_id` referencing the canonical vocabulary registry. Both paths use the same asset payload schemas — only the slot-key vocabulary differs.
Creative formats in AdCP use standardized asset types with well-defined properties. Assets are the discrete, typed building blocks used by formats to define requirements and by manifests to supply concrete values.
Standardizing asset types ensures consistency across formats and makes requirements easier for buyers and systems to understand.
## Asset types in v2
The full set of asset types valid in a v2 format `slots` declaration's `asset_type` field:
| asset_type | What it carries | Where defined |
| - | - | - |
| `image` | Image file (jpg/png/gif/webp/svg) | `/schemas/core/assets/image-asset.json` |
| `video` | Video file (mp4/webm/mov) | `/schemas/core/assets/video-asset.json` |
| `audio` | Audio file (mp3/aac/wav) | `/schemas/core/assets/audio-asset.json` |
| `text` | Plain text (headline, body, script) | `/schemas/core/assets/text-asset.json` |
| `markdown` | Markdown text | `/schemas/core/assets/markdown-asset.json` |
| `url` | URL with `url_type` discriminator (clickthrough, tracker_pixel, third-party tag) | `/schemas/core/assets/url-asset.json` |
| `html` | Inline HTML | `/schemas/core/assets/html-asset.json` |
| `css` | CSS rules | `/schemas/core/assets/css-asset.json` |
| `javascript` | JavaScript | `/schemas/core/assets/javascript-asset.json` |
| `vast` | VAST tag (URL or inline XML), VAST 2.x-4.x | `/schemas/core/assets/vast-asset.json` |
| `daast` | DAAST tag (URL or inline XML), 1.0-1.1 | `/schemas/core/assets/daast-asset.json` |
| `webhook` | Webhook URL for async creative production | `/schemas/core/assets/webhook-asset.json` |
| `brief` | Free-text creative brief (input to generative production) | `/schemas/core/assets/brief-asset.json` |
| `catalog` | Reference to a synced catalog (sponsored_placement) | `/schemas/core/assets/catalog-asset.json` |
| `published_post` | Reference to an already-published post that the seller resolves after authorization/review | `/schemas/core/assets/published-post-asset.json` |
| `zip` | Zip archive (HTML5 banner bundle) | `/schemas/core/assets/zip-asset.json` |
| `vast_tracker` | Single VAST `Tracking` event URL (decomposed) | `/schemas/core/assets/vast-tracker-asset.json` |
| `daast_tracker` | Single DAAST `Tracking` event URL (decomposed) | `/schemas/core/assets/daast-tracker-asset.json` |
| `pixel_tracker` | Renderer-fired HTTP tracker (image pixel or JS include) for any web-rendered canonical. `event` (impression / viewable_mrc\_\* / viewable_video_50 / audible_video_complete / click / custom) × `method` (img / js). Maps to IAB OpenRTB Native 1.2 `imptrackers[]` / `jstracker` / `eventtrackers[]` / `link.clicktrackers[]`; standardized event types 1-4 are reused, while audible completion is an AdCP-defined event and `custom` can carry exchange/vendor extensions | `/schemas/core/assets/pixel-tracker-asset.json` |
| `object` | Structured object (image_carousel `cards`, `video_brief` for generative video) — sub-shape declared by the canonical | (no standalone schema; per-canonical sub-shape) |
In a v2 manifest's `assets` map, the **slot key** is the canonical's `asset_group_id` (e.g., `image_main`, `video_main`, `script`, `cards`, `landing_page_url`) and the **value** carries the matching asset payload with its `asset_type` discriminator. The format declaration's `slots[].asset_type` tells the validator which payload schema applies.
Published-post references use the same rule: a product that accepts existing posts declares a `published_post` slot, and the manifest value carries `asset_type: "published_post"` with a `post_url` or `platform_post_id`.
## Important: Payload vs Requirements
For payload schemas (the structure of the actual asset data supplied in creative manifests), see:
* [Asset Type Registry](https://adcontextprotocol.org/schemas/3.2.8/creative/asset-types/index.json) - Links to all payload schemas
* Core Asset Schemas at `/schemas/3.2.8/core/assets/` - Individual asset payload definitions
**Key distinction:**
**Format requirements** (this document) define constraints such as:
* Whether an asset is required or optional
* Acceptable file or container formats
* Duration, dimension, or aspect ratio limits
* File size and bitrate limits
* Allowed or restricted features (for tag-based assets)
**Payload schemas** (core schemas) define the supplied values, such as:
* `url`
* `content` (for inline text or inline tag markup)
* `width` / `height` (when declared)
* `duration_ms` (when applicable)
* `format` (declared container type)
File-size limits use decimal, exact units throughout AdCP: `*_kb` means 1 KB = 1,000 bytes, `*_mb` means 1 MB = 1,000,000 bytes, and `*_bytes` is an exact byte count. Do not interpret KB/MB fields as KiB/MiB.
## Asset Type Schema
The official JSON schema for asset types is available at:
* **Production**: [https://adcontextprotocol.org/schemas/asset-types-v1.json](https://adcontextprotocol.org/schemas/asset-types-v1.json)
* **GitHub**: [https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/asset-types-v1.json](https://github.com/adcontextprotocol/adcp/blob/main/static/schemas/asset-types-v1.json)
## Core Asset Types
### Video Asset
Video assets represent video files with specific technical requirements.
```json theme={null}
{
"asset_type": "video",
"required": true,
"duration_seconds": 15,
"acceptable_formats": ["mp4"],
"acceptable_codecs": ["h264"],
"acceptable_resolutions": ["1920x1080", "1280x720"],
"aspect_ratio": "16:9",
"max_file_size_mb": 30,
"min_bitrate_mbps": 8,
"max_bitrate_mbps": 10
}
```
**Properties:**
* `duration_seconds`: Expected video duration
* `min_duration_seconds` / `max_duration_seconds`: Duration range (if flexible)
* `acceptable_formats`: Container formats (mp4, webm, mov)
* `acceptable_codecs`: Video codecs (h264, h265, vp8, vp9, av1)
* `acceptable_resolutions`: List of width x height strings
* `aspect_ratio`: Required aspect ratio (16:9, 9:16, 1:1, etc.)
* `max_file_size_mb`: Maximum file size in decimal megabytes (1 MB = 1,000,000 bytes)
* `min_bitrate_mbps` / `max_bitrate_mbps`: Bitrate range in Mbps
* `features`: Additional requirements (e.g., \["non-skippable", "sound on"])
### Image Asset
Static image assets for banners, logos, and visual content.
```json theme={null}
{
"asset_type": "image",
"required": true,
"width": 300,
"height": 250,
"acceptable_formats": ["jpg", "png", "gif"],
"max_file_size_kb": 200,
"animation_allowed": true
}
```
**Properties:**
* `width` / `height`: Dimensions in pixels
* `pixel_ratio`: Optional intrinsic pixels per logical render pixel (for example, `2` for a 600×500 asset rendered into a logical 300×250 slot). SDKs infer it when the target format's dimensions are sufficient.
* `min_width` / `min_height`: Minimum dimensions (px; typically used by responsive/sizeless formats)
* `aspect_ratio`: Required aspect ratio
* `acceptable_formats`: Image formats (jpg, png, gif, webp, svg)
* `max_file_size_kb`: Maximum file size in decimal kilobytes (1 KB = 1,000 bytes)
* `transparency`: Whether transparency is required/supported
* `animation_allowed`: Whether animated GIFs are accepted
* `notes`: Additional requirements (e.g., "Must be free of text")
**Use Cases:**
* High-density delivery in any canonical: declare accepted densities with `slots[].pixel_ratios`; use top-level `params.pixel_ratios` for the `image` canonical's `image_main` slot.
* Multi-rendition delivery: add `slots[].required_pixel_ratios` and provide that image slot as an array with one rendition per required density. Accepted densities outside the required subset remain optional.
* Fixed layout: provide `width` and `height`. Do not include `min_width`, `min_height`, or `aspect_ratio`.
* Responsive (fixed image aspect ratio): provide `min_width`, `min_height` and `aspect_ratio`. Do not include `width` or `height`.
* Responsive (any image aspect ratio): provide `min_width` and `min_height` only. Do not include `width`, `height`, or `aspect_ratio`.
**Note**: In fixed layouts, the image slot is an exact pixel box, so specify `width` and `height`. In responsive layouts, the renderer will resize the image; use `min_width`/`min_height` to ensure there are enough pixels for a sharp result after scaling. Use `aspect_ratio` only when the image asset itself must be a specific shape (e.g., 16:9); omit it if any image aspect ratio is acceptable
### Text Asset
Text content for headlines, descriptions, CTAs, etc.
```json theme={null}
{
"asset_type": "text",
"required": true,
"text_type": "headline",
"max_length": 90,
"min_length": 10
}
```
**Properties:**
* `text_type`: Specific type (title, headline, description, body, cta, advertiser_name, disclaimer)
* `max_length`: Maximum character count
* `min_length`: Minimum character count
* `default`: Default value if not provided
* `allowed_characters`: Regex pattern for validation
* `format`: Expected format (plain, currency, percentage)
### URL Asset
Links for clickthroughs, tracking, and landing pages. Two related but distinct fields describe a URL asset:
* **`url_type`** (on the manifest asset) — the **mechanism** the receiver uses to invoke this URL.
* **`url-asset-requirements.role`** (on the format) — the **purpose** this URL slot serves in the creative.
A slot can be `click_tracker` (purpose) and accept a `tracker_pixel` (mechanism) URL — those describe different things.
#### Manifest-side: `url_type` (mechanism)
Senders **SHOULD** include `url_type` on every URL asset. The valid values are:
| Value | Mechanism |
| - | - |
| `clickthrough` | User-click destination (landing page or ad-tech redirector) |
| `ad_request` | Invokes a third-party display creative endpoint at impression time |
| `tracker_pixel` | Fires HTTP GET, expects 1×1 pixel or 204 response (impression / event / 3P trackers) |
| `tracker_script` | Loads as a `"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://acmecorp.example.com/holiday-sale?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
The `CLICK_URL` macro was substituted with the provided value; `CACHEBUSTER` remains as a placeholder for the sales agent to resolve at serve time.
Do not use `recipe_hash` to deduplicate ad tags, prove legal/disclosure equivalence, or join build results to served delivery data. Use `build_variant_id` and the promoted `creative_id` for lineage and reporting.
> [!NOTE]
>
> **Cross-agent workflow**: When creative generation and media buying are handled by different agents, use `build_creative` on the creative agent to produce a manifest with tags, then [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) on the sales agent to upload it. When the sales agent implements both protocols, this happens on a single endpoint — see [Creative capabilities on sales agents](/dist/docs/3.2.8/creative/sales-agent-creative-capabilities).
### Multi-format generation
Generate creatives for multiple formats in a single call using `target_capability_ids`. The agent produces one manifest per format from the same source assets and brief:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "d4e5f6a7-b8c9-4012-d345-6789abcdef01",
"message": "Create display banners for our spring campaign",
"target_capability_ids": [
"display_image_300x250",
"display_image_728x90",
"display_image_320x50"
],
"brand": {
"domain": "acmecorp.com"
},
"creative_manifest": {
"format_kind": "image",
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.acmecorp.com/spring-hero.png",
"width": 1200,
"height": 628
},
"headline": {
"asset_type": "text",
"content": "Spring Collection Now Available"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://acmecorp.example.com/spring?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
The response uses `creative_manifests` instead of singular `creative_manifest`. Each result is a complete canonical manifest, ready for `sync_creatives` or [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative):
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"creative_manifests": [
{
"format_kind": "image",
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/spring_300x250.png",
"width": 300,
"height": 250
},
"headline": { "asset_type": "text", "content": "Spring Collection Now Available" },
"clickthrough_url": { "asset_type": "url", "url": "https://acmecorp.example.com/spring?campaign={MEDIA_BUY_ID}" }
}
},
{
"format_kind": "image",
"assets": { /* same structure, adapted for 728x90 */ }
},
{
"format_kind": "image",
"assets": { /* same structure, adapted for 320x50 */ }
}
]
}
```
Multi-capability requests are atomic — if any capability fails, the entire request fails. Response order matches `target_capability_ids`; each manifest's `format_kind` describes the resulting canonical contract.
### Multi-format workflow
After a multi-format build, preview all results using `preview_creative` batch mode. Each element of `creative_manifests` in the build response becomes a `creative_manifest` in the batch preview request:
```json theme={null}
{
"request_type": "batch",
"quality": "draft",
"requests": [
{ "target_capability_id": "preview_image_300x250", "creative_manifest": { /* 300x250 manifest from build response */ } },
{ "target_capability_id": "preview_image_728x90", "creative_manifest": { /* 728x90 manifest from build response */ } },
{ "target_capability_id": "preview_image_320x50", "creative_manifest": { /* 320x50 manifest from build response */ } }
]
}
```
Resolve each preview route from a `creative.supported_formats[]` entry whose `operations` contains `preview` and whose canonical declaration satisfies that manifest. Build and preview capability IDs may differ, even on the same agent.
To refine a single format from a multi-format build, call `build_creative` again with `target_capability_id` (singular) and pass back that format's manifest. You don't need to rebuild all formats — just iterate on the one that needs work.
> [!NOTE]
>
> Multi-format requests with `include_preview: true` generate one default preview per format. Custom `preview_inputs` are only supported with single-format requests. For multi-format builds where you need context-specific previews (device variants, different contexts), use a separate `preview_creative` batch call after building.
### Transformers & variants
Select a transformer (discovered via [`list_transformers`](/dist/docs/3.2.8/creative/task-reference/list_transformers)) with `transformer_id`, supply a typed `config` keyed to its params, and ask for alternatives with `max_variants`. The agent returns the [variant response](#variant-response): `creatives[]`, each holding a `variants[]` array. Read `recommended` / `rank` to surface the agent's best-of-N pick; traffic the variant(s) you want by their `build_variant_id`.
Resolutions and quality tiers go on `target_capability_ids` (or `quality`), not on `variant_axis` — variants are alternatives for the *same* format.
```javascript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { BuildCreativeResponseSchema } from '@adcp/sdk';
const result = await testAgent.buildCreative({
account: { account_id: 'acct_acme' },
transformer_id: 'audiostack_voiceover',
config: { voice: 'isaac', speaking_rate: 1.1, mastering_preset: 'podcast' },
target_capability_id: 'audio_vo',
creative_manifest: {
format_kind: 'audio_hosted',
assets: { script: { asset_type: 'text', content: 'Discover the new winter collection.' } },
},
max_variants: 3,
variant_axis: { dimension: 'best_of_n', label: 'Read takes' },
keep_mode: 'keep_one',
idempotency_key: '0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5',
});
const parsed = BuildCreativeResponseSchema.parse(result);
for (const creative of parsed.creatives ?? []) {
for (const variant of creative.variants) {
console.log(variant.build_variant_id, variant.rank, variant.recommended, variant.vendor_cost);
}
}
```
```python test=false theme={null}
import asyncio
from adcp.testing import test_agent
from adcp import BuildCreativeResponse
async def main():
result = await test_agent.build_creative(
account={"account_id": "acct_acme"},
transformer_id="audiostack_voiceover",
config={"voice": "isaac", "speaking_rate": 1.1, "mastering_preset": "podcast"},
target_capability_id="audio_vo",
creative_manifest={
"format_kind": "audio_hosted",
"assets": {"script": {"asset_type": "text", "content": "Discover the new winter collection."}},
},
max_variants=3,
variant_axis={"dimension": "best_of_n", "label": "Read takes"},
keep_mode="keep_one",
idempotency_key="0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5",
)
parsed = BuildCreativeResponse.model_validate(result)
for creative in parsed.creatives or []:
for variant in creative.variants:
print(variant.build_variant_id, variant.rank, variant.recommended, variant.vendor_cost)
asyncio.run(main())
```
You pay for all three takes (`per_unit` × 3); `keep_mode` is advisory. Keeping is a separate trafficking step on the chosen `build_variant_id` — use that id as the `creative_id` when promoting the produced manifest through [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives). The kept variant then lazily earns a creative record whose `creative_id` is the build leaf id and flows to [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) and delivery reporting.
### Paid build with pricing
When the creative agent charges and `account` is provided, the response includes pricing fields. The agent selects the applicable pricing option server-side based on the account's rate card and the work performed — the buyer does not pass `pricing_option_id` in the request.
**Per-unit pricing (transformation agent)**:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "e5f6a7b8-c9d0-4123-e456-789abcdef012",
"account": { "account_id": "acct_acme_creative" },
"creative_id": "cr_hero_banner",
"target_capability_id": "display_728x90"
}
```
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_kind": "image",
"assets": {
"ad_tag": {
"content": "..."
}
}
},
"pricing_option_id": "po_standard_per_format",
"vendor_cost": 2.00,
"currency": "USD",
"consumption": {
"renders": 1
}
}
```
The `pricing_option_id` corresponds to one of the options from [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives#pricing). The buyer passes it in [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) for reconciliation.
**CPM pricing (ad server)** — `vendor_cost` is 0 at build time because cost accrues when impressions are served:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": { "..." : "..." },
"pricing_option_id": "po_video_cpm",
"vendor_cost": 0,
"currency": "USD"
}
```
## Response format
### Single-format response
When the request uses `target_capability_id`, the response contains a single creative manifest:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"recipe_hash": "rh_winter_300x250_4c2a",
"creative_manifest": {
"format_kind": "image",
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"catalog_id": "winter-sale"
},
"banner_image": {
"asset_type": "image",
"url": "https://cdn.example.com/generated-banner.png",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "50% Off Winter Sale"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### Multi-format response
When the request uses `target_capability_ids`, the response contains an array of creative manifests:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"creative_manifests": [
{
"format_kind": "image",
"assets": { /* ... */ }
},
{
"format_kind": "image",
"assets": { /* ... */ }
}
]
}
```
### Variant response
When the request uses `max_creatives`, `max_variants` > 1, `variant_axis`, or `refine_from_build_variant_id`, the agent returns the `BuildCreativeVariantSuccess` shape — the third success shape (`oneOf` member 3 of 6) alongside the single- and multi-format responses, which are unchanged and still used when you build one creative with one variant.
> [!WARNING]
>
> **No fallback.** If you send any of `max_creatives`, `max_variants > 1`, `variant_axis`, or `refine_from_build_variant_id`, you **must** handle `creatives[]` — you will not get `creative_manifest`/`creative_manifests` back. There is no automatic downgrade to the single/multi shapes.
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creatives": [
{
"build_creative_id": "bc_card_01",
"catalog_item_ref": { "catalog_type": "product", "item_id": "sku_winter_parka" },
"variants": [
{
"build_variant_id": "bv_card01_a",
"recipe_hash": "rh_card01_bestofn_7b91",
"creative_manifest": { "format_kind": "image", "assets": { "...": "..." } },
"variant_axis_value": "take_1",
"recommended": true,
"rank": 1,
"pricing_option_id": "po_per_image",
"vendor_cost": 0.40,
"currency": "USD",
"consumption": { "images_generated": 1 }
},
{
"build_variant_id": "bv_card01_b",
"recipe_hash": "rh_card01_bestofn_7b91",
"creative_manifest": { "format_kind": "image", "assets": { "...": "..." } },
"variant_axis_value": "take_2",
"recommended": false,
"rank": 2,
"pricing_option_id": "po_per_image",
"vendor_cost": 0.40,
"currency": "USD",
"consumption": { "images_generated": 1 }
}
]
}
],
"items_total": 150,
"items_returned": 5,
"vendor_cost": 4.00,
"currency": "USD"
}
```
*The `creatives[]` array above is abbreviated to one of the 5 returned groups; the aggregate `vendor_cost` of $4.00 covers all 5 groups × 2 variants × $0.40 — it equals the sum of every produced leaf's `vendor_cost`, not just the leaves shown.*
* **creatives\[]**: One entry per built creative group. With `max_creatives`, there is one entry per sampled catalog item (`catalog_item_ref` identifies which item); without catalog fan-out there is a single entry. Treat this as the produced group set; choose among alternatives inside each group's `variants[]`.
* **creatives\[].build_creative_id**: Identifies a built creative within this response.
* **creatives\[].catalog_item_ref**: Present on catalog fan-out — an object identifying the source catalog item via `item_id` (plus optional `catalog_type`).
* **creatives\[].signal_condition**: Present on signal fan-out — the SignalTargeting condition this creative group is FOR (e.g. weather=rain). Shares `signal_ref` identity with sales-side package targeting so the sales agent can match and reject incompatible assignments.
* **creatives\[].errors\[]**: Present only on a *failed* catalog item — catalog fan-out is non-atomic, so a failed item is returned as a `creatives[]` entry carrying `errors[]` and no `variants[]`, without failing the batch.
* **creatives\[].variants\[]**: The choose-among alternatives produced for this creative group. Length is at most `max_variants`. Each variant carries its own complete `creative_manifest`.
* **variants\[].build_variant_id**: Identifies a single variant — the leaf-level **lineage anchor**. This is its **own namespace** — never reuse a `preview_id` (a [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) render) or a served `variant_id` (a delivery-time identifier) here. You traffic a chosen build by passing its `build_variant_id`.
* **variants\[].recipe_hash**: Optional ETag-style identity for the build-determining inputs that produced the leaf. It is agent-computed, opaque, and comparable only within the same agent. Best-of-N leaves from the same source recipe SHOULD share a value. It is useful for cache transparency, cost-avoidance hints, and recipe-level grouping, but it is not output equality, not legal/disclosure equivalence, and not the build-to-delivery join.
* **variants\[].parent_build_variant_id**: Present only on a refined variant ([Refinement](#refinement)) — the `build_variant_id` of the source it was refined from. Absent for first-generation builds.
* **variants\[].variant_axis_value**: The value of the `variant_axis` dimension this variant represents (e.g. a voice, a theme).
* **variants\[].recommended** / **variants\[].rank**: Best-of-N signals — `recommended` flags the agent's top pick; `rank` orders the variants. These plus `variant_axis` and `keep_mode` are how best-of-N is expressed.
* **variants\[].eval**: Present only when the request supplied an advisory [`evaluator`](#request-parameters) and the agent advertises `creative.supports_evaluator`. The rank-side of the [`get_creative_features`](/dist/docs/3.2.8/governance/creative/get_creative_features) feature oracle. `eval.features[]` is **`creative-feature-result[]`** — the same shape `get_creative_features.results[]` returns (e.g. a `creative_quality_score` number, an `on_brief` categorical, a calibrated `predicted_performance`); the wrapper is open, each feature item is closed. The agent runs a **gate-then-rank** pipeline over its best-of-N: it evaluates each leaf, drops leaves failing the hard `evaluator.feature_requirement[]` gate from its recommended survivors, then orders survivors by `evaluator.rank_by` (`[{feature_id, direction}]`) — which is what `recommended`/`rank` reflect. The gate is **internal pruning** of which leaves the agent recommends from its own exploration, not an AdCP-layer block: what is produced and billed is governed by `max_variants`/`max_creatives`/`max_spend`, so this block appears only on returned (billed) leaves. Feature discovery uses `get_adcp_capabilities.governance.creative_features`; `evaluator_id` is an account-scoped preset that emits values over that feature vocabulary, not a discovered feature ID and not a separate evaluator feature catalog. The exemplars form calibrates one `predicted_performance` feature in \[0,1]; a pass/warn/fail verdict is a categorical string feature value gated via `feature_requirement.allowed_values` — `eval.features[]` is a feature measurement, never a stored verdict. When the evaluator names an external agent, it must be on the seller's `creative_policy.accepted_verifiers[]` (off-list → [`EVALUATOR_AGENT_NOT_ACCEPTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-evaluator-agent-not-accepted)); the producing agent authenticates its outbound call on the transport, not inside the evaluator payload. Sellers SHOULD populate `eval.calls_used` / `eval.seconds_used` when `agent_url` was used and an `eval_budget` was supplied.
* **variants\[] pricing receipt**: Each variant carries a per-leaf receipt (`pricing_option_id`, `vendor_cost`, `currency`, `consumption`) for the work that produced it. Whenever the build reports cost (the aggregate `vendor_cost` is present), every produced leaf MUST carry its own `vendor_cost` + `currency` (schema-enforced) — leaves are the billing source of truth, and an untrafficked leaf is reconciled from this receipt alone. A CPM-deferred leaf reports `vendor_cost: 0`.
* **items_total** / **items_returned**: For catalog fan-out, the total eligible catalog items and how many creatives were returned (e.g. "5 of 150").
* **leaves_total** / **leaves_returned**: Leaf-granular counts — total leaves the request would produce vs. how many were actually produced/billed. When `budget_status` is `capped`, `leaves_returned` \< `leaves_total` is the shortfall (works even for variant-only fan-out with no catalog).
* **vendor_cost** / **currency**: Aggregate cost across all produced variants in the response.
* **keep_mode_applied**: Echoes the `keep_mode` the agent applied (present when the request set it). `keep_mode` is advisory and doesn't change what's produced or billed, so this is your confirmation the hint was received — the audit trail for a "I asked for keep_one but was billed for N" dispute.
* **selection_strategy_applied**: Echoes the `selection_strategy` the agent applied (when `max_creatives` sampling occurred). The ranking itself shows in `rank`/`recommended` on the leaves.
* **budget_status**: `complete` (default; absent == complete) or `capped` — a `max_spend` ceiling stopped production early (a successful partial build, not a failure). See [Spend controls](#spend-controls).
* **errors\[]**: Advisory (non-terminal) entries on an otherwise-successful build — e.g. a [`BUDGET_CAP_REACHED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-budget-cap-reached) notice when `budget_status` is `capped`.
> [!WARNING]
>
> You pay for **every produced variant** (`per_unit` × N), not just the ones you keep. Keeping is a separate client act of trafficking the chosen `build_variant_id`(s), typically by using each kept leaf as `creative_id` on [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives). A kept variant lazily earns a creative record when it is added to the library or first trafficked; that `creative_id` is what flows to [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) and delivery reporting. An unkept variant is still billed but never earns a `creative_id`.
> [!NOTE]
>
> **Atomicity differs by axis.** Variant production *per format* is atomic — if one variant for a format fails, that format's build fails. Catalog fan-out (`max_creatives`, per item) is **non-atomic**: individual `creatives[]` entries may succeed while others fail. A failed item is returned as a `creatives[]` entry carrying `errors[]` (and no `variants[]`); the batch still succeeds.
>
> **Build variants, representations, revisions, and served variants are separate.** `build_variant_id` identifies a candidate produced by this task. `representation_id` identifies one equivalent trafficking form inside a complete `revision_id`. The served `variant_id` in [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery) identifies an immutable execution that actually ran. Keeping a build variant may promote it to a durable creative/revision; representation selection and later serving do not reuse its build ID as either of the other identities.
>
> **Resolutions and quality tiers are not variants.** Multiple sizes or quality levels belong on the format axis — pass them as `target_capability_ids` (or `quality`), not as `variant_axis` values. Variants are alternatives *for the same format* (different voice, theme, or best-of-N take).
### Refinement
Conversational refinement re-builds a prior variant with free-form direction — "make it warmer", "tighten the CTA". The typed `config` surface is closed by design, so free-form intent rides the **open** surface that already exists: the `message` field (whose description is already *"For refinement, this describes the desired changes"*). Refinement is therefore not a new task — it's `build_creative` with one extra input:
* Pass `refine_from_build_variant_id` (a prior leaf's `build_variant_id`) plus your instruction in `message` and any `config` delta.
* The agent re-builds from that leaf and returns **new** variants, each with `parent_build_variant_id` set to the source. A refinement is **never a mutation** — the parent leaf is unchanged, and the new leaf earns its own `build_variant_id` (and, on trafficking, its own `creative_id`).
* `transformer_id` and the target format(s) are **inherited** from the parent; you don't repeat them. Passing a `transformer_id` or target format that differs from the parent's is an [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request). `config` is applied as a **delta** over the parent's config.
* Composes with `max_variants` / `variant_axis` (e.g. "three warmer takes" → three refined leaves), but **not** with `max_creatives` / catalog fan-out — you refine one produced creative, not a catalog.
* Requires the agent to advertise `creative.supports_refinement: true` (it retains produced leaves for an agent-defined window). Agents that retain nothing return [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature); refine a buyer-held manifest instead via the transform path (`creative_manifest` + `message`). An unknown or no-longer-retained ref returns [`REFERENCE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-reference-not-found) with `error.field` set to `refine_from_build_variant_id`.
Any build can be refined, not just variant builds: a single-format `BuildCreativeSuccess` carries an optional `build_variant_id` (present when the agent supports refinement) that you pass as `refine_from_build_variant_id`. Multi-format builds that need per-output refinable leaves should request the variant shape (`max_variants`), since the bare `creative_manifests[]` array carries no leaf ids.
AI-derivative attribution rides the manifest's existing `provenance`; `parent_build_variant_id` carries only the lineage edge (refinements chain into a tree).
```json test=false theme={null}
{
"refine_from_build_variant_id": "bv_card01_a",
"message": "Warmer lighting, and move the logo to the lower-right.",
"max_variants": 3,
"account": { "account_id": "acct_acme" },
"idempotency_key": "7f2a1b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
}
```
### Spend controls
Fan-out and refinement can produce many independently-billed leaves (`max_creatives` × `max_variants`), and `per_unit` pricing gives a *rate* but not the *unit count* in advance (a 6-second voiceover and a 60-second one cost 10× at the same rate). Two opt-in controls, both gated by `creative.supports_spend_controls`:
* **Estimate first (`mode: "estimate"`).** A dry run: the agent produces and bills nothing and returns a `BuildCreativeEstimate` with a `cost_low`/`cost_high` band (and `basis`: `fixed` = exact, `estimated_units` = generative projection, `cpm_deferred` = cost accrues at serve). The band is the load-bearing piece — the seller derives it from your actual inputs, so you don't have to guess unit counts.
* **Cap the call (`max_spend: { amount, currency }`).** A hard stop: the agent produces leaves until the next would push aggregate `vendor_cost` over `amount`, then returns the partial `BuildCreativeVariantSuccess` with `budget_status: "capped"` and an advisory `BUDGET_CAP_REACHED` in `errors[]` — every returned leaf is real and billed, nothing produced is discarded. The leaf-granular shortfall is `leaves_returned` \< `leaves_total` (not `items_returned`/`items_total`, which count catalog items and don't capture a variant-only or mid-item cap); the `BUDGET_CAP_REACHED` advisory is the authoritative cap signal. If even the first leaf would exceed the cap, the call fails with a terminal `BUDGET_CAP_REACHED`. `currency` must match the rate card (no FX) or the request is rejected `INVALID_REQUEST` (`error.field: max_spend.currency`). `max_spend` bounds only **build-time** `vendor_cost` — CPM-priced builds (`basis: cpm_deferred`) are 0 at build time and accrue at serve, so the cap never engages; bound a CPM fan-out with `max_creatives` instead.
They compose: estimate to get `cost_high`, then execute with `max_spend` = `cost_high` × a safety margin (CPM builds excepted — their `cost_high` is 0 at build time). `max_spend` caps a **single call**; to bound an autonomous **refinement loop**, track aggregate `vendor_cost` across calls and stop issuing them (a buyer responsibility in this revision — a protocol-level session budget is deferred to the working group).
> [!WARNING]
>
> `max_spend` and `mode: "estimate"` require the agent to advertise `creative.supports_spend_controls`; otherwise they're rejected with `UNSUPPORTED_FEATURE`. They're only meaningful with `bills_through_adcp: true` (an out-of-band biller has no AdCP cost to cap against).
>
> **Governance applicability.** A creative service advertising `adcp.governance_enforcement` for `build_creative` requires an approved `governance_context` only when the execution incurs positive vendor cost. Estimate-only calls and zero-cost retrieval are exempt. A creative ad server that never commits or meters spend through AdCP does not acquire a [`sync_governance`](/dist/docs/3.2.8/accounts/tasks/sync_governance) obligation merely by trafficking creative; if it later exposes an AdCP-billed mutation, that commitment-bearing task must be declared and governed explicitly.
### Estimate response
A `mode: "estimate"` request returns the `BuildCreativeEstimate` shape (`oneOf` member 4 of 6) — produced and billed nothing, just a projected cost band:
```json test=false theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"mode": "estimate",
"estimate": {
"items_total": 150,
"items_to_produce": 5,
"variants_per_item": 3,
"leaves_total": 15,
"currency": "USD",
"cost_low": 6.00,
"cost_high": 9.00,
"cost_expected": 7.50,
"basis": "estimated_units"
},
"expires_at": "2026-06-01T00:00:00Z"
}
```
* **estimate.leaves_total** = `items_to_produce` × `variants_per_item` (× `conditions_total` when `signal_conditions` was sent) — the number of billable leaves `mode: "execute"` would produce.
* **estimate.cost_low / cost_high / cost_expected**: the projected aggregate cost band. The seller derives it from your actual inputs.
* **estimate.basis**: `fixed` (per-format flat — `cost_low == cost_high`, exact), `estimated_units` (generative `per_unit`; the band reflects unit-count uncertainty), or `cpm_deferred` (CPM — build-time cost 0, accrues at serve, so the band is 0).
* **estimate.per_leaf** (optional): per-leaf breakdown.
* Estimates are **advisory / non-binding** in this revision (binding quotes are deferred to the working group).
### Field descriptions
* **creative_manifest**: (single-format) The complete creative manifest ready for use with `sync_creatives` or `preview_creative`
* **creative_manifests**: (multi-capability) Array of portable canonical creative manifests, one per requested capability and in request order. Each contains its own `format_kind` and, when needed, `format_option_ref`.
* **format_kind**: The canonical format produced by the selected capability
* **assets**: Map of asset keys to asset content — includes creative content (images, text, URLs), catalogs, briefs, and anything else the format requires
* **expires_at**: Optional ISO 8601 timestamp when generated asset URLs in the manifest expire. Set to the earliest expiration across all generated assets. Re-build the creative after this time to get fresh URLs. Not present when the manifest contains no expiring URLs (e.g., pure text generation or assembly-only transforms).
* **preview**: Optional. Present when `include_preview` was true in the request and the agent supports inline preview. Contains the same content fields as a `preview_creative` single response (`previews`, `interactive_url`, `expires_at`) minus the `response_type` discriminator, so clients can reuse the same preview rendering logic. Preview URLs follow the same durability contract as `preview_creative`: they remain dereferenceable until `expires_at`, or until explicit out-of-band revocation when no expiration is present. For single-capability responses, each entry in `previews[]` corresponds to an input set from `preview_inputs`. For multi-capability responses, each entry includes a `capability_id` and corresponds to one requested capability (one default preview per capability; `preview_inputs` is ignored).
* **preview_error**: Optional. Standard error object (`code`, `message`, `recovery`) present when `include_preview` was true but preview generation failed. The `recovery` field indicates whether the failure is `transient` (retry later), `correctable`, or `terminal`. Distinguishes "agent doesn't support inline preview" (field absent, no error) from "preview generation failed" (field present with structured error).
### Compliance errors
If the manifest includes a brief asset with `compliance` requirements that the creative agent cannot satisfy, the agent MUST return an error — not a partial success. Unsatisfied disclosures are a hard failure.
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "failed",
"errors": [
{
"code": "COMPLIANCE_UNSATISFIED",
"message": "Required disclosure cannot be rendered in this format",
"field": "creative_manifest.assets.brief.compliance.required_disclosures[0]",
"details": {
"disclosure_text": "Past performance is not indicative of future results.",
"position": "footer",
"reason": "Format display_mobile_320x50 does not support footer position"
},
"suggestion": "Use a format that supports footer disclosures, or change position to 'overlay'"
}
]
}
```
Creative agents MUST validate that all `required_disclosures` can be satisfied in the target format before generating the creative. If any disclosure cannot be placed as specified, the entire request fails. This ensures regulated creatives are never served without required legal text.
## Response timing
How the creative agent responds depends on how long the operation will take:
| Expected duration | Status | Caller experience |
| - | - | - |
| Under 30 seconds | `completed` | Result returned directly — synchronous |
| Over 30 seconds, server actively processing | `working` | Out-of-band status updates while the server continues processing. Caller holds the connection — still synchronous from their perspective |
| Blocked on external dependency (human review, approval) | `submitted` | Truly async — caller should configure a webhook via `push_notification_config` and move on |
The creative agent decides which path to take based on the work involved. Library retrieval is instant. Simple transformations take seconds. AI generation varies — a quick banner might complete in 10 seconds, a complex video composition might take minutes.
### `working` is a progress signal, not a polling trigger
When the server expects to take more than 30 seconds but is actively processing, it sends `working` as an out-of-band MCP status update. This keeps the client informed ("I'm on it") without requiring the caller to switch to a polling or webhook pattern. The connection stays open and the result arrives when it's ready.
### When to go async
`submitted` means the operation is blocked on something outside the server's control:
* **Human creative review** — brand guidelines require approval before returning
* **External approval workflows** — third-party compliance or legal review
For these cases, configure a webhook via `push_notification_config` to receive the result. See [Async Operations](/dist/docs/3.2.8/building/by-layer/L3/async-operations) and [Push Notifications](/dist/docs/3.2.8/building/by-layer/L3/webhooks).
### Human-in-the-loop
The agent may return `status: "input-required"` when it needs human input — for example, when brand guidelines require creative approval or when the agent needs clarification on creative direction:
```json theme={null}
{
"reason": "CREATIVE_DIRECTION_NEEDED"
}
```
**Reason codes:**
* `APPROVAL_REQUIRED` — Creative needs human approval before finalizing
* `CREATIVE_DIRECTION_NEEDED` — Agent needs clarification on creative brief or direction
* `ASSET_SELECTION_NEEDED` — Agent needs the caller to choose between asset options
## Workflow integration
### Typical generation workflow
1. **Build**: Use `build_creative` to generate/transform the manifest
2. **Preview**: Use [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) to see how it renders (see [preview_creative](/dist/docs/3.2.8/creative/task-reference/preview_creative))
3. **Sync**: Use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) to traffic the finalized creative
You can combine steps 1 and 2 by setting `include_preview: true` on the build request. If the agent supports it, the response includes a `preview` object alongside the manifest — same content fields as `preview_creative`, no extra round trip. If the agent doesn't support inline preview, the field is simply absent and you fall back to a separate `preview_creative` call. Always check for the presence of `preview` rather than assuming it will be there when requested.
Use `preview_quality` to control render fidelity independently from build quality. For example, build at `quality: "draft"` (fast concept generation) but preview at `preview_quality: "production"` (full-fidelity render to show stakeholders the layout). If `preview_quality` is omitted, the agent uses its own default.
```json theme={null}
// Build at draft quality, but preview at production quality for stakeholder review
{
"message": "Create a display banner for our winter sale",
"target_capability_id": "display_300x250_generative",
"brand": { "domain": "mybrand.com" },
"quality": "draft",
"include_preview": true,
"preview_quality": "production",
"creative_manifest": {
"format_kind": "image",
"assets": {
"product_catalog": {
"type": "product",
"catalog_id": "winter-products"
}
}
}
}
// Or: Build first, preview separately
// Step 1: Build
{
"message": "Create a display banner for our winter sale",
"target_capability_id": "display_300x250_generative",
"brand": { "domain": "mybrand.com" },
"creative_manifest": {
"format_kind": "image",
"assets": {
"product_catalog": {
"type": "product",
"catalog_id": "winter-products"
}
}
}
}
// Step 2: Preview (using the output manifest from step 1)
{
"request_type": "single",
"format_kind": "image",
"creative_manifest": {
/* output from build_creative - includes all assets */
},
"inputs": [{"name": "Desktop view"}, {"name": "Mobile view"}]
}
// Step 3: Sync (if preview looks good)
{
"creative_manifests": [{ /* approved manifest from build_creative */ }]
}
```
**Key insight**: The manifest carries everything. Briefs, catalogs, images, text — all live in the assets map and flow through from input to output. No need to pass them separately at each step.
## Examples
### Example 1: Pure generation (generative format)
Generate a creative from scratch using a generative format:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "f6a7b8c9-d0e1-4234-f567-89abcdef0123",
"message": "Create a display banner for our winter sale. Use warm colors and emphasize the 50% discount",
"target_capability_id": "display_300x250_generative",
"brand": {
"domain": "mybrand.com"
},
"creative_manifest": {
"format_kind": "image",
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"items": [
{
"offering_id": "winter-sale",
"name": "Winter Sale Collection",
"description": "50% off all winter items"
}
]
}
}
}
}
```
**Response**:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_kind": "image",
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"catalog_id": "winter-sale"
},
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/banner_12345.png",
"width": 300,
"height": 250
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### Example 2: Format transformation
Transform an existing 728x90 leaderboard to a 300x250 banner:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "a7b8c9d0-e1f2-4345-a678-9abcdef01234",
"message": "Adapt this leaderboard creative to a 300x250 banner format",
"creative_manifest": {
"format_kind": "image",
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.mybrand.com/leaderboard.png",
"width": 728,
"height": 90
},
"headline": {
"asset_type": "text",
"content": "Spring Sale - 30% Off Everything"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/spring?campaign={MEDIA_BUY_ID}"
}
}
},
"target_capability_id": "display_300x250"
}
```
**Response**:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_kind": "image",
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/resized/banner_67890.png",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "Spring Sale - 30% Off"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/spring?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### Example 3: Transformation with specific instructions
Adapt a creative for mobile with specific design changes:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "b8c9d0e1-f2a3-4456-b789-abcdef012345",
"message": "Make this mobile-friendly: increase text size, simplify the layout, and make the CTA button more prominent",
"creative_manifest": {
"format_kind": "image",
"assets": {
"background_image": {
"asset_type": "image",
"url": "https://cdn.mybrand.com/bg.jpg",
"width": 300,
"height": 600
},
"headline": {
"asset_type": "text",
"content": "Discover Our New Collection"
},
"body_text": {
"asset_type": "text",
"content": "Shop the latest styles with free shipping on orders over $50"
},
"cta_text": {
"asset_type": "text",
"content": "Shop Now"
}
}
},
"target_capability_id": "display_mobile_320x50"
}
```
**Response**:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_kind": "image",
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/mobile/banner_mobile_123.png",
"width": 320,
"height": 50
},
"headline": {
"asset_type": "text",
"content": "New Collection - Shop Now"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/new?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
### Example 4: Generation with creative brief
Generate a creative using structured campaign context via `brand` and a brief asset on the manifest:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "c9d0e1f2-a3b4-4567-c890-bcdef0123456",
"message": "Create a display banner for the holiday campaign targeting gift shoppers",
"target_capability_id": "display_300x250_generative",
"brand": {
"domain": "acmecorp.com"
},
"creative_manifest": {
"format_kind": "image",
"assets": {
"brief": {
"asset_type": "brief",
"name": "Holiday Sale 2025",
"objective": "conversion",
"audience": "Holiday gift shoppers aged 25-55",
"territory": "festive savings",
"messaging": {
"headline": "Holiday Deals Are Here",
"cta": "Shop Now",
"key_messages": [
"Up to 50% off select items",
"Free shipping on orders over $50"
]
},
"reference_assets": [
{
"url": "https://cdn.acmecorp.com/holiday-mood-board.pdf",
"role": "mood_board",
"description": "Holiday campaign mood board with festive color palette"
}
]
},
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"items": [
{
"offering_id": "holiday-sale",
"name": "Holiday Sale Collection",
"description": "Up to 50% off select holiday items"
}
]
}
}
}
}
```
### Example 5: Generation with compliance requirements
Generate a financial services creative with regulatory disclosures and prohibited claims:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "d0e1f2a3-b4c5-4678-d901-cdef01234567",
"message": "Create a display banner promoting retirement planning advisory services",
"target_capability_id": "display_300x250_generative",
"brand": {
"domain": "pinnaclewealth.com"
},
"creative_manifest": {
"format_kind": "image",
"assets": {
"brief": {
"asset_type": "brief",
"name": "Retirement Advisory Q1 2026",
"objective": "consideration",
"audience": "Pre-retirees aged 50-65 with investable assets",
"territory": "trusted financial guidance",
"messaging": {
"headline": "Plan Your Retirement with Confidence",
"cta": "Schedule a Consultation",
"key_messages": [
"Personalized retirement planning",
"Tax-efficient investment strategies"
]
},
"compliance": {
"required_disclosures": [
{
"text": "Past performance is not indicative of future results.",
"position": "footer",
"jurisdictions": ["US"],
"regulation": "SEC Rule 156"
},
{
"text": "Securities offered through Pinnacle Wealth Securities, LLC. Member FINRA/SIPC.",
"position": "footer",
"jurisdictions": ["US"],
"regulation": "FINRA Rule 2210"
},
{
"text": "Capital at risk. The value of investments can go down as well as up.",
"position": "prominent",
"jurisdictions": ["GB"],
"regulation": "FCA COBS 4.5"
},
{
"text": "Pinnacle Wealth Advisors is a registered investment adviser.",
"position": "footer"
}
],
"prohibited_claims": [
"guaranteed returns",
"risk-free investment",
"outperform the market"
]
}
}
}
}
}
```
Compliance requirements differ by jurisdiction: the US requires SEC-mandated disclosures while the UK requires FCA-mandated risk warnings. The third disclosure (no `jurisdictions`) applies globally. The `prohibited_claims` array tells the creative agent which claims to avoid in generated copy.
### Example 6: Commerce media with brief and product catalog
Generate a sponsored product carousel with campaign context, compliance disclosures, and a synced product catalog:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "e1f2a3b4-c5d6-4789-e012-def012345678",
"message": "Create a product carousel highlighting the top 4 sale items",
"target_capability_id": "sponsored_product_carousel",
"brand": {
"domain": "novabrands.com"
},
"creative_manifest": {
"format_kind": "sponsored_placement",
"assets": {
"brief": {
"asset_type": "brief",
"name": "Spring Sale 2026",
"objective": "conversion",
"audience": "Value-conscious shoppers aged 25-45",
"messaging": {
"headline": "Spring Sale — Up to 40% Off",
"cta": "Shop Now"
},
"compliance": {
"required_disclosures": [
{
"text": "Sponsored",
"position": "prominent"
},
{
"text": "Prices may vary by location. See store for details.",
"position": "footer"
}
]
}
},
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "spring_sale_2026"
}
}
}
}
```
The brief and product catalog travel together in the manifest's `assets` map. The selected `creative.supported_formats[]` declaration exposes both `brief` and `catalog` slots, so the buying agent can sync the required catalog before submitting.
### Example 7: Build with inline preview
Build a creative and get preview renders in the same response:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "f2a3b4c5-d6e7-4890-f123-ef0123456789",
"message": "Create a banner for our spring campaign",
"target_capability_id": "display_300x250_generative",
"brand": {
"domain": "novabrands.com"
},
"include_preview": true,
"preview_inputs": [
{ "name": "Default" },
{ "name": "Dark mode", "macros": { "COLOR_SCHEME": "dark" } }
],
"creative_manifest": {
"format_kind": "image",
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"items": [
{
"offering_id": "spring-promo",
"name": "Spring Collection",
"description": "30% off new arrivals"
}
]
}
}
}
}
```
**Response** (when the agent supports inline preview):
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_kind": "image",
"assets": {
"offering_catalog": {
"asset_type": "catalog",
"type": "offering",
"catalog_id": "spring-promo"
},
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/spring_abc123.png",
"width": 300,
"height": 250
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://novabrands.com/spring"
}
}
},
"preview": {
"previews": [
{
"preview_id": "prev_default",
"renders": [
{
"render_id": "r1",
"output_format": "url",
"preview_url": "https://preview.creative-agent.com/abc123/default",
"role": "primary",
"dimensions": { "width": 300, "height": 250 }
}
],
"input": { "name": "Default" }
},
{
"preview_id": "prev_dark",
"renders": [
{
"render_id": "r2",
"output_format": "url",
"preview_url": "https://preview.creative-agent.com/abc123/dark",
"role": "primary",
"dimensions": { "width": 300, "height": 250 }
}
],
"input": { "name": "Dark mode", "macros": { "COLOR_SCHEME": "dark" } }
}
],
"expires_at": "2026-03-13T06:00:00Z"
},
"expires_at": "2026-03-13T06:00:00Z"
}
```
The `preview` object contains the same content fields as a [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) single response (`previews`, `interactive_url`, `expires_at`). If the agent does not support inline preview, this field is absent — the buyer agent falls back to a separate `preview_creative` call. If preview generation fails, the response includes `preview_error` with a standard error object (`code`, `message`, `recovery`) instead.
### Example 8: Draft generation with item limit
Generate a draft-quality creative from a large catalog, capping the number of items:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "a3b4c5d6-e7f8-4901-a234-f01234567890",
"message": "Create hero images for our top sale items",
"target_capability_id": "sponsored_product_carousel",
"brand": {
"domain": "novabrands.com"
},
"quality": "draft",
"item_limit": 4,
"creative_manifest": {
"format_kind": "sponsored_placement",
"assets": {
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "spring_sale_2026"
}
}
}
}
```
The catalog may contain hundreds of products, but `item_limit: 4` ensures only 4 hero images are generated. `quality: "draft"` produces fast, lower-fidelity output for review.
**Response**:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-response.json",
"status": "completed",
"creative_manifest": {
"format_kind": "sponsored_placement",
"assets": {
"product_catalog": {
"asset_type": "catalog",
"type": "product",
"catalog_id": "spring_sale_2026"
},
"card_1_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card1_abc123.jpg",
"width": 400,
"height": 400
},
"card_2_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card2_def456.jpg",
"width": 400,
"height": 400
},
"card_3_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card3_ghi789.jpg",
"width": 400,
"height": 400
},
"card_4_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/draft/card4_jkl012.jpg",
"width": 400,
"height": 400
}
}
},
"expires_at": "2026-03-02T06:00:00Z"
}
```
The `expires_at` field signals when the generated CDN URLs expire. Re-build after this time to get fresh URLs. Once the direction is approved, re-submit the output manifest with `quality: "production"` for final renders.
## Key concepts
### Brand vs creative brief
| | Brand | Creative Brief |
| - | - | - |
| **Scope** | Brand identity | Campaign context |
| **Lifespan** | Stable across campaigns | Specific to a campaign or flight |
| **Contains** | Colors, logos, fonts, tone | Audience, territory, messaging, compliance, reference assets |
| **Legal** | Brand-level disclaimers (always-on) | Campaign-specific regulatory disclosures (regional, product-based) |
| **Source** | Brand registry / `/.well-known/brand.json` | Agency or brand team |
| **Lives on** | Resolved via domain lookup | The manifest's assets map (`assets.brief`) |
Both are optional. `brand` provides stable brand identity (colors, logos, tone) resolved via the domain's `/.well-known/brand.json`. The brief is an asset on the manifest (`assets.brief`), so it travels with the creative through regeneration, resizing, and auditing. The `message` field provides per-request natural language instructions.
**Precedence**: The `brand` parameter is the authoritative source for creative rendering context (colors, logos, tone).
**Layering**: The brief asset on the manifest provides structured direction; `message` on the request provides per-request natural language overrides. When both provide conflicting direction, `message` takes precedence as the most specific instruction.
### Transformation model
`build_creative` follows a **manifest-in, manifest-out** model:
* Input: Creative manifest (can be minimal or complete -- everything lives in assets)
* Process: Transform/generate based on `message` and manifest content
* Output: Target creative manifest ready for preview or sync (brief carries forward)
### Pure generation vs transformation
* **Pure Generation**: Provide `target_capability_id`, any catalog or seed assets required by that capability, and `message`. The creative agent generates a canonical output manifest from scratch.
* **Transformation**: Provide complete `creative_manifest` with all existing assets. The creative agent adapts existing assets to the target format, optionally following guidance in `message`.
### Integration with other tasks
1. **build_creative** → Generates manifest (optionally with inline preview via `include_preview`)
2. **preview_creative** → Renders the manifest separately (see [preview_creative](/dist/docs/3.2.8/creative/task-reference/preview_creative))
3. **sync_creatives** → Traffics the finalized manifest
Use `include_preview: true` to combine build and preview into one call. If the agent doesn't support it, the response simply omits the `preview` field — fall back to a separate [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) call. Either way, the preview content fields (`previews`, `interactive_url`, `expires_at`) are the same.
This separation allows you to:
* Build once, preview multiple times with different contexts
* Iterate on build without re-syncing
* Preview before committing to traffic
### Iterative refinement
`build_creative` supports multi-turn iteration without a mode flag. The presence and combination of fields determines the operation:
* **Generation**: `message` + minimal `creative_manifest` (empty or seed assets) + `target_capability_id`
* **Transformation**: full `creative_manifest` + `message` + `target_capability_id`
* **Library retrieval**: `creative_id` + `target_capability_id` + optional `macro_values`
* **Refinement**: previous output as `creative_manifest` + `message` with changes
To refine, pass the previous response's `creative_manifest` back as input with a new `message`. Alternatively, update the brief asset (`assets.brief`) to change the creative direction — the brief is the buyer-owned source of truth for what the creative should be.
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/build-creative-request.json",
"idempotency_key": "b4c5d6e7-f8a9-4012-b345-012345678901",
"message": "Make the headline bolder and increase the contrast on the CTA button",
"target_capability_id": "display_300x250_generative",
"creative_manifest": {
"format_kind": "image",
"assets": {
"banner_image": {
"asset_type": "image",
"url": "https://cdn.creative-agent.com/generated/banner_12345.png",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "50% Off Winter Sale"
},
"clickthrough_url": {
"asset_type": "url",
"url": "https://mybrand.example.com/winter-sale?campaign={MEDIA_BUY_ID}"
}
}
}
}
```
## Error codes
| Code | Description |
| - | - |
| [`FORMAT_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-format-not-supported) | The `target_capability_id` (or `target_capability_ids[N]`) is not advertised by this creative agent. Refresh `get_adcp_capabilities.creative.supported_formats[]` and retry with a supported capability. |
| [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) | The `creative_manifest` is malformed or missing required assets for the target format |
| [`CREATIVE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-not-found) | The `creative_id` does not exist in the agent's library (or in the specified `concept_id`) |
| [`CREATIVE_REJECTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-rejected) | The creative failed content-policy, brand-safety, or accessibility review. Accessibility failures SHOULD use `error-details/accessibility-violation.json`. |
| [`COMPLIANCE_UNSATISFIED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-compliance-unsatisfied) | A required disclosure from the brief cannot be rendered in the target format (e.g., format does not support the required disclosure position) |
# get_creative_delivery
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/task-reference/get_creative_delivery
get_creative_delivery retrieves variant-level delivery data with manifests and performance metrics for generative and static creatives in AdCP.
Retrieve creative delivery data including variant-level breakdowns with manifests and metrics. This task returns what variants were created from your creatives, what they looked like (via manifests), and how they performed.
This is a Creative Protocol task. Call it on any agent that declares `"creative"` in `supported_protocols` and exposes the `get_creative_delivery` tool — whether that's a dedicated creative service or a [sales agent implementing the Creative Protocol](/dist/docs/3.2.8/creative/sales-agent-creative-capabilities).
**Request Schema**: [`/schemas/3.2.8/creative/get-creative-delivery-request.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/get-creative-delivery-request.json)
**Response Schema**: [`/schemas/3.2.8/creative/get-creative-delivery-response.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/get-creative-delivery-response.json)
## Request Parameters
At least one scoping filter (`media_buy_ids` or `creative_ids`) is required.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | [account-ref](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) | No | Account reference. Pass `{ "account_id": "..." }` or `{ "brand": {...}, "operator": "..." }` if the seller supports implicit resolution. Limits results to creatives within this account. |
| `media_buy_ids` | string\[] | Yes\* | Filter to specific media buys by publisher ID |
| `creative_ids` | string\[] | Yes\* | Filter to specific creatives by ID |
| `start_date` | string | No | Start date for delivery period (YYYY-MM-DD, interpreted in the platform's reporting timezone) |
| `end_date` | string | No | End date for delivery period (YYYY-MM-DD, interpreted in the platform's reporting timezone) |
| `max_variants` | integer | No | Maximum variants to return per creative. Useful for generative creatives with large variant counts. |
| `pagination` | object | No | Cursor-based pagination parameters (`max_results`, `cursor`) for the creatives array. When omitted, all matching creatives are returned. |
\* At least one of `media_buy_ids` or `creative_ids` must be provided.
## Response
| Field | Description |
| - | - |
| `account_id` | Account identifier (present when scoped to a specific account) |
| `media_buy_id` | Seller's media buy identifier (present when request was scoped to a single buy) |
| `currency` | ISO 4217 currency code for monetary values (e.g., 'USD', 'EUR') |
| `reporting_period` | Date range with start/end timestamps and `timezone` (IANA identifier — platforms report in their native timezone) |
| `creatives` | Array of creative delivery data with variant breakdowns |
| `pagination` | (Optional) Pagination info with `max_results`, `cursor`, and `has_more`. Present when the request included pagination parameters. |
### Creative Object
| Field | Description |
| - | - |
| `creative_id` | Creative identifier |
| `media_buy_id` | Seller's media buy identifier (present when the request spanned multiple media buys) |
| `format_kind` | Canonical format of this creative |
| `totals` | Aggregate delivery metrics across all variants — see [Delivery metrics fields](#delivery-metrics-fields) below |
| `variant_count` | Total number of distinct `variant_id` rows within this creative (may exceed `variants` array length when `max_variants` is used). |
| `variants` | Array of variant-level delivery data (empty if creative has no variants yet) |
### Delivery metrics fields
Fields available on both `creative.totals` and each `variant` entry. Commonly-used subset — see the [delivery-metrics schema](https://adcontextprotocol.org/schemas/3.2.8/core/delivery-metrics.json) for the full list including incrementality, brand lift, and broadcast metrics.
| Field | Description |
| - | - |
| `impressions` | Impressions delivered |
| `spend` | Amount spent (in `currency`) |
| `clicks` | Total clicks |
| `ctr` | Click-through rate (clicks/impressions) |
| `cpm` | Cost per thousand impressions ((spend/impressions) × 1000) |
| `cost_per_click` | Cost per click (spend/clicks) |
| `views` | Billable views — threshold varies by format and pricing model |
| `completed_views` | Video/audio completions |
| `completion_rate` | Completion rate (completed_views/impressions); `null` when not applicable (e.g. a non-video buy) |
| `quartile_data` | Audio/video quartile completion data — object with `q1_views`, `q2_views`, `q3_views`, `q4_views`; `null` when not applicable (e.g. a non-video buy) |
| `reach` | Unique reach in units specified by `reach_unit`. Measurement window declared via `reach_window`; without it, do not sum across rows |
| `reach_unit` | Unit of measurement for `reach`; required when `reach` is present |
| `reach_window` | Window semantics for reach/frequency — object with `kind` (`cumulative` for uniques since campaign start, `period` for non-overlapping snapshot, `rolling` for trailing window) and `period` (Duration, required for `period` and `rolling`). Optional but strongly recommended whenever `reach` is present |
| `frequency` | Average frequency per `reach_unit`, measured over `reach_window` |
| `grps` | Gross Rating Points delivered (for CPP) |
| `conversions` | Total attributed conversions; equals the sum of `by_event_type[].count` when present |
| `conversion_value` | Total monetary value of attributed conversions |
| `roas` | Return on ad spend (conversion_value/spend) — see note below |
| `cost_per_acquisition` | Cost per conversion (spend/conversions) — see note below |
| `new_to_brand_rate` | Fraction of conversions from first-time brand buyers (0–1) |
| `leads` | Leads generated (convenience alias for `by_event_type` where `event_type='lead'`) |
| `by_event_type` | Conversions by event type — array of `{ event_type, count, value?, event_source_id? }` |
| `by_action_source` | Conversions by action source (website, app, in_store) — array of `{ action_source, count, value?, event_source_id? }` |
| `dooh_metrics` | DOOH-specific data — object with `loop_plays`, `screens_used`, `screen_time_seconds`, `sov_achieved`, `venue_breakdown` |
| `ooh_metrics` | Classic (static) OOH data (experimental in 3.2) — object with `panels` (multi-identifier), `posting_period_start`/`posting_period_end`, `estimated_impressions`, `estimation_basis`, `postings` (posting records with photo evidence) |
| `viewability` | Viewability data — object with `vendor`, `measurable_impressions`, `viewable_impressions`, `viewable_rate`, `viewed_seconds` (average in-view duration per measurable impression — pairs with the `viewed_seconds` optimization goal), and `standard`. `standard` SHOULD be present whenever measured viewability values are reported |
| `engagements` | Total ad engagements beyond viewing (platform-specific) |
| `follows` | New followers or subscriptions attributed to delivery |
| `saves` | Saves, bookmarks, or pins attributed to delivery |
| `profile_visits` | In-platform page visits attributed to delivery |
| `engagement_rate` | Platform-specific engagement rate (engagements/impressions) |
| `vendor_metric_values` | Vendor-attested metrics (viewability, attention, etc.) — one entry per vendor and metric identifier |
> **Spend-derived metrics.** Sellers should not populate `roas` and `cost_per_acquisition` on individual `variant` objects — spend cannot be attributed per-variant since it applies to the creative as a whole. These fields are meaningful only on `creative.totals`. `by_event_type` entries carry `count` and `value` per event type, but not spend-derived rates.
> **Platform-conditional fields.** `dooh_metrics` is present only for DOOH campaigns; `ooh_metrics` only for static OOH campaigns. Engagement fields (`engagements`, `follows`, `saves`, `profile_visits`, `engagement_rate`) are platform-specific; not all sellers emit them on standardized fields — some use `variant.ext` for engagement data instead.
### Variant Object
Each variant row represents a specific execution within one source revision: a fixed creative (Tier 1), an asset combination the platform selected (Tier 2), or a generated variant (Tier 3). For catalog-driven packages, each catalog item rendered as a distinct ad execution is a variant — the variant's manifest includes the catalog reference with the specific item rendered.
| Field | Description |
| - | - |
| `variant_id` | Agent-assigned served-execution identifier. Existing agents retain uniqueness within agent + creative. An agent advertising `creative.supports_revisions` uses an agent-unique immutable value, which is the unambiguous lookup key when it also supports variant preview. |
| `revision_id` | Buyer-authored input revision from which this execution was derived. Historical rows may name an older revision than the creative currently returned by [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives). |
| `locale_variant_id` | Buyer-assigned localized variant that supplied the served assets. Required for delivered variants of a localized creative, including default fallback; omitted for unlocalized creatives. |
| `manifest` | (Optional) The rendered canonical creative manifest—the actual output served, with `format_kind` and resolved assets. |
| `generation_context` | (Optional, Tier 3) Input signals that triggered generation — e.g., page topic, conversation theme, query category. Platforms provide summarized/anonymized signals, not raw user input. When content context is managed through AdCP content standards, includes an `artifact` reference linking to the specific content artifact. Supports `ext` for vendor-specific context structures. |
| `ext` | (Optional) Platform-specific data. Social platforms use this for engagement metrics (upvotes, comments, shares) that vary by platform. |
| Standard metrics | All [Delivery metrics fields](#delivery-metrics-fields) — same shape as `creative.totals` |
`creative_id`, `revision_id`, and `variant_id` are separate namespaces. The
canonical build-to-delivery join is `build_creative.variants[].build_variant_id`
→ promoted `creative_id` → delivery `creative_id`. `revision_id` identifies the
immutable buyer-authored input state beneath that creative; for a seller
advertising `creative.supports_revisions`, `variant_id` is an agent-unique AdCP
served-execution identity. Every execution derived from
a revision carries that revision even when the seller transcodes or chooses
another equivalent delivery representation.
### Revision attribution
Do not compare every row to the creative's current `list_creatives.revision_id`.
A reporting window may contain executions from several accepted revisions; each
row carries the source revision that actually produced that execution.
Every row is revision-homogeneous: all of its metrics come from exactly one
source revision and, when localized, one locale. For an agent advertising
`creative.supports_revisions`, `variant_id` is agent-unique and MUST NOT be
reused for another creative, revision, locale, or rendered manifest; this keeps
[`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) replay by
`variant_id` unambiguous when variant preview is supported. An adapter
whose native ad platform reuses an identifier maps each distinct execution to
a distinct AdCP `variant_id` and may retain the native identifier in `ext`.
`variant_count` counts distinct `variant_id` values before applying
`max_variants`. Tier 1 therefore has one row per revision and locale represented
in the requested period, not necessarily one row for the whole period. A seller
that cannot partition delivery this way cannot advertise
`creative.supports_revisions: true`.
For localized delivery, `locale_variant_id` is checked against the source
revision's accepted localization topology, not only the current
`list_creatives` topology.
### Localized delivery attribution
For a localized creative, every returned execution MUST include
`locale_variant_id` and that value MUST exist in the accepted localization
topology of the row's source revision. When that revision is current, the value
therefore also exists in `list_creatives.localization.variants[]`; historical
rows are checked against buyer-retained sync state rather than a newer current
topology. This identifies the assets that
actually served after strict RFC 4647 Lookup, an explicit locale fallback, or
the default action and is required for every such path. When the selected
product format carries `locale_policy`, this value MUST also identify a variant
eligible under its accepted language ranges; buyer fallbacks and defaults never
bypass that seller constraint. `variant_id` remains the seller execution identity;
`locale_variant_id` is the buyer's stable locale identity.
Derived metrics like `ctr`, `completion_rate`, `roas`, and `cost_per_click` are platform-calculated and may not equal naive division of their component fields due to rounding, attribution windows, or filtered impressions.
## Tier Behavior
### Tier 1: Standard Creatives
Within one source revision and locale, a standard creative maps 1:1 to one
variant. A report spanning revision or locale boundaries contains distinct
variant rows; a row's metrics match the creative totals only when it is the
sole row in the reporting period.
```json theme={null}
{
"media_buy_id": "mb_12345",
"currency": "USD",
"reporting_period": {
"start": "2026-01-20T00:00:00-05:00",
"end": "2026-01-27T23:59:59-05:00",
"timezone": "America/New_York"
},
"creatives": [
{
"creative_id": "hero_video_30s",
"totals": {
"impressions": 150000,
"spend": 7500,
"clicks": 4500,
"ctr": 0.03,
"completion_rate": 0.72
},
"variants": [
{
"variant_id": "hero_video_30s",
"impressions": 150000,
"spend": 7500,
"clicks": 4500,
"ctr": 0.03,
"completion_rate": 0.72
}
]
}
]
}
```
### Platform engagement metrics
Social and feed-native platforms include engagement data in the `ext` field on each variant, since engagement types vary by platform:
```json theme={null}
{
"variant_id": "promoted_post_running_community",
"impressions": 85000,
"spend": 4250,
"clicks": 2550,
"ctr": 0.03,
"ext": {
"upvotes": 1240,
"comments": 87,
"shares": 34,
"saves": 156,
"comment_sentiment": "positive"
}
}
```
The `ext` field is not standardized across platforms — each platform defines its own engagement schema. Buyers aggregating across social platforms should map platform-specific fields to a common model.
### Tier 2: Asset Group Optimization
Buyer provides multiple asset alternatives using a format with `selection_mode: "optimize"`. Platform tests combinations and returns the manifest for each variant showing which assets were selected.
```json theme={null}
{
"media_buy_id": "mb_12345",
"currency": "USD",
"reporting_period": {
"start": "2026-01-20T00:00:00-05:00",
"end": "2026-01-27T23:59:59-05:00",
"timezone": "America/New_York"
},
"creatives": [
{
"creative_id": "summer_campaign_assets",
"totals": {
"impressions": 200000,
"spend": 10000,
"clicks": 8000,
"ctr": 0.04
},
"variants": [
{
"variant_id": "var_headline_a_image_c",
"manifest": {
"format_kind": "image",
"assets": {
"headline_0_text": {
"asset_type": "text",
"content": "Summer Sale - 50% Off"
},
"image_0_url": {
"asset_type": "image",
"url": "https://cdn.brand.com/beach_hero.jpg",
"width": 300,
"height": 250
}
}
},
"impressions": 120000,
"spend": 6000,
"clicks": 6000,
"ctr": 0.05
},
{
"variant_id": "var_headline_b_image_d",
"manifest": {
"format_kind": "image",
"assets": {
"headline_0_text": {
"asset_type": "text",
"content": "Shop Summer Styles"
},
"image_0_url": {
"asset_type": "image",
"url": "https://cdn.brand.com/sunset_hero.jpg",
"width": 300,
"height": 250
}
}
},
"impressions": 80000,
"spend": 4000,
"clicks": 2000,
"ctr": 0.025
}
]
}
]
}
```
### Tier 3: Generative Creative
Platform generates variants from brand manifest and input contexts. The `manifest` contains the generated assets — which may differ entirely from what the buyer submitted.
When the publisher uses AdCP content standards, `generation_context` can include an `artifact` reference linking the variant to the specific content (article, video, etc.) that triggered generation. Platforms can also use `ext` for vendor-specific context structures.
```json theme={null}
{
"media_buy_id": "mb_12345",
"currency": "USD",
"reporting_period": {
"start": "2026-01-20T00:00:00-05:00",
"end": "2026-01-27T23:59:59-05:00",
"timezone": "America/New_York"
},
"creatives": [
{
"creative_id": "generative_banner",
"totals": {
"impressions": 300000,
"spend": 15000,
"clicks": 12000,
"ctr": 0.04
},
"variants": [
{
"variant_id": "gen_mobile_morning",
"generation_context": {
"context_type": "web_page",
"artifact": {
"property_id": { "type": "domain", "value": "techreview.example.com" },
"artifact_id": "article_semiconductor_trends_2026"
},
"topic": "technology, semiconductors",
"device_class": "mobile"
},
"manifest": {
"format_kind": "image",
"assets": {
"hero_image": {
"asset_type": "image",
"url": "https://cdn.creative.example.com/generated/mobile_morning_v1.jpg",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "Start Your Summer Right"
}
}
},
"impressions": 180000,
"spend": 9000,
"clicks": 9000,
"ctr": 0.05
},
{
"variant_id": "gen_desktop_evening",
"generation_context": {
"context_type": "web_page",
"topic": "lifestyle, evening entertainment",
"device_class": "desktop"
},
"manifest": {
"format_kind": "image",
"assets": {
"hero_image": {
"asset_type": "image",
"url": "https://cdn.creative.example.com/generated/desktop_evening_v1.jpg",
"width": 728,
"height": 90
},
"headline": {
"asset_type": "text",
"content": "Evening Deals Await"
}
}
},
"impressions": 120000,
"spend": 6000,
"clicks": 3000,
"ctr": 0.025
}
]
}
]
}
```
## Previewing Variants
Use [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) with `request_type: "variant"` to see what a specific variant looked like when served:
```json theme={null}
{
"request_type": "variant",
"variant_id": "gen_mobile_morning"
}
```
Since each variant includes its full `manifest`, you can also pass the manifest directly to `preview_creative` as a standard single request to re-render it.
## Relationship to delivery reporting
| Task | Protocol | What it provides |
| - | - | - |
| [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) | Media Buy | WHERE and HOW MUCH: impressions, spend, placement data, optional `by_creative` breakdown |
| `get_creative_delivery` | Creative | WHAT RAN and HOW: variant manifests and variant-level metrics |
Use `media_buy_id` + `creative_id` as join keys to correlate data across both responses.
When a sales agent implements both protocols, both tasks are available on the same agent URL. See [Creative capabilities on sales agents](/dist/docs/3.2.8/creative/sales-agent-creative-capabilities) for the full pattern.
## Cross-agent aggregation
When running campaigns across multiple sellers, call `get_creative_delivery` on each agent separately and correlate results:
* **Join key**: Use `creative_id` (buyer-assigned) to correlate the same creative across agents. If you used `concept_id` during upload, filter by concept to group related creatives.
* **Variant row scope**: The published default scopes `variant_id` to agent + creative. An agent advertising `creative.supports_revisions` strengthens this to agent-unique and immutable. In either case, use the structured tuple `(agent_url, media_buy_id-or-null, creative_id, variant_id)` as the globally scoped reporting row key; `revision_id` and `locale_variant_id` are immutable attribution fields, not extensions of variant identity.
* **Timezone handling**: Each agent may report in its own timezone via `reporting_period.timezone`. Normalize to a common timezone before aggregating metrics.
* **`max_variants` selection**: Agents choose which variants to return when `max_variants` limits the result set. Most agents prioritize by impression volume (most-served first). For representative sampling, make multiple calls with different time ranges rather than relying on a single large `max_variants` value.
## Building a cross-agent dashboard
When aggregating delivery data from multiple agents into a unified view, follow this sequence:
1. **Collect**: Call `get_creative_delivery` on each agent in parallel, using the same `creative_ids` filter.
2. **Normalize timezones**: Convert each agent's `reporting_period` to a common timezone before summing.
3. **Merge by `creative_id`**: Group results by `creative_id` across agents. Sum `totals` (impressions, spend, clicks). Do not average derived metrics like `ctr` — recompute them from the summed components.
4. **Build a variant-row key**: Serialize the structured tuple `agent_url + media_buy_id-or-null + creative_id + variant_id`. Use actual `null`, not string sentinels, so legitimate IDs cannot collide with absence. Distinct revisions and locales already have distinct agent-assigned `variant_id` values.
5. **Group by `concept_id`**: For campaign-level roll-ups, use `concept_id` to group related creatives across sizes and sellers. Pull the concept-to-creative mapping from [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) on each agent.
```javascript theme={null}
// Pseudocode: aggregate delivery from 3 sellers
const agents = [pinnacle, novaSports, streamhaus];
const results = await Promise.all(
agents.map(agent =>
agent.getCreativeDelivery({
creative_ids: ['acme_holiday_300x250'],
start_date: '2026-11-01',
end_date: '2026-11-15',
})
)
);
const merged = {};
for (const [i, result] of results.entries()) {
if (result.errors) continue; // skip failed agents, retry later
for (const creative of result.creatives) {
const key = creative.creative_id;
if (!merged[key]) merged[key] = { impressions: 0, spend: 0, clicks: 0, variants: [] };
merged[key].impressions += creative.totals.impressions;
merged[key].spend += creative.totals.spend;
merged[key].clicks += creative.totals.clicks || 0;
for (const v of creative.variants || []) {
merged[key].variants.push({
...v,
variant_row_id: JSON.stringify([
agents[i].url,
creative.media_buy_id ?? result.media_buy_id ?? null,
creative.creative_id,
v.variant_id,
]),
});
}
}
}
// Recompute derived metrics
for (const c of Object.values(merged)) {
c.ctr = c.impressions > 0 ? c.clicks / c.impressions : 0;
}
```
## Capability declaration
Agents that support this task expose `get_creative_delivery` in their tool surface and declare Creative Protocol support through [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities):
```json theme={null}
{
"supported_protocols": ["creative"],
"creative": {
"has_creative_library": true,
"supports_revisions": true
}
}
```
Buyers discover candidate creative agents through the registry, then confirm the live endpoint's tool and `get_adcp_capabilities` surfaces. This applies to any endpoint implementing the Creative Protocol, including a sales agent with creative capabilities.
# list_creative_formats (deprecated)
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/task-reference/list_creative_formats
Deprecated AdCP 3.x named-format discovery task and its canonical 3.2 replacements.
`list_creative_formats` is deprecated in AdCP 3.2. It combined three different questions into one agent-global list and therefore could not accurately describe publisher acceptance, product deliverability, and creative production at the same time.
Existing 3.x agents MAY continue serving the task for compatibility. New implementations MUST use the canonical surfaces below and SHOULD derive any legacy response mechanically from canonical declarations rather than maintaining a second catalog. The task follows its own compatibility schedule; removal of exact plural `format_ids` fields in AdCP 4.0 does not itself remove this task.
## Use the surface that owns the fact
| Question | Canonical source |
| - | - |
| What formats does a publisher declare? | The publisher's `/.well-known/adagents.json` `formats[]`, with AgenticAdvertising.org community-mirror fallback when the publisher has not adopted |
| What formats can this sales agent deliver for a product? | [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) → `Product.format_options[]` |
| What can this creative agent build, validate, or preview? | [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) → `creative.supported_formats[]` |
Sales agents MUST NOT use an agent-global format list as a purchasability promise. Product `format_options[]` is the closed sellable set, and placement declarations may narrow it.
Creative agents advertise stable build routing separately from publisher/product format identity:
```json theme={null}
{
"creative": {
"supported_formats": [
{
"capability_id": "streamhaus_vertical_video",
"operations": ["build", "validate", "preview"],
"format": {
"publisher_domain": "shorts.streamhaus.example",
"format_option_id": "vertical_video",
"format_kind": "video_hosted",
"params": {
"aspect_ratio": "9:16",
"duration_ms_range": [3000, 60000]
}
}
}
],
"preview": {
"routes": [{
"capability_id": "streamhaus_vertical_video",
"rendering_origin": "agent_approximation"
}]
}
}
}
```
The buyer passes `streamhaus_vertical_video` as `target_capability_id` to [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative). The returned manifest carries canonical `format_kind: "video_hosted"`; capability IDs never appear on products or manifests.
## Registry reverse discovery
The AgenticAdvertising.org registry indexes canonical creative capabilities. To find creative agents that claim they can build an exact publisher format:
```http theme={null}
GET /api/registry/agents?publisher_domain=shorts.streamhaus.example&format_option_id=vertical_video&creative_operation=build
```
Generic agents can advertise a canonical parameter envelope without publisher identity. A match is valid only when the capability can satisfy every target constraint—not merely because both declarations share the same `format_kind`.
## Compatibility behavior
The deprecated request and response schemas remain available at:
* [`/schemas/3.2.8/media-buy/list-creative-formats-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/list-creative-formats-request.json)
* [`/schemas/3.2.8/media-buy/list-creative-formats-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/list-creative-formats-response.json)
Compatibility implementations SHOULD:
1. Keep canonical declarations as the only authored source.
2. Project named formats only for a peer that still requires them.
3. Never infer a publisher catalog from one seller's products.
4. Never return publisher-declared formats as if every format were deliverable by the responding sales agent.
See [Canonical formats](/dist/docs/3.2.8/creative/canonical-formats) for the complete matching and ownership model.
# list_creatives
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/task-reference/list_creatives
list_creatives browses and filters creatives in an AdCP library by asset type, format, status, concept, and tags with cursor-based pagination.
Browse and filter creatives in a creative library. Supports filtering by asset type, format, status, concept, tags, date range, and dynamic variables, with pagination and optional field enrichment.
For every account the caller can access, the library membership is
**source-neutral**: sellers MUST return creatives the caller can see regardless
of whether they were created through [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives), a seller UI or API,
seller automation, another authorized principal, or a connected platform.
Filters and lifecycle defaults still apply. An implementation that exposes
only AdCP-created creatives is not a conforming account snapshot.
Implemented by any agent that hosts a creative library — creative agents (ad servers, creative management platforms) and sales agents that manage creatives.
**Response time**: \~1 second (simple database lookup)
## Overview
**Key features:**
* Filter by asset type, format, status, tags, dates, assignments, concepts, and variables
* Sort by creation date, update date, name, status, or assignment count
* Cursor-based pagination for large libraries
* Optionally include assignments, delivery snapshots, items, and dynamic creative optimization (DCO) variables
* Return only specific fields to reduce response size
* Filter by creative concept (groups of related creatives across sizes/formats)
* Find DCO creatives and inspect their dynamic content slots
* Find creatives with seller indicators such as package-scoped creative fatigue
* Reconcile source-neutral external changes through the optional, experimental [account change feed](/dist/docs/3.2.8/accounts/tasks/list_account_changes)
## Request parameters
**Schema**: [`creative/list-creatives-request.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/list-creatives-request.json)
### Core parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `filters` | object | No | Filter criteria — see [filtering options](#filtering-options) below |
| `sort` | object | No | Sorting parameters |
| `pagination` | object | No | Pagination controls |
### Data inclusion options
| Parameter | Type | Required | Description |
| - | - | - | - |
| `include_assignments` | boolean | No | Include package assignment information (default: true) |
| `assignment_projection` | string | No | `all` (default) returns active assignments; `matching` returns only assignments matching `filters.indicator_types` and requires that filter. |
| `assignment_limit` | integer | No | Maximum nested assignment rows per creative (default: 50, maximum: 200). |
| `include_snapshot` | boolean | No | Include a lightweight delivery snapshot — lifetime impressions and last-served date (default: false). For detailed analytics, use [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery). |
| `include_items` | boolean | No | Include items for multi-asset formats like carousels and native ads (default: false) |
| `include_variables` | boolean | No | Include dynamic content variable definitions (default: false) |
| `include_pricing` | boolean | No | Include `pricing_options` on each creative (default: false). Requires `account`. |
| `include_purged` | boolean | No | Include soft-purged creative tombstones (default: false). See [Purged tombstones](#purged-tombstones). |
| `include_webhook_activity` | boolean | No | Include recent webhook fires per creative (default: false). See [Webhook activity](#webhook-activity). |
| `webhook_activity_limit` | integer | No | Maximum `webhook_activity[]` records per creative when `include_webhook_activity: true` (default: 50, range 1–200). |
| `account` | [AccountRef](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) | No | Account reference for pricing. When provided with `include_pricing`, the agent returns `pricing_options` from this account's rate card on each creative. |
| `fields` | array | No | Specific optional fields to return (omit for all fields). Every row still includes the released base envelope: `creative_id`, `name`, `status`, `created_date`, `updated_date`, and exactly one of `format_id` or `format_kind`. Optional selections include `"assignments"`, `"assets"`, `"pricing_options"`, and `"rights"` / `"rights_attestation_evaluations"`; selecting rights evaluations automatically includes `rights`. |
## Filtering options
The `filters` object supports these optional, composable filters:
| Filter | Type | Description |
| - | - | - |
| `accounts` | [AccountRef](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references)\[] | Filter by owning accounts |
| `format_kinds` | CanonicalFormatKind\[] | Filter by canonical format kinds |
| `format_ids` | FormatID\[] | Deprecated named-format compatibility filter |
| `asset_types` | AssetContentType\[] | Filter by asset types directly assigned to top-level creative asset slots; values within the array use OR logic |
| `statuses` | [CreativeStatus](/dist/docs/3.2.8/creative/specification#creative-status-lifecycle)\[] | Filter by approval status |
| `tags` | string\[] | Filter by tags (all must match) |
| `tags_any` | string\[] | Filter by tags (any must match) |
| `name_contains` | string | Case-insensitive name search |
| `creative_ids` | string\[] | Filter by specific creative IDs (max 100) |
| `concept_ids` | string\[] | Filter by concept groupings |
| `has_variables` | boolean | Filter for DCO creatives with dynamic variables |
| `created_after` / `created_before` | date-time | Filter by creation date range |
| `updated_after` / `updated_before` | date-time | Filter by last-modified date range |
| `assigned_to_packages` | string\[] | Filter by package assignments \* |
| `media_buy_ids` | string\[] | Filter by media buy assignments \* |
| `unassigned` | boolean | Filter for unassigned creatives \* |
| `has_served` | boolean | Filter for creatives that have served at least one impression \* |
| `indicator_types` | `IndicatorType[]` | Filter for creatives with at least one package assignment carrying any requested current indicator type. See the [standard indicator catalog](/dist/docs/3.2.8/media-buy/media-buys/indicators#standard-indicator-types). \* |
\* Assignment-related filters are specific to sales agents. Standalone creative agents ignore these.
### Asset-type matching
`asset_types` matches a creative when at least one direct object value in the top-level `creative.assets` map has an exact `asset_type` value in the requested set. Multiple requested values use **OR logic**. Array-valued slots are not inspected, and matching does not recurse into nested asset fields such as `cards[].media`; broader traversal is deferred.
All active filter fields compose with **AND logic**. For example, the following request returns published-post creatives that also match the requested canonical format kind; a creative satisfying only one condition is excluded:
```json theme={null}
{
"filters": {
"asset_types": ["published_post"],
"format_kinds": ["native_in_feed"]
}
}
```
For deterministic status and assignment filters, every returned creative MUST
satisfy the supplied predicates: `status` MUST be a member of `statuses`, and a
sales agent applying `media_buy_ids` MUST return only creatives with an
assignment to at least one requested media buy. These predicates remain in force
across every page and compose with each other and with all other active filters.
A seller MUST NOT accept them and return the unfiltered library.
A filtered request can validly return the same rows as an unfiltered request
when every visible creative already matches. Conformance is established from
status and assignment membership—not by requiring the two response payloads to
differ. Standalone creative agents retain the documented exception for
sales-agent-specific assignment filters.
Use `asset_types: ["published_post"]` to find existing-published-post reference creatives across sellers without enumerating publisher-specific format options, or `asset_types: ["zip"]` to find HTML5 bundle archives. Values such as `url`, `text`, and `image` are common companion assets, so they often produce broad result sets when used alone.
Agents that do not implement `asset_types` MUST ignore that field and apply all other active filters. They must not reject the request solely because the filter is unsupported. Because unsupported agents deliberately over-return, buyers that require an exact filtered result MUST retain a local fallback: request `assets` (or omit `fields`), traverse every page until `pagination.has_more` is false, and locally inspect the returned top-level asset objects. When a seller returns `query_summary.filters_applied`, buyers can verify that it includes `asset_types`; absence means the local fallback is required.
> [!NOTE]
>
> **Archived creatives are excluded by default.** To include archived creatives in results, explicitly include `"archived"` in the `statuses` array. Suspended creatives are not archived; include `"suspended"` when you specifically want recoverably offline creatives such as published-post references with expired authorization.
> [!NOTE]
>
> For published-post reference products, `list_creatives` is limited to the downstream publisher identities the seller is authorized to inspect. If a product requires a second platform connection such as `publisher_identity` and it is missing, the seller should return [`AUTHORIZATION_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-authorization-required) with `error.details.missing_connections[]`. It should not present `list_creatives` as global platform post search.
## Sorting options
Sort results by various fields with ascending or descending order:
```json theme={null}
{
"sort": {
"field": "created_date",
"direction": "desc"
}
}
```
**Available sort fields:**
* `created_date` - When the creative was created (default)
* `updated_date` - When creative was last modified
* `name` - Creative name (alphabetical)
* `status` - Approval status
* `assignment_count` - Number of package assignments
## Pagination
Control result set size with cursor-based pagination:
```json theme={null}
{
"pagination": {
"max_results": 50,
"cursor": "eyJjcmVhdGVkX2RhdGUiOi4uLn0"
}
}
```
## Response format
**Schema**: [`creative/list-creatives-response.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/list-creatives-response.json)
The response provides creative data with optional enrichment:
```json theme={null}
{
"query_summary": {
"total_matching": 1,
"returned": 1,
"filters_applied": ["status=approved"]
},
"pagination": {
"has_more": false,
"total_count": 1
},
"creatives": [
{
"creative_id": "ft_88201",
"revision_id": "rev_2026_08_23_01",
"name": "Holiday Sale - Medium Rectangle",
"format_kind": "image",
"status": "approved",
"created_date": "2026-01-15T10:30:00Z",
"updated_date": "2026-01-15T14:20:00Z",
"concept_id": "concept_holiday_2026",
"concept_name": "Holiday 2026 Campaign",
"variables": [
{
"variable_id": "headline_text",
"name": "Headline",
"variable_type": "text",
"default_value": "Holiday Sale - 50% Off",
"required": true
}
]
}
],
"format_summary": {
"display_static_300x250": 1
},
"status_summary": {
"approved": 1
}
}
```
When the seller advertises `creative.supports_revisions: true`, `revision_id`
is the current buyer-authored input revision for that creative. It is exact
readback of the value accepted by [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives), not a seller processing or
transcode version. Older creatives without revision identity may omit it.
### Per-creative fields
| Field | Type | Description |
| - | - | - |
| `creative_id` | string | Unique creative identifier |
| `revision_id` | string | Current buyer-authored input revision when the current content is revision-bound. Omitted for legacy/unversioned current content. |
| `name` | string | Human-readable name |
| `format_kind` | string | Canonical format kind |
| `format_option_ref` | object | Optional exact publisher/product option reference |
| `format_id` | object | Deprecated 3.x named-format compatibility field |
| `status` | string | Approval status |
| `created_date` | string | Creation timestamp |
| `updated_date` | string | Last modified timestamp |
| `assets` | object | Creative assets (images, text, URLs, etc.) |
| `localization` | object | Exact materialized locale assets, buyer-assigned variant identities, and default/unmatched policy for localized creatives. |
| `localization_unavailable` | object | Fail-closed per-item errors and retryability when exact localization readback cannot be constructed. Mutually exclusive with `localization`. |
| `tags` | string\[] | Tags for categorization |
| `rights` | array | Exact retained rights constraints and portable references. Presentation only; not proof of seller verification. |
| `rights_attestation_evaluations` | array | Seller-produced, freshness-bounded grant evaluations. Each reference must exactly match one reference in the returned `rights` array. |
| `concept_id` | string | Creative concept ID |
| `concept_name` | string | Human-readable concept name |
| `variables` | array | DCO variable definitions (when `include_variables=true`) |
| `assignments` | object | Package assignments (when `include_assignments=true`) |
| `snapshot` | object | Delivery snapshot (when `include_snapshot=true`) |
| `snapshot_unavailable_reason` | string | Why snapshot is missing — `SNAPSHOT_UNSUPPORTED`, `SNAPSHOT_TEMPORARILY_UNAVAILABLE`, or `SNAPSHOT_PERMISSION_DENIED` |
| `items` | array | Items for multi-asset formats (when `include_items=true`) |
| `pricing_options` | [VendorPricingOption](/dist/docs/3.2.8/creative/specification#pricing)\[] | Pricing options for this creative (when `include_pricing=true` and `account` provided). Vendors may offer multiple options (volume tiers, context-specific rates, different models per product line). Same pattern as [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) and [`list_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/list_content_standards). |
### Assignment indicators
Creative-library sellers that advertise `list_creatives` in `media_buy.relationship_notifications.projection_tasks` attach evaluated indicator state to `assignments.assigned_packages[]` and include `media_buy_id` plus `approval_status` on every row, including unknown rows. These fields mirror [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) for the same relationship. A mixed publisher/placement outcome uses `approval_status: "partially_approved"` plus complete `approval_scopes[]`; the assignment webhook remains a compact invalidation and buyers reread these scopes. Each evaluated row includes `indicator_types_evaluated`, `indicators_as_of`, and `indicators[]`; omitted types remain unknown.
```json theme={null}
{
"include_assignments": true,
"filters": {
"indicator_types": ["creative_fatigue"]
},
"fields": ["creative_id", "assignments"],
"assignment_projection": "matching",
"assignment_limit": 50,
"pagination": {
"max_results": 100
}
}
```
This request limits optional payload to assignments while retaining each row's released base envelope (`creative_id`, `name`, `status`, dates, and one format identity). `assignment_count` remains the total active relationship count; `returned_assignment_count`, optional `matching_assignment_count`, and `assignments_truncated` describe the bounded nested projection. When truncated, use `get_media_buys` as the complete repair path.
The standard indicator shape intentionally contains no indicator ID, source envelope, lifecycle status, or sub-version. The responding seller is the source; AdCP defines the broad meaning of the type for the negotiated protocol release. Seller-specific scores, methodology, evaluation windows, and upstream attribution belong in `ext`.
Omitted `indicators` means unknown. An empty array is evaluated-clear only for `indicator_types_evaluated` and declared coverage. Do not infer clearing from filtered/paginated disappearance; directly reread without `indicator_types`. See [Indicators and Warnings](/dist/docs/3.2.8/media-buy/media-buys/indicators).
### Rights attestation readback
Selecting `fields: ["rights_attestation_evaluations"]` automatically includes `creative_id` and `rights`. Every evaluation's `{rights_id, content_digest, reference}` must select exactly one retained constraint and one byte-for-byte equal `attestation_refs` entry. The evaluation array is complete rather than independently truncated: because `rights` has no item ceiling, neither does its evaluation readback. A `verified` result is reusable only when the seller retrieves the byte-identical result from its own local evaluation store keyed by `(evaluated_by, reference_digest)`, for that exact unchanged grant, and only until `valid_until`. The `evaluated_by` string alone is not provenance; buyer-authored and foreign-seller readback fails closed. The result is not a serving authorization and does not replace use, country, time, package, or impression-cap checks. When the seller advertises `media_buy.rights_attestations.requirement: "required"`, every applicable constraint on a serving-eligible creative needs at least one current verified result.
### Localized creative readback
For a localized creative, top-level `creative_id` identifies the creative and
`localization` is the authoritative locale-topology round trip. The localization
object lists exactly one source plus every materialized target variant;
source-only monolingual topology therefore contains one variant. It preserves
the originating request's exact source ID/locale, target ID/locale set, default
ID, unmatched action, and any explicit locale fallback rules. Each entry
returns complete resolved assets under its buyer-assigned `locale_variant_id`; no seller- or
platform-assigned variant ID is required. The top-level creative `status` is the
single review lifecycle for the complete locale set.
Verifiers enforce unique locale and buyer locale-variant ID values, exactly one
source role, a default ID that references one variant, unique fallback language
ranges whose IDs reference stored variants, and
equality between source readback assets and top-level creative assets.
These rules are machine-readable in `x-adcp-validation` because draft-07
`uniqueItems` compares whole objects and cannot express uniqueness or reference
integrity by property.
This object is atomic. If the seller omits a requested locale, normalizes it
to a different locale, or loses an asset or identity, the seller returns
`localization_unavailable` instead of a partial `localization` object. The item
remains in the current page and counts toward `query_summary.returned` and
pagination. Buyers may use its base metadata but MUST NOT infer locale
eligibility. Selecting `fields: ["localization"]` automatically includes the
creative ID, status, assets, format identity, and unavailable state
needed to interpret this result.
At delivery, sellers apply strict RFC 4647 Lookup: progressively truncate the
requested range and match only an equal seller-eligible canonical tag. A
selected product or placement `locale_policy` first filters this readback with
RFC 4647 Basic Filtering; it never mutates or removes the globally stored
variants. When no variant matches for a preference, sellers apply the most-specific explicit
`locale_fallbacks` rule for that preference before moving to the next one. When
all preferences miss both paths, they follow `unmatched_locale_action`: serve
`default_locale_variant_id` or do not serve.
The ordered preference list itself comes from the seller's serving environment;
AdCP neither carries it here nor defines how browser, content, geography, user,
app, or platform signals produce it or their precedence.
The chosen `locale_variant_id` is reported by [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery).
### Pricing
When `include_pricing=true` and `account` is provided, each creative includes `pricing_options` from the account's rate card:
```json theme={null}
{
"pricing_options": [
{
"pricing_option_id": "po_video_cpm",
"model": "cpm",
"cpm": 0.50,
"currency": "USD"
}
]
}
```
The buyer passes the applied `pricing_option_id` (from the [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) response) in [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) for billing verification. Vendors may offer multiple options — volume/commitment tiers, context-specific rates (premium vs. standard placements), or entirely different pricing models for different product lines. This is the same pattern used by [signals](/dist/docs/3.2.8/signals/tasks/get_signals) and [content standards](/dist/docs/3.2.8/governance/content-standards/index).
### Delivery snapshot
When `include_snapshot=true`, each creative includes a lightweight delivery snapshot for operational questions like "is this creative active?" or "when did it last serve?" This is not analytics — for detailed performance data, use [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery).
```json theme={null}
{
"snapshot": {
"as_of": "2026-03-08T14:30:00Z",
"staleness_seconds": 3600,
"impressions": 145200,
"last_served": "2026-03-07T22:15:00Z"
}
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `as_of` | date-time | Yes | When this snapshot was captured |
| `staleness_seconds` | integer | Yes | Maximum age of data in seconds |
| `impressions` | integer | Yes | Lifetime impressions (not scoped to any date range) |
| `last_served` | date-time | No | Last time this creative served. Absent when it has never served. |
### Purged tombstones
When a creative is destroyed via [`creative.purged`](https://adcontextprotocol.org/schemas/3.2.8/creative/creative-purged-webhook.json) with `purge_kind: soft`, the seller retains a tombstone for 30 days from the purge timestamp. The tombstone surfaces on `list_creatives` only when the request sets `include_purged: true`:
```json theme={null}
{
"creative_id": "ft_87100",
"name": "Holiday Sale - Leaderboard (purged)",
"status": "approved",
"purge": {
"kind": "soft",
"at": "2026-05-18T02:59:48Z",
"reason_code": "retention_expired"
}
}
```
The `status` field on a tombstone is **frozen at its pre-purge value** (in the example above, `"approved"` is what the creative was right before purge — not a current claim). Buyers MUST treat the creative as gone: assignments, serving operations, and delivery reads no longer apply. The presence of the `purge` block is the unambiguous signal.
Hard-purged creatives (`purge_kind: hard`, used for legal erasure under GDPR Article 17 / CCPA / equivalent) retain no tombstone; the [`creative.purged`](https://adcontextprotocol.org/schemas/3.2.8/creative/creative-purged-webhook.json) webhook is the only signal. See the [snapshot-and-log conforming-pairs catalog](/dist/docs/3.2.8/protocol/snapshot-and-log#current-conforming-pairs) for the recovery exclusion.
### Webhook activity
When `include_webhook_activity: true`, each returned creative carries a `webhook_activity[]` array of the most recent fires scoped to that creative — `creative.status_changed`, `creative.purged`, `creative.assignment_changed`, and assignment-level `indicators.changed` deliveries. This is the buyer's debug surface for "did the publisher fire? did my endpoint receive it? was the retry trail clean?" — the same shape and contract as `webhook_activity[]` on [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys). See [Webhook activity log pattern](/dist/docs/3.2.8/protocol/snapshot-and-log#webhook-activity-log-pattern) for the full normative contract (retention, three-state presence, request-field conventions).
**To subscribe** when the seller declares `media_buy.relationship_notifications`, register a [`notification_configs[]`](/dist/docs/3.2.8/accounts/tasks/sync_accounts#account-level-webhook-subscriptions) entry on the account via [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts). The seller fires per-subscriber against each entry whose `event_types[]` includes the type. Indicator support itself may be poll-only; push-capable sellers may advertise `indicators.changed` and independently advertise `creative.assignment_changed`. Subscriptions are prospective, so establish a complete all-status or known-ID baseline through `get_media_buys` after activation. Dedupe later invalidations and reread `get_media_buys` rather than applying payload state; `webhook_activity[]` on this read is a bounded reverse projection and debug log, not proof of complete repair.
Three-state presence applies:
* **Field omitted** — seller does not surface webhook activity on this read.
* **`[]`** — seller surfaces the field but no fires fall in the retention window for this creative.
* **Non-empty** — actual records, most recent first, capped at `webhook_activity_limit` (max 200).
Correlate to your endpoint logs by `idempotency_key`. Each record's `notification_type` discriminates the fire kind:
```json theme={null}
{
"webhook_activity": [
{
"idempotency_key": "whk_01HW9D2T3VXQ5M7K9N1P3R5S7U",
"notification_id": "cs_ft88201_2026_05_18a",
"subscriber_id": "buyer-primary",
"fired_at": "2026-05-18T14:20:00Z",
"completed_at": "2026-05-18T14:20:00Z",
"notification_type": "creative.status_changed",
"attempt": 1,
"status": "success",
"url": "https://buyer.example/webhooks/adcp/creative",
"http_status_code": 200,
"response_time_ms": 142,
"payload_size_bytes": 612,
"error_message": null
}
]
}
```
Buyers diagnose "no fires arrived" by combining: (a) subscriber registration state on `list_accounts.accounts[].notification_configs[]` — is the right URL active with the right `event_types[]`? — and (b) seller capability declaration via [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) — does the seller support the event types I subscribed to? Field omission on `webhook_activity` alone does not distinguish "seller doesn't surface the log" from "no fires occurred."
### Buyer handler (end-to-end)
A buyer's webhook handler for `creative.status_changed` correlates each fire with library state via `creative_id`, dedupes on `idempotency_key`, and re-reads `list_creatives` for the authoritative snapshot (per [snapshot-and-log Rule 3](/dist/docs/3.2.8/protocol/snapshot-and-log#the-five-rules)):
```javascript theme={null}
// POST /webhooks/adcp/creative
async function handleCreativeWebhook(req, res) {
// 1. Verify signature per the registered scheme (RFC 9421 by default).
if (!verifyWebhookSignature(req)) return res.status(401).end();
const fire = req.body; // creative-status-changed-webhook or creative-purged-webhook
const { notification_type, idempotency_key, creative_id, account_id } = fire;
// 2. Dedupe at-least-once delivery.
if (await alreadyProcessed(idempotency_key)) return res.status(200).end();
// 3. Re-read snapshot for authoritative state. Push is signal; snapshot is truth.
const snapshot = await testAgent.listCreatives({
filters: { creative_ids: [creative_id] },
include_purged: notification_type === "creative.purged"
});
// 4. Apply local effects from the snapshot, not the webhook payload.
await reconcileCreative(snapshot.creatives[0]);
await markProcessed(idempotency_key);
return res.status(200).end();
}
```
Two pitfalls this handler avoids: (1) applying state from the webhook payload directly (ordering and re-emission make the payload non-authoritative); (2) skipping dedup (sellers retry on non-2xx and re-emit on missed-events warnings).
## Account requirements
> [!NOTE]
>
> Creative agents that host a library should implement the [accounts protocol](/dist/docs/3.2.8/accounts/overview) ([`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) / [`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts)) so buyers can establish access before querying creatives. This is the same accounts protocol used by sales agents for media buys — there is no separate version. Sales agents that already implement the accounts protocol for media buys do not need to do anything additional.
## Examples
### Concept-scoped query with variables
List all approved creatives in a specific concept, including DCO variable definitions:
```json theme={null}
{
"filters": {
"concept_ids": ["concept_holiday_2026"],
"statuses": ["approved"]
},
"include_variables": true,
"sort": {
"field": "created_date",
"direction": "desc"
}
}
```
### Format-specific query
Find canonical image creatives across concepts:
```json theme={null}
{
"filters": {
"format_kinds": ["image"],
"statuses": ["approved"]
}
}
```
### Find DCO creatives
Find creatives with dynamic content variables for personalized campaigns:
```json theme={null}
{
"filters": {
"has_variables": true,
"statuses": ["approved"]
},
"include_variables": true
}
```
### Field-limited query
Get minimal creative data for a selection dropdown:
```json theme={null}
{
"fields": ["creative_id", "name", "format_kind", "status"],
"include_assignments": false,
"filters": {
"statuses": ["approved"]
},
"sort": {
"field": "name",
"direction": "asc"
}
}
```
### Library health check
Find active creatives with delivery snapshots to identify stale or dormant assets:
```json theme={null}
{
"filters": {
"media_buy_ids": ["mb_summer_2026", "mb_spring_2026"],
"statuses": ["approved"]
},
"include_assignments": true,
"include_snapshot": true,
"sort": {
"field": "updated_date",
"direction": "desc"
}
}
```
## Related tasks
* [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery) - Detailed performance analytics with date ranges, variant breakdowns, and full delivery metrics
* [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) - Build manifests from library creatives or generate from scratch
* [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) - Upload and manage creative assets on any agent hosting a creative library
* [Canonical formats](/dist/docs/3.2.8/creative/canonical-formats) - Discover product, publisher, and creative-agent format declarations
* [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) - Generate previews of creative manifests
# list_transformers
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/task-reference/list_transformers
list_transformers discovers account-scoped creative transformers — the agent-offered, selectable units of build capability (voices, models, styles) used by build_creative.
Discover the **transformers** a creative agent offers for your account. A transformer is the creative analog of a media-buy product: an agent-offered, account-scoped, selectable unit of build capability (a voice, a model, a style, a director) with a typed configuration surface and per-account pricing. You discover transformers here, then select one with `transformer_id` in [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative).
**Response Time**: \~1 second (account-scoped lookup)
**Authentication**: Account-scoped. Transformers, their enumerable option values, and pricing are resolved for the calling credential — including custom values you configured (e.g. cloned voices) that exist only for your account.
**Request Schema**: [`/schemas/3.2.8/creative/list-transformers-request.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/list-transformers-request.json)
**Response Schema**: [`/schemas/3.2.8/creative/list-transformers-response.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/list-transformers-response.json)
Offered only by agents that set `creative.supports_transformers: true` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities).
## Why transformers
The set of render knobs a creative agent exposes — and their legal values — is **account-specific and dynamic**. Your configured voices aren't a global enum or a list you hold; the *agent* knows them, and the set changes when you add one. So discovery flows agent → buyer, the same way [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) surfaces account-scoped inventory. `list_transformers` is that discovery surface for creative build capability.
The agent chooses granularity: a distinct voice or model may be its own transformer, or a single transformer may expose `voice`/`model` as an enumerable `config` param. Either way you use the same call — list transformers, expand a param if you want its values.
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `transformer_ids` | string\[] | No | Return only these specific transformer IDs |
| `input_format_kinds` | string\[] | No | Filter to transformers accepting any of these canonical format kinds |
| `output_capability_ids` | string\[] | No | Filter to transformers that can produce any of these `creative.supported_formats[].capability_id` values |
| `name_search` | string | No | Search transformers by name (case-insensitive partial match) |
| `brief` | string | No | Natural-language brief to rank/filter transformers and their option values (e.g. "warm female Spanish-language voiceover"). Curates to intent rather than returning the full set. |
| `expand_params` | string\[] | No | Param `field` names for which to return the **first page** of account-scoped option **values** inline on `params[].options[]`. Omit for the lean default (descriptors only). |
| `expand_pagination` | object\[] | No | Fetch the **next page** of a specific param's options, scoped per `{ transformer_id, field, options_cursor }` (cursor from a prior response's `params[].options_cursor`). Use once you hold a cursor, instead of `expand_params`. |
| `include_pricing` | boolean | No | Include `pricing_options` on each transformer. Requires `account`. |
| `account` | AccountRef | Conditional | Required when `include_pricing` is true. Transformers are account-scoped regardless. |
| `pagination` | object | No | `max_results` and `cursor` (opaque cursor from previous response) |
### The `expand` mode
By default the response returns each transformer's param **schemas** with small closed enums inlined (e.g. `mastering_preset`). To get the **values** of an account-scoped enumerable param (e.g. your voices), name it in `expand_params` — that returns the **first page** on `params[].options[]`. When a param's values are truncated, its `params[].options_cursor` is set; fetch the next page by passing `{ transformer_id, field, options_cursor }` in **`expand_pagination`** (each `(transformer, param)` pages independently). Values are brief-filtered — "warm Spanish female voice" narrows a 300-voice catalog to a handful instead of dumping all of them. There is no separate options endpoint; value enumeration (and its pagination) is a mode of this one tool.
## Response
| Field | Description |
| - | - |
| `transformers` | Array of transformer descriptors (see below) |
| `errors` | Optional array of task-specific errors and warnings |
| `pagination` | Pagination cursor when more transformers are available |
Each transformer carries:
| Field | Description |
| - | - |
| `transformer_id` | Stable id; pass to [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) `transformer_id` |
| `name` | Human-readable name |
| `input_formats` / `output_capability_ids` | Canonical declarations it accepts and creative capabilities it produces. A `build_creative` target MUST be a subset of `output_capability_ids`. Omitted `input_formats` means it builds from a brief or raw assets. |
| `params` | Config knobs (see [Transformer Param](https://adcontextprotocol.org/schemas/3.2.8/core/transformer-param.json)): `field`, `type`, `value_source` (`inline`/`range`/`enumerable`/`free_text`), `allowed_values`/`minimum`/`maximum`, `options[]`+`options_cursor` (when expanded), `max_length` (for `free_text`), `default`. `free_text` is an open buyer-authored string (e.g. a `negative_prompt`); a param MUST NOT be a generation-count knob — count rides `max_variants`/`max_creatives`. |
| `pricing_options` | Per-account rate card. `applies_to_output_capability_ids` may price different canonical outputs differently; an unscoped option is the default. |
See [Transformer schema](https://adcontextprotocol.org/schemas/3.2.8/core/transformer.json) for the complete object.
## Common Scenarios
### Discover voices for a brief, with values
```javascript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { ListTransformersResponseSchema } from '@adcp/sdk';
const result = await testAgent.listTransformers({
account: { account_id: 'acct_acme' },
brief: 'warm female Spanish-language voiceover',
output_capability_ids: ['audio_vo'],
expand_params: ['voice'],
include_pricing: true,
});
const parsed = ListTransformersResponseSchema.parse(result);
for (const t of parsed.transformers) {
console.log(t.transformer_id, t.name);
const voice = t.params?.find((p) => p.field === 'voice');
for (const opt of voice?.options ?? []) console.log(' voice:', opt.value, opt.metadata);
}
```
```python test=false theme={null}
import asyncio
from adcp.testing import test_agent
from adcp import ListTransformersResponse
async def main():
result = await test_agent.list_transformers(
account={"account_id": "acct_acme"},
brief="warm female Spanish-language voiceover",
output_capability_ids=["audio_vo"],
expand_params=["voice"],
include_pricing=True,
)
parsed = ListTransformersResponse.model_validate(result)
for t in parsed.transformers:
print(t.transformer_id, t.name)
asyncio.run(main())
```
### Then build with the selected transformer
Pass the chosen `transformer_id` and a typed `config` (keyed by each param's `field`) to [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative):
```json test=false theme={null}
{
"transformer_id": "audiostack_voiceover",
"config": { "voice": "isaac", "speaking_rate": 1.1, "mastering_preset": "podcast" },
"creative_manifest": { "format_kind": "audio_hosted", "assets": { "script": { "asset_type": "text", "content": "Discover the new winter collection." } } },
"target_capability_id": "audio_vo",
"account": { "account_id": "acct_acme" },
"idempotency_key": "0c1d2e3f-4a5b-6c7d-8e9f-a0b1c2d3e4f5"
}
```
## Error Handling
| Code | Meaning | Recovery |
| - | - | - |
| [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing) | `include_pricing` requested without a resolvable account | Supply `account` / authenticate |
| [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) | Malformed filter or pagination cursor | Correct the request |
Unknown `expand_params` (a `field` no transformer exposes) are ignored, not an error — the param simply returns no `options`.
## Learn More
* [build_creative](/dist/docs/3.2.8/creative/task-reference/build_creative) — select a transformer and produce creatives (incl. variants)
* [get_adcp_capabilities](/dist/docs/3.2.8/protocol/get_adcp_capabilities) — `creative.supports_transformers` discriminator
* [Vendor pricing](https://adcontextprotocol.org/schemas/3.2.8/core/vendor-pricing-option.json) — the `per_unit` rate model
# preview_creative
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/task-reference/preview_creative
preview_creative renders an existing creative manifest into viewable output in AdCP, in single or batch mode, returning URL, image, or HTML output.
`preview_creative` renders an existing creative manifest into viewable output. It does not generate or modify the input manifest — use [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) for that. Supports both single creative preview and batch preview (5-10x faster for multiple creatives).
**Request Schema**: [`/schemas/3.2.8/creative/preview-creative-request.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/preview-creative-request.json)
**Response Schema**: [`/schemas/3.2.8/creative/preview-creative-response.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/preview-creative-response.json)
## Quick Start
### Single Creative Preview
```json theme={null}
{
"request_type": "single",
"target_capability_id": "preview_image_300x250",
"creative_manifest": { /* includes format_kind, assets */ }
}
```
Response:
```json theme={null}
{
"response_type": "single",
"previews": [
{
"preview_id": "prev_001",
"renders": [
{
"render_id": "render_1",
"output_format": "url",
"preview_url": "https://creative-agent.example.com/preview/abc123",
"role": "primary"
}
],
"input": { "name": "Default", "macros": {} }
}
],
"expires_at": "2027-02-15T18:00:00Z"
}
```
Embed the primary render in an iframe:
```html theme={null}
```
### Direct HTML Embedding
For faster rendering without iframe overhead, request HTML directly:
```json theme={null}
{
"request_type": "single",
"target_capability_id": "preview_image_300x250",
"creative_manifest": { /* includes format_kind, assets */ },
"output_format": "html"
}
```
Response contains raw HTML:
```json theme={null}
{
"response_type": "single",
"previews": [
{
"preview_id": "prev_002",
"renders": [
{
"render_id": "render_1",
"output_format": "html",
"preview_html": "...",
"role": "primary"
}
],
"input": { "name": "Default", "macros": {} }
}
],
"expires_at": "2027-02-15T18:00:00Z"
}
```
> [!WARNING]
>
> Treat `preview_html` and `preview_url` as untrusted even when the provider is publisher-designated. Never inject returned HTML into the host DOM. Render HTML via iframe `srcdoc` and URLs in a cross-origin iframe, in both cases with an empty sandbox token set and caller-enforced restrictive CSP. Provider-supplied embedding recommendations are advisory and MUST NOT loosen that policy.
### Batch Preview (Multiple Creatives)
Preview multiple creatives in one API call (5-10x faster):
```json theme={null}
{
"request_type": "batch",
"requests": [
{ "target_capability_id": "preview_image_300x250", "creative_manifest": { /* creative 1 */ } },
{ "target_capability_id": "preview_video_16x9", "creative_manifest": { /* creative 2 */ } }
]
}
```
Response contains results in order:
```json theme={null}
{
"response_type": "batch",
"results": [
{ "success": true, "creative_id": "creative_1", "response": { "previews": [...], "expires_at": "..." } },
{ "success": true, "creative_id": "creative_2", "response": { "previews": [...], "expires_at": "..." } }
]
}
```
### Variant Preview (Post-Flight)
Preview what a specific variant looked like when served. Use `variant_id` from [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery) response:
```json theme={null}
{
"request_type": "variant",
"variant_id": "gen_mobile_morning"
}
```
Response:
```json theme={null}
{
"response_type": "variant",
"variant_id": "gen_mobile_morning",
"previews": [
{
"preview_id": "prev_gen_morning",
"renders": [
{
"render_id": "render_1",
"output_format": "url",
"preview_url": "https://creative-agent.example.com/preview/variant/gen_mobile_morning",
"role": "primary",
"dimensions": { "width": 300, "height": 250 }
}
]
}
],
"manifest": {
"format_kind": "image",
"assets": {
"hero_image": {
"asset_type": "image",
"url": "https://cdn.creative.example.com/generated/mobile_morning_v1.jpg",
"width": 300,
"height": 250
},
"headline": {
"asset_type": "text",
"content": "Start Your Summer Right"
}
}
},
"expires_at": "2027-02-15T18:00:00Z"
}
```
Since each variant from `get_creative_delivery` includes its full `manifest`, you can also pass the manifest directly to `preview_creative` as a standard single request to re-render it.
## Request Parameters
All modes use a single flat object with `request_type` as the discriminant.
| Parameter | Type | Required | Description |
| - | - | - | - |
| `request_type` | string | Yes | `"single"`, `"batch"`, or `"variant"` |
| `creative_manifest` | object | Conditional | Complete creative manifest with all required assets for the format. For single requests and batch items, supply either this field or `creative_id`. |
| `creative_manifest.format_kind` | CanonicalFormatKind | Yes for inline manifests | Portable canonical format identity. |
| `target_capability_id` | string | No | Agent-local renderer route from `get_adcp_capabilities.creative.supported_formats[]`; the selected entry's `operations` must contain `preview`. In batch mode this is the default for items, which may override it. Omit only when exactly one advertised preview capability matches the canonical manifest; zero or multiple matches return [`FORMAT_NOT_SUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-format-not-supported). |
| `inputs` | array | No | Array of input sets for multiple preview variants. Used in single mode. |
| `quality` | string | No | `"draft"` (fast, lower-fidelity) or `"production"` (full quality). In batch mode, sets the default for all requests. |
| `output_format` | string | No | `"url"` (default) or `"html"`. In batch mode, sets the default for all requests. |
| `item_limit` | integer | No | Maximum catalog items to render per preview variant. Used in single mode. |
| `template_id` | string | No | Specific template ID for custom format rendering. Used in single mode. |
| `requests` | array | Batch | Array of 1-50 preview requests. Each item supplies either a canonical `creative_manifest` or library `creative_id`, and may also carry `target_capability_id`, inputs, quality, output format, item limit, and template ID. |
| `variant_id` | string | Variant | Agent-assigned AdCP served-execution identifier from [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery). It is agent-unique for agents advertising `creative.supports_revisions`; callers SHOULD also send `creative_id` for legacy agents whose IDs are scoped to agent + creative. |
| `creative_id` | string | Conditional | Creative-library identifier. Use instead of `creative_manifest` to preview a stored canonical creative; in batch mode it is set per item. In variant mode it disambiguates the legacy agent + creative identifier scope. |
| `allow_async` | boolean | No | Opt in to a `status: "submitted"` response for slow rendering. Defaults to `false`; agents MUST stay synchronous or return a terminal error when absent or false. |
| `push_notification_config` | object | No | Optional terminal completion/failure webhook when `allow_async` is true and the agent returns `submitted`. The task remains pollable without it; this field alone never causes async execution. |
**Required** column values: *Conditional* = single requests and batch items require one of `creative_manifest` or `creative_id`; *Batch* = required when `request_type` is `"batch"`; *Variant* = required when `"variant"`.
Discover renderers from `get_adcp_capabilities.creative.supported_formats[]` by selecting entries whose `operations` contains `preview` and whose canonical `format` satisfies the manifest. New 3.2 producers MUST list routable entries in `creative.preview.routes[]`, whose capability-ID set equals the preview-operation capability IDs. Each route declares informational `rendering_origin` as `platform_native` or `agent_approximation`. `capability_id` is an agent-local renderer route; it never belongs in the portable manifest. If multiple renderers match, the caller must select one explicitly.
An agent cannot grant itself authority. Even `platform_native` remains informational unless a matching publisher-origin placement `preview_provider` delegates that endpoint and capability route. Buyers preserve the origin label and follow the [rendering authority and composition rules](/dist/docs/3.2.8/creative/canonical-formats#rendering-authority-and-fallback-order).
### Opt-in asynchronous preview
`preview_creative` is synchronous by default. A buyer that can poll task results MAY set `allow_async: true`. Only then may an agent hand rendering to a queue or external renderer, release the request connection, and return:
```json theme={null}
{
"response_type": "submitted",
"status": "submitted",
"task_id": "task_preview_abc123",
"message": "Production-quality video preview queued"
}
```
The buyer polls [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) with `task_id`; the completed task result contains the normal single, batch, or variant preview response. If the request also supplies `push_notification_config`, the agent sends at least the terminal completion/failure notification and the same task remains pollable. `response_type: "submitted"` keeps this fourth arm in the same discriminator family as the three synchronous preview arms; `status: "submitted"` is the task-lifecycle signal.
`submitted` is for work that continues after the request connection is released, including a queued upstream renderer. If the agent is actively rendering while keeping the connection open, it uses `working` progress and returns the normal response on that connection. When `allow_async` is false or absent, agents MUST NOT return the submitted shape. [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) already has a separate async response contract and is unchanged by this field.
Preview remains read-only in every lifecycle state. Queuing a preview MUST NOT build or approve a creative, add it to a creative library, or modify the supplied or stored manifest.
### Input Sets
Generate multiple preview variants by providing different contexts:
```json theme={null}
{
"inputs": [
{ "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
{ "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } },
{ "name": "Morning Context", "context_description": "User commuting to work" }
]
}
```
**Available macros**: `DEVICE_TYPE`, `COUNTRY`, `CITY`, `DMA`, `GDPR`, `US_PRIVACY`, `CONTENT_GENRE`, etc.
**Context descriptions**: For AI-generated content like host-read audio ads.
## Response Format
### Single Mode Response
```typescript theme={null}
{
response_type: "single";
quality_used?: "draft" | "production"; // Required when the request supplied quality
previews: Preview[]; // One per input (or one default)
interactive_url?: string; // Optional sandbox for interactive formats
expires_at?: string; // Optional ISO 8601 expiration; omitted means no expiration
}
```
### Batch Mode Response
```typescript theme={null}
{
response_type: "batch";
results: Array<{
success: boolean;
creative_id: string;
quality_used?: "draft" | "production"; // Required when effective request supplied quality
response?: {
previews: Preview[];
expires_at?: string;
};
errors?: Array<{ code: string; message: string; }>;
}>;
}
```
### Preview Structure
```typescript theme={null}
{
preview_id: string;
renders: Array<{
render_id: string;
output_format: "url" | "html" | "both";
preview_url?: string; // When output_format is "url" or "both"
preview_html?: string; // When output_format is "html" or "both"
role: string; // "primary", "companion", etc.
dimensions?: { width: number; height: number; };
}>;
input: {
name: string;
macros?: Record;
context_description?: string;
};
}
```
**Multi-render formats**: Some formats produce multiple pieces (video + companion banner). Each has its own `render_id` and `role`.
## Previewing generative creative
For generative formats — contextual display, AI-generated native, conversational ads — the creative doesn't exist until serve time. Preview serves two distinct purposes:
### Pre-flight: representative samples
Before the campaign runs, use single or batch mode to preview what the agent *could* generate given different contexts. Pass `inputs` with `context_description` to simulate serve-time conditions:
```json theme={null}
{
"$schema": "/schemas/3.2.8/creative/preview-creative-request.json",
"request_type": "single",
"quality": "draft",
"creative_manifest": {
"format_kind": "agent_placement",
"assets": {
"brief": {
"asset_type": "brief",
"name": "Sustainability story",
"objective": "awareness",
"messaging": {
"key_messages": ["Highlight our sustainability story. Match tone to editorial context."]
}
}
}
},
"inputs": [
{ "name": "Tech article", "context_description": "Article about semiconductor manufacturing" },
{ "name": "Lifestyle blog", "context_description": "Blog post about sustainable living" }
]
}
```
These previews are *representative*, not definitive. Real serve-time output depends on live signals (actual page content, user device, time of day) that can't be fully simulated. Use draft quality for fast iteration on the brief and creative direction, then production quality for stakeholder review.
### Post-flight: exact replay
After the campaign runs, use variant mode to see exactly what was served. Pass a `variant_id` from [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery):
```json theme={null}
{
"request_type": "variant",
"variant_id": "gen_tech_mobile_001"
}
```
The response includes the variant's actual manifest — the specific headline, image, and layout the agent generated for that context. This is a faithful replay, not a re-generation.
### Setting expectations
| Aspect | Standard creative | Generative creative |
| - | - | - |
| Pre-flight preview | At production quality, fidelity-accurate within the selected renderer's presentation; draft may approximate | Representative — shows the agent's interpretation of the brief under simulated conditions |
| Post-flight preview | Same as pre-flight | Exact — faithful replay of served output via variant mode |
| `quality: "draft"` | Iteration render; final fidelity is not guaranteed | Lower-fidelity sample for reviewing creative direction |
| `quality: "production"` | Fidelity-accurate review render | Fidelity-accurate sample of serve-time presentation |
| Number of variants | Typically 1 (or a few device variants) | Potentially thousands — one per context |
For generative formats where every impression produces a different creative (like AI chat or real-time contextual), pre-flight previews are best understood as *samples from a distribution* rather than *the ad*. The brief and brand identity constrain the distribution; previews let you verify the agent interprets those constraints correctly.
### Conversational and interactive formats
For formats where the ad is stateful — AI chat, interactive experiences, conversational native — preview takes on additional meaning:
* **Pre-flight** renders a representative first interaction or simulated conversation. The `interactive_url` field in the preview response (when present) provides a sandbox where reviewers can interact with the experience directly. Use `context_description` to simulate different conversation entry points.
* **Post-flight** variant replay shows the actual exchange that occurred. For multi-turn formats, the variant manifest captures the full content the agent produced (message sequence, responses, media assets shown). The level of detail depends on the agent — some provide full transcripts, others provide summarized content with anonymized user signals.
These formats have the widest gap between pre-flight and post-flight: a pre-flight preview can only approximate one possible conversation path, while the live experience adapts to each user. Preview enough scenarios to verify tone, guardrails, and brand consistency.
### Quality levels
The preview quality tier describes render fidelity, not merely the renderer's relative cost or speed. It is not a validation result, compliance or brand-safety clearance, seller acceptance, or authorization to serve. Buyers use the applicable validation, governance, and seller creative-review workflows for those decisions.
Quality and authority are independent. `quality_used: "production"` means full fidelity within the selected renderer; it does not turn an undelegated route into publisher-authoritative presentation. Buyer tooling MUST retain quality, rendering origin, and delegation provenance when it records or presents a preview.
Each rendered piece may include `renderer` audit metadata: a stable `renderer_id`, exact semantic `version`, export name, informational `rendering_origin`, and whether the actual output suppresses every tracking, navigation, and remote-asset request. This metadata makes a render reproducible but does not grant authority. Buyers resolve authority only from a matching publisher-origin placement `preview_provider` delegation.
* **`draft`** is an iteration render for reviewing creative direction. It MUST preserve the supplied manifest or brief's core concept, content, and non-fidelity constraints, but it MAY use lower-resolution or placeholder assets; approximate layout, typography, color, motion, audio, or interactive behavior; and omit final polish. The protocol does not guarantee that any of those listed fidelity dimensions is final in a draft preview.
* **`production`** is a fidelity-accurate review render. For standard or otherwise deterministic creative, it MUST faithfully render the supplied manifest—or the stored manifest resolved from `creative_id`—and its assets using the serve-time presentation controlled by the selected renderer. In `preview_creative`, material asset substitution or approximation requires `quality_used: "draft"`. It MUST include disclosure and compliance elements required by the manifest and those owned by that rendering layer for the supplied context.
Publisher- or serving-layer elements outside the selected renderer are guaranteed only when the targeted preview capability represents that integrated rendering context. A standalone creative renderer is not responsible for reproducing downstream elements it cannot determine. Buyers that need an end-to-end composed review SHOULD request a preview from the applicable seller or publisher rendering capability.
For generative creative, `production` means that the sample uses the serve-equivalent generation pipeline and configuration, honors the same declared constraints, and uses the same full-fidelity presentation rules as serve-time generation. It does not promise that the same content will be generated for every impression. Final assets and layout MAY vary where the format varies them at serve time.
For stateful or interactive creative, a `production` preview MUST render the sampled state or path with serve-time visual and control fidelity. The tier makes no behavioral-coverage guarantee beyond that sample. Buyers assessing guardrails, disclosure persistence, error states, or multi-turn behavior SHOULD use `interactive_url`, when present, and exercise a scenario suite appropriate to the format.
These definitions also apply to `preview_quality` on an inline [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) preview. In 3.x, that inline response does not echo `quality_used`, so an agent MUST either meet the requested `preview_quality` or return `preview_error`; it cannot silently substitute another tier. Buyers that need a successful response to echo the rendered tier use `preview_creative`.
### Quality mismatch
If the requested quality level is not supported, the agent renders at the best quality it can provide and reports that tier in `quality_used`. When a single request supplies `quality`, the response MUST include `quality_used`. For batch mode, each successful result whose effective request supplied `quality`—either on the item or through the batch-level default—MUST include `quality_used`. Agents SHOULD report `quality_used` even when the request omitted `quality`, so buyers can record the renderer's default tier.
Buyers MUST compare `quality_used` with the requested value before treating a preview as a production-fidelity review artifact. A mismatch means the agent applied a different tier; specifically, requested `production` with `quality_used: "draft"` is an explicit downgrade. `quality_used` does not appear on variant-mode replay because that mode reproduces a historical execution rather than selecting a new render-quality tier. Agents are not required to support both quality levels or advertise per-capability quality discovery.
In 3.x, `quality_used` is a binary fidelity gate: it does not identify which dimensions caused a downgrade. Buyers that receive a mismatch need agent-specific or out-of-band diagnostics before deciding whether to retry, select another renderer, or revise the creative.
### Preview expiration and variant retention
Preview responses may include an `expires_at` timestamp. When present, consumers should treat preview URLs as invalid after that time and re-generate them before reuse. When `expires_at` is omitted, the preview URLs do not expire. For generative creative, re-generating a pre-flight preview may produce different output — the same brief and context can yield different creative each time.
### Preview URL durability
`preview_url` is the protocol resource buyers and MCPUI hosts render. AdCP does not define a separate durable asset pointer for preview renders in 3.x; if a creative agent needs an internal asset key, resource URI, or storage object ID, it remains agent-internal unless the schema adds a future field for it.
Creative agents MUST keep each `preview_url` dereferenceable until the response's `expires_at` timestamp. When `expires_at` is omitted, the URL has no protocol-level expiration and must remain dereferenceable until the agent explicitly revokes or purges it out of band. Do not back preview URLs only with pod-local `Map`/LRU state in multi-process or multi-pod deployments, because a browser fetch, later refinement call, or reviewer session may land on a different process than the one that created the preview.
Durable storage does not require permanent public CDN hosting. A preview URL can resolve through the creative agent's authenticated preview route as long as the route can recover the render from shared storage, such as a database row, object store key, or shared cache tier, for the advertised lifetime.
Variant previews (post-flight) depend on the agent retaining variant data. Agents are not required to retain variant data indefinitely. If you request a variant preview for a variant the agent has purged, expect a standard error response. For long-running campaigns, retrieve and archive variant previews periodically rather than assuming they will remain available.
## Examples
### Device Variants
```json theme={null}
{
"$schema": "/schemas/3.2.8/creative/preview-creative-request.json",
"request_type": "single",
"creative_manifest": {
"format_kind": "native_in_feed",
"assets": {
"hero_image": { "asset_type": "image", "url": "https://cdn.example.com/hero.jpg", "width": 1200, "height": 627 },
"headline": { "asset_type": "text", "content": "Veterinarian Recommended" }
}
},
"inputs": [
{ "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
{ "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } }
]
}
```
### Batch with HTML Output
Preview multiple creatives for a grid layout:
```json theme={null}
{
"request_type": "batch",
"output_format": "html",
"requests": [
{ "creative_manifest": { /* creative 1 */ } },
{ "creative_manifest": { /* creative 2 */ } }
]
}
```
### AI-Generated Audio Preview
```json theme={null}
{
"$schema": "/schemas/3.2.8/creative/preview-creative-request.json",
"request_type": "single",
"creative_manifest": {
"format_kind": "audio_hosted",
"assets": {
"script_template": { "content": "This episode brought to you by {{BRAND_NAME}}..." },
"brand_voice": { "content": "Friendly, enthusiastic, conversational." }
}
},
"inputs": [
{ "name": "Weather Podcast", "context_description": "Podcast discussing weather patterns" },
{ "name": "Fitness Podcast", "context_description": "Podcast about marathon training" }
]
}
```
## HTTP Status Codes
**Single mode:**
* **200 OK** - Preview generated successfully
* **400 Bad Request** - Invalid canonical manifest
* **404 Not Found** - Format not supported
**Batch mode:**
* **200 OK** - Batch processed (check individual `success` fields)
* **400 Bad Request** - Invalid batch structure
## Key Points
* Every render's `preview_url` returns an untrusted HTML page for cross-origin iframe embedding with an empty sandbox token set
* Use `output_format: "html"` for grids of 10+ previews (no iframe overhead)
* Batch mode is 5-10x faster than individual requests
* Preview URLs expire only when `expires_at` is present; omitted `expires_at` means no protocol-level expiration
* Back preview URLs with storage that survives the URL's advertised lifetime; process-local maps are only appropriate for single-process demos or shorter-than-process-lifetime URLs
* Handle partial batch failures by checking each result's `success` field
## Related Documentation
* [Advanced Preview Patterns](/dist/docs/3.2.8/creative/task-reference/preview_creative-advanced) - Caching, workflows, implementation notes
* [Creative Manifests](/dist/docs/3.2.8/creative/creative-manifests) - Manifest structure
* [Creative Formats](/dist/docs/3.2.8/creative/formats) - Format specifications
# preview_creative (Advanced)
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/task-reference/preview_creative-advanced
Advanced AdCP preview patterns including format showcase pages, caching strategies, and batch preview workflows for creative agents.
Advanced patterns for creative preview integration including workflows, caching strategies, and implementation notes.
For basic usage, see [preview_creative](/dist/docs/3.2.8/creative/task-reference/preview_creative).
## Common Workflows
### Format Showcase Pages
Build a browsable catalog of available formats:
```typescript theme={null}
// 1. List all formats from creative agent
const capabilities = await creative_agent.get_adcp_capabilities({ protocols: ["creative"] });
const formats = capabilities.creative.supported_formats;
// 2. Generate format card previews (batch + HTML)
const formatPreviews = await creative_agent.preview_creative({
request_type: "batch",
output_format: "html",
requests: formats.map(capability => ({
creative_manifest: createExampleManifest(capability.format)
}))
});
// 3. Render in a grid
function FormatCatalog({ formatPreviews }) {
return (
{formatPreviews.results.map((result, idx) => (
result.success && (
)
))}
);
}
```
### Campaign Review Grid
Review all creatives before launch:
```typescript theme={null}
const campaignCreatives = await getCreativesForCampaign(campaignId);
const previews = await creative_agent.preview_creative({
request_type: "batch",
output_format: "html",
requests: campaignCreatives.map(c => ({ creative_manifest: c.manifest }))
});
function CampaignReview({ previews }) {
return (
{previews.results.map((result, idx) => (
))}
);
}
```
### Web Component Integration
For production applications with lazy loading:
```html theme={null}
```
**Benefits:**
* Shadow DOM for CSS isolation
* Lazy loading (only loads when visible)
* Framework agnostic
## Choosing Output Format
**Use `output_format: "url"` (default) when:**
* Security is paramount (third-party creatives)
* Building interactive preview tools
* Need iframe isolation
**Use `output_format: "html"` when:**
* Building format catalogs (10+ formats)
* Creating campaign review grids (20+ creatives)
* Server-side rendering
* Working with trusted creative agents only
## Caching Strategy
Cache individual preview results by canonical format identity (`format_kind` plus optional `format_option_ref`) + manifest hash:
```typescript theme={null}
function cachePreviewResults(results, formatIds, manifests) {
results.forEach((result, idx) => {
if (result.success) {
const cacheKey = `${formatIds[idx]}:${hashManifest(manifests[idx])}`;
cache.set(cacheKey, result.response, result.response.expires_at);
}
});
}
async function getPreviewsWithCache(formatIds, manifests) {
const cached = [];
const toFetch = [];
formatIds.forEach((id, idx) => {
const cacheKey = `${id}:${hashManifest(manifests[idx])}`;
const cachedResult = cache.get(cacheKey);
if (cachedResult && !isExpired(cachedResult.expires_at)) {
cached[idx] = cachedResult;
} else {
toFetch.push({ idx, id, manifest: manifests[idx] });
}
});
// Batch fetch only missing previews
if (toFetch.length > 0) {
const fetched = await client.preview_creative({
request_type: "batch",
output_format: "html",
requests: toFetch.map(f => ({ creative_manifest: f.manifest }))
});
fetched.results.forEach((result, i) => {
cached[toFetch[i].idx] = result.response;
});
}
return cached;
}
```
**Key points:**
* Cache by canonical format identity + manifest hash (not the entire batch)
* Request \[A,B,C] → cache each separately
* Later request \[B,C,D] → only fetch D
* Always check `expires_at` before using cached previews
## Preview URL Storage
Preview URLs are review resources, not just transport conveniences. A buyer, browser, or MCPUI host may fetch a `preview_url` after the original [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) call returns, after a pod restart, or from a different pod than the one that created the render.
For production agents, persist enough preview state to resolve every `preview_url` through its advertised lifetime:
* If `expires_at` is present, keep the render available until that timestamp.
* If `expires_at` is omitted, treat the URL as non-expiring at the protocol layer and keep it available until explicit out-of-band revocation or purge.
* Use shared storage for multi-process or multi-pod deployments: database metadata plus object storage, a shared cache tier, or an authenticated preview route that can recover the render from durable session state.
* Limit process-local `Map` or LRU storage to single-process demos, local development, or URLs whose advertised lifetime is shorter than the process lifetime you can actually guarantee.
## Error Handling
```typescript theme={null}
const response = await client.preview_creative({
request_type: "batch",
requests: formatRequests
});
const succeeded = response.results.filter(r => r.success);
const failed = response.results.filter(r => !r.success);
if (failed.length > 0) {
console.log(`${failed.length} previews failed`);
failed.forEach((result) => {
console.error(` - ${result.error.code}: ${result.error.message}`);
});
}
// Display successful previews, show error states for failures
function displayPreviews(results) {
return results.map((result, idx) => {
if (result.success) {
return ;
} else {
return retryPreview(idx)}
/>;
}
});
}
```
## Migration from Single to Batch
**Before (Sequential):**
```python theme={null}
previews = []
for format in formats:
preview = await client.preview_creative(
request_type="single",
creative_manifest=format.format_card.manifest
)
previews.append(preview)
# Total time: N × 250ms = 5000ms for 20 formats
```
**After (Batch):**
```python theme={null}
response = await client.preview_creative(
request_type="batch",
output_format="html",
requests=[
{"creative_manifest": fmt.format_card.manifest}
for fmt in formats
]
)
# Total time: ~500ms for 20 formats
```
## Use Case Patterns
### Device Variants
```json theme={null}
{
"inputs": [
{ "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
{ "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } },
{ "name": "CTV", "macros": { "DEVICE_TYPE": "ctv" } }
]
}
```
### Geographic Variants
```json theme={null}
{
"inputs": [
{ "name": "NYC", "macros": { "CITY": "New York", "DMA": "501" } },
{ "name": "LA", "macros": { "CITY": "Los Angeles", "DMA": "803" } }
]
}
```
### Privacy Compliance Testing
```json theme={null}
{
"inputs": [
{ "name": "Full consent", "macros": { "GDPR": "1", "GDPR_CONSENT": "CPc7TgP..." } },
{ "name": "No consent", "macros": { "GDPR": "1", "GDPR_CONSENT": "" } },
{ "name": "LAT enabled", "macros": { "LIMIT_AD_TRACKING": "1" } }
]
}
```
### AI Content Variants
```json theme={null}
{
"inputs": [
{ "name": "Morning commute", "context_description": "User commuting to work" },
{ "name": "Evening relaxation", "context_description": "User relaxing at home" }
]
}
```
## Implementation Notes
### For Creative Agents
**Required:**
1. Return complete HTML pages from `preview_url`
2. Handle all media types (images, video, audio, interactive)
3. Echo input parameters in response
4. Validate manifest before rendering
5. Apply macro values (or use defaults)
6. Back preview URLs with storage that survives load balancing and restarts for the URL's advertised lifetime
7. Implement security sandboxing
8. Set reasonable expiration (24-48 hours) for previews that should not be retained indefinitely
**Optional enhancements:**
* Provide `hints` object (media type, dimensions, duration)
* Provide `embedding` metadata (sandbox policy, CSP)
* Support responsive design
* Include accessibility features
### For Buyers
1. Just iframe the `preview_url` - no special rendering needed
2. Use `inputs` array for specific scenarios
3. Check `input` field to confirm macros applied
4. Share preview URLs with clients for approval
5. Use `interactive_url` for advanced testing
### For Publishers
1. Return consistent HTML from preview URLs
2. Implement responsive preview pages
3. For legacy named formats, document the coarse universal set via `supported_macros`; for canonical delivery paths, publish exact `macro_resolution_capabilities` on the selected format option
4. Clarify preview vs production differences
5. Consider providing `interactive_url` for testing
## Related Documentation
* [preview_creative](/dist/docs/3.2.8/creative/task-reference/preview_creative) - Basic usage and parameters
* [Creative Manifests](/dist/docs/3.2.8/creative/creative-manifests) - Manifest structure
* [Universal Macros](/dist/docs/3.2.8/creative/universal-macros) - Available macro values
# sync_creatives
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/task-reference/sync_creatives
sync_creatives uploads and manages creative assets in an AdCP library with bulk uploads, upsert semantics, and generative creative support.
Upload and manage creative assets in a creative library. Supports bulk uploads, upsert semantics, and generative creatives. Implemented by any agent that hosts a creative library — creative agents (ad servers, creative management platforms) and sales agents that manage creatives.
**Response time**: Instant to days (returns `completed`, or `submitted` for review that takes hours/days)
**Request Schema**: [`creative/sync-creatives-request.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/sync-creatives-request.json)
**Response Schema**: [`creative/sync-creatives-response.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/sync-creatives-response.json)
## Quick start
Upload creative assets:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncCreativesResponseSchema } from "@adcp/sdk";
import { randomUUID } from "node:crypto";
const result = await testAgent.syncCreatives({
account: {
brand: { domain: "acmecorp.com" },
operator: "acmecorp.com",
sandbox: true,
},
idempotency_key: randomUUID(),
creatives: [
{
creative_id: "creative_video_001",
name: "Summer Sale 30s",
format_kind: "video_hosted",
assets: {
video: {
asset_type: "video",
url: "https://cdn.example.com/summer-sale-30s.mp4",
width: 1920,
height: 1080,
duration_ms: 30000,
},
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
// Validate response against schema
const validated = SyncCreativesResponseSchema.parse(result.data);
// Three-shape discriminated union: errors | submitted | creatives
if ("errors" in validated && validated.errors && !("creatives" in validated) && !("status" in validated)) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("status" in validated && validated.status === "submitted") {
// Whole sync queued asynchronously — invoke get_task_status with task_id or await webhook
console.log(`Sync queued as task ${validated.task_id}: ${validated.message ?? ""}`);
} else if ("creatives" in validated) {
console.log(`Synced ${validated.creatives.length} creatives`);
for (const c of validated.creatives) {
// c.status carries review state: approved, pending_review, rejected, processing, archived
if (c.status === "pending_review" || c.status === "processing") {
console.log(` ${c.creative_id}: awaiting review (${c.status})`);
}
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from uuid import uuid4
async def main():
result = await test_agent.simple.sync_creatives(
account={
'brand': {'domain': 'acmecorp.com'},
'operator': 'acmecorp.com',
'sandbox': True
},
idempotency_key=str(uuid4()),
creatives=[{
'creative_id': 'creative_video_001',
'name': 'Summer Sale 30s',
'format_kind': 'video_hosted',
'assets': {
'video': {
'asset_type': 'video',
'url': 'https://cdn.example.com/summer-sale-30s.mp4',
'width': 1920,
'height': 1080,
'duration_ms': 30000
}
}
}]
)
# Three-shape discriminated union: errors | submitted | creatives
if getattr(result, 'status', None) == 'submitted':
# Whole sync queued asynchronously — invoke get_task_status with task_id or await webhook
print(f"Sync queued as task {result.task_id}: {getattr(result, 'message', '') or ''}")
return
if getattr(result, 'errors', None) and not getattr(result, 'creatives', None):
raise Exception(f"Operation failed: {result.errors}")
print(f"Synced {len(result.creatives)} creatives")
for c in result.creatives:
# c.status carries review state: approved, pending_review, rejected, processing, archived
if getattr(c, 'status', None) in ('pending_review', 'processing'):
print(f" {c.creative_id}: awaiting review ({c.status})")
asyncio.run(main())
```
**Note:** Per-creative async review is surfaced via `creatives[].status` (e.g., `pending_review`) on the synchronous success response. When the *whole* operation is queued (batch ingestion, governance review gating the sync), the response is a submitted envelope with top-level `status: "submitted"` and a `task_id`. See [Async approval workflow](#async-approval-workflow).
For campaigns with a short launch window, [sync the creative into a seller library before booking, wait for review, then assign it to a package](/dist/docs/3.2.8/creative/creative-libraries#prepare-creatives-before-a-time-sensitive-launch). Library approval and package assignment eligibility are separate checks.
## Read-after-write visibility
Creatives accepted via a synchronous `sync_creatives` success response MUST be committed to the creative library before the response is returned. They MUST be immediately visible to subsequent [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) calls from the same account and authorized caller, including creatives whose review lifecycle status is `processing` or `pending_review`.
Implementations that acknowledge a creative on the synchronous success branch but buffer the library write until a later background commit are not conformant. If the whole sync operation cannot commit before returning, use the submitted task envelope instead; the visibility requirement then applies when the task completes with accepted creatives.
## Request parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | object | Yes | Account reference identifying the advertiser/workspace for this sync ([account-ref](/dist/docs/3.2.8/accounts/overview)) |
| `idempotency_key` | string | Yes | Client-generated key that makes retries safe. Use a fresh UUID or other unique value per request. |
| `creatives` | Creative\[] | Yes | Creative assets to upload/update (max 100) |
| `creative_ids` | string\[] | No | Optional filter to limit sync scope to specific creative IDs. Only these creatives are affected, others remain untouched. Useful for partial updates and error recovery. |
| `assignments` | array | No | Array of `{creative_id, package_id}` objects for bulk assignment. Optional `weight` and `placement_ids` per assignment. |
| `dry_run` | boolean | No | When true, rehearse this exact sync operation without applying it (default: false). Use this for seller trafficking acceptance checks; use [`validate_input`](https://adcontextprotocol.org/schemas/3.2.8/creative/validate-input-request.json) for manifest-only preflight against canonical/product format targets. |
| `validation_mode` | string | No | Validation strictness: `"strict"` (default) or `"lenient"` |
| `delete_missing` | boolean | No | When true, creatives not in this sync are archived (default: false). Cannot be combined with `creative_ids`. Cannot delete creatives assigned to active, non-paused packages. |
Every `creatives[]` item in one request MUST have a unique `creative_id`.
Duplicate IDs make response correlation and write ordering ambiguous, so the
seller rejects the request rather than applying last-write-wins behavior.
### Creative object
| Field | Type | Required | Description |
| - | - | - | - |
| `creative_id` | string | Yes | Unique identifier for this creative |
| `revision_id` | string | No | Buyer-assigned input-content revision scoped to `creative_id`. May be sent to any 3.2 peer; `creative.supports_revisions: true` gates reliance on its guarantees. |
| `name` | string | Yes | Human-readable name |
| `format_kind` | CanonicalFormatKind | Yes for 3.2 authoring | Portable canonical format path. Pair with `format_option_ref` when exact routing is required. |
| `format_id` | FormatId | Deprecated | Named-format compatibility path for older 3.x peers; mutually exclusive with `format_kind`. |
| `format_option_ref` | FormatOptionRef | No | Optional structured reference to a product or publisher format option. Required when the target product has multiple options with the same `format_kind`. |
| `assets` | object | Yes | Assets keyed by the selected format's slot name (`asset_group_id` for canonical formats). Catalogs are included as assets with `asset_type: "catalog"`. See [Catalogs](/dist/docs/3.2.8/creative/catalogs). |
| `localization` | object \| null | No | Sync-only explicit source and target locale variants. Requires `get_adcp_capabilities.creative.localization`. An object replaces the complete locale set; null removes it. Omission preserves existing localization only when source assets are exactly unchanged. |
| `tags` | string\[] | No | Searchable tags for creative organization |
New 3.2 integrations use `format_kind` with `format_option_ref` when routing depends on a product's declared option. A compatibility implementation may accept the legacy branch from an older peer, but never mixes both shapes.
Before uploading, buyers MUST verify each creative manifest against the target product's canonical `format_options[]`. The manifest MUST include every asset slot that the selected format option declares as required, keyed by that slot's `asset_group_id`.
### Creative revisions
Buyers may send `revision_id` to any 3.2 peer. When the agent advertises
`creative.supports_revisions: true`, buyers may rely on it to correlate one
immutable input state through sync, review, readback, and delivery. Without the
capability, the receiver may ignore the field and the buyer cannot rely on
revision guarantees. A supporting seller echoes it on accepted `created`, `updated`,
and `unchanged` items and omits it on `failed` and `deleted` items.
The identity is `(creative_id, revision_id)`. Reusing that pair with identical
canonical revision content is safe even under a new `idempotency_key`. Reusing
it with changed content fails that creative item with
[`CREATIVE_REVISION_CONTENT_MISMATCH`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-revision-content-mismatch) and leaves its prior state unchanged; other batch items may still process. Mint a new `revision_id` for intentional
content changes. Metadata-only changes to `name` or `tags`, and assignment
changes, do not require a new revision. The seller checks `idempotency_key`
conflicts first, then revision content.
Canonical revision content is RFC 8785 JCS of the effective buyer-authored
creative state after applying existing sync mutation semantics, then removing
exactly the top-level `creative_id`, `revision_id`, `name`, `tags`,
`status`, `weight`, `placement_refs`, and `placement_ids` fields. Sellers do not
materialize defaults or normalize values before this comparison. Nested fields
with those names remain content. Duplicate JSON member names are rejected.
An allowed omitted `localization` preserves the prior topology before
comparison. `localization: null` removes localization from the effective state
before comparison, so a later allowed omission represents that same
unlocalized state. URL identity is the submitted URL string (plus
any submitted digest), so use immutable or digest-bound asset references when
byte-level identity matters.
A different revision ID with content identical to the current canonical state
is accepted as `updated`, becomes current, and preserves the existing review
state. A seller atomically rebinds any in-flight review to that new
identical-content ID. A previously bound historical ID must still match its
retained fingerprint and, when its content differs from current, enters review
again if accepted. A different revision with changed content enters review. Sellers retain revision
fingerprint bindings for the creative's lifetime (and any soft-purge tombstone
window); a hard purge starts a new creative incarnation. Revision IDs are not
ordering counters—buyers serialize writes, and stale review results for older
revisions cannot change the current revision or status.
When an existing unversioned creative first adopts revision identity, identical
effective content is accepted as `updated`, binds the supplied ID, and preserves
review state. If content also changes, the seller binds the ID only when the
ordinary update is accepted, and changed content enters review.
An omitted `revision_id` preserves current revision identity only for
content-equivalent updates. If a supporting seller accepts changed content from
a legacy unversioned caller, it clears current revision identity and does not
mint one; later readback, webhooks, and delivery omit the field while historical
bindings remain retained. Prior approval does not transfer, and an accepted
content-bearing unversioned update enters the ordinary review lifecycle.
With `dry_run: true`, the seller evaluates existing revision conflicts and may
echo the simulated revision, but it does not reserve an ID, change bindings or
tombstones, select a current revision, or alter review state.
When an item carries `representation_selection`, its `creative_id` and
`revision_id` must equal the selection lineage. The seller binds revision
identity to `representation_selection.revision_content_digest`, which commits
to the complete [`CreativeRepresentationSet`](/dist/docs/3.2.8/creative/representation-sets),
not to the selected manifest bytes alone. The actor that emitted the selection
must first verify the digest against the complete set. A downstream seller that
receives only the selected output can enforce stable digest reuse, but cannot
claim it independently inspected representations it never received.
The seller separately verifies `selected_output_digest` with the same manifest
projection used by [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative): remove top-level `$schema`,
`representation_selection`, `creative_id`, `revision_id`, `name`, `tags`,
`status`, `weight`, `placement_refs`, `placement_ids`, `inputs`, and
then include every other field. It tracks
`(selected_representation_id, selected_output_digest)` as the execution review
fingerprint. A changed selection or changed derived output is an
`updated` creative and follows ordinary re-review even when the source-set
`revision_id` and digest remain unchanged. [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) returns the exact
current selection lineage while that execution remains current.
The seller never performs that replacement implicitly. Once accepted, the
selection is pinned even if later product or seller capabilities would choose
a different representation. Capability drift affects future resolution and
assignment checks; it does not mutate the library creative or start re-review.
The buyer must explicitly resolve again with `build_creative` and submit the
new selected output here. This sync response acknowledges the update and starts
ordinary re-review. If the seller can no longer serve the pinned execution, it
uses the ordinary seller/system status-change and media-buy impairment
surfaces without substituting another representation.
A sync item carrying `representation_selection` MUST omit `localization`,
including `null`, in this version, and the stored creative must not already
have localization that ordinary omission would preserve. Remove an existing
topology first with a separate accepted sync carrying `localization: null` and
no `representation_selection`, then submit the selected output. Localization
replaces materialized serving assets and cannot be treated as digest-neutral library metadata. A future
localized representation-set contract must define locale topology inside the
pre-binding revision and selected-output projections explicitly.
Revision support does not add staged activation or revision history. A newly
accepted content revision follows the ordinary creative update and review
lifecycle, and prior approval does not transfer to changed content. The
buyer-initiated transition is acknowledged on this response rather than a
`creative.status_changed` webhook; subsequent seller/system review transitions
use the ordinary webhook. The prior revision is not kept serving during review.
A revised creative under re-review is ineligible for delivery like any other
`pending_review` creative until it re-reaches `approved`. Other creatives
assigned to the same package are unaffected and continue under the seller's
ordinary selection behavior. A package that relies only on the revised creative
therefore has a serving gap by default; buyers that need zero-gap replacement
can sync the candidate under a new `creative_id` and change assignments after
approval. Staged activation of a replacement under the same identity is outside
this revision contract.
Creatives produced through [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative)
become buyer-authored revision state when the buyer accepts and syncs the
returned manifest, choosing the `creative_id` and minting (or omitting) the
`revision_id`. Seller-side drafts before that sync boundary are outside AdCP's
revision history; seller transformation and transcoding after the boundary do
not mint buyer revision IDs.
### Native localization
Discover support before writing. The agent's
`get_adcp_capabilities.creative.localization` block advertises structural
support, RFC 4647 Lookup, and an optional target ceiling. Locale, format, and
account support is validated against each request. A seller MUST reject an
unsupported locale/format pair, duplicate target locale/ID, target locale/ID
that reuses the source value, missing materialized assets, or invalid default
reference before mutating seller systems or the creative library. JSON Schema `uniqueItems`
compares whole objects and is not sufficient for those property-level rules;
conformance verifiers consume the schema's `x-adcp-validation` constraints.
This is the only localization mutation surface. Inline package creatives in
[`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) reject `localization`; sync the
localized library creative here, then assign it by `creative_id`.
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/creative/sync-creatives-request.json",
"adcp_version": "3.1",
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"account": { "account_id": "acct_nova" },
"creatives": [
{
"creative_id": "summer_image_localized",
"name": "Summer image — localized",
"format_kind": "image",
"assets": {
"image": {
"asset_type": "image",
"url": "https://cdn.nova.example/summer-en.jpg",
"width": 1080,
"height": 1080
},
"headline": {
"asset_type": "text",
"content": "Summer starts here",
"language": "en-US"
}
},
"localization": {
"source": {
"locale_variant_id": "loc_en_us",
"locale": "en-US"
},
"target_variants": [
{
"locale_variant_id": "loc_es_mx",
"locale": "es-MX",
"assets": {
"image": {
"asset_type": "image",
"url": "https://cdn.nova.example/summer-es-mx.jpg",
"width": 1080,
"height": 1080
},
"headline": {
"asset_type": "text",
"content": "El verano empieza aquí",
"language": "es-MX"
}
}
}
],
"locale_fallbacks": [
{
"language_range": "es",
"locale_variant_id": "loc_es_mx"
}
],
"default_locale_variant_id": "loc_en_us",
"unmatched_locale_action": "do_not_serve"
}
}
]
}
```
Source identifies production provenance, not the serving default. Every target
contains materialized locale-specific overrides; missing slots inherit source.
`target_variants` may be empty to declare the canonical locale of a monolingual
source-only creative, such as a single `fr-CA` creative for French-only Québec
inventory. Do not invent a second locale variant merely to declare source
language.
`default_locale_variant_id` may select source or target. This task never asks
the seller to translate: use buyer tooling, [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative), or a separate
translation/transformation agent first, then sync the resulting assets.
At delivery, the seller applies RFC 4647 Lookup to ordered locale preferences.
Each progressively truncated requested range matches only an equal available
canonical tag; it does not prefix-match sibling regional tags.
The ordered list comes from the seller's serving environment and is outside
this task: AdCP does not define how browser, content, geography, user, app, or
platform signals produce it or their precedence.
For each preference, a strict miss is followed by the most-specific matching
`locale_fallbacks` rule before the next preference is tried. The example's `es`
rule lets an `es-ES` preference use `loc_es_mx`; without that rule, no regional
substitution is inferred. After every preference misses both paths, the seller
follows `unmatched_locale_action`: serve `default_locale_variant_id` or make the
creative ineligible. It never silently assumes the source is the default.
Standalone library sync has no product context and does not apply product locale
policy. When `assignments[]` binds a creative to a package whose effective
format option has `locale_policy`, the
seller uses RFC 4647 Basic Filtering to derive the eligible source/target
variant set before running the buyer algorithm above. For example, seller range
`fr` accepts `fr-CA` and `fr-FR`. The assignment fails with
[`CREATIVE_LOCALE_NOT_ACCEPTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-locale-not-accepted) if no materialized variant matches. If
`unmatched_locale_action` is `serve_default`, the default variant must also be
seller-eligible. Buyer fallback and default rules never override the product or
placement constraint; nonmatching variants remain stored for other products.
The seller runs this check independently for every placement where the
assignment may serve. If one placement fails, the assignment is rejected unless
the buyer narrows its placement scope to compatible placements.
Accepted localized results include `localization` as a complete
source-plus-target variant list. The response preserves the request's exact
source ID/locale, target ID/locale set, fallback-rule set, default ID, and unmatched action. Each
variant returns complete resolved assets under the same buyer-assigned
`locale_variant_id`; no seller- or platform-assigned variant ID is required.
The enclosing creative's single `status` governs the complete set. If the
seller cannot read back any one of those values exactly, the item fails rather
than silently falling back to the source language.
Every accepted localized result (`created`, `updated`, or `unchanged`) MUST
carry top-level aggregate `status` and complete `localization`; `failed` and
`deleted` results MUST omit localization. A later
[`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) read preserves the exact source/target identities.
`delete_missing` remains creative-scoped. If it archives a creative, every
locale variant follows the whole creative lifecycle, and omitted target locales
are never treated as missing creatives. A non-null `localization` object
transactionally replaces top-level source assets and the complete locale set;
failure leaves the prior state unchanged and must not expose orphaned locale
variants.
Null removes localization. Omission preserves localization only when top-level
source assets exactly equal the prior source assets. The normal active-delivery
update protection applies to all three operations.
### Promoting a build_creative variant
When a buyer keeps a produced build leaf, the canonical promotion is to use the kept `build_variant_id` as the new `creative_id`. The seller does not need to hold a separate lineage mapping; delivery reporting can join back to the build leaf through the normal `creative_id`.
```json test=false theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
"account": { "account_id": "acct_acmecorp" },
"creatives": [
{
"creative_id": "bv_card01_a",
"name": "Summer card - studio take",
"format_kind": "image",
"assets": {
"headline_0_text": {
"asset_type": "text",
"content": "Summer Sale - 50% Off"
},
"image_0_url": {
"asset_type": "image",
"url": "https://cdn.example.com/beach-hero.jpg",
"width": 300,
"height": 250
}
}
}
]
}
```
Later, [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery) uses `creative_id` as the join key. A workflow that mints a different library id instead of using the kept `build_variant_id` loses this protocol-visible join unless a future scoped lineage field is adopted.
### Asset structure
Assets are keyed by role name. Each role contains the asset details:
```json test=false theme={null}
{
"assets": {
"video": {
"url": "https://cdn.example.com/video.mp4",
"width": 1920,
"height": 1080,
"duration_ms": 30000
},
"thumbnail": {
"url": "https://cdn.example.com/thumb.jpg",
"width": 300,
"height": 250
}
}
}
```
For published-post reference products, the asset role is usually `published_post` and the payload contains a post URL or platform post ID instead of uploaded media bytes. Buyers can submit these assets through the canonical creative path, for example `format_kind: "video_hosted"` plus the product's `format_option_ref`, instead of creating a platform-specific `format_id`. If the seller can resolve the post but lacks a required downstream platform connection, such as the publisher identity that owns the post, the correctable error is [`AUTHORIZATION_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-authorization-required). New implementations should include `error.details.missing_connections[]` so the caller can send a human through the correct connections flow and retry after authorization is restored.
### Assignments structure
Assignments are at the request level, mapping creative IDs to package IDs. Standalone creative agents that do not manage media buys ignore this field.
```json test=false theme={null}
{
"assignments": [
{ "creative_id": "creative_video_001", "package_id": "pkg_premium" },
{ "creative_id": "creative_video_001", "package_id": "pkg_standard" },
{ "creative_id": "creative_display_002", "package_id": "pkg_standard" }
]
}
```
**Adopter note (`@adcp/sdk` server-side):** the typed `syncCreatives(creatives, ctx)` signature does not surface `assignments` as a positional argument. The wire envelope lands on `RequestContext.input`, so handlers read `ctx.input.assignments` to fan out package bindings and emit `creatives[i].assigned_to` in the response. The same escape hatch applies to any request field the typed signature intentionally does not model. See [`adcp#5797`](https://github.com/adcontextprotocol/adcp/issues/5797) for the trace that motivated this note (SDK ≥ 11.1.0 threads `params` into `ctx.input`; earlier lines dropped the field at the projector seam).
## Response
Responses use discriminated unions — a response has exactly one of three shapes, never mixed:
**1. Synchronous success** — per-creative results:
* `creatives` - Results for each creative processed (includes both successful and failed items)
* `dry_run` - Boolean indicating if this was a dry run (optional)
**2. Terminal error** — no creatives processed:
* `errors` - Array of operation-level errors (auth failure, service unavailable)
**3. Submitted task envelope** — whole operation queued asynchronously (batch ingestion, governance review gating the sync):
* `status` - Always `"submitted"`
* `task_id` - Handle for polling via [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) on the A2A profile (or the advertised AdCP polling task on MCP), or receiving a webhook on completion
* `message` - Optional human-readable explanation of the queue state
The final per-creative `creatives` array lands on the task completion artifact, not on the submitted envelope. Per-item async review (one creative in `pending_review` while the rest of the sync resolves synchronously) belongs on the synchronous success branch with `status: "pending_review"` on that item, not here.
**Each creative in the success response includes:**
* All request fields
* `platform_id` - Platform's internal ID (when `action` is not `failed`)
* `revision_id` - Exact request revision on accepted `created`, `updated`, or `unchanged` items when supplied. Omitted on `failed` and `deleted`.
* `action` - Lifecycle operation performed by this sync: `created`, `updated`, `unchanged`, `failed`, `deleted`
* `status` - **Advisory** review-lifecycle state ([`CreativeStatus`](https://adcontextprotocol.org/schemas/3.2.8/enums/creative-status.json)): `processing`, `pending_review`, `approved`, `suspended`, `rejected`, `archived`. A UI hint and polling-scheduling signal — **not** a spend-authorization gate. Orthogonal to `action` — `action` describes what the sync did, `status` describes where the creative is in the review lifecycle. Values come from `CreativeStatus` only, never from `CreativeAction` (never put `created`/`updated`/`failed` in `status`). Sellers with async review return `processing` or `pending_review`; sellers with synchronous review MAY return a terminal value (`approved`/`rejected`) or `suspended` when a recoverable dependency/authorization gate prevents serving. **Buyers MUST NOT gate downstream spend or package activation on `status: approved` from this response** — reconcile via [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) or a signed review webhook before committing spend. Authoritative state is always via `list_creatives`. **MUST be omitted** when `action` is `failed` or `deleted` — failed items have no meaningful review state (see `errors`); deleted items are gone from the library. The schema enforces the omission rule via a conditional constraint.
* `localization` - Exact materialized source/target locale state. Required with top-level `status` on every accepted localized item, omitted on failed/deleted/unlocalized items. The top-level status is the single creative-wide review state.
* `errors` - Array of error messages (only when `action: "failed"`)
* `warnings` - Array of non-fatal warnings (optional)
**See schema for complete field list**: [sync-creatives-response.json](https://adcontextprotocol.org/schemas/3.2.8/creative/sync-creatives-response.json)
## Common scenarios
### Bulk upload
Upload multiple creatives in one call:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncCreativesResponseSchema } from "@adcp/sdk";
import { randomUUID } from "node:crypto";
const result = await testAgent.syncCreatives({
account: {
brand: { domain: "acmecorp.com" },
operator: "acmecorp.com",
sandbox: true,
},
idempotency_key: randomUUID(),
creatives: [
{
creative_id: "creative_display_001",
name: "Summer Sale Banner 300x250",
format_kind: "image",
assets: {
image: {
asset_type: "image",
url: "https://cdn.example.com/banner-300x250.jpg",
width: 300,
height: 250,
},
},
},
{
creative_id: "creative_video_002",
name: "Product Demo 15s",
format_kind: "video_hosted",
assets: {
video: {
asset_type: "video",
url: "https://cdn.example.com/demo-15s.mp4",
width: 1920,
height: 1080,
duration_ms: 15000,
},
},
},
{
creative_id: "creative_display_002",
name: "Summer Sale Banner 728x90",
format_kind: "image",
assets: {
image: {
asset_type: "image",
url: "https://cdn.example.com/banner-728x90.jpg",
width: 728,
height: 90,
},
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncCreativesResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("creatives" in validated) {
console.log(`Successfully synced ${validated.creatives.length} creatives`);
validated.creatives.forEach((creative) => {
console.log(` ${creative.creative_id}: ${creative.action}`);
});
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from uuid import uuid4
async def main():
result = await test_agent.simple.sync_creatives(
account={
'brand': {'domain': 'acmecorp.com'},
'operator': 'acmecorp.com',
'sandbox': True
},
idempotency_key=str(uuid4()),
creatives=[
{
'creative_id': 'creative_display_001',
'name': 'Summer Sale Banner 300x250',
'format_kind': 'image',
'assets': {
'image': {
'asset_type': 'image',
'url': 'https://cdn.example.com/banner-300x250.jpg',
'width': 300,
'height': 250
}
}
},
{
'creative_id': 'creative_video_002',
'name': 'Product Demo 15s',
'format_kind': 'video_hosted',
'assets': {
'video': {
'asset_type': 'video',
'url': 'https://cdn.example.com/demo-15s.mp4',
'width': 1920,
'height': 1080,
'duration_ms': 15000
}
}
},
{
'creative_id': 'creative_display_002',
'name': 'Summer Sale Banner 728x90',
'format_kind': 'image',
'assets': {
'image': {
'asset_type': 'image',
'url': 'https://cdn.example.com/banner-728x90.jpg',
'width': 728,
'height': 90
}
}
}
]
)
# Check for operation-level errors first
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
print(f"Successfully synced {len(result.creatives)} creatives")
for creative in result.creatives:
print(f" {creative.creative_id}: {creative.action}")
asyncio.run(main())
```
### Generative creatives
Use the creative agent to generate creatives from brand identity data. See the [Generative Creatives guide](/dist/docs/3.2.8/creative/generative-creative) for complete workflow details.
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncCreativesResponseSchema } from "@adcp/sdk";
import { randomUUID } from "node:crypto";
const result = await testAgent.syncCreatives({
account: {
brand: { domain: "acmecorp.com" },
operator: "acmecorp.com",
sandbox: true,
},
idempotency_key: randomUUID(),
creatives: [
{
creative_id: "creative_gen_001",
name: "AI-Generated Summer Banner",
format_kind: "image",
assets: {
prompt: {
asset_type: "text",
content: "Create a summer banner for outdoor enthusiasts. Headline: Summer gear built for every trail. CTA: Shop the collection.",
},
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncCreativesResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("creatives" in validated) {
console.log(
"Generative creative synced:",
validated.creatives[0].creative_id
);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from uuid import uuid4
async def main():
result = await test_agent.simple.sync_creatives(
account={
'brand': {'domain': 'acmecorp.com'},
'operator': 'acmecorp.com',
'sandbox': True
},
idempotency_key=str(uuid4()),
creatives=[{
'creative_id': 'creative_gen_001',
'name': 'AI-Generated Summer Banner',
'format_kind': 'image',
'assets': {
'prompt': {
'asset_type': 'text',
'content': 'Create a summer banner for outdoor enthusiasts. Headline: Summer gear built for every trail. CTA: Shop the collection.'
}
}
}]
)
# Check for operation-level errors first
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
print(f"Generative creative synced: {result.creatives[0].creative_id}")
asyncio.run(main())
```
### Dry run validation
Validate creative configuration without uploading:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncCreativesResponseSchema } from "@adcp/sdk";
import { randomUUID } from "node:crypto";
const result = await testAgent.syncCreatives({
account: {
brand: { domain: "acmecorp.com" },
operator: "acmecorp.com",
sandbox: true,
},
idempotency_key: randomUUID(),
dry_run: true,
creatives: [
{
creative_id: "creative_test_001",
name: "Test Creative",
format_kind: "video_hosted",
assets: {
video: {
asset_type: "video",
url: "https://cdn.example.com/test-video.mp4",
width: 1920,
height: 1080,
duration_ms: 30000,
},
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncCreativesResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors && validated.errors.length > 0) {
console.log("Validation errors found:");
validated.errors.forEach((error) => console.log(` - ${error.message}`));
} else if (
"creatives" in validated && validated.creatives?.some((creative) => creative.action === "failed")
) {
console.log("Creative validation errors found.");
} else if (
"assignments" in validated && validated.assignments?.some((assignment) => assignment.status === "error")
) {
console.log("Assignment validation errors found.");
} else {
console.log("Validation passed! Ready to sync.");
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from uuid import uuid4
async def main():
result = await test_agent.simple.sync_creatives(
account={
'brand': {'domain': 'acmecorp.com'},
'operator': 'acmecorp.com',
'sandbox': True
},
idempotency_key=str(uuid4()),
dry_run=True,
creatives=[{
'creative_id': 'creative_test_001',
'name': 'Test Creative',
'format_kind': 'video_hosted',
'assets': {
'video': {
'asset_type': 'video',
'url': 'https://cdn.example.com/test-video.mp4',
'width': 1920,
'height': 1080,
'duration_ms': 30000
}
}
}]
)
if hasattr(result, 'errors') and result.errors:
error_messages = [error.message for error in result.errors]
raise Exception(f"Validation errors: {error_messages}")
if any(getattr(creative, 'action', None) == 'failed' for creative in getattr(result, 'creatives', [])):
raise Exception('Creative validation errors found')
if any(getattr(assignment, 'status', None) == 'error' for assignment in getattr(result, 'assignments', [])):
raise Exception('Assignment validation errors found')
print('Validation passed! Ready to sync.')
asyncio.run(main())
```
### Scoped update with creative_ids filter
Update only specific creatives from a large library without affecting others:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncCreativesResponseSchema } from "@adcp/sdk";
import { randomUUID } from "node:crypto";
// Update just 2 creatives out of 100+ in the library
const result = await testAgent.syncCreatives({
account: {
brand: { domain: "acmecorp.com" },
operator: "acmecorp.com",
sandbox: true,
},
idempotency_key: randomUUID(),
creative_ids: ["creative_video_001", "creative_display_001"],
creatives: [
{
creative_id: "creative_video_001",
name: "Summer Sale 30s - Updated",
format_kind: "video_hosted",
assets: {
video: {
asset_type: "video",
url: "https://cdn.example.com/updated-video.mp4",
width: 1920,
height: 1080,
duration_ms: 30000,
},
},
},
{
creative_id: "creative_display_001",
name: "Summer Sale Banner - Updated",
format_kind: "image",
assets: {
image: {
asset_type: "image",
url: "https://cdn.example.com/updated-banner.jpg",
width: 300,
height: 250,
},
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncCreativesResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Update failed: ${JSON.stringify(validated.errors)}`);
}
if ("creatives" in validated) {
console.log(
`Updated ${validated.creatives.length} creatives, others untouched`
);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from uuid import uuid4
async def main():
# Update just 2 creatives out of 100+ in the library
result = await test_agent.simple.sync_creatives(
account={
'brand': {'domain': 'acmecorp.com'},
'operator': 'acmecorp.com',
'sandbox': True
},
idempotency_key=str(uuid4()),
creative_ids=['creative_video_001', 'creative_display_001'],
creatives=[
{
'creative_id': 'creative_video_001',
'name': 'Summer Sale 30s - Updated',
'format_kind': 'video_hosted',
'assets': {
'video': {
'asset_type': 'video',
'url': 'https://cdn.example.com/updated-video.mp4',
'width': 1920,
'height': 1080,
'duration_ms': 30000
}
}
},
{
'creative_id': 'creative_display_001',
'name': 'Summer Sale Banner - Updated',
'format_kind': 'image',
'assets': {
'image': {
'asset_type': 'image',
'url': 'https://cdn.example.com/updated-banner.jpg',
'width': 300,
'height': 250
}
}
}
]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Update failed: {result.errors}")
print(f"Updated {len(result.creatives)} creatives, others untouched")
asyncio.run(main())
```
**Why use creative_ids filter:**
* Scoped updates: Only specified creatives modified, even with 100+ in library
* Error recovery: Retry only failed creatives after bulk sync validation failures
* Performance: Publisher can optimize processing when scope is known upfront
* Safety: Explicit targeting reduces risk of unintended changes
## Async approval workflow
Two distinct async patterns — match the right one to the agent's behavior:
**Per-creative async review** (common): the sync operation itself resolves synchronously, but one or more creatives require downstream review (brand safety, policy compliance). Items in review come back on the synchronous success response with `status: "pending_review"` (or `processing` during ingestion). The buyer reconciles terminal state via [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) or a webhook.
**Operation-level async** (less common): the whole sync is queued — the seller cannot return any per-item results before responding, because ingestion is batched or governance review gates the entire sync. The response is a submitted envelope:
* Top-level `status: "submitted"` with `task_id`
* `message` — optional human-readable explanation
* No `creatives` array on this envelope
Invoke [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) on the A2A profile (or the advertised AdCP polling task on MCP), or wait for the webhook. The completion artifact carries the `creatives` array with per-item `action`/`status` results; operation-level failures surface as `status: "failed"` on the task.
**See:** [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for webhook configuration.
## Sync modes
### Upsert (default)
* Creates new creatives or updates existing by `creative_id`
* `assignments[]` remains the deprecated additive assignment shorthand
* `assignment_operations[]` can traffic existing IDs without resending creative bodies: `assign` upserts weight/placement scope, `unassign` removes one assignment, and `replace` atomically swaps an existing creative for a replacement
* Updates provided fields, leaves others unchanged
* Use `creative_ids` filter to limit scope to specific creatives
### Dry run
* Rehearses the same `sync_creatives` acceptance path without committing library, assignment, review, or serving changes
* Returns operation-level errors, per-creative failures, assignment errors, and warnings the seller can determine before mutation
* Does not create or update creatives, package assignments, review state, or serving state
* Use for seller trafficking acceptance checks; use [`validate_input`](https://adcontextprotocol.org/schemas/3.2.8/creative/validate-input-request.json) for manifest-only canonical/product preflight
## Error handling
| Error Code | Description | Resolution |
| - | - | - |
| [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) | Format not supported by this seller or product | Check the product's canonical `format_options[]` |
| [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) | Manifest failed format validation: an asset file is corrupt or invalid, or assets don't match the format's requirements (codec, dimensions, duration). `error.field` identifies the offending asset path | Verify asset types and specifications match the format definition |
| [`PACKAGE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-package-not-found) | Package ID doesn't exist in media buy | Verify `package_id`; for legacy package correlation use [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) + package `context.buyer_ref` |
| [`CREATIVE_REJECTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-rejected) | Creative failed content-policy, brand-safety, or accessibility review | Revise according to the applicable policy or validated accessibility criteria |
| [`CREATIVE_LOCALE_NOT_ACCEPTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-locale-not-accepted) | Assigned creative has no materialized variant accepted by the package's effective format `locale_policy`, lacks locale topology, or uses an ineligible `serve_default` | Supply a matching source/target variant, choose a compatible format option, or change the default policy |
| [`INVALID_STATE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-state) | Creative is assigned to an active, non-paused package (blocks updates and `delete_missing` deletions) | Pause the package first, or create a new creative version |
Sellers that declare `creative_specs.vast_validation` of `document` or `wrapper` additionally validate `vast` assets at sync time (including `dry_run`) and can return [`VAST_PARSE_FAILED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-vast-parse-failed), [`VAST_VERSION_MISMATCH`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-vast-version-mismatch), or [`VAST_WRAPPER_DEPTH_EXCEEDED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-vast-wrapper-depth-exceeded). See [VAST Validation](/dist/docs/3.2.8/creative/channels/video#vast-validation).
## Best practices
1. **Use upsert semantics** - Same `creative_id` updates existing creative rather than creating duplicates. This allows iterative creative development. Note: updates are blocked for creatives in active delivery (see #6).
2. **Rehearse seller acceptance first** - Use `dry_run: true` when you need to catch upload, upsert, assignment, account, policy, or format errors before mutating the seller's creative library. Use [`validate_input`](https://adcontextprotocol.org/schemas/3.2.8/creative/validate-input-request.json) earlier in the workflow only for manifest-structure preflight or multi-target product comparison.
3. **Batch assignment operations** - Use one idempotent `assignment_operations[]` call for assignment updates, removals, and replacements. This keeps creative trafficking separate from MediaBuy commercial controls and avoids races between calls.
4. **CDN-hosted assets** - Use publicly accessible CDN URLs for faster processing. Platforms can fetch assets directly without proxy delays.
5. **Brand identity** - For generative creatives, validate brand identity schema before syncing to avoid processing failures.
6. **Active delivery protection** - Creatives assigned to active, non-paused packages cannot be updated or deleted via `delete_missing`. Pause the package first, use `assignment_operations` to unassign or replace the creative, or create a new creative with a different `creative_id`.
## Related tasks
* [Canonical formats](/dist/docs/3.2.8/creative/canonical-formats) - Check product and publisher format contracts before upload
* [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) - Browse and filter creatives in a library
* [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative) - Build manifests from library creatives or generate from scratch
* [`preview_creative`](/dist/docs/3.2.8/creative/task-reference/preview_creative) - Generate previews of creative manifests
* [Creative Asset Types](/dist/docs/3.2.8/creative/asset-types) - Technical requirements for assets
# Migrating Template Format IDs
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/template-format-ids
Replace parameterized template format IDs with canonical declarations and creative capability IDs in AdCP 3.2.
Template and parameterized `format_id` patterns are deprecated in AdCP 3.2. They combined structural constraints, namespace ownership, and operation routing in one compound identifier. Canonical declarations separate those concerns.
## Replacement model
| Legacy use | Canonical replacement |
| - | - |
| A template ID plus width/height fields | `format_kind` with explicit canonical `params` |
| A seller's supported template list | Each product's `format_options[]` |
| A creative agent's template catalog | `creative.supported_formats[]` |
| Selecting a build template | `target_capability_id` and, when applicable, `transformer_id` |
| A manifest's template reference | `format_kind` plus optional `format_option_ref` |
## Product declaration
```json theme={null}
{
"format_option_id": "display_image_300x250",
"format_kind": "image",
"params": {
"width": 300,
"height": 250,
"slots": [
{ "asset_group_id": "image_main", "asset_type": "image", "required": true }
]
}
}
```
Flexible size support uses `sizes[]` or a responsive bounds envelope in `params`; it does not mint one partially parameterized identifier.
## Creative capability
```json theme={null}
{
"capability_id": "display_image_builder",
"operations": ["build", "validate", "preview"],
"format": {
"format_kind": "image",
"params": {
"sizes": [{ "w": 300, "h": 250 }, { "w": 728, "h": 90 }]
}
}
}
```
```json theme={null}
{
"target_capability_id": "display_image_builder",
"message": "Adapt the launch concept to a 300x250 placement"
}
```
If the creative service offers separately priced or configured templates, expose them through `list_transformers`. Each transformer declares `output_capability_ids[]`; build requests select one with `transformer_id`.
## Compatibility
Implementations may still parse legacy template IDs for older 3.x peers. Normalize them to canonical declarations immediately and do all matching on the canonical shape. Do not author new template IDs or treat a deprecated `list_creative_formats` response as a source of truth.
See [Canonical formats](/dist/docs/3.2.8/creative/canonical-formats) and [`list_transformers`](/dist/docs/3.2.8/creative/task-reference/list_transformers).
# Tracker execution contracts
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/tracker-execution-contracts
Declare which buyer-supplied pixel, VAST, and DAAST trackers a product accepts and initiates, then preserve that commitment in the package snapshot.
AdCP 3.2 separates two questions that a buyer must answer before assigning a creative:
1. **Will the seller accept and initiate this tracker?** Read the selected product format option's `tracker_execution_contract`.
2. **How will the tracker URL's macros be processed?** Match each occurrence against the exact [`macro_resolution_capabilities`](/dist/docs/3.2.8/creative/universal-macros).
Neither promise implies the other. A seller can resolve `{CACHEBUSTER}` without accepting the containing tracker, and it can accept a tracker whose required macro is unsupported. Buyers must satisfy both contracts before committing spend.
This 3.2 surface covers only first-class `pixel_tracker`, `vast_tracker`, and `daast_tracker` manifest assets. It does not inspect trackers embedded in fetched VAST/DAAST documents, wrappers, JavaScript responses, or generic URL assets. Runtime preview observation is a separate, later capability; the production commitment does not depend on it.
## Product-format authority
The binding commitment is `Product.format_options[].tracker_execution_contract`, alongside `format_kind` and `params`. It is seller execution behavior, not a canonical-format parameter. A product option carrying the contract must have a stable `format_option_id` so the buyer can bind resolution and package assignment to exactly one option.
```json theme={null}
{
"format_option_id": "acme_display_300x250",
"format_kind": "image",
"params": {
"width": 300,
"height": 250,
"slots": [
{ "asset_group_id": "image_main", "asset_type": "image", "required": true },
{ "asset_group_id": "impression_tracker", "asset_type": "pixel_tracker", "required": false },
{ "asset_group_id": "click_tracker", "asset_type": "pixel_tracker", "required": false }
]
},
"tracker_execution_contract": {
"complete": true,
"honored": [
{
"selector_id": "display_impression_pixel",
"asset_type": "pixel_tracker",
"event": "impression",
"method": "img",
"execution_actor": "seller",
"firing_paths": ["client"]
},
{
"selector_id": "display_click_pixel",
"asset_type": "pixel_tracker",
"event": "click",
"method": "img",
"execution_actor": "seller",
"firing_paths": ["client"]
}
]
}
}
```
Publisher and placement declarations may narrow an upstream contract, but the seller-returned product option contains the complete effective contract used for selection and purchase. Creative-agent `supported_formats[]`, transformer inputs, manifests, representations, and deprecated format projections cannot create seller authority; those projections strip the contract and its digest.
Every asset type named in `honored[]` must also have at least one matching first-class slot in the effective selected format declaration. A contract cannot promise a `pixel_tracker`, `vast_tracker`, or `daast_tracker` that the same format rejects structurally. This is why the image example explicitly adds tracker slots instead of relying on the image canonical's default slots.
Publisher, placement, and seller derivation is directional. Expand each selector to atomic tuples of `(normalized non-version selector identity, exact version or null, execution_actor, firing_path)`. When the parent contract is complete, every tuple in the child effective contract must exist in its parent; only then may tuples be compressed back into selector arrays. For example, a complete parent that permits VAST 4.2 on `client` and VAST 4.3 on `server` does not permit a child selector containing both versions and both paths, because that cross-product invents 4.2/server and 4.3/client commitments.
An incomplete or omitted parent is not a closed ceiling. A downstream declaration may add or omit affirmative tuples for its narrower scope, but the effective contract remains incomplete until every applicable layer is complete. An omitted tuple in an incomplete child is undeclared, not an assertion that the tuple is unsupported. A complete parent remains complete after valid subset narrowing, and every child tuple must exist in that parent.
## Exact selectors
Each `honored[]` entry selects one exact tracker/event combination. It is not a cross-product of all declared events, versions, targets, actors, and paths.
| Branch | Required identity | Important restrictions |
| - | - | - |
| `pixel_tracker` | `event`, `method: img` | `event: custom` requires a nonempty `custom_event_name`. JavaScript tracker execution is not supported by the 3.2 contract. |
| `vast_tracker` | `vast_versions[]`, `vast_event`, `target` | `progress` requires `offset`; other events forbid it. The event/target pair must be valid in every listed version. |
| `daast_tracker` | `daast_versions[]`, `daast_event`, `target` | `progress` requires `offset`; other events forbid it. The event/target pair must be valid in every listed version. |
Every branch also requires a stable `selector_id`, one `execution_actor` (`seller` or `request_executor`), and a nonempty `firing_paths[]` set (`client`, `server`, or both). Multiple paths mean that one path may perform the single initiation for a logical event; they do not authorize duplicate client-and-server firing.
Asset defaults are normalized before matching: omitted `pixel_tracker.method` is `img`, omitted VAST/DAAST `target` is `linear`, and a legacy `offset` on a non-`progress` asset is ignored and removed before comparison. Contract selectors themselves must omit `offset` for non-`progress` events. Existing 3.x asset schemas remain permissive about event/target combinations; the strict standards matrix is applied when matching those assets to a contract-bearing product. Two byte-identical URLs in different manifest slots are still two tracker instances. For each logical occurrence of the selected event, the named actor initiates every accepted instance exactly once. This promises construction and handoff of the outbound action—not network delivery, HTTP success, attribution, or reporting credit.
The following VAST/DAAST contract is valid only on an effective option whose `params.slots[]` includes first-class `vast_tracker` and `daast_tracker` slots:
```json theme={null}
[
{
"format_option_id": "acme_video_trackers",
"format_kind": "video_hosted",
"params": {
"slots": [
{ "asset_group_id": "video_main", "asset_type": "video", "required": true },
{ "asset_group_id": "video_start_tracker", "asset_type": "vast_tracker", "required": false }
]
},
"tracker_execution_contract": {
"complete": true,
"honored": [{
"selector_id": "linear_vast_start",
"asset_type": "vast_tracker",
"vast_versions": ["4.2", "4.3"],
"vast_event": "start",
"target": "linear",
"execution_actor": "request_executor",
"firing_paths": ["client", "server"]
}]
}
},
{
"format_option_id": "acme_audio_trackers",
"format_kind": "audio_hosted",
"params": {
"slots": [
{ "asset_group_id": "audio_main", "asset_type": "audio", "required": true },
{ "asset_group_id": "audio_quartile_tracker", "asset_type": "daast_tracker", "required": false }
]
},
"tracker_execution_contract": {
"complete": true,
"honored": [{
"selector_id": "linear_daast_quartile",
"asset_type": "daast_tracker",
"daast_versions": ["1.1"],
"daast_event": "firstQuartile",
"target": "linear",
"execution_actor": "request_executor",
"firing_paths": ["client"]
}]
}
}
]
```
`close` remains accepted in legacy DAAST asset payloads for AdCP 3.x compatibility, but it is not in the DAAST 1.0/1.1 standards event enum and therefore cannot appear in a closed 3.2 execution selector.
`complete: true` makes unlisted combinations explicitly unsupported; `complete: true, honored: []` explicitly accepts no buyer-supplied trackers. An omitted contract or `complete: false` leaves omissions undeclared, never unsupported. Listed entries remain affirmative commitments in either case.
## VAST and DAAST execution versions
A first-class VAST/DAAST selector is matched against one exact execution version, never a guessed member of a plural acceptance set.
* When the manifest includes the exact sibling VAST or DAAST delivery document, its version supplies the execution version.
* When the seller assembles trackers without such a sibling document, `build_creative.representation_destination` must carry `execution_vast_version` or `execution_daast_version`.
* The chosen value must belong to the destination format's accepted version set and the selector's version set.
* `representation_selection` echoes the exact version as lineage through sync and list readback.
The seller reviews the tuple `(selected_representation_id, selected_output_digest, execution_vast_version-or-null, execution_daast_version-or-null)`. Changing an execution version requires re-resolution and ordinary re-review even when the selected manifest bytes are unchanged. Later package assignment must use the same exact version; it cannot silently rebind an approved execution to a different package version.
## Resolution, sync, and package assignment
Seller-bound representation resolution follows this order:
1. Normalize tracker defaults and select one exact VAST/DAAST execution version.
2. Match every first-class manifest tracker against the destination option's effective contract.
3. Match every declared macro occurrence independently against the exact macro-capability tuple.
4. Select only a representation that satisfies both checks.
With a complete contract, an unlisted tracker makes the candidate incompatible. A failed representation receives `tracker_contract_mismatch`, with the representation ID, manifest asset JSON Pointer, normalized selector identity, and destination format-option reference. Macro incompatibility remains the separate `macro_unsupported` rejection; an implementation must not collapse the two causes.
Library-only `sync_creatives` can validate manifest structure and preserve revision/selection lineage, but it does not prove that an arbitrary product accepts the tracker. Package assignment and `create_media_buy` revalidate the selected manifest against the immutable package snapshot before spend. A mismatch rejects assignment; it never silently removes a tracker or weakens the package contract.
## Immutable package snapshots
Every package that selects a contract-bearing format stores a `PackageFormatSnapshot` in `formats_to_provide[]`, even when creative coverage is already complete. `formats_pending[]` may be empty, but the snapshot remains because serving uses the package-time commitment rather than mutable product discovery.
```json theme={null}
{
"product_id": "prod_acme_video",
"format_option_id": "acme_vast_preroll",
"format_kind": "video_vast",
"params": {
"vast_versions": ["4.2", "4.3"]
},
"tracker_execution_contract": {
"complete": true,
"honored": []
},
"execution_vast_version": "4.3",
"placement_refs": [
{
"publisher_domain": "publisher.example",
"placement_id": "preroll"
}
],
"tracker_execution_contract_digest": "sha256:11ba6e00858e9da168d855433c21052b6c2599abbc8b59e3a587e207b10669e0",
"product_snapshot_digest": "sha256:9f3abb83f15c6d16940d4ada694476397a71a9adc3a5dbc602f432bfd194bff2"
}
```
`tracker_execution_contract_digest` is SHA-256 over RFC 8785 canonical JSON of the contract object. `product_snapshot_digest` covers the product ID, complete selected format declaration, sorted effective placement references, exact execution version when applicable, and the tracker-contract digest. Optional fields are omitted rather than encoded as `null`, schema defaults are not materialized, and duplicate JSON members are rejected before canonicalization.
The snapshot and both digests are immutable for the package lifetime. Changing the selected format, placement set, execution version, or tracker contract requires a replacement package with a new `package_id`. A package spanning placements can snapshot only their common effective intersection; differing contracts require separate snapshots with disjoint placement sets or separate packages.
## Buyer checklist
Before assigning a creative, a buyer should verify:
* the product option has a stable ID and matches the creative's `format_option_ref`;
* each first-class tracker matches one honored selector after default normalization;
* the exact VAST/DAAST execution version is accepted at every layer;
* every required macro declaration matches the product and seller macro capabilities;
* a complete contract contains no unlisted tracker instance;
* the package snapshot and digests match the contract used during selection; and
* assignment revalidation succeeds before spend.
Absence is not rejection. If the contract is omitted or incomplete, the missing combinations are undeclared and the buyer must resolve the uncertainty out of band or choose another product.
# Universal Macros
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/creative/universal-macros
Universal macros in AdCP insert dynamic tracking data into creatives with platform-agnostic placeholders replaced at impression time.
Universal macros enable buyers to include dynamic tracking data in their creatives without needing to know each publisher's ad server implementation details. Macros are placeholders that get replaced with actual values at impression time.
Universal semantics and source syntax are separate. `{CACHEBUSTER}`, `[CACHEBUSTING]`, and a vendor token can share a cache-busting meaning while requiring different resolvers and encoding. Never translate from spelling alone.
## Overview
When you provide creative assets to AdCP, you can include universal macro placeholders in:
* Impression tracking URLs
* Click tracking URLs
* VAST tracking events
* Landing page URLs
**Example**:
```
https://track.brand.com/imp?
campaign={MEDIA_BUY_ID}&
creative={CREATIVE_ID}&
device={DEVICE_ID}&
cb={CACHEBUSTER}
```
At impression time, this becomes:
```
https://track.brand.com/imp?
campaign=mb_spring_2025&
creative=cr_video_30s&
device=ABC-123-DEF&
cb=87654321
```
## Declared source-token contracts
Delivery assets may attach `macro_declarations[]`. Each entry describes one occurrence of one exact source token. Company names are not dialect values: `dialect` is the small family enum `adcp | iab_vast | iab_daast | vendor | unknown`; IAB and vendor entries add an authority-controlled `dialect_namespace` and immutable `dialect_revision`.
The namespace identifies the registry, while the revision pins the exact mapping bytes. For the live IAB VAST macro registry, use its canonical published registry URL as the namespace and an immutable source commit or content digest as the revision; a VAST document version is not a macro-registry revision because the registry evolves independently. Compatibility requires exact namespace and revision equality—implementations never treat a moving branch name or “latest” content as the revision.
Translation and value resolution are different operations. `translate_to_native` changes an AdCP token into a declared downstream token without inserting a runtime value. The translated asset replaces the old declaration with the supplied `translation_target`. `resolve_value` inserts a concrete value using the exact encoding profile. `preserve` performs no mutation.
The first contract permits one translation hop followed by value resolution; `translation_target.next_operation` is therefore fixed to `resolve_value`, which prevents cycles and unbounded chains. On the sales execution path, a translation is compatible only when both seller-wide and selected-product sets contain the source translation tuple and an exact target resolution tuple. On `build_creative`, `preview_creative`, and `validate_input`, the selected `creative.supported_formats[]` route is the authoritative capability set and build-time operations use `performed_by: creative_agent`; no seller authority is borrowed. The emitted target declaration keeps the source `declaration_id`, `location`, `required`, and `unavailable_behavior`, and replaces token, dialect identity, operation, actor, and encoding from `translation_target`.
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.1/core/assets/display-tag-asset.json",
"asset_type": "display_tag",
"delivery_type": "tag_url",
"url": "https://ads.acme-example.com/render?cb=[CACHEBUSTING]&click=%%ACME_CLICK_ESC2%%&gdpr={GDPR}&consent={GDPR_CONSENT}&gpp={GPP_STRING}&player=[PLAYERSTATE]&unknown=%%VENDOR_TOKEN%%",
"macro_declarations": [
{
"declaration_id": "cachebuster",
"token": "[CACHEBUSTING]",
"dialect": "iab_vast",
"dialect_namespace": "https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html",
"dialect_revision": "git:e0858cd714474bf17ef61065097456d7643ff838",
"dialect_semantic": "CACHEBUSTING",
"mapping_status": "verified_universal",
"universal_semantic": "CACHEBUSTER",
"operation": "resolve_value",
"performed_by": "request_executor",
"location": { "field": "url", "occurrence": 0, "context": "url_query_value" },
"encoding": { "kind": "iab_vast_uri", "depth": 1 },
"required": true,
"unavailable_behavior": "reject"
},
{
"declaration_id": "nested-click",
"token": "%%ACME_CLICK_ESC2%%",
"dialect": "vendor",
"dialect_namespace": "https://macros.acme-example.com/registry",
"dialect_revision": "mapping-v1",
"dialect_semantic": "CLICK_ESC2",
"mapping_status": "verified_universal",
"universal_semantic": "CLICK_URL",
"operation": "resolve_value",
"performed_by": "seller",
"location": { "field": "url", "occurrence": 0, "context": "url_query_value" },
"encoding": { "kind": "rfc3986", "depth": 2 },
"required": true,
"unavailable_behavior": "reject"
},
{
"declaration_id": "gdpr-applies",
"token": "{GDPR}",
"dialect": "adcp",
"dialect_semantic": "GDPR",
"mapping_status": "verified_universal",
"universal_semantic": "GDPR",
"operation": "resolve_value",
"performed_by": "seller",
"location": { "field": "url", "occurrence": 0, "context": "url_query_value" },
"encoding": { "kind": "none", "depth": 0 },
"required": true,
"unavailable_behavior": "reject"
},
{
"declaration_id": "tcf-consent",
"token": "{GDPR_CONSENT}",
"dialect": "adcp",
"dialect_semantic": "GDPR_CONSENT",
"mapping_status": "verified_universal",
"universal_semantic": "GDPR_CONSENT",
"operation": "resolve_value",
"performed_by": "seller",
"location": { "field": "url", "occurrence": 0, "context": "url_query_value" },
"encoding": { "kind": "rfc3986", "depth": 1 },
"required": false,
"unavailable_behavior": "omit_parameter"
},
{
"declaration_id": "gpp-string",
"token": "{GPP_STRING}",
"dialect": "adcp",
"dialect_semantic": "GPP_STRING",
"mapping_status": "verified_universal",
"universal_semantic": "GPP_STRING",
"operation": "resolve_value",
"performed_by": "seller",
"location": { "field": "url", "occurrence": 0, "context": "url_query_value" },
"encoding": { "kind": "rfc3986", "depth": 1 },
"required": false,
"unavailable_behavior": "omit_parameter"
},
{
"declaration_id": "player-state",
"token": "[PLAYERSTATE]",
"dialect": "iab_vast",
"dialect_namespace": "https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html",
"dialect_revision": "git:e0858cd714474bf17ef61065097456d7643ff838",
"dialect_semantic": "PLAYERSTATE",
"mapping_status": "dialect_defined",
"operation": "resolve_value",
"performed_by": "request_executor",
"location": { "field": "url", "occurrence": 0, "context": "url_query_value" },
"encoding": { "kind": "iab_vast_uri", "depth": 1 },
"required": false,
"unavailable_behavior": "dialect_sentinel"
},
{
"declaration_id": "unidentified-token",
"token": "%%VENDOR_TOKEN%%",
"dialect": "unknown",
"dialect_semantic": "unresolved",
"mapping_status": "unresolved",
"operation": "preserve",
"location": { "field": "url", "occurrence": 0, "context": "opaque" },
"encoding": { "kind": "none", "depth": 0 },
"required": false,
"unavailable_behavior": "preserve"
}
]
}
```
The click redirect's depth of two is part of the contract, not an implementation hint. `rfc3986` encodes UTF-8 bytes outside the RFC 3986 unreserved set once per depth. `iab_vast_uri` follows the cited VAST registry's one-pass rules, including array serialization and unavailable-value sentinels. A resolver never invents consent strings, device identifiers, vendor IDs, impression IDs, or fallback values.
`dialect_semantic` is the cited namespace's exact meaning. `universal_semantic` appears only for a verified mapping into AdCP's closed universal vocabulary. A dialect-defined token such as `[PLAYERSTATE]` remains specific without being mislabeled as a generic vendor semantic. Unknown tokens are schema-constrained to optional, zero-encoding preservation.
Every `declaration_id` is unique within its asset. Each declared token must exist at the named zero-based occurrence, and every claimed occurrence must have exactly one declaration. This occurrence-level rule prevents one encoding contract from being applied indiscriminately to the same spelling in a URL, path, or opaque markup context.
## Capability matching and validation
Sellers publish a seller-wide ceiling in `execution.creative_specs.macro_resolution_capabilities`. The selected product format option publishes the binding set in its top-level `macro_resolution_capabilities` field, alongside `format_kind` and `params`. Each entry is one exact semantic/operation/actor contract; it does not create a cross-product from a semantic list and maximum depth. Capability metadata is deliberately outside canonical `params`: it describes who can process a selected format option, not the creative shape itself.
Standalone creative agents use a separate route rule: the selected `creative.supported_formats[]` entry's `format.macro_resolution_capabilities` is authoritative for build, preview, and validation, and its build-time entries name `performed_by: creative_agent`. The sales seller∩product intersection is evaluated later if the resulting manifest enters a seller execution path.
```json theme={null}
{
"format_kind": "video_vast",
"macro_resolution_capabilities": [
{
"dialect": "adcp",
"dialect_semantic": "GDPR_CONSENT",
"mapping_status": "verified_universal",
"universal_semantic": "GDPR_CONSENT",
"operation": "resolve_value",
"performed_by": "seller",
"supported_contexts": ["url_query_value"],
"supported_encodings": [{ "kind": "rfc3986", "depth": 1 }]
},
{
"dialect": "iab_vast",
"dialect_namespace": "https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html",
"dialect_revision": "git:e0858cd714474bf17ef61065097456d7643ff838",
"dialect_semantic": "PLAYERSTATE",
"mapping_status": "dialect_defined",
"operation": "resolve_value",
"performed_by": "request_executor",
"supported_contexts": ["url_query_value"],
"supported_encodings": [{ "kind": "iab_vast_uri", "depth": 1 }]
}
],
"params": {
"vast_versions": ["3.0", "4.0"]
}
}
```
Compatibility matches dialect family, namespace, revision, exact dialect semantic, verified universal mapping when present, operation, actor, occurrence context, and exact encoding. Local capabilities are required only when the local path performs the operation. A token owned by an advertised downstream request executor is classified `resolvable`; its source bytes remain unchanged until that actor runs. `preserved_for_downstream` is reserved for an intentional `preserve` operation with no exact resolver claim.
`request_executor` is functional rather than organizational: it is the component actually issuing the governed VAST/DAAST or tracking request, whether that is a client player, publisher player, SSAI service, or another execution component.
`validate_input` and `sync_creatives` return one path-addressable `macro_resolution_results[]` entry per declaration:
* `resolvable` — the selected path advertises the exact operation; no serve-time result is implied;
* `preserved_for_downstream` — the declaration intentionally requests byte-preserved handoff and makes no exact resolver claim;
* `unsupported` — no compatible resolver/capability exists; or
* `ambiguous` — the declaration does not establish one safe meaning.
A required `unsupported` or `ambiguous` token fails with `MACRO_RESOLUTION_FAILED`. Its `error.details` MUST conform to [`error-details/macro-resolution-failed.json`](https://adcontextprotocol.org/schemas/3.2.1/error-details/macro-resolution-failed.json). Results include the asset pointer, declaration ID, requested encoding, structured reason, and advertised encoding candidates.
## Relationship to existing macro surfaces
The occurrence contract extends the existing lifecycle; it does not replace it:
1. `format.supported_macros` is the legacy named-format projection of accepted AdCP universal semantics. It does not prove native-dialect execution, ownership, or encoding.
2. `build_creative.macro_values` and preview macro values supply concrete raw values. With declarations, a value binds only a verified-universal `resolve_value` occurrence performed_by `creative_agent` and advertised by the selected creative route, after representation selection, using its exact encoding. It never bypasses `translate_to_native` or the target capability chain. Without declarations, the legacy behavior remains unchanged for 3.x compatibility.
3. `translateUniversalMacros` has a raw `native` arm and a one-pass encoded `value` arm. With declarations, a native mapping performs `translate_to_native`, emits the exact target token unchanged, and replaces the source declaration with its `translation_target`; a concrete mapping follows the declaration's encoding. Existing unmapped/frozen-consent diagnostics remain mandatory.
4. Dropping an unmapped query parameter is behavior of that explicitly invoked legacy helper. It is not the ingest or transport default. Assets without declarations retain opaque-token transport and are not proven compatible.
5. Webhook `supported_macros` describes runtime webhook arguments, while preview/build `macros` are sample values. Neither is a creative-token resolution capability.
6. The product [tracker execution contract](/dist/docs/3.2.8/creative/tracker-execution-contracts) remains responsible for whether a seller accepts and initiates each exact buyer tracker/event combination. Its macro checks reuse these exact capability entries; it does not redefine dialect, ownership, or encoding. Passing one check never implies passing the other.
Catalog-item universal semantics retain their existing stricter rule: UTF-8/NFC values receive exactly one RFC 3986 unreserved-set encoding pass. A declaration cannot weaken or add nesting to that governed catalog substitution profile; nested redirect encoding applies only to a separately cited click-redirect mapping.
## Available Macros by Format
Different creative contracts support different macros. Read macro support from the selected product, publisher, or creative-capability canonical declaration.
### Common Macros (All Formats)
| Macro | Description | Example Value |
| - | - | - |
| `{MEDIA_BUY_ID}` | Your AdCP media buy identifier | `mb_spring_2025` |
| `{PACKAGE_ID}` | Your AdCP package identifier | `pkg_ctv_prime` |
| `{CREATIVE_ID}` | Your AdCP creative identifier | `cr_video_30s` |
| `{CACHEBUSTER}` | Random number to prevent caching | `87654321` |
| `{TIMESTAMP}` | Unix timestamp in milliseconds | `1704067200000` |
| `{CLICK_URL}` | Publisher's click tracking URL | *(auto-inserted by sales agent)* |
### Privacy & Compliance Macros
**Critical for regulatory compliance** - Use these to respect user privacy choices in your creative logic.
| Macro | Description | Example Value |
| - | - | - |
| `{GDPR}` | GDPR applicability flag | `1` (applies), `0` (doesn't apply) |
| `{GDPR_CONSENT}` | IAB TCF 2.0 consent string | `CPc7TgPPc7TgPAGABC...` |
| `{US_PRIVACY}` | US Privacy (CCPA) string | `1YNN` |
| `{GPP_STRING}` | Global Privacy Platform consent string | `DBABMA~CPXxRfAPXxRfAAfKABENB-CgAAAAAAAAAAYgAAAAAAAA` |
| `{GPP_SID}` | GPP Section ID(s) indicating applicable sections | `7`, `7,8` (US National, US National + California) |
| `{IP_ADDRESS}` | User IP address (often masked for privacy) | `203.0.113.42`, `""` (when restricted) |
| `{LIMIT_AD_TRACKING}` | Limit Ad Tracking enabled | `1` (limited), `0` (allowed) |
> **Privacy Warning**: `{IP_ADDRESS}` is considered personal data under GDPR and many privacy regulations. This macro may return an empty string or masked/truncated IP depending on user privacy settings, publisher policies, and regional regulations. Use geo macros (`{COUNTRY}`, `{REGION}`, `{CITY}`) instead when possible.
**Example - Privacy-aware tracking**:
```javascript theme={null}
// In creative logic
if (GDPR == 1 && GDPR_CONSENT == '') {
// No consent - don't load tracking pixels
} else {
// Load tracking
}
```
### Device & Environment Macros
| Macro | Description | Example Value |
| - | - | - |
| `{DEVICE_TYPE}` | Device category | `mobile`, `tablet`, `desktop`, `ctv`, `dooh` |
| `{OS}` | Operating system | `iOS`, `Android`, `tvOS`, `Roku` |
| `{OS_VERSION}` | OS version | `17.2`, `14.0` |
| `{DEVICE_MAKE}` | Device manufacturer | `Apple`, `Samsung`, `Roku` |
| `{DEVICE_MODEL}` | Device model | `iPhone15,2`, `Roku Ultra` |
| `{USER_AGENT}` | Full user agent string | `Mozilla/5.0 ...` |
| `{APP_BUNDLE}` | App bundle ID (domain or numeric) | `com.publisher.app`, `123456789` |
| `{APP_NAME}` | Human-readable app name | `Publisher News App` |
### Geographic Macros
| Macro | Description | Example Value |
| - | - | - |
| `{COUNTRY}` | ISO 3166-1 alpha-2 country code | `US`, `GB`, `CA`, `FR`, `JP`, `AU` |
| `{REGION}` | State/province/region code | `NY`, `CA` (US states), `ON` (Canada), `IDF` (France), `NSW` (Australia) |
| `{CITY}` | City name | `New York`, `London`, `Tokyo`, `Sydney` |
| `{ZIP}` | Postal code | `10001` (US), `SW1A 1AA` (UK), `75001` (France), `100-0001` (Japan) |
| `{DMA}` | [Nielsen DMA code](https://help.thetradedesk.com/s/article/Nielsen-DMA-Regions) (US TV markets) | `501` (New York), `803` (Los Angeles) |
| `{LAT}` | Latitude | `40.7128`, `51.5074`, `35.6762` |
| `{LONG}` | Longitude | `-74.0060`, `-0.1278`, `139.6503` |
### Identity Macros
| Macro | Description | Example Value |
| - | - | - |
| `{DEVICE_ID}` | Mobile advertising ID (IDFA/AAID) | `ABC-123-DEF-456` |
| `{DEVICE_ID_TYPE}` | Type of device ID | `idfa`, `aaid` |
### Web Context Macros
For web-based inventory:
| Macro | Description | Example Value |
| - | - | - |
| `{DOMAIN}` | Domain where ad is shown | `nytimes.com` |
| `{PAGE_URL}` | Full page URL (encoded) | `https%3A%2F%2F...` |
| `{REFERRER}` | HTTP referrer URL | `https://google.com` |
| `{KEYWORDS}` | Page keywords (comma-separated) | `business,finance,tech` |
### Placement & Position Macros
| Macro | Description | Example Value |
| - | - | - |
| `{PLACEMENT_ID}` | Global Placement ID (IAB standard) | `12345678` |
| `{FOLD_POSITION}` | Position relative to fold (display) | `above_fold`, `below_fold` |
| `{AD_WIDTH}` | Ad slot width | `300`, `728` |
| `{AD_HEIGHT}` | Ad slot height | `250`, `90` |
### Video Content Macros
For video formats with content context:
| Macro | Description | Example Value |
| - | - | - |
| `{VIDEO_ID}` | Content video identifier | `vid_12345` |
| `{VIDEO_TITLE}` | Content video title | `Breaking News Story` |
| `{VIDEO_DURATION}` | Content duration in seconds | `600` |
| `{VIDEO_CATEGORY}` | IAB content category | `IAB1` (Arts & Entertainment) |
| `{CONTENT_GENRE}` | Content genre | `news`, `sports`, `comedy` |
| `{CONTENT_RATING}` | Content rating | `G`, `PG`, `TV-14` |
| `{PLAYER_WIDTH}` | Video player width | `1920` |
| `{PLAYER_HEIGHT}` | Video player height | `1080` |
### Video Ad Pod Macros
For video ads in commercial breaks:
| Macro | Description | Example Value |
| - | - | - |
| `{POD_POSITION}` | Position within ad break | `1`, `2`, `3` |
| `{POD_SIZE}` | Total ads in this break | `3` |
| `{AD_BREAK_ID}` | Unique ad break identifier | `break_mid_1` |
**Note**: Video formats also support all [IAB VAST 4.x macros](http://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html) like `[CACHEBUSTING]`, `[TIMESTAMP]`, `[DOMAIN]`, `[IFA]`, etc. These work natively in VAST XML.
### Audio Content Macros
For audio formats with content context:
| Macro | Description | Example Value |
| - | - | - |
| `{STATION_ID}` | Radio station or podcast identifier | `WXYZ-FM`, `pod_12345` |
| `{COLLECTION_NAME}` | Program or collection name | `Morning Drive`, `Tech Talk Daily` |
| `{INSTALLMENT_ID}` | Podcast episode identifier | `ep_2025_01_15` |
| `{AUDIO_DURATION}` | Content duration in seconds | `3600` |
### Impression Identification
| Macro | Description | Example Value |
| - | - | - |
| `{IMPRESSION_ID}` | Upstream-minted unique identifier per impression (publisher or ad-decision layer) | `8c9e2f3a-7b1c-4d5e-9f6a-1a2b3c4d5e6f` (UUID), `01ARZ3NDEKTSV4RRFFQ69G5FAV` (ULID), or equivalent |
The `{IMPRESSION_ID}` macro carries a unique identifier for one impression opportunity. It is a general-purpose impression key — buyers, measurement vendors, attribution providers, and verification services all use this kind of identifier to deduplicate impression events, reconcile pixel firings across vendors, join impressions to clicks, and detect retries. Whichever upstream layer mints the value (see hierarchy below) substitutes it into creative tracking URLs, and any downstream consumer that needs to identify the impression uses the same value.
**Common use cases:**
* **Per-impression deduplication.** A single impression often fires many pixels (impression, viewability, video quartiles, completion, third-party verification). All of them sharing one `{IMPRESSION_ID}` lets downstream consumers reconcile "is this the same impression?" without time- or URL-based heuristics.
* **TMP cross-identity dedup.** When a TMP impression resolves to multiple user identities, the buyer's impression tracker writes the same `{IMPRESSION_ID}` to every identity's log so distinct-impression counts dedup correctly. See [Impression Tracker Implementation](/dist/docs/3.2.8/trusted-match/impression-tracker-implementation).
* **Cross-vendor reconciliation.** Advertisers comparing delivery between an ad server, a verification vendor, and a measurement vendor join on `{IMPRESSION_ID}` rather than building cross-walks.
* **Pixel retry dedup.** A pixel firing twice (network retry, page refresh) carries the same `{IMPRESSION_ID}`, so a server-side dedup pass on the id catches retries without over-counting.
**When to include it:**
* **Recommended on every impression tracking URL** — the macro is small, cheap, and the use cases above all benefit when it is consistently present.
* **Required for TMP context-only impressions** — when Identity Match returned no eligibility (or wasn't called) and no `{TMPX}` is present on the pixel, `{IMPRESSION_ID}` is the only available cross-identity dedup key for the buyer's impression tracker.
**Format is implementation choice.** The protocol requires uniqueness with sufficient entropy to avoid cross-seller / cross-time collisions; it does not pin a wire format. UUID (any version), ULID, snowflake-style IDs, or any other collision-resistant identifier scheme are all acceptable. Buyers MUST treat the value as an opaque string for dedup purposes — no parsing, no format assumptions.
**Three valid sources for the value, in priority order:**
1. **Publisher-side mint** (highest priority): the publisher's own first-party code mints a fresh identifier per impression opportunity — e.g., server-side, before the ad request reaches the decision layer — and passes it forward so the decision layer can substitute it via `{IMPRESSION_ID}`. Works for both context-only and identity-bearing impressions.
2. **Decision-layer mint** (used when the publisher hasn't minted): the ad-decision layer (Prebid TMP module, ad server, SSP, or equivalent client) mints the identifier at the context↔identity join and substitutes it via `{IMPRESSION_ID}`. Also works for both context-only and identity-bearing impressions.
3. **Buyer-side mint at TMPX decode** (fallback, identity-bearing only): when neither layer above minted, the buyer's impression tracker mints the id locally at TMPX decode time per [`Impression Tracker Implementation`](/dist/docs/3.2.8/trusted-match/impression-tracker-implementation). This works only when `{TMPX}` is present — it cannot cover context-only impressions.
Each layer MUST defer to whatever value an upstream layer already produced — minting a fresh id at a lower layer when a higher layer already supplied one would split logs for the same impression across two ids. In practice this means: if the publisher minted, the decision layer passes it through; if either of those minted, the buyer uses the value from the pixel rather than minting at decode.
**Relationship to `{CACHEBUSTER}`.** The two are not interchangeable. `{CACHEBUSTER}` is a low-entropy anti-cache value sufficient to defeat HTTP intermediaries; it is not a globally-unique impression key. Both can appear in the same tracking URL serving different purposes.
### TMP Exposure Tracking
| Macro | Description | Example Value |
| - | - | - |
| `{TMPX}` | TMP exposure token (HPKE-encrypted) | `k1.dG1weC1leGFtcGxl...` |
The `{TMPX}` macro carries an encrypted exposure token from the [Identity Match](/dist/docs/3.2.8/trusted-match/specification) response. It contains the user's resolved identity tokens encrypted via HPKE, enabling the buyer's impression pixel to log per-user exposures for real-time frequency capping. Publishers substitute `{TMPX}` into tracking URLs exactly like other macros. The token is opaque — publishers MUST NOT parse, log, or make decisions based on its value.
See [TMPX Exposure Tokens](/dist/docs/3.2.8/trusted-match/specification#tmpx-exposure-tokens) for the encryption format and key management.
### AXE Integration (Legacy)
| Macro | Description | Example Value |
| - | - | - |
| `{AXEM}` | AXE contextual metadata (encoded blob) | `eyJjb250ZXh0IjoiLi4uIn0=` |
The `{AXEM}` macro is from the legacy AXE integration. In [TMP](/dist/docs/3.2.8/trusted-match), this is replaced by:
* **Structured creative assets** move to the `creative_manifest` field on the [Offer](/dist/docs/3.2.8/trusted-match/specification#offer).
* **Loose dynamic rendering values** use the Offer's `creative_data` map under the package's publisher/creative contract; they are not ad-server macro substitutions.
* **Per-user exposure tracking** uses the [`{TMPX}`](#tmp-exposure-tracking) macro from Identity Match.
### Catalog Item Macros
For catalog-driven creatives (carousels, dynamic product ads, job boards, store locators). These macros resolve to the identifier of the specific catalog item being rendered at serve time — the same identifiers used in conversion event `content_ids` via the [`content_id_type`](/dist/docs/3.2.8/creative/catalogs#conversion-events) field.
| Macro | Description | Example Value |
| - | - | - |
| `{CATALOG_ID}` | Buyer-defined catalog identifier | `gmc-primary`, `job-feed` |
| `{SKU}` | Product SKU identifier | `SKU-12345` |
| `{GTIN}` | Global Trade Item Number | `00013000006040` |
| `{OFFERING_ID}` | AdCP offering identifier | `summer-sale` |
| `{JOB_ID}` | Job posting identifier | `vacancy-amsterdam-chef-42` |
| `{HOTEL_ID}` | Hotel property identifier | `grand-amsterdam` |
| `{FLIGHT_ID}` | Flight route identifier | `AMS-BCN-2025-06` |
| `{VEHICLE_ID}` | Vehicle listing identifier | `VIN-1234` |
| `{LISTING_ID}` | Real estate listing identifier | `prop-amsterdam-01` |
| `{STORE_ID}` | Store location identifier | `amsterdam-flagship` |
| `{PROGRAM_ID}` | Education program identifier | `mba-2025` |
| `{DESTINATION_ID}` | Travel destination identifier | `barcelona` |
Use the macro that matches your catalog's `content_id_type`. For example, a product catalog with `content_id_type: "gtin"` uses `{GTIN}` in tracker URLs; a job catalog uses `{JOB_ID}`.
#### Catalog content macros
The macros above resolve to the catalog item's **identifier**. Catalog **content** macros resolve to a catalog item's scalar **field values**, for catalog-driven creative templates (`sponsored_placement` / DPA — Meta DPA, Snap Collection, TikTok Shopping). They are the substitute-the-value analog of the ID macros above: same single-brace family, same substitution-safety rules below, just more tokens.
| Macro | Description | `catalog_field` | Example Value |
| - | - | - | - |
| `{ITEM_NAME}` | Item name/title | `name` | `Summer Sale` |
| `{ITEM_DESCRIPTION}` | Item description | `description` | `Up to 50% off summer collection` |
| `{ITEM_TAGLINE}` | Promotional tagline | `tagline` | `Start measuring today` |
| `{ITEM_PRICE}` | Price amount | `price.amount` | `29.99` |
| `{ITEM_PRICE_CURRENCY}` | ISO 4217 currency code | `price.currency` | `USD` |
Each token maps 1:1 to a documented catalog item field via the existing `catalog_field` dot-notation vocabulary used by [`field_bindings`](/dist/docs/3.2.8/creative/catalogs#field-bindings) — content macros do **not** introduce a parallel field vocabulary. The five tokens are deliberately small and cross-vertical; vertical-specific deep fields (e.g. `star_rating`, `salary.min`) are served by `field_bindings` scalars, not universal content macros. URL-valued and image-valued fields (e.g. `landing_url`, image pools) bind via `field_bindings` to `url`/asset slots and are **not** content macros — substituting a whole URL as an entire `href` would also break the `encodeURIComponent`-equivalent percent-encoding contract below.
**Single-brace `{MACRO}` only.** `{{double-brace}}` is **not** an AdCP content-macro syntax and MUST NOT be used. Double-brace is reserved as one of the downstream ad-server macro syntaxes (`%%...%%`, `${...}`, `[...]`, `{{...}}`) that the sales agent MUST neutralize/percent-encode (see the nested-expansion rule below); adopting it for AdCP content macros would relax that guarantee and collide with downstream ad servers that interpret `{{...}}` natively.
Which catalog items render is **seller-declared** via the `fanout_mode` enum on the [`sponsored_placement`](/dist/docs/3.2.8/creative/canonical-formats) format (`single_item` / `per_item` / `multi_item_in_creative`) — there is no buyer-side selection field. On ML-optimized DPA surfaces (Meta Advantage+, TikTok Shopping) the platform commonly overrides buyer-authored overlay text, so content macros are a buyer-declared **hint** the seller MAY honor, not a guaranteed substitution.
#### Substitution safety (catalog-item macros)
Catalog-item macros are the one macro class where the value originates in **buyer-controlled data** (the catalog feed) and expands at impression time into **publisher-controlled contexts** (impression tracker URLs, click tracker URLs, VAST tracking-event URLs, AND landing / clickthrough URLs — the full set of [URL substitution targets](#overview) above). That flow is attacker-adjacent: a catalog value containing `&`, `#`, `?`, CR/LF, a stray URL fragment, or a Unicode bidi override can break out of the URL context, inject a Host-header via CRLF, or spoof audit-log rendering if substituted raw.
The following rules apply to all catalog-item macros listed above — both the ID macros (`{CATALOG_ID}`, `{SKU}`, `{GTIN}`, `{OFFERING_ID}`, `{JOB_ID}`, `{HOTEL_ID}`, `{FLIGHT_ID}`, `{VEHICLE_ID}`, `{LISTING_ID}`, `{STORE_ID}`, `{PROGRAM_ID}`, `{DESTINATION_ID}`) and the content macros (`{ITEM_NAME}`, `{ITEM_DESCRIPTION}`, `{ITEM_TAGLINE}`, `{ITEM_PRICE}`, `{ITEM_PRICE_CURRENCY}`):
* **Normalize to Unicode NFC before encoding.** Prior to percent-encoding, catalog-item values that are not already in Unicode Normalization Form C (NFC) MUST be normalized to NFC per Unicode Standard Annex #15. Sellers and buyers MAY send catalog values in any normalization form at `sync_catalogs` ingest (the catalog is stored as-supplied); the normalization to NFC is a step in the substitution pipeline immediately before percent-encoding, not a catalog-ingest requirement. Without this step, two implementations that both satisfy the unreserved-whitelist rule below produce different bytes for the same visual string — `café` (NFC: U+00E9) and `cafe\u0301` (NFD: U+0065 + combining U+0301) encode to `caf%C3%A9` vs `e%CC%81` respectively. NFC matches web-platform convention (WHATWG URL, HTML5 DOM, W3C Character Model). NFKC / NFKD are **not** acceptable substitutes — their compatibility folding silently mutates fullwidth/halfwidth variants and other visually-distinct glyphs that legitimately appear in Japanese/Korean retailer catalogs.
* **Percent-encode every octet that is not in the RFC 3986 `unreserved` set.** Sales agents MUST percent-encode the NFC-normalized catalog-item value such that only RFC 3986 `unreserved` characters (`ALPHA / DIGIT / "-" / "." / "_" / "~"`) remain unescaped before substituting it into a URL context (query string, path segment, or fragment). Non-ASCII octets MUST be percent-encoded after UTF-8 encoding per RFC 3986 §2.5. This is the `encodeURIComponent`-equivalent contract: reserved characters (`: / ? # [ ] @ ! $ & ' ( ) * + , ; =`) are escaped as one would expect, but so are CR (`%0D`), LF (`%0A`), space (`%20`), C0/C1 control characters, and Unicode bidi overrides — the broader enumeration closes CRLF-injection and bidi-spoofing vectors that a reserved-only rule would leave open. Encoding is applied exactly once at substitution time; downstream VAST players and ad servers firing the URL verbatim is the expected contract — they do not and MUST NOT re-decode before firing.
* **Nested macro expansion is prohibited.** A catalog-item value that itself contains text matching AdCP's `{MACRO_NAME}` syntax MUST NOT be re-expanded. Sales agents perform AdCP macro substitution in one pass: source placeholders are replaced with literal values, and those literal values are not re-scanned. A `{JOB_ID}` value of `vacancy-{DEVICE_ID}-42` produces the literal string `vacancy-%7BDEVICE_ID%7D-42` (after percent-encoding of the braces) in the emitted URL, not a second-round expansion. This rule binds AdCP's `{...}` syntax only; catalog-item values containing downstream ad-server macro syntaxes (`%%...%%`, `${...}`, `[...]`, `{{...}}`) remain the sales agent's responsibility to neutralize when targeting an ad server that would interpret them — percent-encoding per the rule above typically suffices, since `%`, `$`, `[`, `]`, and `{` all land outside the `unreserved` set.
* **Scope is URL contexts only.** These rules apply when a catalog-item macro is substituted into a URL context. When a catalog-item macro is substituted into an HTML-attribute context (for example, a banner template's `href` or `data-*` attribute rendered server-side), percent-encoding per this section does not by itself prevent attribute-context breakout; the renderer MUST additionally apply HTML-attribute escaping — the two encodings are layered, not alternatives, because the value must survive both the URL parser and the HTML attribute parser. AdCP's normative contract bounds to the URL-context case; publisher-side HTML-attribute handling is out of scope for this spec.
Non-catalog macros (`{MEDIA_BUY_ID}`, `{PACKAGE_ID}`, `{CREATIVE_ID}`, `{COUNTRY}`, `{DEVICE_TYPE}`, etc.) are populated from publisher- or ad-server-mediated state, not from buyer-supplied feed data. Their encoding contract is governed by the ad-server integration (OpenRTB, VAST), which percent-encodes by convention. Some macros in this class derive from attacker-spoofable inputs (`{USER_AGENT}`, `{REFERRER}`, `{PAGE_URL}`, `{DOMAIN}`, `{APP_BUNDLE}` come from request headers or page metadata); the OpenRTB / ad-server encoding convention is the control today. This spec's normative MUST deliberately scopes to the buyer-controlled catalog-item class — a narrower, verifiable contract than a universal canonicalization rule.
**Conformance fixture.** Reference test vectors pinning the encoding behavior — reserved-character breakout, nested-expansion literal preservation, CRLF injection, non-ASCII — are versioned at [`static/compliance/source/test-vectors/catalog-macro-substitution.json`](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/catalog-macro-substitution.json). Sales agents SHOULD validate their substitution code against these vectors before shipping.
### Creative Variant Macros
| Macro | Description | Example Value |
| - | - | - |
| `{CREATIVE_VARIANT_ID}` | Seller-assigned creative variant identifier | `variant_a`, `v2_mobile` |
> **Note**: Publisher-specific custom macros may be defined in individual creative format specifications as `extra supported macros`.
## Usage Examples
### Video Creative with Tracking
```json theme={null}
{
"creative_id": "cr_video_30s",
"format_kind": "video_vast",
"assets": {
"vast_xml": {
"asset_type": "vast",
"delivery_type": "inline",
"content": "\n\n \n \n \n \n \n \n 00:00:30 \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n ",
"vast_version": "4.2"
}
}
}
```
**Key Points**:
* Mix AdCP macros (`{MEDIA_BUY_ID}`) with VAST macros (`[CACHEBUSTING]`)
* AdCP macros use `{CURLY_BRACES}`
* VAST macros use `[SQUARE_BRACKETS]`
* Declare dialect, owner, and encoding when compatibility must be proven before trafficking
### Display Creative with Tracking
```json theme={null}
{
"creative_id": "cr_banner_300x250",
"format_kind": "image",
"assets": {
"banner_image": {
"url": "https://cdn.brand.com/banners/spring_300x250.jpg",
"width": 300,
"height": 250
},
"impression_pixel": {
"url": "https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cre={CREATIVE_ID}&device={DEVICE_ID}&domain={DOMAIN}&cb={CACHEBUSTER}"
},
"landing_url": {
"url": "https://brand.com/spring?campaign={MEDIA_BUY_ID}"
}
}
}
```
### Audio Creative with Tracking
```json theme={null}
{
"creative_id": "cr_audio_30s",
"format_kind": "audio_hosted",
"assets": {
"audio_file": {
"url": "https://cdn.brand.com/audio/spring_30s.mp3",
"duration_ms": 30000
},
"impression_tracker": {
"url": "https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&station={STATION_ID}&show={COLLECTION_NAME}&cb={CACHEBUSTER}"
}
}
}
```
### Catalog-Driven Creative with Item Tracking
```json theme={null}
{
"creative_id": "cr_product_carousel",
"format_kind": "image_carousel",
"catalogs": [{
"catalog_id": "gmc-primary",
"type": "product",
"content_id_type": "gtin",
"tags": ["summer"]
}],
"assets": {
"impression_pixel": {
"url": "https://track.brand.com/imp?buy={MEDIA_BUY_ID}&catalog={CATALOG_ID}&item={GTIN}&cb={CACHEBUSTER}",
"url_type": "tracker_pixel"
},
"click_tracker": {
"url": "https://track.brand.com/click?buy={MEDIA_BUY_ID}&catalog={CATALOG_ID}&item={GTIN}",
"url_type": "tracker_pixel"
}
}
}
```
**Key point**: `{GTIN}` resolves to the specific product's GTIN at serve time. For a carousel showing 5 products, each product impression/click fires with that product's identifier — enabling per-item attribution.
## Macro Availability by Inventory Type
Not all macros are available in all inventory types. Check format specifications to see which macros are supported.
This matrix is informative implementation guidance, not a capability claim. The selected product format option's exact `macro_resolution_capabilities` entry is authoritative for dialect identity, operation, actor, context, and encoding; legacy named formats may expose only the coarser `supported_macros` projection.
**Important**: The columns below represent format types (Display, Video, etc.) which can run in different environments (app vs web). For example:
* Display ads in mobile apps have `DEVICE_ID` (✅\*), but display ads on web do not
* The ✅\* notation means "available in-app contexts only"
* Format type + inventory environment determine actual macro availability
| Macro Category | Display | Video | Audio | Native | CTV/OTT | DOOH | Mobile App | Mobile Web | Desktop Web |
| - | - | - | - | - | - | - | - | - | - |
| **Common** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{MEDIA_BUY_ID}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{PACKAGE_ID}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{CREATIVE_ID}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{CACHEBUSTER}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{TIMESTAMP}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Privacy** | | | | | | | | | |
| `{GDPR}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{GDPR_CONSENT}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{US_PRIVACY}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{GPP_STRING}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{GPP_SID}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{IP_ADDRESS}` | ✅‡ | ✅‡ | ✅‡ | ✅‡ | ✅‡ | ❌ | ✅‡ | ✅‡ | ✅‡ |
| `{LIMIT_AD_TRACKING}` | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ❌ | ✅ | ❌ | ❌ |
| **Identity** | | | | | | | | | |
| `{DEVICE_ID}` | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ❌ | ✅ | ❌ | ❌ |
| `{DEVICE_ID_TYPE}` | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ❌ | ✅ | ❌ | ❌ |
| **Geographic** | | | | | | | | | |
| `{COUNTRY}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{REGION}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{CITY}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{ZIP}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{DMA}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{LAT}/{LONG}` | ✅† | ❌ | ❌ | ✅† | ❌ | ✅ | ✅† | ❌ | ❌ |
| **Device** | | | | | | | | | |
| `{DEVICE_TYPE}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{OS}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{OS_VERSION}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{APP_BUNDLE}` | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ❌ | ✅ | ❌ | ❌ |
| `{USER_AGENT}` | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
| **Web Context** | | | | | | | | | |
| `{DOMAIN}` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
| `{PAGE_URL}` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
| `{REFERRER}` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
| `{KEYWORDS}` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
| **Placement** | | | | | | | | | |
| `{PLACEMENT_ID}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `{FOLD_POSITION}` | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ |
| **Video Content** | | | | | | | | | |
| `{VIDEO_ID}` | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `{VIDEO_CATEGORY}` | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `{CONTENT_GENRE}` | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Video Ad Pods** | | | | | | | | | |
| `{POD_POSITION}` | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `{POD_SIZE}` | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `{AD_BREAK_ID}` | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Audio Content** | | | | | | | | | |
| `{STATION_ID}` | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `{COLLECTION_NAME}` | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **TMP Exposure** | | | | | | | | | |
| `{TMPX}` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅§ | ✅ | ✅ | ✅ |
**Legend**:
* ✅ = Available
* ❌ = Not available
* ✅\* = In-app only (not mobile web)
* ✅† = When location permission granted
* ✅‡ = Often restricted due to privacy regulations (may return empty or masked value)
* ✅§ = DOOH uses play-log-based reporting rather than pixel URLs
**Important Notes**:
* Privacy macros (`{LIMIT_AD_TRACKING}`, `{DEVICE_ID}`) may return empty values based on user privacy settings
* Geographic macros accuracy varies by publisher's data capabilities
* `{PLACEMENT_ID}` refers to the IAB Global Placement ID standard
## How Macros Work
### 1. Discovery
Inspect the selected canonical declaration to see which macros it supports:
```json theme={null}
{
"format_option_id": "video_30s_vast",
"format_kind": "video_vast",
"macro_resolution_capabilities": [
{
"dialect": "adcp",
"dialect_semantic": "GDPR_CONSENT",
"mapping_status": "verified_universal",
"universal_semantic": "GDPR_CONSENT",
"operation": "resolve_value",
"performed_by": "seller",
"supported_contexts": ["url_query_value"],
"supported_encodings": [{ "kind": "rfc3986", "depth": 1 }]
}
],
"params": {
"vast_versions": ["4.2"]
}
}
```
Legacy named formats may still expose `supported_macros` as an array of universal macro names. That is a compatibility projection, not proof of actor, native dialect, context, or encoding support.
### 2. Include Macros in Creatives
Add macro placeholders in your tracking URLs using `{MACRO_NAME}` syntax:
```
https://track.brand.com/imp?campaign={MEDIA_BUY_ID}&device={DEVICE_ID}
```
### 3. Sales Agent Processing
When you create a media buy via `create_media_buy`, the sales agent:
1. **Replaces AdCP ID macros** with your actual IDs:
* `{MEDIA_BUY_ID}` → `mb_spring_2025`
* `{PACKAGE_ID}` → `pkg_ctv_prime`
* `{CREATIVE_ID}` → `cr_video_30s`
2. **Translates platform macros** to their ad server's syntax:
* `{CACHEBUSTER}` → `%%CACHEBUSTER%%` (GAM) or `{{timestamp}}` (Kevel)
* `{DEVICE_ID}` → `%%ADVERTISING_IDENTIFIER_PLAIN%%` (GAM)
* `{DOMAIN}` → `%%SITE%%` (GAM)
3. **Inserts click trackers** automatically into clickable elements
4. **Leaves VAST macros unchanged** (for video formats)
#### Implementing translation with the SDK
Sales agents don't have to hand-roll the rewrite. The `@adcp/sdk` package ships a
`translateUniversalMacros` helper that applies a per-macro mapping to a tracking
URL's query-parameter values. Each macro maps to either a **native** ad-server token
(left raw, filled by the ad server at impression time) or a concrete **value** the
agent already knows (substituted now, percent-encoded per RFC 3986):
The behavior below is the established undeclared-token compatibility path. With occurrence declarations, a `native` mapping implements `translate_to_native` and emits the target declaration, while a concrete value follows the declaration's exact encoding profile. The helper's safety and privacy diagnostics are unchanged in either mode.
```typescript theme={null}
import { translateUniversalMacros } from '@adcp/sdk';
const mapping = {
// AdCP identifiers the agent knows at media-buy creation → concrete values
'{MEDIA_BUY_ID}': { value: 'mb_spring_2025' },
'{PACKAGE_ID}': { value: 'pkg_ctv_prime' },
// Runtime macros → the ad server's native syntax (Google Ad Manager shown)
'{CACHEBUSTER}': { native: '%%CACHEBUSTER%%' },
'{DEVICE_ID}': { native: '%%ADVERTISING_IDENTIFIER_PLAIN%%' },
};
const {
url,
dropped_params,
unmapped_macros,
dropped_consent_macros,
frozen_consent_macros,
suspect_native_values,
} = translateUniversalMacros(
'https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cb={CACHEBUSTER}&device={DEVICE_ID}',
mapping,
);
// url:
// https://track.brand.com/imp?buy=mb_spring_2025&pkg=pkg_ctv_prime&cb=%%CACHEBUSTER%%&device=%%ADVERTISING_IDENTIFIER_PLAIN%%
// dropped_params: [] (every macro was mapped)
// unmapped_macros: []
// dropped_consent_macros: [] (no consent macro was dropped)
// frozen_consent_macros: [] (no consent macro was supplied as a fixed value)
// suspect_native_values: [] (no value entry contains native-token syntax)
```
Behavior:
* **`native` entries are inserted verbatim** — `%%CACHEBUSTER%%` is not percent-encoded,
so the ad server still recognizes it. A native mapping containing U+0000–U+001F
or U+007F is invalid: the helper raises a typed `unsafe_native_mapping` error and
emits no translated URL.
* **`value` entries are RFC-3986 percent-encoded**, so a value containing reserved
characters can't break or inject into the URL.
* A consent/privacy macro supplied through **`value`** is still encoded, but it is
also surfaced in **`frozen_consent_macros`**. Inspect this advisory field: fixing a
consent string at translation time can produce a stale-consent pixel.
* **A parameter whose universal macro the agent does not support is dropped entirely**
(its key is reported in `dropped_params`, the macro in `unmapped_macros`) — better to
omit a tracker the agent can't fill than to emit a broken one. A dropped
consent/privacy macro (`{GDPR_CONSENT}`, `{US_PRIVACY}`, …) is also surfaced in
**`dropped_consent_macros`** — **inspect it** so a forgotten mapping doesn't silently
ship a consent-degraded pixel.
* **Already-minted parameters pass through untouched** — `pkg_id=123456` (no macro) is
left exactly as-is.
* **`suspect_native_values`** flags any `value` entry containing native-token syntax
(`%%…%%`, `{{…}}`, `${…}`, `[UPPER_SNAKE]`), including syntax surrounded by literal
prefixes or suffixes. The `value` arm would percent-encode that syntax so it could not
expand at impression time; use the `native` arm for the complete value.
* Only query-parameter **values** are translated; a macro in a key position is left
untouched. The path and fragment also pass through byte-for-byte.
* Substitution is single-pass. Macro-shaped text inside a substituted `value` is data,
percent-encoded once, and never re-expanded.
* A URL ending in a bare trailing `?` is normalized by removing the delimiter.
* Diagnostic ordering is deterministic: `dropped_params` follows query occurrence
order (including repeated keys); `unmapped_macros` and `dropped_consent_macros`
follow first occurrence and are deduplicated; `frozen_consent_macros` and
`suspect_native_values` follow mapping property order and are deduplicated.
The language-neutral golden fixture at
[`/compliance/latest/test-vectors/universal-macro-translation.json`](https://adcontextprotocol.org/compliance/latest/test-vectors/universal-macro-translation.json)
pins the output URL, every diagnostic array, typed rejection cases, and ratified
edge-case ordering.
SDK implementations MUST run the applicable versioned fixture rather than maintain an
independent behavioral table.
### 4. Impression Time
The publisher's ad server replaces remaining macros with actual values:
```
https://track.brand.com/imp?
campaign=mb_spring_2025&
device=ABC-123-DEF-456&
cb=87654321
```
## Best Practices
### Use Macros Consistently
Include the same core set of macros across all your creatives:
```
?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cre={CREATIVE_ID}&cb={CACHEBUSTER}
```
This makes your tracking data consistent and easier to analyze.
### Check Format Support
Always inspect the selected canonical declaration. Not all formats support all macros.
### Combine VAST and AdCP Macros
For video, use both systems together:
* **VAST macros** `[CACHEBUSTING]`, `[TIMESTAMP]` - for standard video tracking
* **AdCP macros** `{MEDIA_BUY_ID}`, `{DEVICE_ID}` - for your campaign tracking
### Privacy Compliance
**Critical**: Always respect user privacy choices in your creative logic.
#### GDPR Compliance (EU Traffic)
For campaigns serving in the EU:
```javascript theme={null}
// Check consent before loading tracking
if (GDPR == 1) {
if (GDPR_CONSENT && GDPR_CONSENT != '') {
// User has consented - load tracking pixels
loadTracking();
} else {
// No consent - skip tracking
console.log('Tracking skipped - no GDPR consent');
}
} else {
// GDPR doesn't apply - load tracking
loadTracking();
}
```
#### US Privacy / CCPA Compliance
For US traffic:
```javascript theme={null}
// Check US Privacy string
if (US_PRIVACY == '1YYN') {
// User has opted out - don't sell personal info
skipPersonalizedTracking();
} else {
// Load normal tracking
loadTracking();
}
```
#### Device-Level Privacy
Respect Limit Ad Tracking settings:
```javascript theme={null}
// Check if device ID is available
if (LIMIT_AD_TRACKING == 1 || DEVICE_ID == '' || DEVICE_ID == '00000000-0000-0000-0000-000000000000') {
// User has limited tracking - use contextual attribution
useContextualTracking();
} else {
// Device ID available
useDeviceTracking(DEVICE_ID);
}
```
#### Privacy Macro Behavior
**Empty Values**: Privacy-restricted macros return empty strings or zeros:
* `{DEVICE_ID}` → `""` or `00000000-0000-0000-0000-000000000000` when LAT enabled
* `{GDPR_CONSENT}` → `""` when no consent provided
* `{IP_ADDRESS}` → `""` or masked/truncated IP when privacy restricted
**Always test for empty values** before using privacy-sensitive macros.
### URL Encoding
Do not URL-encode the placeholder token itself. Supply raw values to the actor named by the occurrence declaration; that actor applies the declaration's exact encoding profile. Depending on the execution path, the actor may be the seller, source ad server, or request executor.
**Example**:
```
❌ WRONG: https://track.com/imp?device=%7BDEVICE_ID%7D
✅ CORRECT: https://track.com/imp?device={DEVICE_ID}
```
The declared actor encodes the concrete value exactly as specified. Callers must not pre-encode values, and downstream actors must not add an undeclared pass.
### Template Syntax
AdCP macro-bearing URLs are not RFC 6570 templates. Plain URLs retain ordinary absolute HTTP(S) URI validation. For structural validation, verifiers mask recognized token lexical forms (`{NAME}`, `${NAME}`, `[NAME]`, and `%%NAME%%`) with an RFC 3986 unreserved sentinel and validate the resulting absolute HTTP(S) URI. This masking applies whether the occurrence is declared or travels on the undeclared 3.x compatibility path; it assigns no meaning, actor, or encoding and does not change the original bytes. RFC 6570 operators (`{+SKU}`, `{#SKU}`, `{?SKU}`, and similar forms) have no special expansion meaning. Processing is literal token replacement only when an applicable declaration or the explicit legacy helper authorizes it.
## Implementation Notes for Sales Agents
*This section is for AdCP implementers, not buyers.*
### Macro Translation Approach
Sales agents must translate universal macros to their ad server's native syntax. The recommended approach:
**Option 1: Hard-Code During Trafficking (MVP)**
* When creating ad server creatives, replace AdCP ID macros with actual values
* Translate platform macros to ad server syntax
* Creates one creative per line item but is simple and reliable
**Option 2: Dynamic Wrapper (Future)**
* Intercept ad calls and inject values dynamically
* More complex but avoids creative duplication
### Translation Examples
**Google Ad Manager**:
```javascript theme={null}
{
'{CACHEBUSTER}': '%%CACHEBUSTER%%',
'{DEVICE_ID}': '%%ADVERTISING_IDENTIFIER_PLAIN%%',
'{DEVICE_ID_TYPE}': '%%ADVERTISING_IDENTIFIER_TYPE%%',
'{DOMAIN}': '%%SITE%%',
'{VIDEO_ID}': '%%VIDEO_ID%%'
}
```
**Kevel**:
```javascript theme={null}
{
'{CACHEBUSTER}': '{{timestamp}}',
'{DEVICE_ID}': '{{device.ifa}}',
'{DEVICE_ID_TYPE}': '{{device.ifaType}}',
'{DOMAIN}': '{{request.domain}}'
}
```
**Xandr Monetize**:
```javascript theme={null}
{
'{CACHEBUSTER}': '${CACHEBUSTER}',
'{DEVICE_ID}': '${DEVICE_APPLE_IDA}', // or ${DEVICE_AAID}
'{DOMAIN}': '${DOMAIN}'
}
```
### Click Tracker Insertion
A click on a creative produces two distinct signals, and AdCP models them as **separate asset slots**:
| Slot | Asset | Role | OpenRTB Native parallel |
| - | - | - | - |
| `landing_page_url` | `url` | The single terminal destination the user navigates to. | `link.url` |
| `click_tracker` | `pixel_tracker` (`event: click`) | A measurement hop that fires on click **without** navigating the user there. Any number may be present. | `link.clicktrackers[]` |
This separation is inherited from IAB OpenRTB Native: a click has **exactly one destination** and **N fire-and-forget click trackers** (the `link.fallback` deeplink is an alternative form of that one destination, not a second one). At serve time the sales agent fires every `click_tracker` as a count beacon and navigates the user to the one `landing_page_url`. Both slots are defined in [Asset Types](/dist/docs/3.2.8/creative/asset-types).
**Macro insertion.** Sales agents insert their ad server's click-tracking macro ahead of the destination so the platform records the click and forwards the user. The destination encoding is ad-server-specific (GAM uses append-style `%%CLICK_URL_UNESC%%`; other servers ship a self-contained `?...&rurl=` form):
**Original creative**:
```html theme={null}
Click here
```
**After insertion (GAM)**:
```html theme={null}
Click here
```
**Preserving the buyer's clickthrough parameters.** Inserting a click macro can strip query parameters already present on the buyer-supplied clickthrough URL — including ones the agent does not recognize, such as a buyer-side vendor's click identifier — which silently breaks downstream attribution. An agent that forwards these parameters applies the encoding discipline [Substitution safety](#substitution-safety-catalog-item-macros) defines for catalog-item values (Unicode NFC normalization, then percent-encoding to the RFC 3986 `unreserved` set) to any value derived from buyer- or third-party-supplied data, so preservation does not reopen URL-context breakout, CRLF injection, or bidi spoofing. Whether to make parameter preservation a normative requirement is part of the click-tracking proposal under working-group review ([#5693](https://github.com/adcontextprotocol/adcp/issues/5693)).
**Getting a buyer's click identifier onto the landing.** A `click_tracker` is a count beacon: it records the click but does not place its identifier into the user's landing session, because only `landing_page_url` is navigated. When a buyer needs its click identifier to reach the landing (for click-level conversion attribution), the reliable, redirect-free pattern is to put that identifier directly on the `landing_page_url` it supplies — either as a literal value (`&buyer_click_id=abc123`) or composed from an AdCP macro the buyer controls (`&buyer_click_id={CREATIVE_ID}`, expanded by the sales agent at serve time). `{buyer_click_id}` is not itself an AdCP universal macro — that universal set is closed even though qualified vendor dialects remain extensible — so the buyer supplies the value, not a new universal token. Because the identifier rides on the one navigated URL, no party's redirect has to be the terminal hop. This works for any identifier the buyer can supply or derive ahead of serve time, and avoids multi-party redirect chaining entirely.
Identifiers that can only be minted at click time (inside a vendor's own redirect) cannot survive on a count beacon, and routing the user *through* the vendor's redirect so its identifier lands requires a chaining contract AdCP does not define. A buyer-declarable "this tracker must be in the navigation path" slot semantic is under working-group discussion ([#5693](https://github.com/adcontextprotocol/adcp/issues/5693)); until it lands, the count beacon is the default and in-path identifier survival is out of scope.
### Mapping Storage
Store the mapping between AdCP IDs and ad server IDs for reconciliation:
```javascript theme={null}
{
media_buy_id: "mb_spring_2025",
ad_server_order_id: "1234567",
packages: [
{
package_id: "pkg_ctv_prime",
ad_server_line_item_id: "8901234"
}
]
}
```
Return this in `create_media_buy` responses and make it queryable for reconciliation.
## Related Documentation
* [Creative Formats](/dist/docs/3.2.8/creative/formats) - Understanding format specifications and discovery
* [Creative Protocol](/dist/docs/3.2.8/creative) - How creatives work in AdCP
* [sync_creatives](/dist/docs/3.2.8/creative/task-reference/sync_creatives) - Creative management API
# Accountability
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/advanced-topics/accountability
How buyers and sellers negotiate, enforce, and resolve performance standards, measurement terms, and cancellation policies in AdCP guaranteed buys.
## Overview
Guaranteed media buys in AdCP have three accountability surfaces:
* **Performance standards** — rate thresholds for viewability, IVT, completion, brand safety, and attention (IAB T\&Cs Section XI)
* **Measurement terms** — who counts the billing metric and what remedies (makegoods) apply when thresholds are breached (IAB T\&Cs Sections V, VII, IX)
* **Cancellation policy** — notice period and cancellation fee for early termination (IAB T\&Cs Section XII)
These are structured, machine-readable fields — not free text. Buyer and seller agents negotiate them programmatically through the standard product discovery and buy creation workflow.
## Lifecycle
### 1. Discovery: Buyer States Requirements
At `get_products`, the buyer filters for products that meet their performance requirements:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442010",
"buying_mode": "brief",
"brief": "Premium video for CPG brand, Q3 flight",
"filters": {
"delivery_type": "guaranteed",
"required_performance_standards": [
{
"metric": "viewability",
"threshold": 0.70,
"standard": "mrc",
"vendor": { "domain": "doubleverify.com" }
},
{
"metric": "ivt",
"threshold": 0.05,
"vendor": { "domain": "doubleverify.com" }
}
]
}
}
```
Products that cannot meet these thresholds or do not support the specified vendors are excluded from results. The buyer is saying: "I need DoubleVerify for viewability at 70% MRC and IVT under 5%."
### 2. Product Response: Seller Declares Defaults
Returned products include the seller's default `performance_standards`, `measurement_terms`, and `cancellation_policy`:
```json theme={null}
{
"product_id": "premium_video_q3",
"delivery_type": "guaranteed",
"performance_standards": [
{ "metric": "viewability", "threshold": 0.70, "standard": "mrc", "vendor": { "domain": "doubleverify.com" } },
{ "metric": "ivt", "threshold": 0.05, "vendor": { "domain": "doubleverify.com" } },
{ "metric": "completion_rate", "threshold": 0.75, "vendor": { "domain": "doubleverify.com" } }
],
"measurement_terms": {
"billing_measurement": {
"vendor": { "domain": "admanager.google.com" },
"max_variance_percent": 10
},
"makegood_policy": {
"available_remedies": ["additional_delivery", "credit", "invoice_adjustment"]
}
},
"cancellation_policy": {
"notice_period": { "interval": 30, "unit": "days" },
"cancellation_fee": { "type": "percent_remaining", "rate": 0.5 }
}
}
```
The buyer can see all terms before committing budget.
### 3. Refinement: Negotiate Before Committing
Using `buying_mode: "refine"`, the buyer can propose changes to performance standards or measurement terms. This uses the same `required_performance_standards` filter — the seller responds with updated products reflecting what they can offer. Refinement is iterative and non-binding.
### 4. Buy Creation: Buyer Proposes, Seller Accepts
At `create_media_buy`, the buyer can propose different terms on the package request:
```json theme={null}
{
"product_id": "premium_video_q3",
"budget": 50000,
"pricing_option_id": "cpm_usd_fixed",
"performance_standards": [
{ "metric": "viewability", "threshold": 0.75, "standard": "mrc", "vendor": { "domain": "doubleverify.com" } },
{ "metric": "ivt", "threshold": 0.03, "vendor": { "domain": "doubleverify.com" } }
],
"measurement_terms": {
"billing_measurement": {
"vendor": { "domain": "campaignmanager.google.com" },
"max_variance_percent": 5
}
}
}
```
The seller has three responses:
* **Accept** — echo the buyer's terms on the confirmed package
* **Reject** — return `TERMS_REJECTED` with details about which term failed and acceptable range
* **Adjust** — return modified terms on the confirmed package (the buyer agent inspects the response to see what changed)
When the buyer omits `performance_standards` or `measurement_terms`, the product's defaults apply.
#### Measurement terms for phased-maturation channels
Some channels produce billing-grade data in phases rather than delivering final numbers on day one — broadcast TV, DOOH, digital with IVT filtering, podcast downloads, and others. For these, the buyer proposes a `measurement_window` alongside the vendor, specifying which maturation stage the guarantee is reconciled against:
```json theme={null}
{
"product_id": "primetime_30s_q4",
"budget": 250000,
"pricing_option_id": "unit_rate_30s",
"agency_estimate_number": "EST-2026-04821",
"measurement_terms": {
"billing_measurement": {
"vendor": { "domain": "videoamp.com" },
"measurement_window": "c7",
"max_variance_percent": 10
}
}
}
```
The `measurement_window` references a `window_id` from the product's `reporting_capabilities.measurement_windows`. This tells both sides: "VideoAmp's C7 numbers are what we reconcile against." For a DOOH product it would be `"final"` (post-IVT/fraud-check); for digital it might be `"post_sivt"`. The same mechanism declares both which data is authoritative for billing and when it becomes available — reconciliation and invoicing clocks follow that declared availability. The `agency_estimate_number` is the financial reference that links the order to the agency's media plan — it travels with the order through the transaction lifecycle.
### 5. Confirmed Package: The Contract
The confirmed package reflects the agreed terms — the binding contract:
```json theme={null}
{
"package_id": "pkg_001",
"product_id": "premium_video_q3",
"performance_standards": [
{ "metric": "viewability", "threshold": 0.75, "standard": "mrc", "vendor": { "domain": "doubleverify.com" } },
{ "metric": "ivt", "threshold": 0.03, "vendor": { "domain": "doubleverify.com" } }
],
"measurement_terms": {
"billing_measurement": {
"vendor": { "domain": "campaignmanager.google.com" },
"max_variance_percent": 5
},
"makegood_policy": {
"available_remedies": ["additional_delivery", "credit", "invoice_adjustment"]
}
}
}
```
### 6. Creative Enforcement
When agreed `performance_standards` specify a vendor, creatives assigned to that package MUST include `tracker_script` or `tracker_pixel` URL assets from that vendor. Sales agents SHOULD reject creative assignments that lack required verification tags with `CREATIVE_REJECTED`.
For example, if the agreed terms include DoubleVerify for viewability, every creative on the package must carry DV tags so viewability can be measured.
**Formats without tracker support**: Not all formats accept third-party tracking assets. Broadcast TV spots, for instance, have no tracker slot — there is no pixel to fire on a television. Buyer agents should check the format's `assets` array for tracker slots before proposing performance standards that require creative-level verification. When a format does not support trackers, measurement comes from the vendor declared in `billing_measurement` (panel data, set-top box telemetry) rather than creative-embedded pixels. See [Format definitions](/dist/docs/3.2.8/creative/formats#third-party-tracker-support) for details.
### 7. Breach and Resolution
When a performance standard or billing measurement variance is breached, the seller proposes a remedy from the agreed `makegood_policy`:
* **`additional_delivery`** — extend or add impressions (like-for-like, same or later campaign)
* **`credit`** — credit toward future buys on the same account
* **`invoice_adjustment`** — reduce the invoice for the current buy
The buyer accepts or disputes.
## Cancellation Policy
Cancellation policy is not a negotiation surface. The seller declares it on the product; the buyer accepts it by creating a media buy. A guaranteed buy canceled without sufficient notice incurs the declared cancellation fee.
**Cancellation fee types:**
* `percent_remaining` — percentage of remaining committed spend (e.g., 50%)
* `full_commitment` — buyer owes the full committed budget
* `fixed_fee` — flat monetary amount
* `none` — no cancellation fee
## Insertion Orders
The insertion order is a signing wrapper around a committed proposal. It does not introduce new deal terms. All negotiated terms live on products and packages. The IO's `terms` object provides summary fields (advertiser, publisher, budget, dates, payment terms) so buyer agents can verify the IO matches the proposal before a human signs via DocuSign or similar.
## Vendor Identity and Measurement Agents
All measurement and verification vendors are identified by domain using the standard [brand reference](/dist/docs/3.2.8/brand-protocol/brand-json) — the same system used for brands, operators, and accounts. Examples:
* `{ "domain": "doubleverify.com" }` — DoubleVerify
* `{ "domain": "integralads.com" }` — IAS
* `{ "domain": "oracle.com", "brand_id": "moat" }` — MOAT
* `{ "domain": "campaignmanager.google.com" }` — Google Campaign Manager
* `{ "domain": "admanager.google.com" }` — Google Ad Manager
* `{ "domain": "videoamp.com" }` — VideoAmp (broadcast/CTV measurement)
* `{ "domain": "comscore.com" }` — Comscore (cross-platform measurement)
The vendor's `brand.json` at their domain is the discovery point for their agent capabilities. Vendors declare agents in the `agents` array with `type: "measurement"`:
```json theme={null}
{
"house": {
"domain": "doubleverify.com",
"name": "DoubleVerify",
"agents": [
{
"type": "measurement",
"url": "https://api.doubleverify.com/adcp/measurement",
"id": "dv_measurement"
}
]
}
}
```
This follows the same pattern used for all agent types in brand.json — brand, rights, governance, creative, buying, and signals agents are all discovered the same way.
The buyer or seller queries the measurement agent for current rates against agreed performance standards, rather than waiting for post-campaign reporting. The measurement vendor participates as an agent, not a black box.
### Relationship to Content Standards
[Content standards agents](/dist/docs/3.2.8/governance/content-standards) validate WHAT was delivered (brand safety, content categorization). Performance standards measure HOW WELL it was delivered (viewability rates, IVT rates, completion rates). The vendor may be the same company — DoubleVerify provides both brand safety scoring and viewability measurement — but the concerns are distinct:
* **Content standards**: `validate_content_delivery` — "was this ad placed next to safe content?"
* **Performance standards**: measurement agent — "what percentage of impressions were viewable?"
Both use agent-to-agent workflows. Content standards are already fully specified. Measurement agent interfaces are a follow-up to this specification.
# Accounts & Security
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/advanced-topics/accounts-and-security
AdCP accounts and security — authentication, rate cards, billing entities, and data isolation for multi-tenant media buying between buyer and seller agents.
An **Account** represents a billing relationship between a buyer and a seller in AdCP. Sales agents use accounts to determine pricing (rate cards), billing entities, and to enforce data isolation between different buyers.
## Authentication
All requests must be authenticated using a bearer token in the standard `Authorization` header:
```
Authorization: Bearer
```
The server validates this token and identifies the **agent** making the request. The agent may have access to one or more accounts.
See [Authentication](/dist/docs/3.2.8/building/by-layer/L2/authentication) for details on obtaining credentials and authentication methods.
### Agents and Accounts
AdCP distinguishes between:
* **Agent**: The authenticated entity making API calls (e.g., `"pinnacle_trading_desk"`)
* **Account**: The billing relationship for a media buy (e.g., `"acme_c/o_pinnacle"`)
An agent may operate on multiple accounts. For example, an agency trading desk might manage accounts for multiple advertisers and their own house account. See [Accounts and Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) for details.
For an end-to-end buyer-declared account example, including seller-mediated human setup and activation, see [Provision a seller-mediated account](/dist/docs/3.2.8/accounts/provisioning-walkthrough).
## Data Isolation
Authentication provides the foundation for strict data isolation. Sales agents **MUST** enforce the following rules:
1. When an object like a `MediaBuy` is created, it **MUST** be permanently associated with the account used for that request.
2. For any subsequent request to read or modify that object, the server **MUST** verify that the agent has access to that account.
3. If the agent does not have access, the server **MUST** return a permission denied error.
This model ensures that one account's data cannot be accessed by agents who lack authorization. Passing an `account_id` for an account you don't have access to will result in an error.
## Security Requirements
For the full normative implementation reference — two-step authorization, row-level security, IDOR defense, and the wider security posture (webhooks, idempotency, signed governance context) — see [Security — Agent and Account Isolation](/dist/docs/3.2.8/building/by-layer/L1/security#agent-and-account-isolation).
### Required Security Measures
Sales agent implementations **MUST**:
* Validate bearer tokens on every authenticated request
* Enforce account-based data isolation
* Use TLS for all communications
* Log authentication failures for security monitoring
### Recommended Security Measures
Sales agent implementations **SHOULD**:
* Implement rate limiting per agent and account
* Support token expiration and refresh
* Provide audit logging for compliance
* Support IP allowlisting for high-security accounts
# Agentic eXecution Engine (AXE)
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/advanced-topics/agentic-execution-engine
Agentic eXecution Engine (AXE) — AdCP's real-time execution layer for brand suitability enforcement, frequency capping, and dynamic audience targeting at impression time.
> [!WARNING]
>
> AXE is deprecated. The [Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match) replaces AXE with structural privacy separation, multi-surface support (web, mobile, CTV, AI assistants, retail media), and a standardized offer model. New integrations should use TMP. Existing AXE integrations will continue to work — the `axei`/`axex`/`axem` segment model maps to TMP's offers and signals.
The Agentic eXecution Engine (AXE) is AdCP's original real-time execution layer that enables dynamic audience targeting, brand suitability enforcement, and frequency management at impression time.
AXE is how AdCP reaches impression-time execution. It enables cross-publisher frequency capping the same way OpenRTB enables programmatic decisioning: by giving the buyer or orchestrator a real-time look at each impression before the ad server decides whether to serve.
## Two-Phase Workflow
AXE operates in two distinct phases: **offline campaign setup** and **real-time ad serving**.
### Phase 1: Offline Setup
Before ads serve, campaigns are configured and segment data is synchronized:
```mermaid theme={null}
flowchart TB
subgraph offline["Offline Setup Phase"]
direction TB
buyer["**Buyer Agent**
• Campaigns
• Budgets
• Targeting"]
signal["**Signal Agent**
• Audiences
• Contextual
• Suitability"]
orch["**Orchestrator**
• Map to AXE segments
• Sync to RTD"]
sales["**Sales Agent**
Create line items
with AXE targeting"]
buyer --> orch
signal --> orch
orch --> sales
end
```
**What happens:**
1. **Buyer Agent** creates campaigns with targeting and budgets via AdCP
2. **Signal Agents** attach contextual data (audiences, brand suitability rules, weather triggers)
3. **Orchestrator** maps campaigns to AXE segments and syncs data to the real-time module
4. **Sales Agent** creates ad server line items targeting AXE segment key-values
### Phase 2: Real-Time Serving
When an ad request arrives, AXE evaluates it in real-time and returns segment decisions:
```mermaid theme={null}
flowchart TB
subgraph realtime["Real-Time Serving Phase"]
direction TB
page["**Page**
User visits"]
adserver1["**Ad Server**
GAM / Kevel"]
prebid["**Prebid**
OpenRTB request"]
axe["**AXE**
Segment lookup"]
page --> adserver1 --> prebid --> axe
axeresponse["**AXE Response**
axei: Include segment
axex: Exclude (suitability)
axem: Creative macro data"]
axe --> axeresponse
adserver2["**Ad Server**
Match segments to line items
→ Serve ad"]
axeresponse --> adserver2
end
```
**What happens:**
1. User visits page, triggering ad request
2. Ad server initiates request to Prebid (or similar)
3. Prebid sends OpenRTB bid request to AXE
4. AXE evaluates user/context and returns segment values
5. Ad server matches segments to line items and serves appropriate ad
## AXE Segment Types
AXE returns three types of segment values to the ad server:
| Segment | Key | Purpose | Example |
| - | - | - | - |
| **Include** | `axei` | Audience targeting - user belongs to this segment | `"seg_auto_intenders"` |
| **Exclude** | `axex` | Brand suitability/suppression - block this impression | `"unsafe_content"` |
| **Macro** | `axem` | Creative personalization data | `"eyJjb250ZXh0IjoiLi4uIn0="` |
### How Segments Flow to Creatives
```json theme={null}
{
"packages": [{
"product_id": "premium_video",
"targeting_overlay": {
"axe_include_segment": "seg_auto_intenders_q1",
"axe_exclude_segment": "seg_existing_customers"
}
}]
}
```
At impression time:
* `axei` is checked against `axe_include_segment` → must match to serve
* `axex` is checked against `axe_exclude_segment` → must NOT match to serve
* `axem` is passed to creative via the `{AXEM}` macro
## Data Flow Example
Here's a concrete example of AXE in action for a customer acquisition campaign:
### Setup (Offline)
**1. Buyer uploads suppression list:**
```
Advertiser CRM
→ Hash emails (SHA256)
→ Upload to orchestrator
→ Receive segment ID: "seg_existing_customers_acme"
```
**2. Create media buy with AXE targeting:**
```json theme={null}
{
"packages": [{
"product_id": "premium_video_millennials",
"budget": { "amount": 50000 },
"targeting_overlay": {
"axe_exclude_segment": "seg_existing_customers_acme"
}
}]
}
```
**3. Sales Agent creates line item:**
```
Line item: "Acme Q1 Acquisition"
Targeting: axex != "seg_existing_customers_acme"
```
### Serving (Real-Time)
**4. User visits publisher site:**
```
GET /ad-request
User-Agent: Mozilla/5.0...
Cookie: uid=abc123
```
**5. AXE lookup:**
```
Input: uid=abc123
Check: Is abc123 in seg_existing_customers_acme?
Result: YES (hashed email matches)
```
**6. AXE response:**
```json theme={null}
{
"axei": null,
"axex": "seg_existing_customers_acme",
"axem": null
}
```
**7. Ad server decision:**
```
Line item requires: axex != "seg_existing_customers_acme"
Current axex: "seg_existing_customers_acme"
Decision: DO NOT SERVE (user is existing customer)
```
**Result:** Acquisition budget is not wasted on existing customers.
## Core Capabilities
### 1. Dynamic Audience Targeting
Bring your own DMP/CDP segments to publisher inventory:
* Upload audience data (hashed emails, device IDs, etc.)
* Receive segment IDs from your orchestrator
* Reference segment IDs in `axe_include_segment`
* AXE matches users at impression time
**Use cases:** Lookalike targeting, CRM activation, behavioral segments
### 2. Brand Suitability
Real-time content evaluation at impression time:
* **Content classification** - News, entertainment, sports, etc.
* **Sentiment analysis** - Positive/negative content detection
* **Keyword blocking** - Brand-specific term avoidance
* **Adjacency rules** - What other ads are on the page
Brand suitability rules flow from Signal Agents through the orchestrator to AXE.
### 3. Cross-Publisher Frequency Management
Unlike publisher-side caps, AXE tracks exposure across:
* Multiple publishers
* Multiple campaigns
* Multiple devices (with identity resolution)
AXE enforces frequency caps and returns segment decisions to the ad server. The ad server doesn't know *why* a segment matched or didn't match—it just knows whether to serve.
### How Cross-Publisher Frequency Capping Works
> [!NOTE]
>
> Cross-publisher frequency capping is now handled by the [Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match), which uses structurally separated Context Match and Identity Match operations. The AXE segment model maps to TMP's offers and eligibility responses.
In the AXE model, every eligible impression is checked in real time against shared exposure state:
```mermaid theme={null}
flowchart LR
pubA["**Publisher A**
Impression opportunity"]
pubB["**Publisher B**
Impression opportunity"]
pubC["**Publisher C**
Impression opportunity"]
req["**OpenRTB-style request**
user, placement, context"]
axe["**AXE**
Evaluate cap eligibility"]
state["**Exposure store**
cross-publisher history"]
decision["**Decision**
serve or suppress"]
pubA --> req
pubB --> req
pubC --> req
req --> axe
state --> axe
axe --> decision
```
In TMP, this same pattern is achieved with structural privacy: the Identity Match path handles frequency caps (the buyer checks exposure history without knowing what page the user is on), and the Context Match path handles content relevance (the buyer evaluates packages without knowing who the user is). The publisher joins both responses locally.
### 4. First-Party Data Activation
Activate your customer data without sharing PII:
1. Hash customer identifiers (emails, phone numbers)
2. Upload to orchestrator (data stays with orchestrator)
3. Reference via segment ID in campaigns
4. AXE matches at impression time
5. Publisher never sees raw customer data
## Privacy by Design: Opaque Segment IDs
A key AXE design principle is that **segment IDs are intentionally opaque**. The ad server only sees that segment `ABCD` passed or failed—it doesn't know what type of targeting the segment represents.
This could mean:
* User exceeded frequency cap
* Page failed brand suitability check
* User is in a first-party suppression list
* User matches an audience segment
This opacity protects buyer data. Publishers and ad servers cannot reverse-engineer:
* Which users are in buyer CRM lists
* Frequency cap thresholds
* Brand suitability rules
* Audience segment definitions
All the ad server knows is: "AXE says serve" or "AXE says don't serve."
## Integration Points
### For Buyers
| Step | Action | Result |
| - | - | - |
| 1 | Upload audience to orchestrator | Receive segment ID |
| 2 | Include segment ID in `create_media_buy` | Campaign created with AXE targeting |
| 3 | Monitor delivery reports | Track segment match rates |
### For Publishers
Publishers don't implement AXE directly — the orchestrator handles integration (see [How AXE Reaches the Page](#how-axe-reaches-the-page)). Publisher responsibilities:
1. **Enable the orchestrator's integration** - Add RTD module (Prebid) or enable platform integration
2. **Accept key-value targeting** - Pass `axei`, `axex` values to ad server
3. **Configure line items** - Target on AXE segment key-values
4. **Declare support** - Indicate AXE compatibility in `adagents.json`
### For Orchestrators
Orchestrators operate the AXE layer:
1. **Segment ingestion** - Accept audience data from buyers
2. **Real-time lookups** - Sub-10ms segment membership checks
3. **Signal integration** - Apply brand suitability and contextual signals
4. **Frequency state** - Maintain cross-campaign exposure tracking
5. **Ad platform integration** - Expose segments via Prebid RTD module, platform container, or server-side endpoint
## How AXE Reaches the Page
AXE is a protocol-level concept. **Orchestrators implement AXE** and integrate it into ad serving environments. The integration path depends on the ad platform:
| Integration Path | How It Works | Example |
| - | - | - |
| **Prebid RTD module** | Orchestrator distributes a Prebid module that calls the AXE endpoint during auction | `exampleRtdProvider` |
| **Proprietary ad platform** | AXE runs as a container or secure enclave within the platform's infrastructure | Platform-native integration |
| **Server-side** | AXE endpoint called server-to-server by the ad platform before decisioning | Custom ad server integration |
The common thread: whatever the integration path, AXE evaluates segments and returns `axei`/`axex`/`axem` decisions that the ad platform uses for targeting. For cross-publisher frequency capping, those impression-time calls are what let the buyer apply shared exposure rules across sellers instead of relying on one publisher's local ad server counter.
### The Chain: Orchestrator → AXE Endpoint → Segment Targeting
```
Ad platform calls orchestrator's AXE endpoint
→ AXE evaluates segments and returns axei/axex/axem values
→ Values used for targeting decisions (key-values, container logic, etc.)
→ Matching campaigns serve
```
The `axe_integrations` URL in a seller's [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) response tells buyers which orchestrator's AXE endpoint the seller connects to:
```json theme={null}
{
"media_buy": {
"execution": {
"axe_integrations": ["https://axe.example.com"]
}
}
}
```
### Prebid Integration (Web)
For web publishers using Prebid, AXE integrates via the orchestrator's RTD module. The module name in Prebid matches the orchestrator, not "AXE":
```javascript test=false theme={null}
// Prebid build includes: rtdModule, exampleRtdProvider, ...other modules
pbjs.setConfig({
realTimeData: {
auctionDelay: 100,
dataProviders: [{
name: 'example', // Orchestrator's module name
waitForIt: true,
params: {
// Orchestrator-specific configuration
}
}]
}
});
```
The orchestrator's RTD module:
1. Intercepts the auction before bids are requested
2. Sends an OpenRTB-style request to the AXE endpoint
3. Receives segment decisions (axei/axex/axem)
4. Sets targeting key-values on the ad server request
Publishers don't need to know AXE internals — the orchestrator's module handles everything.
### Proprietary Platform Integration
AXE can also run within proprietary ad platforms as a container or secure enclave. In this model:
* The orchestrator deploys AXE logic into the platform's infrastructure
* Segment evaluation happens within the platform's decisioning pipeline
* No external network call is needed at impression time — reducing latency
* The platform calls AXE as part of its native ad selection process
This is particularly relevant for platforms that don't use Prebid or where latency requirements are stricter than what an external RTD call allows.
### Identifying AXE Support
The definitive check is the seller's `get_adcp_capabilities` response. For Prebid-based integrations, you can also inspect the page directly:
| What to look for | Where | Meaning |
| - | - | - |
| `axe_integrations` in capabilities | `get_adcp_capabilities` response | Seller supports AXE |
| `axei`/`axex`/`axem` key-values | Ad server request (network tab) | AXE segments flowing to ad server |
| Orchestrator RTD module (e.g., `exampleRtdProvider`) in Prebid build | Page source or `pbjs.installedModules` | AXE via Prebid |
| Orchestrator entry in `realTimeData.dataProviders` | `pbjs.getConfig('realTimeData')` | AXE is active |
Different orchestrators may implement AXE through different integration paths — the segment protocol (axei/axex/axem) is the same regardless of how AXE is deployed.
## Universal Macro:
Creatives can receive AXE context data for dynamic rendering:
```html theme={null}
```
The `{AXEM}` macro contains base64-encoded contextual metadata:
* Weather conditions
* Content category
* User segment attributes (anonymized)
* Custom orchestrator data
See [Universal Macros](/dist/docs/3.2.8/creative/universal-macros) for details.
## When to Use AXE
| Scenario | Use AXE? | Alternative |
| - | - | - |
| Target users in my CRM | ✅ Yes | — |
| Suppress existing customers | ✅ Yes | — |
| Cross-publisher frequency cap | ✅ Yes | — |
| Real-time brand suitability | ✅ Yes | — |
| Target "millennials in California" | ❌ No | Express in brief |
| Geographic restrictions | ❌ No | Use `geo_countries` |
| Publisher's audience segments | ❌ No | Express in brief |
| Single-publisher frequency cap | ❌ No | Publisher ad server handles this |
## Performance
AXE is designed for ad serving latency requirements:
| Operation | Target Latency |
| - | - |
| Segment membership lookup | \< 10ms |
| Brand suitability evaluation | \< 20ms |
| Frequency check | \< 5ms |
| Combined AXE decision | \< 50ms |
## Related Documentation
* **[Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting)** - Brief-based targeting and geographic overlays
* **[Signals Protocol](/dist/docs/3.2.8/signals/overview)** - Signal discovery and activation
* **[Universal Macros](/dist/docs/3.2.8/creative/universal-macros)** - Creative-level AXE integration
* **[Orchestrator Design](/dist/docs/3.2.8/building/operating/orchestrator-design)** - Building orchestration platforms
# Billing Authority
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/advanced-topics/billing-authority
How AdCP names the authoritative counter of a media buy's billing metric, marks numbers as final, and reconciles between buyer and seller views when those views disagree.
## Overview
For a media buy to invoice deterministically, two questions must have machine-readable answers:
1. **Whose number is authoritative?** Different deals name different parties — the seller's ad server, a buyer's third-party ad server, or a named measurement vendor like Nielsen or IAS.
2. **Has that number stopped moving?** Telemetry settles over hours, days, or weeks (broadcast C3 → C7 DVR accumulation, digital post-IVT scrubbing, podcast 30-day downloads, conversion dedup). Final numbers are billable; provisional numbers are not.
AdCP answers both with structured terms already on the wire: `measurement_terms.billing_measurement` (negotiated at `create_media_buy`) names authority; `is_final` / `final` flags with `finalized_at` timestamps (on `get_media_buy_delivery` and `report_usage`) mark closure.
This page ties those pieces together.
> [!NOTE]
>
> **Billing authority and Reliable Reporting are separate contracts today.**
> [Reliable Reporting](/dist/docs/3.2.8/media-buy/reporting-core-implementation-guide)
> (experimental in 3.2) answers a different question: *did the report I was
> promised arrive, intact, on time?* It gives the seller-produced feed
> obligations, immutable revisions, a binding digest, health states, and — when
> the seller opts in — a buyer-to-seller
> [`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status)
> loop. None of that decides whose *count* governs the invoice, which is what
> this page's `billing_measurement` does.
>
> So both surfaces can read green while an invoice is still disputed: a buyer's
> consumer status can be `received` and the seller's health `complete` on a feed
> whose numbers sit outside `max_variance_percent` of the authoritative party's.
> `reporting-delivery-config.json` reserves an `authoritative_party` field
> (`seller` | `consumer`, default `seller`) so the two models can be unified
> additively. In 3.2 the only accepted value is `seller`; sellers MUST reject
> `consumer` with `UNSUPPORTED_FEATURE` because no released minor defines the
> buyer-deposited revision task. Tracked in
> [#7440](https://github.com/adcontextprotocol/adcp/issues/7440).
## Naming authority
`measurement_terms.billing_measurement` carries:
| Field | Meaning |
| - | - |
| `vendor` (required, [BrandRef](/dist/docs/3.2.8/brand-protocol/brand-json)) | The party whose count of the billing metric governs invoicing. Same field shape covers seller's ad server, buyer's 3PAS, or a third-party vendor — the BrandRef domain disambiguates. |
| `max_variance_percent` | Tolerance above which the seller's and authoritative party's counts trigger resolution under `makegood_policy`. IAB default is 10%; broadcast/CTV often 5%. |
| `measurement_window` | Which maturation stage of the data is the reconciliation point (`c7`, `post_sivt`, `downloads_30d`, etc.) — references a `window_id` from the product's `reporting_capabilities.measurement_windows`. |
| `finalization_deadline_hours` | Maximum hours by which the authoritative party MUST publish a final record. When `measurement_window` is set, hours are counted from the window's close (not from `reporting_period.end`); when absent, from `reporting_period.end`. The deadline applies symmetrically to whichever party is named in `vendor`. On miss, the counterparty MAY fall back to its own attestation; the breach is handled under `makegood_policy`. |
Absence is informative: when `billing_measurement` is absent the default is seller-attested, with no contractual finalization deadline.
## Marking numbers as final
Final means **settled for the named measurement window** — not "final forever." A broadcast row marked `is_final: true` for `measurement_window: "c3"` is final for C3; a later `c7` row supersedes it with its own provisional → final lifecycle. A future structured dispute would join on `(media_buy_id, reporting_period, measurement_window)`; 3.2 does not define one.
### On `get_media_buy_delivery`
Each row in `media_buy_deliveries[]` carries:
* `is_final: boolean` — row-level finality, equivalent to all packages in the row being final for the same window.
* `finalized_at: string (date-time)` — present iff `is_final: true`. Anchors any deadline declared in `billing_measurement.finalization_deadline_hours`.
* Per-package: `by_package[*].is_final`, `by_package[*].finalized_at`, `by_package[*].measurement_window`, `by_package[*].supersedes_window`.
### On `report_usage`
> [!NOTE]
>
> **Predecessor path.** For media-buy billing, `report_usage` is the
> pre-Reliable-Reporting channel for buyer- and vendor-attested numbers. It has no
> obligations, no immutable revisions, no RFC 8785/JCS binding digest, no
> supersession chain, and no status surface, so a missing or restated settlement
> file is not detectable on the wire the way a missing reporting obligation is.
> It remains the supported path for the buyer-attested and vendor-attested flows
> below until a buyer-deposited revision task exists
> ([#7440](https://github.com/adcontextprotocol/adcp/issues/7440)). Non-media-buy
> `report_usage` variants (signals, governance, creative, brand) are unaffected
> and are not superseded by Reliable Reporting.
Each usage record carries:
* `final: boolean` — **absent means unknown.** Set `true` only when the reporter has actually settled the numbers (e.g., post-SIVT month-end close). Set `false` for preliminary records (daily pacing pushes, intra-period progress). When `measurement_terms.billing_measurement` names this reporter as authoritative, the receiver MUST NOT invoice on `final: false` or absent — request a final record first. For 3.0-style usage with no `billing_measurement` and for non-media-buy variants (signals, governance, creative, brand — domains with no provisional state concept), receivers MAY treat absent as final, preserving existing behavior.
* `finalized_at: string (date-time)` — present iff `final: true`.
* `measurement_window: string` — SHOULD be set when the buy's `billing_measurement.measurement_window` is set, so the receiver reconciles against the correct stage.
When the same `(account, media_buy_id, reporting_period)` is later reported with `final: true`, that record supersedes any prior records for the period.
### Distinguishing webhook finality from row finality
`get_media_buy_delivery` webhooks carry a top-level `notification_type` enum that includes `"final"` — this signals **"this is the last scheduled notification for the campaign,"** not that contained rows are final for invoicing. The two axes are independent: a webhook with `notification_type: "final"` may still contain rows where `is_final: false` (e.g., a campaign-end notification before C7 settles). Always check the per-row `is_final` for billing decisions.
## How a seller produces an invoice
### Seller-attested (default)
```
billing_measurement absent, or vendor names seller's own ad server
```
Seller invoices off `get_media_buy_delivery` rows where `is_final: true` for the contracted `measurement_window`. No `report_usage` from the buyer is required.
### Buyer-attested (3PAS)
```
billing_measurement.vendor.domain = "campaignmanager.google.com" (buyer's CM360)
billing_measurement.max_variance_percent = 10
billing_measurement.measurement_window = "post_sivt"
billing_measurement.finalization_deadline_hours = 240 // 10 days after post_sivt close
```
Sequence:
1. Buyer's CM360 settles post-SIVT for the period.
2. The buyer's operator — in practice a holdco platform (e.g., Choreograph, Annalect, Acxiom) or an in-house agency engineering team that wraps the CM360 export — calls `report_usage` with the media-buy record: `media_buy_id`, `impressions`, `vendor_cost`, `currency`, `final: true`, `finalized_at`, `measurement_window: "post_sivt"`. Daily pacing pushes (if used) set `final: false`; only the settled file sets `final: true`.
3. Seller compares against its own post-SIVT row from `get_media_buy_delivery` (`is_final: true`, same `measurement_window`). If `|seller - buyer| / max ≤ max_variance_percent`, the seller invoices on the buyer's numbers.
4. If variance exceeds threshold, the seller proposes a remedy from `makegood_policy.available_remedies`.
5. If the buyer doesn't publish a final record within `finalization_deadline_hours`, the seller MAY invoice off its own seller-attested numbers and treat the late finalization as a breach under `makegood_policy`.
> **Today's reality:** monthly 3PAS reconciliation is mostly handled out-of-band via CSV/PDF emailed to the seller's AR team. This flow is the wire-format upgrade — the first adopters are likely holdco operators with the engineering to wrap CM360 / Flashtalking / Innovid exports in `report_usage`, working with sympathetic direct publishers rather than RTB SSPs.
### Vendor-attested (named third party)
```
billing_measurement.vendor.domain = "nielsen.com"
billing_measurement.max_variance_percent = 5
billing_measurement.measurement_window = "c7"
billing_measurement.finalization_deadline_hours = 528 // 22 days after c7 close
```
Two operational patterns, depending on who holds the vendor relationship:
* **Seller holds the vendor relationship (the common CTV pattern).** The seller pulls C7 numbers from Nielsen (NPower, etc.) on its own schedule and publishes them on `get_media_buy_delivery` as a row with `measurement_window: "c7"`, `is_final: true`, and `finalized_at` set when the C7 window closes plus its internal processing. No `report_usage` push from the buyer is needed; reconciliation happens against the seller's row.
* **Buyer holds the vendor relationship.** The buyer (or its operator) fetches the vendor's authoritative numbers — e.g., an agency's iSpot subscription, an in-house IAS dashboard export — and pushes them via `report_usage` against the buy's account with `final: true`, `finalized_at`, and `measurement_window: "c7"`. The vendor itself does not call AdCP.
The `vendor.domain` BrandRef identifies who the contract names, not who calls the API. The vendor's own integration (NPower feed, IAS API, DV pinnacle) is out of AdCP scope.
> **Today's reality:** SSPs running RTB will keep being seller-attested for the foreseeable future — their billing systems were never designed for buyer-attested invoice basis and `max_variance_percent` plus `makegood_policy` is not enough commercial cover for them to retrofit it. The first real adopters here are CTV direct sellers (e.g., Disney, NBCU, Paramount) whose Nielsen-backed guarantees already invoice on a measurement vendor's count — for them this PR just describes existing practice in structured terms.
## Resolving disagreements today
When numbers disagree beyond `max_variance_percent`, AdCP 3.0–3.1 expects out-of-band resolution between counterparties, backed by:
* The buy's `makegood_policy.available_remedies` — the menu of remedies (additional delivery, credit, invoice adjustment) the seller has pre-committed to.
* Final records on both sides with `finalized_at` timestamps — a full audit trail of who said what was final, when.
* The original `committed_metrics` and `measurement_terms` captured at `create_media_buy` — what the parties signed up for.
A structured dispute task — opening a dispute on the wire, transitioning it through `under_review` / `seller_proposed_adjustment` / `buyer_accepted` / `unresolved_arbitration`, and recording resolution in the audit log — does not exist in 3.2 and is not scheduled for it. The data shape needed to dispute (final records, attestation, measurement window, makegood menu) is already on the wire in 3.1, and Reliable Reporting has since added the first piece of the eventual lifecycle: `reporting-status-issue.json` carries `issue_state` (`open` / `acknowledged` / `resolved` / `waived`), `opened_at`, and an inert `external_ref` for correlation with each side's own ticketing. A shared dispute lifecycle built on those fields is tracked in [#7440](https://github.com/adcontextprotocol/adcp/issues/7440).
A variance beyond `max_variance_percent` is **not** a
`sync_reporting_status` `content_mismatch`. That consumer status is reserved
for contract facts the accepted reporting configuration generation already
fixed — a frozen media buy missing from the denominator, a promised metric
absent, the wrong currency. A disagreement about how many impressions occurred
is a measurement dispute and stays here, under `makegood_policy`.
## Worked example: buyer-attested 3PAS reconciliation
```json title="create_media_buy excerpt — measurement terms" theme={null}
{
"measurement_terms": {
"billing_measurement": {
"vendor": { "domain": "campaignmanager.google.com" },
"max_variance_percent": 10,
"measurement_window": "post_sivt",
"finalization_deadline_hours": 240
},
"makegood_policy": {
"available_remedies": ["additional_delivery", "credit", "invoice_adjustment"]
}
}
}
```
```json title="get_media_buy_delivery — seller's final post-SIVT row" theme={null}
{
"media_buy_deliveries": [
{
"media_buy_id": "mb_q1_2026",
"is_final": true,
"finalized_at": "2026-04-08T18:00:00Z",
"by_package": [
{
"package_id": "pkg_001",
"is_final": true,
"finalized_at": "2026-04-08T18:00:00Z",
"measurement_window": "post_sivt",
"impressions": 5120000,
"spend": 51200
}
]
}
]
}
```
```json title="report_usage — buyer's final 3PAS push" theme={null}
{
"idempotency_key": "f9b3...e2a1",
"reporting_period": { "start": "2026-03-01T00:00:00Z", "end": "2026-03-31T23:59:59Z" },
"usage": [
{
"account": { "account_id": "acct_acme_seller" },
"media_buy_id": "mb_q1_2026",
"currency": "USD",
"impressions": 5040000,
"vendor_cost": 50400,
"final": true,
"finalized_at": "2026-04-09T14:32:00Z",
"measurement_window": "post_sivt"
}
]
}
```
Variance: `|5120000 - 5040000| / 5120000 = 1.56%` — well under the 10% threshold. Seller invoices on the buyer's 5.04M impressions × the agreed rate. Both sides retain audit-traceable final records.
## Related
* [`measurement-terms`](https://adcontextprotocol.org/schemas/3.2.8/core/measurement-terms.json) — schema
* [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) — seller-side finality flags
* [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) — buyer-side / third-party finality flags
* [Accountability](/dist/docs/3.2.8/media-buy/advanced-topics/accountability) — performance standards, makegood remedies, cancellation
* [Reporting capabilities and measurement windows](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting)
* [Reliable Reporting: implementing `reporting.core`](/dist/docs/3.2.8/media-buy/reporting-core-implementation-guide) — the operational delivery contract for the seller-produced feed
* [`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status) — buyer-to-seller consumption status, and why it is not a dispute channel
# Pricing Models
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models
AdCP pricing models — CPM, CPCV, CPP, CPC, CPA, revenue share, time-based, and DOOH pricing. Publisher-declared, buyer-selected model with rate card support.
AdCP supports multiple pricing models to accommodate different advertising channels and business objectives. Publishers declare which pricing models they support, and buyers select from available options.
## Publisher-Declared, Buyer-Selected Model
### How It Works
1. **Publishers declare pricing options** in their products via `pricing_options` array (each with unique `pricing_option_id`)
2. **Buyers discover available options** through `get_products`
3. **Buyers select a specific option** when creating a media buy via `pricing_option_id`
4. **Delivery is measured** according to the declared `delivery_measurement` provider
### Key Benefits
* **Flexibility**: Publishers can offer multiple pricing models for the same inventory
* **Currency Support**: Publishers specify supported currencies; buyers must match
* **Market Standards**: Each channel (TV, video, display, performance) can use its natural pricing unit
* **Clear Expectations**: Both parties agree on pricing before campaign launch
## Measurement & Source of Truth
### Measurement Provider as Source of Truth
**The product declares the measurement provider, and the buyer accepts that provider as the source of truth for the buy.**
Publishers specify their measurement provider in the product:
```json theme={null}
{
"product_id": "premium_video",
"delivery_measurement": {
"provider": "Google Ad Manager with IAS viewability verification",
"notes": "MRC-accredited viewability measurement. 50% in-view for 1 second (display) or 2 seconds (video)."
}
}
```
**Common Measurement Providers:**
* **Ad Servers**: Google Ad Manager, Freewheel, SpringServe
* **Attention Metrics**: Adelaide, Lumen, TVision
* **Third-Party Verification**: IAS, DoubleVerify, Scope3
* **TV/Audio Measurement**: Nielsen, Comscore, iSpot.tv, Triton Digital
* **DOOH**: Geopath, Vistar, Place Exchange
By accepting the product, buyers agree to use the declared measurement provider as the authoritative source for delivery metrics.
### Measurement Terms and Performance Standards
Beyond declaring a provider, sellers can publish structured terms on products — and buyers can negotiate them at buy creation. These are two separate concerns:
* **`measurement_terms`** — Who counts the billing metric and what happens when thresholds are breached (makegoods)
* **`performance_standards`** — What rate thresholds apply (viewability, IVT, completion, brand safety, attention)
```json theme={null}
{
"product_id": "premium_guaranteed_video",
"delivery_measurement": {
"provider": "Google Ad Manager with DoubleVerify verification",
"notes": "MRC-accredited viewability. DV IVT filtering enabled."
},
"measurement_terms": {
"billing_measurement": {
"vendor": { "domain": "admanager.google.com" },
"max_variance_percent": 10
},
"makegood_policy": {
"available_remedies": ["additional_delivery", "credit", "invoice_adjustment"]
}
},
"performance_standards": [
{
"metric": "viewability",
"threshold": 0.70,
"standard": "mrc",
"vendor": { "domain": "doubleverify.com" }
},
{
"metric": "ivt",
"threshold": 0.05,
"vendor": { "domain": "doubleverify.com" }
},
{
"metric": "completion_rate",
"threshold": 0.80,
"vendor": { "domain": "doubleverify.com" }
}
]
}
```
**Measurement terms fields:**
* **`billing_measurement`** — Which vendor's count of the billing metric (determined by `pricing_model`) governs invoicing. `max_variance_percent` defines the threshold at which the non-billing party's count divergence triggers resolution.
* **`makegood_policy`** — Closed menu of remedies available when any performance standard or billing variance is breached. Three remedy types: `additional_delivery` (extend/add impressions, like-for-like), `credit` (toward future buys), `invoice_adjustment` (reduce current invoice). Seller proposes from this menu; buyer accepts or disputes.
**Performance standards fields:**
Each entry in the `performance_standards` array specifies:
* **`metric`** — What is measured: `viewability`, `ivt`, `completion_rate`, `brand_safety`, `attention_score`
* **`threshold`** — Rate as a decimal (0-1). Whether this is a floor or ceiling depends on the metric: viewability, completion_rate, brand_safety, attention_score are floors (must exceed); ivt is a ceiling (must not exceed).
* **`standard`** — Required for viewability (`"mrc"` or `"groupm"`). Omit for other metrics.
* **`vendor`** — Who measures it, identified by domain. When agreed on a confirmed package, creatives MUST include tracker assets from specified vendors.
**Negotiation flow:**
1. Seller publishes `measurement_terms` and `performance_standards` on the product (defaults)
2. Buyer proposes overrides on the package request at `create_media_buy`
3. Seller accepts (echoes on confirmed package), rejects (`TERMS_REJECTED`), or adjusts (returns modified terms)
4. If a threshold is breached, seller proposes a remedy from the agreed `makegood_policy`; buyer accepts or disputes
When the buyer omits these fields, the product's defaults apply.
### Cancellation Policy
Guaranteed products can declare a `cancellation_policy` with the minimum notice period required before cancellation takes effect:
```json theme={null}
{
"product_id": "premium_guaranteed_video",
"delivery_type": "guaranteed",
"cancellation_policy": {
"notice_period": { "interval": 30, "unit": "days" },
"cancellation_fee": { "type": "percent_remaining", "rate": 0.5 }
}
}
```
**Cancellation fee types:**
* **`percent_remaining`** — Percentage of remaining committed spend (requires `rate`, e.g., `0.5` for 50%)
* **`full_commitment`** — Buyer owes the full committed budget regardless of delivery
* **`fixed_fee`** — Flat monetary amount (requires `amount` in the buy's currency)
* **`none`** — No cancellation fee (cancellation with notice is free)
Unlike `measurement_terms`, cancellation policy is not a negotiation surface — the seller declares it and the buyer accepts it by creating a media buy against the product. A guaranteed buy canceled without sufficient notice incurs the declared cancellation fee.
### Best Practices
**For Publishers:**
* Clearly identify your measurement provider (ad server and any third-party verification)
* Explain your measurement methodology in plain language
* For DOOH, specify your audience measurement source (e.g., Geopath, venue sensors)
**For Buyers:**
* Review the measurement provider before committing budget
* Ensure the provider meets your campaign requirements
* Negotiate audit rights in contracts if needed
## Supported Pricing Models
### CPM (Cost Per Mille)
**Cost per 1,000 impressions** - Traditional display advertising pricing.
**Use Cases**: Display, native, banner advertising
**Example**:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpm-option.json",
"pricing_option_id": "cpm_usd_guaranteed",
"pricing_model": "cpm",
"fixed_price": 12.50,
"currency": "USD",
"min_spend_per_package": 5000
}
```
**Billing**: Charged per 1,000 ad impressions served
***
### vCPM (Viewable Cost Per Mille)
**Cost per 1,000 viewable impressions** - Payment only for impressions meeting MRC viewability standard.
**Use Cases**: Display, native, video advertising with viewability guarantee
**Viewability Standard**: MRC (Media Rating Council) standard requires:
* **Display ads**: 50% of pixels in-view for at least 1 continuous second
* **Video ads**: 50% of pixels in-view for at least 2 continuous seconds
**Example**:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/vcpm-option.json",
"pricing_option_id": "vcpm_usd_guaranteed",
"pricing_model": "vcpm",
"fixed_price": 18.50,
"currency": "USD",
"min_spend_per_package": 5000
}
```
**Billing**: Charged per 1,000 viewable impressions (impressions meeting MRC viewability threshold). Viewability is measured by the declared measurement provider.
**Measurement**: When available, publishers declare their viewability measurement provider in the optional `delivery_measurement` field. Common providers include IAS (Integral Ad Science), DoubleVerify, MOAT, and Google Active View.
***
### CPCV (Cost Per Completed View)
**Cost per 100% video/audio completion** - Payment only for fully completed views.
**Use Cases**: Video campaigns, audio ads, pre-roll video
**Example**:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpcv-option.json",
"pricing_option_id": "cpcv_usd_guaranteed",
"pricing_model": "cpcv",
"fixed_price": 0.15,
"currency": "USD"
}
```
**Billing**: Charged only when viewer completes 100% of the video/audio ad. Completion is measured by the declared measurement provider.
***
### CPV (Cost Per View)
**Cost per view at threshold** - Payment when viewer reaches publisher-defined threshold.
**Use Cases**: Video campaigns with shorter completion requirements
**Example**:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpv-option.json",
"pricing_option_id": "cpv_usd_50pct",
"pricing_model": "cpv",
"fixed_price": 0.08,
"currency": "USD",
"parameters": {
"view_threshold": 0.5
}
}
```
**Billing**: Charged when viewer reaches threshold (e.g., 50% completion, 30 seconds)
**Parameters**:
* `view_threshold`: Decimal from 0.0 to 1.0 (e.g., 0.5 = 50% completion)
***
### CPP (Cost Per Point)
**Cost per Gross Rating Point** - Traditional TV/radio buying metric.
**Use Cases**: Connected TV, linear TV, radio, audio streaming
**Example**:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpp-option.json",
"pricing_option_id": "cpp_usd_a18-49",
"pricing_model": "cpp",
"fixed_price": 250.00,
"currency": "USD",
"parameters": {
"demographic": "A18-49",
"min_points": 50
},
"min_spend_per_package": 12500
}
```
**Billing**: Charged per rating point delivered to target demographic
**Parameters**:
* `demographic`: Target demographic (e.g., "A18-49", "W25-54", "M35+")
* `min_points`: Minimum GRP commitment required
**Metrics Reported**:
* `grps`: Total Gross Rating Points delivered
* `reach`: Unique individuals reached
* `frequency`: Average frequency per individual
**Measurement Requirements**:
CPP pricing requires **certified demographic measurement**. Publishers should declare their measurement provider:
```json theme={null}
{
"pricing_model": "cpp",
"fixed_price": 250.00,
"delivery_measurement": {
"provider": "Nielsen DAR",
"notes": "Panel-based demographic measurement for A18-49. GRP reports available weekly."
}
}
```
**Common Measurement Providers for CPP**:
* **Nielsen DAR/TV**: Industry-standard TV measurement
* **Comscore**: Campaign Ratings for CTV
* **iSpot.tv**: Advanced TV analytics
* **Triton Digital**: Audio/streaming measurement
Buyers should verify the measurement provider meets their campaign requirements before accepting CPP deals.
***
### CPC (Cost Per Click)
**Cost per click** - Performance-based pricing for engagement.
**Use Cases**: Direct response campaigns, search ads, social advertising
**Example**:
```json theme={null}
{
"pricing_model": "cpc",
"currency": "USD",
"floor_price": 0.50,
"price_guidance": {
"p50": 1.20,
"p75": 2.00
}
}
```
**Billing**: Charged only when user clicks the ad
***
### CPA (Cost Per Acquisition)
**Cost per conversion event** - Advertiser pays when a defined conversion occurs.
**Use Cases**: Retail media (pay per order), lead generation, app install campaigns, commerce media
**Example**:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpa-option.json",
"pricing_option_id": "cpa_usd_purchase",
"pricing_model": "cpa",
"event_type": "purchase",
"fixed_price": 5.00,
"currency": "USD"
}
```
**Billing**: Charged a fixed price when the specified `event_type` fires. The pricing option declares what event triggers billing — this is independent of `optimization_goals`, which controls delivery optimization.
**Parameters**:
* `event_type` (required): The conversion event that triggers billing. Uses the standard event type enum (e.g., `purchase`, `lead`, `app_install`, `add_to_cart`, `subscribe` for paid subscriptions, `follow` for free durable opt-ins).
* `event_source_id` (optional): When present, only events from this specific source count toward billing. Must match an event source configured via `sync_event_sources`. When omitted, any event of the specified `event_type` counts.
**Example** (different rates by event source):
```json theme={null}
{
"pricing_options": [
{
"pricing_option_id": "cpa_online_purchase",
"pricing_model": "cpa",
"event_type": "purchase",
"event_source_id": "website_pixel",
"fixed_price": 5.00,
"currency": "USD"
},
{
"pricing_option_id": "cpa_instore_purchase",
"pricing_model": "cpa",
"event_type": "purchase",
"event_source_id": "instore_attribution",
"fixed_price": 3.00,
"currency": "USD"
}
]
}
```
**Pricing vs. optimization**: The CPA pricing option's `event_type` (what triggers billing) is independent of the package's `optimization_goals` (what the platform optimizes delivery toward). For example, a package can use CPA pricing on `lead` events while setting an event goal with `event_sources` containing purchase events and `target: { kind: "per_ad_spend", value: 4.0 }` — billing fires on leads, but delivery is optimized for downstream purchase return.
**Refunds and adjustments**: Refund handling and conversion adjustment policies are commercial terms between buyer and seller. The protocol does not govern clawbacks or billing credits for refunded conversions.
**Note**: CPA replaces the need for separate "CPO" (Cost Per Order) or "CPL" (Cost Per Lead) pricing models. A seller can offer multiple CPA options with different event types, event sources, and prices on the same product.
***
### Revenue Share
**Percentage of settled attributed value** - Advertiser pays a fixed commission rate on the portion of attributed conversion value eligible under the parties' agreement.
**Use Cases**: Affiliate networks, content commerce, performance partnerships, and other outcome-priced media
```json theme={null}
{
"pricing_option_id": "affiliate_purchase_4pct",
"pricing_model": "revenue_share",
"event_type": "purchase",
"event_source_id": "affiliate_attribution",
"commission_rate": 0.04,
"currency": "USD",
"commission_basis_description": "Net merchandise value after discounts, excluding tax and shipping; returns removed before commission lock."
}
```
`commission_rate` is a decimal proportion: `0.04` means 4%. Revenue share uses contingent pricing, not fixed-unit or auction pricing, so the option does not carry `fixed_price`, `floor_price`, `price_guidance`, or `max_bid`, and the package request does not carry `bid_price`.
**Billing formula**:
```text theme={null}
spend = round_currency(commissionable_value * commission_rate)
```
`commissionable_value` is the settled value eligible for commission. It is distinct from `conversion_value`, which remains the total attributed value for analytics. The difference may reflect excluded tax or shipping, discounts, ineligible items, returns, or cancellations. `commission_basis_description` tells operators how the authoritative party calculates the eligible amount.
**Settlement flow**:
1. The buyer registers the declared `event_source_id` through `sync_event_sources`.
2. The package's `measurement_terms.billing_measurement` names the authoritative party and commission-lock `measurement_window`.
3. Provisional delivery may report conversion and commissionable values while the return window is open.
4. `adjusted` or `window_update` reports replace earlier values as returns and cancellations settle.
5. A final row reports `commissionable_value`, calculated `spend`, `is_final: true`, and `finalized_at`.
For revenue share, package `budget` is the maximum commission payable—not attributed sales. Sellers must not invoice above that budget without an accepted budget update.
When billing is buyer- or vendor-attested, `report_usage` carries `media_buy_id`, `pricing_option_id`, `commissionable_value`, and `vendor_cost`; the seller verifies the formula against the selected pricing option.
Revenue share is channel-independent. Affiliate is the immediate use case, but sellers may offer this pricing model on other channels where the same commercial contract applies.
***
### Flat Rate
**Fixed cost** - Single payment regardless of delivery volume.
**Use Cases**: Sponsorships, takeovers, exclusive placements, branded content, DOOH fixed slots
**Example** (sponsorship):
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/flat-rate-option.json",
"pricing_option_id": "flat_rate_usd_sponsorship",
"pricing_model": "flat_rate",
"fixed_price": 50000.00,
"currency": "USD"
}
```
**Example** (DOOH slot with parameters):
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/flat-rate-option.json",
"pricing_option_id": "flat_rate_usd_dooh_morning",
"pricing_model": "flat_rate",
"fixed_price": 5000.00,
"currency": "USD",
"parameters": {
"type": "dooh",
"daypart": "morning_commute",
"duration_hours": 4,
"sov_percentage": 25,
"slot_span": 2,
"loop_position": "adjacent_to_content_break",
"estimated_impressions": 120000
}
}
```
**Billing**: Fixed cost for the entire campaign period regardless of delivery volume.
**DOOH parameters** (`parameters.type: "dooh"`):
* `sov_percentage`: Guaranteed time share as a percentage (0-100). Compare it with reported `dooh_metrics.sov_achieved` by dividing `sov_percentage` by 100.
* `slot_span`: Number of consecutive loop slots in this seller-packaged offer. It guarantees contiguity, but not position unless `loop_position` is present.
* `loop_position`: Seller-defined loop-position label, such as `any`, `first`, `last`, or `adjacent_to_content_break`. The vocabulary is open; buyers accept unknown values as opaque, with no position guarantee they understand.
* `loop_duration_seconds`: Deprecated compatibility copy of the placement's `dooh_placement_attributes.loop_duration_seconds`. New integrations read the placement-level value; when both are present they must agree. Offers with different loop durations use distinct placements or products rather than pricing-option-specific copies.
* `min_plays_per_hour`: Minimum guaranteed plays per hour
* `venue_package`: Named collection of screens
* `duration_hours`: Duration of the slot in hours (e.g., 24 for a full-day takeover)
* `daypart`: Named daypart (e.g., `morning_commute`, `evening_rush`)
* `estimated_impressions`: Audience impression estimate (informational, not a delivery guarantee)
Sponsorship flat_rate options omit `parameters` — the fixed price covers the placement without DOOH-specific constraints.
Share of voice is always duration-weighted. For a loop with segment durations
of 10, 10, 20, and 40 seconds, reserving the first two consecutive segments is
20 / 80 = 25% SOV, not 2 / 4 = 50%. On equal-duration loops, time share and
slot-count share produce the same result. Delivery reports use the corresponding
0.0-1.0 scale, so a contracted `sov_percentage` of `25` is reconciled against
`dooh_metrics.sov_achieved` of `0.25`.
***
### Time (Cost Per Time Unit)
**Cost per time unit** - Rate scales with campaign duration, enabling self-serve sponsorships.
**Use Cases**: Homepage takeovers, section sponsorships, premium placements where price depends on booking duration
**Example**:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/time-option.json",
"pricing_option_id": "time_usd_daily",
"pricing_model": "time",
"fixed_price": 50000.00,
"currency": "USD",
"parameters": {
"time_unit": "day",
"min_duration": 1,
"max_duration": 30
}
}
```
**Billing**: Cost = `fixed_price` x number of `time_unit`s in the campaign flight. For example, a 3-day campaign at \$50,000/day = \$150,000 total.
**Parameters**:
* `time_unit` (required): `"hour"`, `"day"`, `"week"`, or `"month"`
* `min_duration` (optional): Minimum booking duration in time units
* `max_duration` (optional): Maximum booking duration in time units
**Time Unit Calculation**:
| Time Unit | Calculation |
| - | - |
| `hour` | rate x hours in flight |
| `day` | rate x calendar days in flight |
| `week` | rate x weeks (seller-defined rounding) |
| `month` | rate x months (seller-defined pro-rating) |
**Comparison with Flat Rate**:
| Aspect | Flat Rate | Time |
| - | - | - |
| Semantics | Fixed total cost | Rate x duration |
| `fixed_price` means | Total campaign cost | Cost per time unit |
| Buyer flexibility | Must negotiate duration | Self-serve any duration |
| Use case | Fixed sponsorships | Scalable sponsorships |
***
## Digital Out-of-Home (DOOH) Pricing
DOOH advertising uses existing pricing models—typically **CPM** or **flat_rate**—with optional parameters to describe the inventory allocation.
### Basic Concepts
* **CPM for DOOH**: Priced per thousand impressions, where impressions are calculated based on venue traffic (e.g., Geopath data)
* **Flat rate for DOOH**: Fixed cost for specific duration or allocation (hourly, daily, or exclusive takeover)
### Simple Example: Billboard Takeover
```json theme={null}
{
"product_id": "billboard_takeover",
"name": "Premium Billboard - 24 Hour Takeover",
"pricing_options": [{
"pricing_model": "flat_rate",
"fixed_price": 50000.00,
"currency": "USD"
}],
"delivery_measurement": {
"provider": "Geopath",
"notes": "Venue traffic data updated monthly. Estimated 2.5M impressions over 24 hours."
}
}
```
### DOOH parameters (optional)
For flat_rate DOOH inventory, publishers may include a `parameters` object with `"type": "dooh"`. See the [flat_rate pricing model](#flat-rate) section above for a complete example and full field list.
**Note**: DOOH measurement and buying practices vary by market. Publishers should clearly explain their measurement methodology and inventory allocation in the product description and `delivery_measurement` field.
***
## Price Breakdown
When buyer and seller have negotiated discounts and commissions, the `price_breakdown` object discloses how `fixed_price` was derived from the rate card. This is optional — sellers who don't need breakdowns omit it entirely, with zero overhead to existing implementations.
`price_breakdown` is a planning-layer construct. It exists on pricing options and confirmed packages within AdCP — it does not propagate into impression-level OpenRTB bid requests or responses.
### Structure
```json theme={null}
{
"pricing_option_id": "cpm_eur_premium",
"pricing_model": "cpm",
"fixed_price": 11.90,
"currency": "EUR",
"price_breakdown": {
"list_price": 14.00,
"adjustments": [
{ "kind": "discount", "name": "volume", "rate": 0.15, "description": "12x frequency discount" },
{ "kind": "commission", "name": "agency", "rate": 0.15, "description": "Agency commission" },
{ "kind": "settlement", "name": "cash_discount", "rate": 0.02, "description": "2% discount for payment within 10 days" }
]
}
}
```
* `list_price` — the rate card or base price before any adjustments
* `adjustments` — ordered list of adjustments, each categorized by `kind`
* `fixed_price` (on the parent pricing option) — must equal the result of applying all `fee` and `discount` adjustments sequentially to `list_price`
Implementations should ignore unrecognized fields in `price_breakdown` and its adjustments to support forward compatibility.
### Adjustment Kinds
Adjustments fall into four kinds based on their economic effect:
| Kind | Effect on buyer price | Effect on publisher revenue | When applied |
| - | - | - | - |
| `fee` | Increases it | Increases it | Before quoting — walks `list_price` up toward `fixed_price` |
| `discount` | Reduces it | Reduces it | Before quoting — walks `list_price` down toward `fixed_price` |
| `commission` | None — budget includes it | Reduces it (revenue split) | Revenue allocation between intermediary and publisher |
| `settlement` | None — post-invoice | Reduces actual payment | At invoicing or payment time |
**Fees** increase what the buyer pays. Ad serving fees, data/targeting surcharges, and brand safety verification costs are additive to the base price. Without fee adjustments, these would be opaque within `list_price`.
**Discounts** reduce what the buyer pays. Volume discounts, negotiated rates, and early booking discounts all lower both the buyer's cost and the publisher's revenue.
**Commissions** are revenue splits. The buyer's price and budget don't change — commission determines how the payment is divided between the intermediary (e.g., agency) and the publisher. Budgets are always managed inclusive of commissions. Multiple commission adjustments compound sequentially, like discounts — e.g., a 15% agency commission followed by a 5% trading desk fee means the publisher receives `budget × 0.85 × 0.95`.
**Settlement adjustments** are applied at invoicing or payment time (e.g., a cash discount for early payment). They don't affect the committed price or budget. Retroactive rebates and performance incentives are out of scope for `price_breakdown` and would be handled through reconciliation workflows.
### Beneficiary
Each adjustment may include an optional `beneficiary` field identifying who receives the adjustment's value. This is most useful for commission adjustments in multi-intermediary chains:
```json theme={null}
{ "kind": "commission", "name": "agency", "rate": 0.15, "beneficiary": "mediaagency.example.com" },
{ "kind": "commission", "name": "trading_desk", "rate": 0.05, "beneficiary": "tradingdesk.example.com" }
```
The value can be a sellers.json domain, an AdCP account ID, or a human-readable party name.
### Invariant
The invariant is: `list_price` with all `fee` and `discount` adjustments applied sequentially equals `fixed_price`. Commission and settlement adjustments don't participate — they're disclosed for transparency. If no fee or discount adjustments are present, `fixed_price` must equal `list_price`.
This invariant applies only when `fixed_price` is present on the parent object. For auction-based packages, `price_breakdown` is informational — see [On Confirmed Packages](#on-confirmed-packages).
Fee and discount adjustments compound in array order using these formulas:
```
For rate-based fees: running = running × (1 + rate)
For amount-based fees: running = running + amount
For rate-based discounts: running = running × (1 − rate)
For amount-based discounts: running = running − amount
```
All monetary values are rounded to the precision of the currency (e.g., 2 decimal places for EUR/USD) at each step. The invariant holds after rounding.
Example with mixed adjustments:
```
list_price: 12.00
fee, amount: 2.00 → 12.00 + 2.00 = 14.00
discount, rate: 0.15 → 14.00 × 0.85 = 11.90
fixed_price: 11.90 ✓
```
For the structure example above: 14.00 × (1 − 0.15) = 11.90 ✓ (no fee adjustments in that example)
### Rate vs. Amount
Each adjustment must include exactly one of `rate` or `amount`:
* `rate` — decimal proportion, strictly between 0 and 1 exclusive (0 \< rate \< 1), e.g., 0.15 for 15%
* `amount` — positive number (> 0) in the pricing option's currency
```json theme={null}
{ "kind": "discount", "name": "volume", "rate": 0.15 }
{ "kind": "discount", "name": "negotiated", "amount": 2.00, "description": "Flat rate reduction" }
```
### Budgets and Commission
Budgets are always denominated at the `fixed_price` level, inclusive of commissions. If a buyer commits €10,000 at an €11.90 CPM, that €10,000 is the buyer's cost. The agency takes their commission from that amount; the publisher receives the remainder.
This means a buyer agent comparing rates across sellers can use `fixed_price` directly — it's the actual cost per unit, regardless of the underlying commission structure.
### On Confirmed Packages
The `price_breakdown` field also appears on the package response (confirmed line item). It is seller-populated — buyer agents should treat it as read-only.
**Fixed-price packages** echo the pricing option's breakdown:
```json theme={null}
{
"package_id": "pkg_12345",
"product_id": "premium_display",
"pricing_option_id": "cpm_eur_premium",
"fixed_price": 11.90,
"budget": 10000,
"price_breakdown": {
"list_price": 14.00,
"adjustments": [
{ "kind": "discount", "name": "volume", "rate": 0.15, "description": "12x frequency discount" },
{ "kind": "commission", "name": "agency", "rate": 0.15, "description": "Agency commission" },
{ "kind": "settlement", "name": "cash_discount", "rate": 0.02, "description": "2% for payment within 10 days" }
]
}
}
```
**Auction-based packages** use `price_breakdown` to disclose commission and settlement terms against the clearing price. For auction packages, `list_price` is set to the clearing price since there is no rate card derivation to disclose. The discount invariant does not apply — the breakdown is informational only:
```json theme={null}
{
"package_id": "pkg_67890",
"product_id": "premium_display",
"pricing_option_id": "cpm_eur_auction",
"bidding": { "bid_amount": 12.50 },
"budget": 10000,
"price_breakdown": {
"list_price": 12.50,
"adjustments": [
{ "kind": "commission", "name": "agency", "rate": 0.15, "description": "Agency commission" },
{ "kind": "settlement", "name": "cash_discount", "rate": 0.02, "description": "2% for payment within 10 days" }
]
}
}
```
***
## Eligible Adjustments
Publishers can declare which adjustment kinds apply to a pricing option using `eligible_adjustments`. This tells buyer agents upfront whether discounts, commissions, or settlement terms are available — before any negotiation begins.
```json theme={null}
{
"pricing_option_id": "cpm_eur_standard",
"pricing_model": "cpm",
"fixed_price": 14.00,
"currency": "EUR",
"eligible_adjustments": ["fee", "discount", "commission", "settlement"]
}
```
When `eligible_adjustments` is present, the buyer knows which kinds of adjustments to expect or request. When absent, no adjustments are pre-declared — the buyer should check `price_breakdown` if present for any adjustments that were already applied.
This field pairs with `price_breakdown`: `eligible_adjustments` signals what is *possible*, while `price_breakdown` shows what was *applied*.
***
## Multi-Currency Support
Publishers can offer the same product in multiple currencies:
```json theme={null}
{
"product_id": "premium_video",
"pricing_options": [
{
"pricing_option_id": "cpm_usd_guaranteed",
"pricing_model": "cpm",
"fixed_price": 45.00,
"currency": "USD"
},
{
"pricing_option_id": "cpm_eur_guaranteed",
"pricing_model": "cpm",
"fixed_price": 40.00,
"currency": "EUR"
},
{
"pricing_option_id": "cpm_gbp_guaranteed",
"pricing_model": "cpm",
"fixed_price": 35.00,
"currency": "GBP"
}
]
}
```
**Buyer Responsibility**: Buyers must select a currency that the publisher supports.
## Fixed vs. Auction Pricing
### Fixed Pricing (`fixed_price` present)
* Publisher sets a fixed price
* Price is guaranteed and predictable
* Common for guaranteed inventory
* Include `fixed_price` field
### Auction Pricing (`fixed_price` absent)
* Final price determined through auction
* Publisher provides `floor_price` (hard minimum) and optional `price_guidance` (percentile hints)
* Common for non-guaranteed inventory
* Buyer expresses execution intent explicitly with `bidding.bid_amount` or `bidding.max_bid`
The pricing option is the seller's commercial offer; `bidding` is the buyer's execution instruction. The pricing option supplies the auction unit and must use the media-buy currency. Every package budget, minimum-spend target, and canonical bidding amount uses that single denomination; split packages requiring another currency into a separate media buy. In 3.2, pricing-option `max_bid` and package `bid_price` remain only as deprecated migration fields. A seller-offered boolean no longer determines whether buyer input is a manual bid, auction ceiling, or average outcome-cost control.
**Auction Example**:
```json theme={null}
{
"pricing_option_id": "cpcv_usd_auction",
"pricing_model": "cpcv",
"currency": "USD",
"floor_price": 0.08,
"price_guidance": {
"p25": 0.10,
"p50": 0.12,
"p75": 0.15,
"p90": 0.18
}
}
```
## Buyer Selection Process
Each package specifies its own pricing option, which determines pricing model and auction unit. Its declared currency must match the single media-buy currency:
```json theme={null}
{
"start_time": "2025-01-01T00:00:00Z",
"end_time": "2025-01-31T23:59:59Z",
"brand": {
"domain": "acmecorp.com"
},
"brief": "Q1 Brand Campaign",
"packages": [{
"product_id": "premium_ctv",
"format_option_refs": [{ "scope": "product", "format_option_id": "video_30s" }],
"pricing_option_id": "cpcv_usd_auction",
"budget": 50000,
"pacing": "even",
"bidding": { "max_bid": 0.16 }
}]
}
```
**How it works:**
1. Package selects `pricing_option_id` from product (e.g., "cpcv_usd_auction")
2. Pricing option determines pricing model, auction unit, and fixed vs auction; its currency must match the media buy
3. Package `budget` and all canonical `bidding` amounts use the media-buy currency
4. Auction-based pricing uses explicit `bidding.bid_amount` for a manual auction bid or `bidding.max_bid` for a hard per-auction ceiling, expressed per the pricing option's unit
5. Sellers reject currency-mismatched packages rather than converting amounts; buyers split them into separate media buys
## Reporting Metrics by Pricing Model
Different pricing models report different primary metrics:
| Pricing Model | Primary Metric | Secondary Metrics |
| - | - | - |
| CPM | impressions | clicks, ctr, spend |
| vCPM | viewable_impressions | impressions, viewability_rate, spend |
| CPCV | completed_views | impressions, completion_rate, spend |
| CPV | views | impressions, quartile_data, spend |
| CPP | grps | reach, frequency, spend |
| CPC | clicks | impressions, ctr, spend |
| CPA | conversions | conversion_value, cost_per_acquisition, roas, spend |
| Flat Rate | N/A | impressions, reach, frequency |
| Time | N/A | impressions, reach, frequency |
## Example: Multi-Model CTV Product
A publisher offering Connected TV inventory with multiple pricing options:
```json theme={null}
{
"product_id": "ctv_premium_sports",
"name": "Premium Sports CTV",
"description": "High-engagement sports content on CTV devices",
"format_options": [
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } },
{ "format_option_id": "video_30s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 30000 } }
],
"delivery_type": "guaranteed",
"pricing_options": [
{
"pricing_option_id": "cpm_usd_guaranteed",
"pricing_model": "cpm",
"fixed_price": 55.00,
"currency": "USD",
"min_spend_per_package": 15000
},
{
"pricing_option_id": "cpcv_usd_guaranteed",
"pricing_model": "cpcv",
"fixed_price": 0.22,
"currency": "USD",
"min_spend_per_package": 15000
},
{
"pricing_option_id": "cpp_usd_m18-49",
"pricing_model": "cpp",
"fixed_price": 300.00,
"currency": "USD",
"parameters": {
"demographic": "M18-49",
"min_points": 50
},
"min_spend_per_package": 15000
}
]
}
```
A buyer could choose CPP pricing if they're planning TV buys, CPCV if optimizing for engagement, or CPM for reach-based campaigns.
## Negotiated and Premium Pricing
Premium sellers — particularly in OOH, CTV sponsorships, and direct deals — often finalize pricing through negotiation rather than publishing fixed rates. AdCP supports this workflow through the existing brief-to-proposal path without requiring a separate quote or price-on-request mechanism.
### Sellers are not required to publish wholesale prices
Product discovery (`get_products`) does not require sellers to disclose wholesale or clearing prices. Sellers may publish products with limited or no public pricing detail — for example, a CTV sponsorship product with audience and format information but no `pricing_options`. The product is discoverable, but the buyer must submit a brief to receive a proposal with actual pricing.
### Selective brief response
Sellers control which briefs they respond to and what pricing they offer. When a seller receives a brief for inventory they choose not to transact on, the protocol-native options are:
* **Omit the product from the proposal entirely** — the buyer sees no proposal for that inventory, signaling unavailability for this request
* **Return `PROPOSAL_NOT_COMMITTED`** — an explicit signal that the seller reviewed the brief but is not offering a committable proposal at this time
Neither requires the seller to disclose why they declined. This is the protocol-native equivalent of "price not available without negotiation."
### The existing flow covers negotiated deals
The standard path for negotiated-price inventory is:
1. **Seller publishes products** with descriptive metadata (audience, formats, properties) but without wholesale pricing
2. **Buyer submits a brief** via `get_products` describing their campaign goals and budget parameters
3. **Seller returns a proposal** with negotiated pricing tailored to the specific brief — or declines to propose
4. **Buyer refines or accepts** the proposal, then passes the `proposal_id` into `create_media_buy`
This mirrors how premium direct deals work today: the seller sees the brief, decides whether to engage, and offers terms specific to the opportunity.
## Best Practices
### For Publishers
1. **Offer relevant pricing models** - Match pricing to your inventory type and buyer expectations
2. **Set appropriate minimums** - Use `min_spend_per_package` to ensure campaign viability
3. **Provide price guidance** - For auction pricing, give realistic floor and percentile data
4. **Consider multi-currency** - Support currencies of your target markets
5. **Document parameters** - Clearly explain thresholds, demographics, and action types
### For Buyers
1. **Select appropriate model** - Choose pricing that aligns with campaign objectives
2. **Match currency** - Ensure you select a currency the publisher supports
3. **Set realistic budgets** - Account for minimum spend requirements
4. **Align goals with pricing** - Set delivery goals that match your pricing model
5. **Monitor relevant metrics** - Focus on the metrics that matter for your pricing model
## Related Documentation
* [Media Products](/dist/docs/3.2.8/media-buy/product-discovery/media-products) - Product model reference
* [Creating Media Buys](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) - How to select pricing when buying
* [Delivery Reporting](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) - Understanding metrics by pricing model
* [Glossary](/dist/docs/3.2.8/reference/glossary) - Pricing and metric definitions
# Sandbox mode
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/advanced-topics/sandbox
AdCP sandbox mode — test product discovery, campaign creation, creatives, and delivery with simulated data. No real spend or production side effects.
## Overview
Sandbox mode lets buyers test the full media buying lifecycle — discovery, campaign creation, creatives, and delivery — without real platform calls or spending real money. Responses contain simulated but realistic data.
Sandbox is **account-level**, not per-request. Once a request references a sandbox account, the entire request is treated as sandbox. This eliminates the risk of accidentally mixing real and test traffic in a multi-step flow.
> [!WARNING]
>
> `account.sandbox` in `get_adcp_capabilities` only advertises support; it does not turn the next media-buy request into a test request. In a natural-key account reference, `sandbox: true` is part of the key that selects the distinct sandbox account and must be repeated on every account-scoped request. In an account-ID namespace, sandbox status belongs to the pre-existing account selected by `account_id`; adding a sandbox boolean to `{ "account_id": "..." }` is invalid and cannot convert a production account. Discover or otherwise obtain the sandbox ID, verify the returned account has `sandbox: true`, and then use only that ID. Resolve and verify the sandbox account before any spend-committing call. Omitting the selector from a natural key defaults to production and can book real inventory.
## Capabilities discovery
Sellers declare sandbox support in `get_adcp_capabilities`:
```json theme={null}
{
"account": {
"sandbox": true
}
}
```
Check this before using sandbox mode. If `account.sandbox` is not declared or is `false`, the seller does not support sandbox.
## Two paths to sandbox
How you enter sandbox mode depends on the seller's account model (`require_operator_auth`). The two paths are completely different — make sure you follow the right one.
### Buyer-declared accounts (`require_operator_auth: false`)
The seller trusts the agent and does not require per-operator authentication. Sandbox is part of the **natural key** — the same brand/operator pair can have both a production and a sandbox account, distinguished by `sandbox: true`.
**Setup:** Declare a sandbox account via `sync_accounts` with `sandbox: true` on the account entry:
```json theme={null}
// sync_accounts — declare a sandbox account
{
"accounts": [{
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"billing": "operator",
"sandbox": true
}]
}
```
**Usage:** Reference the sandbox account by natural key with `sandbox: true` on every request:
```json theme={null}
// get_products — implicit sandbox
{
"account": {
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"sandbox": true
},
"brief": "Premium CTV inventory for Q2 campaign"
}
```
### Account-id namespaces (`require_operator_auth: true`)
The seller requires each operator to authenticate directly. Sandbox accounts are **pre-existing test accounts on the seller's platform** — think Stripe test mode, Google Ads sandbox accounts, or Snap test advertiser accounts. You do not create them; you discover them.
**Setup:** Discover sandbox accounts via `list_accounts` with the `sandbox: true` filter:
```json theme={null}
// list_accounts — find sandbox accounts
{
"sandbox": true
}
```
The seller returns pre-existing test accounts:
```json theme={null}
{
"accounts": [{
"account_id": "acct_sandbox_acme_001",
"name": "Acme Test Account",
"status": "active",
"sandbox": true
}]
}
```
**Usage:** Reference the sandbox account by `account_id` on every request:
```json theme={null}
// get_products — explicit sandbox
{
"account": { "account_id": "acct_sandbox_acme_001" },
"brief": "Premium CTV inventory for Q2 campaign"
}
```
### Quick reference
| | Buyer-declared (`require_operator_auth: false`) | Account-id namespace (`require_operator_auth: true`) |
| - | - | - |
| **Sandbox accounts** | Declared by buyer via `sync_accounts` | Pre-existing on seller's platform |
| **Discovery** | N/A — buyer creates them | `list_accounts` with `sandbox: true` |
| **Account reference** | Natural key with `sandbox: true` | `account_id` |
| **Real-world analogy** | Self-service test mode | Stripe test mode, Google Ads sandbox |
## Response confirmation
Success responses include `sandbox: true` to confirm the request was processed in sandbox mode:
```json theme={null}
{
"products": [...],
"sandbox": true
}
```
## Full lifecycle example (buyer-declared account)
This example shows the buyer-declared account path. It assumes the sandbox account was declared through `sync_accounts` as in Setup above; a natural key the seller hasn't provisioned returns `ACCOUNT_NOT_FOUND` ([Account references before provisioning](/dist/docs/3.2.8/accounts/overview#account-references-before-provisioning)). For account-id namespaces, resolve the sandbox account through `list_accounts` (or out-of-band onboarding for seller-defined IDs), then replace the natural key account reference with `{ "account_id": "acct_sandbox_acme_001" }` in each step.
### 1. Discover products
```json theme={null}
// get_products
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442066",
"buying_mode": "brief",
"account": {
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"sandbox": true
},
"brief": "CTV inventory for brand awareness"
}
```
### 2. Create a media buy
```json theme={null}
// create_media_buy
{
"account": {
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"sandbox": true
},
"proposal_id": "prop_abc",
"total_budget": { "amount": 50000, "currency": "USD" },
"brand": { "domain": "acme-corp.com" },
"start_time": { "start_type": "asap" },
"end_time": "2026-04-01T00:00:00Z"
}
```
The seller returns a simulated media buy with realistic IDs, packages, and creative deadlines — nothing is booked on any real platform.
### 3. Upload creatives
```json theme={null}
// sync_creatives
{
"account": {
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"sandbox": true
},
"creatives": [{
"creative_id": "hero_video_30s",
"name": "Brand Hero Video 30s",
"format_kind": "video_hosted",
"assets": {
"video": {
"url": "https://cdn.example.com/hero.mp4",
"width": 1920,
"height": 1080,
"duration_ms": 30000
}
}
}],
"assignments": {
"hero_video_30s": ["pkg_001"]
}
}
```
### 4. Check delivery
```json theme={null}
// get_media_buy_delivery
{
"account": {
"brand": { "domain": "acme-corp.com" },
"operator": "acme-corp.com",
"sandbox": true
},
"media_buy_ids": ["mb_sandbox_123"]
}
```
The seller returns simulated delivery metrics — impressions, spend, pacing — as if the campaign were running.
## Sandbox vs dry run
Some sync tasks (`sync_creatives`, `sync_catalogs`) support a `dry_run` parameter. These serve different purposes:
| | Sandbox account | `dry_run` |
| - | - | - |
| **Meaning** | Nothing is real | Preview changes without applying |
| **Scope** | All tasks on the account | Sync tasks only |
| **Side effects** | None (simulated) | None (preview only) |
| **Use case** | Test the full lifecycle | Check what a sync would change before committing |
You can combine them — `dry_run: true` on a sandbox account previews the sync without even updating sandbox state.
> [!WARNING]
>
> The `X-Dry-Run`, `X-Test-Session-ID`, and `X-Mock-Time` HTTP headers are **deprecated**. Sandbox mode replaces them as a protocol-level parameter.
>
> * **Sellers MUST NOT** alter behavior based on these headers. Sandbox mode is determined solely by the account reference. Sellers SHOULD ignore the headers entirely and MAY log a deprecation warning to help buyers identify stale integrations.
> * **Buyers MUST NOT** rely on these headers to prevent production side effects. Use a natural-key account reference with `sandbox: true`, or a preverified sandbox `account_id`; an account ID cannot carry a sandbox flag or convert a production account.
## Seller implementation
When a request references a sandbox account (either via `sandbox: true` in the natural key or via a sandbox `account_id`), agents MUST NOT persist production state or cause real-world side effects:
* **MUST NOT** make real ad platform API calls (no real orders, line items, etc.)
* **MUST NOT** charge real money or create real billing records
* **MUST** validate inputs the same way as production (reject invalid budgets, bad dates, etc.)
* **MUST** return realistic response shapes with simulated data
* **SHOULD** include `sandbox: true` in success responses
Sandbox errors are real validation errors. If a buyer sends an invalid budget using a sandbox account, return a real error — don't simulate fake errors.
For **account-id namespace sellers**: ensure your platform has pre-existing sandbox/test accounts that `list_accounts` can return when filtered with `sandbox: true`, or supply sandbox IDs out-of-band.
For **buyer-declared account sellers**: accept `sandbox: true` as part of the natural key in `sync_accounts` and account references. Treat `(brand, operator, sandbox: true)` as a distinct account from `(brand, operator)`.
## Protocol compliance
Sellers that declare `account.sandbox: true` in capabilities MUST:
* Accept sandbox accounts appropriate to their account model
* Apply sandbox semantics to all requests referencing a sandbox account
* NOT persist production state or cause real-world side effects when processing sandbox requests
* Apply normal input validation (sandbox does not bypass validation)
Sellers SHOULD include `sandbox: true` in success responses when processing a sandbox account request.
# Targeting
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/advanced-topics/targeting
AdCP targeting — natural-language briefs, exact geographic and demographic overlays, seller-offered signals, and real-time decisioning.
AdCP uses briefs for semantic intent and typed overlays for exact, auditable constraints. Publishers return products that describe which overlay semantics they can execute.
## Core principle: semantic intent in briefs, exact constraints in overlays
Use campaign briefs for audience meaning, strategy, and seller-led discovery. Instead of configuring every platform-specific targeting parameter, buyers describe those preferences in plain language:
```json theme={null}
{
"brief": "We want to reach millennial parents in major US metro areas who are interested in sustainable products. Focus on mobile and desktop during evening hours when families are planning purchases."
}
```
Publishers then return products that include the targeting capabilities to reach this audience, with targeting costs built into the media pricing.
Use a typed `targeting_overlay` whenever a requirement has a structured representation and must survive booking and readback. This avoids transmitting the same fact as extra prose and avoids asking the seller to spend tokens inferring a value that code can read deterministically. In particular, numeric demographic predicates such as ages 25–40 and exact country constraints belong in the overlay; prose such as “millennial parents interested in sustainable products” remains in the brief.
## Request mutation semantics
Create and update requests use a request-only targeting input so each
replaceable dimension has three transport-safe states. Discovery criteria,
capability output, accepted commercial terms, and package readback continue to
use strict targeting objects and never contain `null`.
| Wire state for one dimension | Create | Update |
| - | - | - |
| Omitted | Inherit the configured-product or product default | Preserve the current effective value |
| Non-null value | Replace that dimension with the supplied value | Replace that dimension with the supplied value |
| `null` | Explicitly suppress the inherited/default dimension | Clear the current dimension |
An explicit clear cannot remove inherent product scope or make the package
unexecutable. Sellers reject such a request instead of treating `null` as
omission. Mutations are atomic, and successful readback omits cleared
dimensions. Empty arrays are not a clear operation and remain invalid where
the strict dimension requires at least one item.
For example, all three states survive ordinary JSON encoding:
```json theme={null}
{
"package_id": "pkg-1",
"targeting_overlay": {
"geo_regions": ["US-CA"],
"audience_include": null
}
}
```
This replaces `geo_regions`, clears `audience_include`, and preserves an
existing `audience_exclude` because that key is absent. On create, the same
absent exclusion dimension inherits its configured/default value.
An explicit hard requirement does not become optional merely because the buyer put it in prose. Sellers MUST apply unambiguous hard targeting stated only in the brief. When a seller's structured interpretation of hard prose materially affects product eligibility, pricing, or forecasting, it MUST return that interpretation once at the discovery response's `targeting_resolution.brief_targeting`; otherwise confirmation remains a best practice. This lets the buyer verify what will actually be applied without repeating the same interpretation on every product. Unchanged values already supplied in `targeting_overlay` are not repeated.
```json theme={null}
{
"targeting_resolution": {
"brief_targeting": {
"geo_countries": ["US"],
"demographics": {
"age": { "min": 18, "max": 44, "include_unknown": false }
}
}
}
}
```
If both prose and a structured field address the same constraint, buyers SHOULD keep them consistent. Sellers MUST reject contradictory hard requirements with `INVALID_REQUEST`; they do not silently choose one interpretation or turn the conflict into an empty result.
When the buyer wants package-level control over specific selectable signals that the seller offers, use `targeting_overlay.signal_targeting_groups` on the package. Buy-time eligibility comes from the selected product's signal targeting contract: `signal_targeting_allowed`, inline `Product.signal_targeting_options` when present, the seller's [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) feed for wholesale products that omit inline options, and `signal_targeting_rules`. Signals are named targetable dimensions, referenced with `signal_ref`: `scope: "product"` for product-local signal options, `scope: "data_provider"` with `data_provider_domain` for signals defined in a data provider's published adagents.json `signals[]`, or `scope: "signal_source"` with `signal_source_url` for source-native signals that are not published in adagents.json `signals[]`. `signal_ref.scope` is the buy-time resolution path, not provenance, and authoritative enrichment lives on the seller, data provider, or source signal definition. Do not overload `audience_include` or `audience_exclude` for this purpose; those fields are only for first-party audiences registered through [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences).
Products can also expose `included_signals` for signals already bundled into or planned into the product. Those signals are descriptive product metadata, not package-level targeting controls, and buyers do not echo them in `signal_targeting_groups`.
## Daypart timezone semantics
Every `daypart_targets` entry uses either `inventory_local` or a concrete IANA timezone identifier:
```json theme={null}
{
"targeting_overlay": {
"daypart_targets": [
{
"days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
"start_hour": 9,
"end_hour": 11,
"timezone": "America/New_York"
}
]
}
}
```
`inventory_local` evaluates the window in the seller-assigned local civil time of each inventory unit that can deliver the impression—for example, 9–11am at each screen, venue, broadcast station, or publisher property. It never means the buyer, account, or server timezone. A concrete IANA zone evaluates one civil-time clock across all targeted inventory—for example, 9–11am New York time everywhere. Omitting `timezone` defaults to `inventory_local`. Numeric UTC offsets are invalid because they do not define daylight-saving transitions, and sellers MUST validate concrete identifiers against their supported IANA timezone database. A syntactically valid but unknown identifier is `INVALID_REQUEST`.
There is no `user_timezone` or `account_timezone` daypart value. A buyer starting from either preference resolves it to a concrete IANA identifier before sending the request, so later preference changes cannot reinterpret an existing schedule. The daypart delivery clock is independent of `reporting_capabilities.timezone`, which controls report bucketing only.
Evaluate a window by converting each candidate delivery instant into the selected civil clock, then comparing the resulting local day and hour with the half-open `[start_hour, end_hour)` interval. A skipped hour during a spring DST transition has no matching instants; both occurrences of a repeated hour during a fall transition match. Entries are independent and may use different clocks. Sellers MUST NOT silently reinterpret a requested clock. At create or update time, a valid timezone or mode outside the selected product's declared support returns [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature).
Support is product-scoped because one seller may route products through different scheduling systems. For backward compatibility, `daypart_targets: true` means `inventory_local` support only. Concrete IANA execution is explicitly opt-in, and the product declares whether it accepts every valid zone or only an exact subset:
```json theme={null}
{
"overlay_support": {
"daypart_targets": {
"timezone_modes": ["inventory_local", "iana"],
"iana_timezones": ["America/New_York", "America/Chicago"]
}
}
}
```
`iana_timezones: true` advertises every valid identifier in the seller's supported IANA database instead of an exact list. Buyers that will choose dayparts after discovery can require one or both modes through `required_overlay_support.daypart_targets`; they can also include `iana_timezones` to require specific zones. The product declaration—not a seller-wide capability—is the binding execution contract.
## Browser-family targeting
Use `targeting_overlay.browser` and `targeting_overlay.browser_exclude` for portable browser-family constraints. The fields intentionally stop at families: browser versions, user-agent strings, backend segment IDs, and arbitrary ad-server key/value expressions are not part of the contract.
```json theme={null}
{
"targeting_overlay": {
"browser": ["chrome", "safari", "samsung_internet"],
"browser_exclude": ["safari"]
}
}
```
Values within `browser` use OR semantics, and `browser_exclude` wins on overlap, so this example delivers on Chrome or Samsung Internet but not Safari. When `browser` is present, omitted families are not eligible. The canonical families are `chrome`, `safari`, `firefox`, `edge`, `opera`, `samsung_internet`, `android_webview`, `other`, and `unknown`.
`other` means the seller recognizes the browser family but it is not one of the explicitly named families. For example, a FreeWheel connector can map recognized values such as Amazon Silk, Android Browser, or Internet Explorer to `other`. `unknown` means the seller cannot classify the browser into a recognized family. Include either value explicitly when that traffic should be eligible; omitting it from an inclusion list excludes it. Samsung Internet remains distinct from Chrome even though both are Chromium-based. `android_webview` means the impression itself is reliably classified as rendering in Android WebView; a native-app placement or an in-app browser opened after a click is not automatically Android WebView.
Browser family describes the impression delivery and rendering environment, not the post-click landing-page browser. Sellers must not infer it solely from operating system, device, “Web” or “Mobile Web” inventory, or placement. Sellers advertising browser support map these portable values to their platform controls internally. A social or app-only product with only device, OS, or placement controls omits `overlay_support.browser` and `overlay_support.browser_exclude` rather than approximating browser support.
Browser and device constraints intersect. For example, `browser: ["safari"]` with `device_platform: ["android"]` may have no executable inventory. During discovery, the seller excludes an incompatible product or returns a configured product with a sparse, buyer-visible `targeting_resolution.modifications` alternative. At create or update, it rejects an exact combination it cannot enforce rather than silently broadening delivery.
Inclusion and exclusion are independent product capabilities. Use concrete values in `targeting_overlay` when pricing and forecasts must reflect them now, and use `required_overlay_support.browser` or `required_overlay_support.browser_exclude` when package values will be supplied later. Requirement `true` asks for any positive support; `{ "families": ["chrome", "firefox"] }` requires both named families. A product advertises unrestricted support as `true`, or partial support as `{ "families": [...] }`. Products such as CTV, audio, DOOH, or app inventory can omit browser support entirely.
## Portable demographic targeting
Use `targeting_overlay.demographics` when the buyer needs a demographic predicate to survive product discovery, purchase, seller compilation, and readback without being reinterpreted from prose. AdCP 3.2 standardizes age first:
```json theme={null}
{
"targeting_overlay": {
"demographics": {
"age": {
"min": 21,
"max": 35,
"include_unknown": false
}
}
}
}
```
`min` and `max` are inclusive integer ages in completed years. Either may be omitted for an open bound, but at least one is required. Before using an open bound, check the product's `supports_unbounded_min` or `supports_unbounded_max` flag; a seller that declares `false` rejects that direction rather than substituting its supported-age limit. `include_unknown` is always required and has no default: people whose age is unavailable are not silently included in a numeric interval. Sellers also reject a range whose `min` is greater than its `max`.
This field is audience selection, not eligibility policy. Continue to use `age_restriction` for a legal minimum age and verification requirements such as alcohol or gambling controls.
When both fields are present, they compose as an intersection; neither overrides the other. `demographics` selects the intended audience, then `age_restriction` applies the eligibility and verification floor. Unknown-age delivery cannot satisfy a minimum-age restriction, so the combined shape requires `include_unknown: false`. Sellers also reject an empty intersection, such as demographic ages 18–20 with `age_restriction.min: 21`. Package readback preserves both controls independently rather than folding the legal restriction into the applied demographic predicate.
### Product-scoped execution
The seller-wide `get_adcp_capabilities.media_buy.execution.targeting.demographics.supported` flag is only a discovery rollup. Exact support lives on each product because one seller can route products through different ad servers.
A product that accepts arbitrary bounds declares `continuous_bounds`:
```json theme={null}
{
"demographic_targeting": {
"age": {
"execution_modes": ["continuous_bounds"],
"min_supported_age": 18,
"max_supported_age": 65,
"supports_unbounded_min": true,
"supports_unbounded_max": true,
"unknown_handling": "selectable",
"supported_bases": ["verified", "declared", "inferred"],
"supported_verification_methods": ["world_id", "id_document"]
}
}
}
```
A bucket-backed product publishes its actual intervals rather than pretending they are a protocol-wide taxonomy:
```json theme={null}
{
"demographic_targeting": {
"age": {
"execution_modes": ["enumerated_intervals"],
"unknown_handling": "always_excluded",
"intervals": [
{ "interval_id": "age_18_24", "age": { "min": 18, "max": 24, "include_unknown": false } },
{ "interval_id": "age_25_34", "age": { "min": 25, "max": 34, "include_unknown": false } },
{ "interval_id": "age_35_44", "age": { "min": 35, "max": 44, "include_unknown": false } }
]
}
}
}
```
That product cannot execute ages 21–35 exactly: `18–24 ∪ 25–34 ∪ 35–44` broadens the request, while `25–34` narrows it. A direct create or update rejects that request. During `get_products`, however, the seller may return a request-scoped configured product whose sparse `targeting_resolution.modifications` replaces the requested interval with 25–34. Selecting that product accepts the disclosed alternative; the resulting package still stores only an equivalent executable predicate.
`unknown_handling` is one of:
* `selectable`: both `include_unknown: true` and `false` are supported.
* `always_excluded`: only `include_unknown: false` is supported.
* `always_included`: only `include_unknown: true` is supported.
`supported_bases` declares how the product can determine age for an individual impression. Sellers publish only bases whose provenance they can preserve and audit; an opaque platform age bucket does not justify guessing a basis. When omitted, the product makes no basis-aware targeting commitment and rejects buyer requests that specify `accepted_bases`.
### Acceptable age determination
Buyers place determination constraints directly on the requested age range:
```json theme={null}
{
"demographics": {
"age": {
"min": 25,
"max": 34,
"include_unknown": false,
"accepted_bases": ["verified", "declared"],
"accepted_verification_methods": ["world_id", "id_document"]
}
}
}
```
Execution accepts only user-level bases:
* `verified`: an applicable age claim was established through an accepted age-assurance method.
* `declared`: the user supplied an age, date of birth, or threshold affirmation.
* `inferred`: the user's age was predicted from behavior, attributes, or a model.
`population_estimate` is deliberately invalid in targeting. Knowing that 80% of a product audience is 25–34 cannot establish whether the current user is 25–34.
`accepted_bases` constrains provenance; it does not weaken the age predicate. The underlying claim must establish the entire requested interval. A declaration that a user is over 16 cannot establish ages 25–34, and a threshold-only World ID `age_over_18` claim cannot establish the upper bound of 34. Sellers reject these requests rather than silently broadening them.
`age_restriction` remains an independent compliance floor and always wins. When `verification_required` is true, the effective basis is `verified`; its `accepted_methods` are intersected with `accepted_verification_methods`. An empty intersection is invalid. A World ID nullifier, `unique_human` claim, or Orb verification level alone never establishes age—the verified proof must contain an applicable `age_over_N` claim and pass the TMP verification, relying-party binding, freshness, and expiry checks.
### Signal-backed execution
A product can declare the `signals` execution mode when it resolves canonical age intent through catalogued signals. The signal's authoritative definition must carry `demographic_predicate`; its name is never evidence of its bounds. Age-annotated signals also declare `restricted_attributes: ["age"]` so governance checks remain structural.
```json theme={null}
{
"id": "adults_25_34",
"name": "Adults 25–34",
"value_type": "binary",
"restricted_attributes": ["age"],
"demographic_predicate": {
"age": { "min": 25, "max": 34, "include_unknown": false }
}
}
```
Multiple intervals or signals may be unioned only when their canonical predicates cover the request with no gap and no extra age. Implementations compare the represented predicate sets deterministically; an AI agent may propose a mapping, but names, inferred provider IDs, and approximate bucket choices never prove equivalence. For inferred or modeled signals, exactness means equality of the declared demographic predicate—not a claim that the provider knows every person's age perfectly. Methodology, modeling, and coverage metadata continue to describe population-level accuracy.
### Governance interaction
Age is a registered restricted-attribute category because some campaign plans prohibit its use in regulated contexts. A direct `targeting_overlay.demographics.age` predicate and a signal carrying `demographic_predicate.age` are both age-based targeting for governance evaluation. They are blocked only when the applicable campaign plan lists `age` in `restricted_attributes`; the registry entry does not create a global prohibition on otherwise lawful demographic targeting.
### Exact readback
Whenever demographic targeting was requested or applied, package state includes
`targeting_resolution.demographics`. Demographics is one dimension inside the
generic targeting-resolution envelope; it preserves both predicates and the
execution mechanism:
```json theme={null}
{
"targeting_overlay": {
"demographics": {
"age": {
"min": 21,
"include_unknown": false,
"accepted_bases": ["verified", "declared"],
"accepted_verification_methods": ["world_id"]
}
}
},
"targeting_resolution": {
"demographics": {
"requested": {
"age": {
"min": 21,
"include_unknown": false,
"accepted_bases": ["verified", "declared"],
"accepted_verification_methods": ["world_id"]
}
},
"applied": {
"age": { "min": 21, "include_unknown": false }
},
"equivalent": true,
"execution": { "type": "continuous_bounds" },
"applied_bases": ["verified"],
"applied_verification_methods": ["world_id"]
}
}
}
```
`targeting_overlay.demographics` preserves the booked predicate and buyer determination constraints. The demographic resolution's `applied` field contains the canonical predicate actually applied; `equivalent` is always `true` for stored packages, and buyers should still recompute predicate equality from `requested` and `applied`. `applied_bases` and `applied_verification_methods` record the effective configured eligibility paths after intersecting buyer constraints, product capability, and age compliance. They do not assert which path every individual impression used. A seller rejects any non-equivalent or unsupported compilation. The same core `Package` schema carries this readback in synchronous `CreateMediaBuySuccess` responses and terminal async completion artifacts; `get_media_buys` exposes the corresponding `PackageStatus` field. Updates use the request-only per-dimension patch semantics above and refresh the resolution atomically.
## Why Brief-Based Targeting?
### Eliminates Targeting Conflicts
* **Declared capability**: The publisher's product defines what can be executed; explicit overlays carry only the buyer controls that need exact wire semantics
* **Defined composition**: Supported overlays intersect with the product instead of competing through hidden precedence rules
* **Pricing consistency**: Targeting costs are transparent and included in media prices
### Simplifies Implementation
* **Natural language**: Buyers describe needs in familiar terms
* **Publisher expertise**: Publishers know their inventory and audience capabilities best
* **Reduced complexity**: No need to learn platform-specific targeting syntax
### Enables Accurate Pricing
* **Inclusive pricing**: All targeting costs are built into the product price
* **No surprises**: Buyers know the complete cost upfront
* **Market-driven**: Pricing reflects true market value of targeted inventory
## Real-Time Decisioning with TMP
For targeting decisions that must happen at impression time, AdCP uses the **[Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match)**. TMP is the real-time execution layer that evaluates pre-negotiated packages at serve time across any surface.
TMP gives the buyer a real-time look at each eligible impression through two structurally separated operations — Context Match (content relevance) and Identity Match (user eligibility) — without exposing user identity and page context to the buyer simultaneously.
**Key capabilities:**
* **Cross-publisher frequency capping**: Manage user exposure across multiple publishers via the Identity Match path
* **Dynamic audience targeting**: Evaluate audience membership at impression time without sharing PII
* **Brand suitability enforcement**: Real-time content evaluation through the Context Match path
* **First-party data activation**: Use your customer data without exposing it to publishers
**When to use TMP:**
* Cross-publisher frequency caps
* Suppression lists (existing customers, past converters)
* Audience segments that can't be expressed in a brief
* Real-time brand suitability beyond static rules
* Any impression-time decision across web, mobile, CTV, AI assistants, or retail media
See the [TMP documentation](/dist/docs/3.2.8/trusted-match) for the full specification and surface-specific integration guides.
## How Publishers Include Targeting
Publishers incorporate targeting capabilities directly into their product definitions:
### Geographic Targeting
Products specify geographic coverage:
```
"Chicago metro premium display package"
"US national mobile video inventory"
"California lifestyle sites network"
```
### Demographic Targeting
Audience characteristics are built into products:
```
"Millennial-focused social media placements"
"Premium business professional network"
"Family-oriented content sites"
```
### Contextual Targeting
Content alignment is inherent in product descriptions:
```
"Sports content premium video inventory"
"Financial news site network"
"Entertainment property display package"
```
### Device & Platform Targeting
Technical specifications included in product format:
```
"Mobile-optimized video formats"
"Connected TV premium inventory"
"Desktop display network"
```
## Brief Examples for Common Targeting Needs
### Geographic Targeting
```json theme={null}
{
"brief": "Target users in New York, Los Angeles, and Chicago metro areas with premium display advertising for our luxury retail brand."
}
```
### Demographic Targeting
```json theme={null}
{
"brief": "Reach parents with children under 10 who are interested in educational content, focusing on weekend and evening viewing times."
}
```
### Contextual Targeting
```json theme={null}
{
"brief": "Place financial services ads adjacent to business and investment content, targeting affluent professionals during business hours."
}
```
### Behavioral Targeting
```json theme={null}
{
"brief": "Target users who have shown interest in sustainable products and eco-friendly brands, particularly those researching major purchases."
}
```
## Product Response Targeting Information
When publishers return products, they include targeting information buyers need:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/get-products-response.json",
"status": "completed",
"cache_scope": "public",
"products": [
{
"product_id": "premium_millennial_mobile",
"name": "Premium Millennial Mobile Package",
"description": "Mobile display inventory reaching adults 25-40 across lifestyle and entertainment apps in the top 25 US metro areas.",
"publisher_properties": [
{
"publisher_domain": "pinnacle-media.example",
"selection_type": "by_tag",
"property_tags": ["lifestyle", "entertainment", "mobile_app"]
}
],
"channels": ["display"],
"delivery_type": "guaranteed",
"format_options": [
{
"format_option_id": "display_300x250_image",
"format_kind": "image",
"params": { "width": 300, "height": 250 }
}
],
"pricing_options": [
{
"pricing_option_id": "premium_mobile_cpm",
"pricing_model": "cpm",
"currency": "USD",
"fixed_price": 8.50
}
],
"forecast": {
"forecast_range_unit": "availability",
"method": "modeled",
"currency": "USD",
"reach_unit": "individuals",
"points": [
{
"metrics": {
"audience_size": { "mid": 2500000 },
"impressions": { "mid": 12000000 }
}
}
]
},
"included_signals": [
{
"signal_ref": {
"scope": "product",
"signal_id": "lifestyle_entertainment_interest"
},
"name": "Lifestyle and entertainment interest",
"value_type": "binary",
"description": "Seller-modeled users with recent lifestyle or entertainment content engagement."
}
],
"reporting_capabilities": {
"available_reporting_frequencies": ["daily"],
"expected_delay_minutes": 240,
"timezone": "America/New_York",
"supports_webhooks": false,
"available_metrics": ["impressions", "clicks", "spend", "ctr"],
"date_range_support": "date_range"
},
"brief_relevance": "Matches the requested millennial audience, mobile app environment, lifestyle/entertainment context, and major US metro coverage."
}
]
}
```
## Filters, targeting, and coverage
`get_products.filters` selects product characteristics such as channel,
delivery type, creative format, currency, and reporting support. It is not a
second targeting language. The legacy targeting-like filter fields remain
schema-valid during migration but are deprecated.
`get_products.targeting_overlay` contains real delivery constraints. The
seller must account for their effective result in availability, price, and
forecast. Exact acceptance of the structured overlay does not require an echo;
if the seller offers a different executable constraint, it returns only the
changed paths in `targeting_resolution.modifications`. Hard targeting inferred
from prose must be confirmed separately in `targeting_resolution.brief_targeting`
when the structured interpretation materially affects eligibility, pricing, or
forecasting; otherwise confirmation remains a best practice.
`required_overlay_support` asks whether a product lets the buyer choose a
dimension later. For example, requesting `geo_metros` support asks for products
that can be narrowed by metro on packages; it does not ask the seller to return
one product per metro. Named places follow the same rule: known IDs belong in
`targeting_overlay.geo_places`, while a buyer that will choose them later asks
for `required_overlay_support.geo_places`. The product answers with binding
selectable permission in `overlay_support`; that permission is not a
value-specific availability guarantee.
Support guarantees selectability subject to disclosed limits, not inventory or
a forecast for every possible value. A forecast returned without concrete metro
values describes the product's discovery/default scope. Rediscover with the
values in `targeting_overlay` for a metro-specific forecast. Fixed prices and
floors remain binding uniformly for supported selections; price guidance is
non-binding. If rates vary by value, the seller returns a configured product
after concrete rediscovery, splits rate tiers into products, or exposes only
non-binding guidance until concrete values are known. It never silently
reinterprets a selected pricing option at a new price.
Coverage is an implementation detail of the same targeting contract. A
constraint may be satisfied by the product's inherent inventory scope or by a
selectable ad-server control. Buyers care about the effective result, not which
mechanism supplied it.
Properties, collections, and placements follow the same model as audience and
geographic targeting. Select a targetable placement with
`targeting_overlay.placement_selection`, and select collections with
`targeting_overlay.collection_selection` (complete selector sets with explicit
`collection_ids`; partial selection requires the product's
`collection_targeting_allowed`). Use
`creative_assignments[].placement_refs` only to route creatives among the
placements already selected by package targeting. On readback, sellers echo
the committed placement and collection selections in the same fields so the
purchased inventory is auditable.
### No raw ad-server key/value targeting
External buyers MUST NOT send arbitrary ad-server keys, values, or expressions
through a generic targeting map. A capability declaration would prove only
that a seller recognizes a key; it would not make the key's semantics,
authorization boundary, privacy behavior, or cross-seller meaning mechanically
verifiable. Sellers compile AdCP's structured targeting, signal references,
and configured products into their own ad-server controls internally.
When a targeting concept is broadly useful, define a typed AdCP field and its
resolution behavior. Use signals for seller-published targetable options and
use property, collection, placement, and format selection for inventory. Do
not use `ext` to expose or accept a generic ad-server targeting control plane.
## When to Use Targeting Overlays
Targeting overlays are the normal home for exact, auditable delivery constraints
in discovery, create, and update. Use them whenever the requested value must
survive seller planning and package readback.
### Geographic Restrictions
Use geo fields **only** for:
* **RCT testing**: Randomized control trials requiring specific geographic splits
* **Regulatory compliance**: Legal requirements for geographic restrictions
* **Product refinement**: When a product spans multiple regions and you need to restrict to a subset
**Inclusion fields** (restrict delivery to these locations):
* `geo_countries`: ISO 3166-1 alpha-2 country codes (e.g., `["US", "GB"]`)
* `geo_regions`: ISO 3166-2 subdivision codes (e.g., `["US-CA", "GB-SCT"]`)
* `geo_metros`: Structured metro areas with explicit system (e.g., `nielsen_dma`, `uk_itl2`) — not all publishers support metro-level targeting
* `geo_postal_areas`: Structured postal areas with explicit country and system (e.g., `US` / `zip`, `GB` / `outward`, `ZA` / `postal_code`) — not all publishers support postal-level targeting
* `geo_places`: Catalog-backed named places with explicit country, identifier system, place type, and stable IDs — use this for platform place entities such as cities or municipalities, not raw place names
**Exclusion fields** (exclude these locations from delivery):
* `geo_countries_exclude`: Same format as `geo_countries`
* `geo_regions_exclude`: Same format as `geo_regions`
* `geo_metros_exclude`: Same format as `geo_metros`
* `geo_postal_areas_exclude`: Same format as `geo_postal_areas`
* `geo_places_exclude`: Same format as `geo_places`
**Note**: Inclusion and exclusion can be combined. Metro and postal targeting require specifying the classification system, enabling international support. Not all geographic granularities are supported by all publishers. Country and region are most widely supported.
### Age Restrictions (Compliance)
Use for **legal compliance** requirements:
* **Alcohol advertising**: Require verified 21+ in the US
* **Gambling/Gaming**: Require verified 18+ or 21+ depending on jurisdiction
* **Cannabis**: Require verified age per local regulations
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"age_restriction": {
"min": 21,
"verification_required": true,
"accepted_methods": ["facial_age_estimation", "id_document", "world_id"]
}
}
```
**Verification methods** (defined in [`age-verification-method.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/age-verification-method.json), based on ISO/IEC 27566-1 age assurance standards):
* `facial_age_estimation` - AI-based age estimation (Yoti, etc.)
* `id_document` - Government ID scan
* `digital_id` - Verified digital identity credentials
* `credit_card` - Payment card age gate
* `world_id` - Applicable verified World ID age-threshold proof or credential. Orb/personhood verification alone is insufficient.
**Note**: "Inferred" age (guessing from behavior/profile) is **not** accepted for regulatory compliance. Platforms declare their supported verification methods in `get_adcp_capabilities`.
### Device Platform (Technical Compatibility)
Use for **technical requirements**:
* **App install campaigns**: iOS-only app requires `device_platform: ["ios"]`
* **CTV campaigns**: Target specific TV operating systems
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"device_platform": ["ios", "android"],
"device_platform_exclude": ["fire_os"]
}
```
Use `device_platform_exclude` when the campaign may run across several
platforms except for a known incompatible platform. If the same value appears
in both lists, exclusion wins. Sellers that cannot enforce the exclusion MUST
reject it rather than silently broadening delivery.
Platform inclusion and exclusion are independently selectable product
capabilities. A buyer that plans to provide exclusions later requests
`required_overlay_support.device_platform_exclude`; a matching product returns
`overlay_support.device_platform_exclude`. Known exclusion values belong in
`targeting_overlay` during discovery so availability, pricing, and forecast use
the effective constraint.
**Available platforms** (defined in [`device-platform.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/device-platform.json), based on Sec-CH-UA-Platform standard extended for CTV):
* Browser: `ios`, `android`, `windows`, `macos`, `linux`, `chromeos`
* CTV: `tvos`, `tizen`, `webos`, `fire_os`, `roku_os`
* Other: `unknown`
### Device type (form factor)
Use for **performance optimization** targeting by hardware category rather than OS:
* **Mobile campaigns**: Target all mobile devices regardless of OS
* **CTV campaigns**: Target connected TVs across all platforms
* **Exclude form factors**: Skip CTV for app-install campaigns
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"device_type": ["mobile", "tablet"]
}
```
**Exclusion** — use `device_type_exclude` to exclude specific form factors:
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"device_type_exclude": ["dooh"]
}
```
**Available types** (defined in [`device-type.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/device-type.json)):
* `desktop`, `mobile`, `tablet`, `ctv`, `dooh`, `unknown`
**Device type vs device platform**: `device_type` targets form factors (mobile, desktop, CTV). `device_platform` targets operating systems (iOS, Android, tvOS). Use `device_type` for performance optimization; use `device_platform` for technical compatibility.
### Language (Localization)
Use for **localization requirements**:
* Creative is in a specific language
* Campaign targets specific language speakers
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"language": ["fr-CA", "en"]
}
```
**Format**: Canonical BCP 47 language ranges (for example, `en`, `fr-CA`, `zh-Hant-TW`). AdCP uses lower-case language and variants, title-case script, and upper-case region.
**Matching**: Sellers apply RFC 4647 §3.3.1 Basic Filtering in the direction buyer range → user language-preference tag. `fr` matches `fr`, `fr-CA`, and `fr-FR`; `fr-CA` matches `fr-CA` and more-specific descendants, but not `fr` or the sibling `fr-FR`. Multiple requested ranges use OR logic.
**Discovery**: The structured `media_buy.execution.targeting.language.supported_languages` capability lists exact selectable request values. A capability entry of `fr` does not authorize a request for `fr-CA`; the seller must list `fr-CA` when that narrower range is accepted. Sellers that cannot enforce a requested value reject the request rather than silently widening or dropping it. A legacy `language: true`, or a structured declaration with no list, indicates coarse support without an exhaustive preflight list.
### Frequency Capping
Two frequency controls can be used independently or together:
**Cooldown between exposures** — `suppress` prevents back-to-back delivery:
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"frequency_cap": {
"suppress": { "interval": 60, "unit": "minutes" }
}
}
```
**Impression cap per entity per window** — `max_impressions` + `per` + `window` limits total exposure:
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"frequency_cap": {
"max_impressions": 5,
"per": "households",
"window": { "interval": 7, "unit": "days" }
}
}
```
Both can be combined. The `per` field uses the same entity types as `reach_unit` on reach optimization goals — use matching values when layering a hard cap on top of a reach campaign.
### Example Geographic Overlay (RCT Testing)
For RCT testing, exclusion targeting is often simpler than inclusion. Instead of listing hundreds of DMAs to include, exclude the holdout markets from a national campaign. When inclusion and exclusion are combined, exclusion fields subtract from the included set (e.g., "US minus these 3 DMAs"):
```json theme={null}
{
"packages": [
{
"product_id": "national_video",
"targeting_overlay": {
"geo_countries": ["US"],
"geo_metros_exclude": [
{ "system": "nielsen_dma", "values": ["501", "803", "602"] }
]
}
},
{
"product_id": "national_video",
"targeting_overlay": {
"geo_metros": [
{ "system": "nielsen_dma", "values": ["501", "803", "602"] }
]
}
}
]
}
```
Inclusion targeting works the same way for cases where you want to specify exact markets:
```json theme={null}
{
"packages": [
{
"product_id": "national_video",
"targeting_overlay": {
"geo_metros": [
{ "system": "nielsen_dma", "values": ["501", "602", "803"] }
]
}
},
{
"product_id": "national_video",
"targeting_overlay": {
"geo_metros": [
{ "system": "nielsen_dma", "values": ["504", "505", "506"] }
]
}
}
]
}
```
## What NOT to Use Targeting Overlays For
**Express these in briefs instead:**
* **Demographic preferences** (age, gender, income) - "Target millennials" or "high-income households" in brief text
* **Device preferences** - "Mobile users" or "CTV viewers" in brief text (use `device_platform` overlay only for technical compatibility)
* **Content categories** - "Sports content" or "News sites" in brief text
* **General audience preferences** - "Auto intenders" or "Luxury shoppers" in brief text. If the buyer wants specific named signals applied to this package, use `signal_targeting_groups`.
* **Daypart preferences** - "Morning commute hours" or "prime time evening" in brief text
**Overlays vs Briefs:**
| Use Case | Overlay | Brief |
| - | - | - |
| Age for compliance (alcohol, gambling) | ✅ `age_restriction` | |
| Age for audience targeting | | ✅ "Target millennials" |
| Device for app compatibility | ✅ `device_platform` | |
| Device for audience preference | | ✅ "Mobile users" |
| Language for creative localization | ✅ `language` | |
| Language for audience preference | | ✅ "Spanish-speaking audiences" |
| First-party CRM audience (retargeting, suppression) | ✅ `audience_include` / `audience_exclude` | |
| Audience preference (interest targeting) | | ✅ "Auto intenders" in brief |
| Specific named signal offered by the seller | ✅ `signal_targeting_groups` | |
| Search/retail media keyword targeting | ✅ `keyword_targets` / `negative_keywords` | |
| Broad thematic intent ("people searching for shoes") | | ✅ "Reach in-market shoe shoppers" |
| Proximity to specific coordinates (within 2hr drive of a city) | ✅ `geo_proximity` | |
| Nearby audience ("people near coffee shops") | | ✅ "Reach people near coffee shops" |
**Why briefs work better for preferences:**
* Natural language captures intent more clearly
* Publishers know their inventory and can target effectively
* Avoids channel-specific complexity (DOOH has no browsers)
* Simpler API with fewer edge cases
## Available Targeting Overlay Parameters
Geographic targeting supports both inclusion (restrict to) and exclusion (exclude from) for all geo dimensions. Inclusion and exclusion fields can be combined — for example, include a country but exclude specific metros within it.
### Exclusion Semantics
**Exclusion without inclusion.** When an exclusion field is present without a corresponding inclusion field, the exclusion applies to the product's full geographic coverage. For example, if a product covers the entire US and the buyer specifies only `geo_metros_exclude`, the excluded metros are removed from the product's national footprint.
**Cross-level resolution.** Geographic levels form a hierarchy: country > region > metro > postal. Sellers SHOULD resolve hierarchical conflicts such that exclusion at a higher level takes precedence over inclusion at a more specific level. For example, `geo_countries_exclude: ["US"]` combined with `geo_regions: ["US-CA"]` SHOULD result in no US delivery — the country-level exclusion takes precedence.
**Same-value overlap.** Sellers SHOULD reject requests where the same value appears in both the inclusion and exclusion field at the same level (e.g., `geo_countries: ["US"]` with `geo_countries_exclude: ["US"]`) and return a descriptive error. ISO subdivision and named-place overlaps are stricter: the same identity in `geo_regions` / `geo_regions_exclude` or `geo_places` / `geo_places_exclude` MUST be rejected.
**Capabilities.** Inclusion and exclusion support are independent. Sellers declare subdivision inclusion through `geo_regions` and exclusion through `geo_regions_exclude`; support for one MUST NOT be inferred from the other. A legacy boolean in seller-wide capabilities is a coarse, informative rollup. Seller-wide structured values are individual routing claims within the response scope, not a promise that multiple values are jointly composable or available through the same execution route or account. Only Product `overlay_support` supplies the binding set of executable targeting permissions for that Product, and its legacy `true` form retains the targeting-overlay contract's binding unrestricted-support meaning. A seller that cannot honor every protocol-valid value MUST return structured country/value Product support instead. If a seller does not support a requested direction, it MUST return a validation error rather than silently ignore the field.
### geo_countries
* **Description**: Restrict delivery to specific countries
* **Format**: ISO 3166-1 alpha-2 country codes
* **Examples**: `["US", "CA"]`, `["GB", "FR", "DE"]`
* **Use cases**: Regulatory compliance, country-specific campaigns
### geo_countries_exclude
* **Description**: Exclude specific countries from delivery
* **Format**: ISO 3166-1 alpha-2 country codes
* **Examples**: `["RU", "CN"]`
* **Use cases**: Regulatory compliance, sanctions
Country inclusion and exclusion support are declared independently on each
Product. A buyer uses `required_overlay_support.geo_countries: true` or
`required_overlay_support.geo_countries_exclude: true` to require future
package-level selection. The matching Product can return either legacy `true`
or structured support such as
`{ "max_values_per_package": 1 }`. The structured form supports
protocol-valid country codes but caps how many values may appear in that field
on one package; it is not a country allowlist and does not guarantee inventory
for every country.
Numeric seller limits do not participate in requirement matching. A seller
MUST reject a create or update that exceeds the disclosed limit with
`UNSUPPORTED_FEATURE`, identify the overflowing targeting field, and leave
existing state unchanged. Legacy `true` remains valid and declares positive
support without a protocol-level cardinality cap.
Numeric limits are ignored only when matching future-support requirements.
Concrete targeting is still bound by them: every returned Product's accepted
effective targeting MUST satisfy its disclosed maximum. A seller MUST exclude
an over-limit candidate unless it returns a distinct configured Product with a
disclosed, compliant targeting modification.
### geo_regions
* **Description**: Restrict delivery to canonical ISO 3166-2 subdivisions, including states, provinces, regions, departments, and overseas subdivisions
* **Format**: ISO 3166-2 subdivision codes
* **Examples**: `["US-CA", "CA-QC"]`, `["FR-49", "FR-2A", "FR-971", "FR-ARA"]`
* **Use cases**: State-level compliance, regional testing
### geo_regions_exclude
* **Description**: Exclude canonical ISO 3166-2 subdivisions from delivery
* **Format**: ISO 3166-2 subdivision codes
* **Examples**: `["US-CA"]`, `["CA-QC"]`
* **Use cases**: Regulatory compliance (e.g., cannabis restrictions by province), RCT holdout regions, regions where product is unavailable
ISO subdivision identifiers are the protocol identity. Sellers MUST execute every requested value exactly or reject/propose a disclosed targeting modification; they MUST NOT silently widen a department to an ancestor, drop an unsupported value, or apply only part of a list. A seller MAY translate a canonical subdivision internally to an exact provider-native representation, including a complete postal-area set, while preserving the requested ISO code in package readback. Native-versus-translated execution is diagnostic and does not change conformance.
Known values belong in `get_products.targeting_overlay.geo_regions` and/or `geo_regions_exclude`, so every returned configured product, price, availability result, minimum, guarantee, and aggregate forecast reflects the effective subdivisions. No separate region resolver is required: configured discovery or refinement is the authoritative value-level preflight.
When region values will be chosen later, buyers request `required_overlay_support.geo_regions` and `geo_regions_exclude` independently. A structured requirement keys support by country. `all_values: true` requires every protocol-valid ISO subdivision active in the seller's support snapshot when the declaration is issued; it does not automatically include values introduced by a later catalog revision. `catalog_version` and `as_of` identify that snapshot when supplied. `values` requests an exact finite candidate set. Returned Product `overlay_support` is binding selectable permission. Requirement matching uses country/value containment: support with `all_values: true` satisfies any requirement for that country; finite support satisfies only requested value subsets. Future support does not guarantee value-specific inventory or commercial terms, so buyers that need a value-specific forecast or guarantee refine with the exact overlay before commitment.
At create or update, unsupported dimensions, countries, or values outside Product `overlay_support` produce `UNSUPPORTED_FEATURE`, while malformed or unknown canonical identifiers inside a declared support envelope produce `INVALID_REQUEST` with an exact `error.field`. A supported create-time selection with no executable inventory produces `PRODUCT_UNAVAILABLE`. `REQUOTE_REQUIRED` remains update-only for an executable change outside the accepted price or guarantee envelope; buyers that know commercially distinct region values before commitment rediscover or refine with the exact overlay. Accepted package state echoes the complete effective ISO subdivision overlay. Updates are atomic.
### geo_metros
* **Description**: Restrict delivery to specific metro areas
* **Format**: Array of objects, each with a `system` and `values`
* **Systems**: `nielsen_dma` (US), `uk_itl1` / `uk_itl2` (UK), `eurostat_nuts2` (EU), `custom`
* **Example**: `[{ "system": "nielsen_dma", "values": ["501", "803"] }]`
* **Use cases**: Local campaigns, metro-level RCT testing
* **Note**: Seller must declare supported systems in `get_adcp_capabilities`
### geo_metros_exclude
* **Description**: Exclude specific metro areas from delivery
* **Format**: Array of objects, each with a `system` and `values`
* **Example**: `[{ "system": "nielsen_dma", "values": ["602"] }]`
* **Use cases**: RCT holdout markets, competitive exclusion zones, markets where product is unavailable
* **Note**: Seller must declare supported systems in `get_adcp_capabilities`
### geo_postal_areas
* **Description**: Restrict delivery to specific postal areas
* **Format**: Array of objects, each with a `country`, `system`, and `values`
* **Systems**: country-local values such as `zip`, `zip_plus_four`, `outward`, `full`, `fsa`, `plz`, `code_postal`, `postcode`, `pin`, and `postal_code`
* **Example**: `[{ "country": "US", "system": "zip", "values": ["10001", "10002"] }]`
* **Use cases**: Hyper-local campaigns, postal-level restrictions
* **Note**: Seller must declare supported systems in `get_adcp_capabilities`. During the 3.x migration, deprecated country-fused systems such as `us_zip` remain accepted for compatibility and SDK backfill.
### geo_postal_areas_exclude
* **Description**: Exclude specific postal areas from delivery
* **Format**: Array of objects, each with a `country`, `system`, and `values`
* **Example**: `[{ "country": "US", "system": "zip", "values": ["90210"] }]`
* **Use cases**: RCT holdout zip codes, restricted delivery areas
* **Note**: Seller must declare supported systems in `get_adcp_capabilities`; the deprecated legacy form remains accepted during the 3.x migration.
### geo_places
* **Description**: Restrict delivery to named administrative or local places represented by stable catalog identifiers
* **Format**: Array of objects with required `country`, `system`, `place_type`, and `values`; optional `system_version`, `value_labels`, and `ext`
* **Systems**: Registered namespaces are `geonames`, `google_ads`, and `microsoft_ads`. Other catalogs use an owner-controlled absolute HTTPS URI, such as `https://seller.example/geo/catalogs/places`. MaxMind `geoname_id` values use the `geonames` namespace; MaxMind is a catalog source/version, not a separate identifier namespace.
* **Example**: `[{ "country": "NL", "system": "geonames", "system_version": "2026-05", "place_type": "city", "values": ["2759794"], "value_labels": { "2759794": "Amsterdam, North Holland, Netherlands" } }]`
* **Use cases**: Target a platform's named city, municipality, borough, neighborhood, post town, city region, or county entity without relying on ambiguous names
* **Note**: `values` are the authoritative targeting keys. Every `value_labels` key MUST appear in `values`; labels exist only for diagnostics and audit readability, and sellers MUST NOT resolve or apply targeting from them. Raw names such as `Amsterdam` are unresolved intent, not valid values.
Within `geo_places`, values and entries have union semantics: delivery may occur in any included place. `geo_places_exclude` subtracts matching places from the current candidate geography, including when no `geo_places` inclusion is present. Inclusion across different geographic dimensions is intersected. Sellers MUST reject the same `(country, system, place_type, value)` in both include and exclude lists, even when the include and exclude entries specify different catalog versions: version is not part of stable place identity. Sellers MAY reject cross-level combinations they cannot resolve safely rather than silently approximating them.
Before sending a place target, buyers inspect `get_adcp_capabilities.media_buy.execution.targeting.geo_places`. Support is declared as exact country/type pairs, not independent lists. Each system also declares `catalog.current_version`, exact `supported_versions`, and an `adcp_geo_place_resolver_v1` endpoint. Buyers resolve raw names—or refresh an existing ID—using an HTTPS GET with exactly one of `q` or `value` from `get-geo-place-resolution-request.json`. The response echoes the normalized request and follows `get-geo-place-resolution-response.json`, carrying machine-readable country/subdivision/type context plus active, removal-planned, or deprecated identifiers and replacements. Ambiguous results require user or agent disambiguation before trafficking.
If `system_version` is omitted from a new target, the seller applies its declared `current_version`. Sellers MUST reject unsupported systems, country/type pairs, versions, deprecated identifiers, and unknown identifiers rather than silently dropping or reinterpreting them. If an identifier is stale, the seller returns a validation error and may surface resolver-provided replacements; it MUST NOT silently substitute a replacement. Sellers MUST echo persisted `geo_places` and `geo_places_exclude` in package `targeting_overlay` state with the exact applied `system_version` and values.
Accepted place targeting is pinned to the echoed `system_version` for the life of the package. Removing that version from `supported_versions` stops new targeting and target-changing updates from using it, but MUST NOT silently mutate, drop, or invalidate an existing package. An unrelated package update preserves the pinned place overlay. If a seller can no longer execute a pinned target, `get_media_buys` MUST still echo it and return a nonfatal `errors[]` entry with `code: "PLACE_TARGET_UNAVAILABLE"`, `recovery: "correctable"`, `field` pointing to the exact `media_buys[N].packages[M].targeting_overlay.geo_places[_exclude][A].values[V]` response path, and `details` containing `media_buy_id`, `package_id`, `system`, `system_version`, `country`, `place_type`, and `value`. The buyer can use resolver `value` lookup against the current catalog to find lifecycle status and proposed replacements, then submit an intentional target update.
Place forecast and delivery breakdown rows are intentionally not part of this release: `geo_level: "place"` remains invalid on reporting surfaces. Package-state echo provides configuration auditability, but not delivery-by-place verification. Place-level forecast, delivery, pacing, and reconciliation require a follow-up reporting RFC.
Known place IDs belong in `get_products.targeting_overlay.geo_places`, so every
returned product, price, and aggregate forecast reflects that effective
targeting even though a place-level breakdown is unavailable. If IDs will be
chosen on packages later, the buyer requests `required_overlay_support.geo_places`
(and independently `geo_places_exclude`) with the required system,
country/type pairs, and optional catalog versions. Returned Product
`overlay_support` is binding selectable permission, not a value-specific
inventory, price, or forecast guarantee. At create, the seller applies this
deterministic disposition matrix to the actual place overlay:
| Condition | Result |
| - | - |
| The dimension, identifier system, country, place type, or combination is outside the selected Product `overlay_support` | `UNSUPPORTED_FEATURE` |
| The tuple is supported, but an ID is invalid, unknown, or deprecated, or an explicit `system_version` is not supported | `INVALID_REQUEST`, with `error.field` identifying the offending field |
| The identifiers are valid and supported, but their effective intersection has no current inventory | `PRODUCT_UNAVAILABLE`; rediscover with the concrete values or choose another product, without silent substitution or repricing |
An accepted create confirms that the returned terms apply to the complete
effective targeting. `PLACE_TARGET_UNAVAILABLE` is reserved for later
degradation of a previously accepted, persisted place target; it is not a
create-time substitute for any result above.
### geo_places_exclude
* **Description**: Exclude catalog-backed named places
* **Format**: Same as `geo_places`
* **Example**: `[{ "country": "US", "system": "geonames", "place_type": "city", "values": ["5392171"], "value_labels": { "5392171": "San Jose, California, United States" } }]`
* **Note**: Seller must declare the system, exact country/type pair, and applied catalog version in `get_adcp_capabilities` and echo the persisted exclusion on package state.
### axe_include_segment
* **Description**: Segment ID for inclusion targeting (legacy AXE field)
* **Format**: String segment identifier
* **Examples**: `"seg_auto_intenders_q1"`, `"audience_lapsed_buyers_30d"`
* **Use cases**: Dynamic audience targeting, first-party data activation
* **Note**: This field is from the legacy AXE integration. New implementations should use [TMP](/dist/docs/3.2.8/trusted-match), where audience targeting is handled through the Identity Match path.
### axe_exclude_segment
* **Description**: Segment ID for exclusion targeting (legacy AXE field)
* **Format**: String segment identifier
* **Examples**: `"seg_existing_customers"`, `"audience_past_converters"`
* **Use cases**: Customer suppression, frequency management
* **Note**: This field is from the legacy AXE integration. New implementations should use [TMP](/dist/docs/3.2.8/trusted-match), where suppression is handled through the Identity Match path.
### audience_include
* **Description**: Restrict delivery to users who are members of these first-party CRM audiences. Only people on the uploaded list are eligible to see the ad.
* **Format**: Array of `audience_id` strings from [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences)
* **Example**: `["lapsed_subscribers", "high_value_prospects"]`
* **Use cases**: Retargeting known users, loyalty campaigns targeting existing members, CRM-based inclusion on closed platforms (LinkedIn, Meta, TikTok, Google Ads)
* **Not for lookalike/expansion**: To find new users *similar to* an audience, describe the intent in your campaign brief ("reach people like our existing customers") — the seller handles expansion strategy
* **Prerequisite**: Audiences must be registered and `ready` via `sync_audiences` before use
* **Note**: Seller must declare support in `get_adcp_capabilities`
### audience_exclude
* **Description**: Suppress delivery to users who are members of these first-party CRM audiences. Matched users are excluded regardless of other targeting.
* **Format**: Array of `audience_id` strings from [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences)
* **Example**: `["existing_customers", "recent_purchasers"]`
* **Use cases**: Customer suppression in acquisition campaigns, excluding recent converters, suppressing opted-out users
* **Prerequisite**: Audiences must be registered and `ready` via `sync_audiences` before use
* **Note**: Seller must declare support in `get_adcp_capabilities`
### signal_targeting_groups
* **Description**: Basic Boolean grouping for seller-offered data signals. Use this for both simple include-only signal targeting and grouped include/exclude expressions such as `(A OR B) AND NOT (C OR D)`.
* **Discovery**: Wholesale products can set `signal_targeting_allowed: true` and omit inline `signal_targeting_options`; buyers then use `get_signals` as the selectable signal feed. Products return inline `signal_targeting_options` when they need product-specific pricing, activation handles, defaults, grouping hints, or a relevant subset for a brief/refine response.
* **Format**: Object with required top-level `operator: "all"` and a `groups` array. The top-level operator is always present, even though v1 only supports `all`.
* **Child groups**: Each child group has `operator: "any"` or `operator: "none"` and a `signals` array of package signal targeting objects. Each signal carries `signal_ref`, `value_type`, and the value fields, plus optional commercial and activation handles.
* **Legacy flat targeting**: `targeting_overlay.signal_targeting` remains schema-valid during the SignalRef migration window for older clients, but it is deprecated. New package-level signal selection uses `signal_targeting_groups` so sellers can apply include/exclude groups, product rules, and per-signal pricing consistently.
* **Semantics**: `any` means the user must match at least one signal in that group. `none` means the user must match none of the signals in that group. With top-level `all`, every child group must pass. For simple include-only targeting, send one child group with `operator: "any"`.
* **Resolution model**: `signal_targeting_rules.resolution_model` tells buyers how the seller applies selected signals to inventory. `direct_targeting` means selected signals behave like package targeting predicates. `seller_planned` means selected signals are inputs to seller-managed planning against product-specific inventory, timing, availability, reach, or pacing constraints; buyers should not attempt to decompose the selected audience into lower-level inventory or schedule decisions.
* **Selection groups**: When the product declares `signal_targeting_rules.selection_group_rules`, each child group MUST contain signals from exactly one `selection_group` and one targeting mode, and buyers MUST send at most one child group for each `(selection_group, targeting_mode)` pair. Sellers MUST reject duplicate, mixed, or collapsed child groups that combine distinct selection-group rules into the same `any` or `none` group. `selection_group` is a product-defined composability bucket, not a backend identity type: for example, a GAM-backed seller may expose both audience segments and key-values as ordinary `signal_ref` options, using one `selection_group` when they are freely OR-combinable and separate `selection_group`s when they must be trafficked as separate ANDed clauses.
* **Pricing**: Include `pricing_option_id` when the selected product's `signal_targeting_options` entry has `pricing_options`; omit only when the signal is bundled into the product price or has no incremental cost. Product-scoped pricing in `signal_targeting_options` is authoritative for that product. If the product option has no product-specific price, sellers MAY use the default pricing exposed in `get_signals`.
* **Signal reference**: Use `signal_ref: { "scope": "product", "signal_id": "..." }` for a product-local signal option. Use `signal_ref: { "scope": "data_provider", "data_provider_domain": "...", "signal_id": "..." }` for a signal defined in a data provider's published adagents.json `signals[]`. `signal_ref` identifies the signal definition; `signal_agent_segment_id` identifies a resolved segment or execution handle when the product option exposes one. Echo an exposed `signal_agent_segment_id` verbatim on the package entry, and prefer it over reconstructing identity from categorical values because providers can namespace handles to distinguish definitions such as real-time rain versus forecast high-precipitation. If the product option has `activation_status: "requires_activation"`, it MUST include `signal_agent_segment_id`; activate the signal first, then include `activation_key` if the seller requires it.
* **Provider-published signals**: For a provider-published signal, `signal_ref.data_provider_domain` identifies the upstream data provider and `signal_ref.signal_id` identifies the public signal definition. Buyers can verify the seller's right to offer the signal by checking the provider's `adagents.json` `authorized_agents` entry for the seller.
* **Product gating**: Sellers SHOULD reject a signal entry when the product does not advertise that signal inline or through `get_signals`, `signal_targeting_allowed` is false for package-level selection, the signal violates the product's `signal_targeting_rules`, the signal's `allowed_targeting_modes` does not allow the requested child group operator, the signal is not active for the account, or the requested value is outside the signal definition. `allowed_targeting_modes: ["include"]` maps to `any` groups; `["exclude"]` maps to `none` groups. Binary package signal entries use `value: true`; use the parent `none` group for exclusion, not `value: false`. Signal targeting limits are product-scoped, not declared in seller-wide `get_adcp_capabilities`, because products may be backed by different ad servers or platforms. If `selection_mode` is `fixed`, buyers SHOULD omit edits to `signal_targeting_groups`; sellers apply the fixed/default selections and MUST echo them on the resulting package state.
* **Updates**: Because `targeting_overlay` is shared by `create_media_buy` and `update_media_buy`, sellers MAY reject mid-flight signal group changes with `REQUOTE_REQUIRED` when the selected signal, group expression, or `pricing_option_id` changes the priced envelope.
* **Not for first-party audiences**: Use `audience_include` / `audience_exclude` for buyer-uploaded audiences from `sync_audiences`.
The backend targeting primitive is intentionally hidden behind `signal_ref`. Buyers should not need a separate identity system for "audience segment" versus "key-value"; the selected product's `signal_targeting_rules` describe whether those options can be composed together. If a product exposes both a `gam_audience_segments` group and a `gam_key_values` group with `targeting_mode: "include"`, the buyer composes two `any` child groups under the top-level `all`, not one collapsed mixed group.
For products where inventory and audience planning are inseparable, such as linear broadcast schedules, sellers use `resolution_model: "seller_planned"`. Mandatory audience selection still lives in `selection_mode: "required"` or a required `selection_group_rules` entry; cross-product audience consistency comes from a shared `scope: "data_provider"` signal definition, even when the seller is also the data provider.
```json theme={null}
{
"packages": [
{
"product_id": "retail_video_premium",
"pricing_option_id": "media_cpm_usd",
"budget": 25000,
"targeting_overlay": {
"signal_targeting_groups": {
"operator": "all",
"groups": [
{
"operator": "any",
"signals": [
{
"signal_ref": { "scope": "product", "signal_id": "high_intent_shoppers" },
"value_type": "binary",
"value": true
},
{
"signal_ref": { "scope": "product", "signal_id": "loyalty_members" },
"value_type": "binary",
"value": true
}
]
},
{
"operator": "none",
"signals": [
{
"signal_ref": { "scope": "product", "signal_id": "recent_purchasers" },
"value_type": "binary",
"value": true
}
]
}
]
}
}
}
]
}
```
### frequency_cap
* **Description**: Limit ad exposure frequency per entity. Two optional controls can be used independently or together.
* **Cooldown control**: `suppress` — minimum duration between consecutive exposures to the same entity. `suppress_minutes` (number) is also accepted for backwards compatibility.
* **Impression cap**: `max_impressions` + `per` + `window` — total impression ceiling per entity per time window. All three fields are required together.
* **Use cases**: User experience management, ad fatigue prevention, complementing reach optimization goals with a hard ceiling
* **Examples**: `{"suppress": {"interval": 60, "unit": "minutes"}}`, `{"max_impressions": 5, "per": "households", "window": {"interval": 7, "unit": "days"}}`
### age_restriction
* **Description**: Require minimum age for compliance
* **Format**: Object with `min` (required), `verification_required`, and `accepted_methods`
* **Examples**: `{"min": 21, "verification_required": true}`, `{"min": 18, "verification_required": true, "accepted_methods": ["world_id"]}`
* **Use cases**: Alcohol (21+), gambling (18+), cannabis regulations
* **Note**: Platforms declare supported verification methods in `get_adcp_capabilities`
### device_platform
* **Description**: Restrict to specific operating system platforms
* **Format**: Array of platform identifiers from Sec-CH-UA-Platform standard
* **Examples**: `["ios"]`, `["ios", "android"]`, `["tvos", "fire_os"]`
* **Use cases**: App install campaigns (iOS-only app), CTV-specific campaigns
* **Values**: `ios`, `android`, `windows`, `macos`, `linux`, `chromeos`, `tvos`, `tizen`, `webos`, `fire_os`, `roku_os`
### device_platform_exclude
* **Description**: Exclude specific operating-system platforms from delivery
* **Format**: Array using the same identifiers as `device_platform`
* **Examples**: `["fire_os"]`, `["tizen", "webos"]`
* **Conflict rule**: Exclusion wins when the same value appears in both platform fields
* **Discovery**: Require future package-level control with `required_overlay_support.device_platform_exclude`; products disclose it through `overlay_support.device_platform_exclude`
* **Failure rule**: A seller that cannot enforce the exclusion rejects the request instead of dropping it
### device_type
* **Description**: Restrict to specific device form factors
* **Format**: Array of device type identifiers
* **Examples**: `["mobile"]`, `["mobile", "tablet"]`, `["ctv"]`
* **Use cases**: Mobile-only promotions, CTV campaigns targeting all TV platforms, excluding DOOH from certain campaigns
* **Values**: `desktop`, `mobile`, `tablet`, `ctv`, `dooh`, `unknown`
* **Note**: Seller must declare `device_type: true` in `get_adcp_capabilities` targeting
### device_type_exclude
* **Description**: Exclude specific device form factors from delivery
* **Format**: Array of device type identifiers
* **Examples**: `["dooh"]`, `["ctv", "dooh"]`
* **Use cases**: Exclude CTV for app-install campaigns, exclude DOOH for direct-response campaigns
* **Note**: Supported when seller declares `device_type: true` in `get_adcp_capabilities`
### browser
* **Description**: Restrict impression delivery to canonical browser families
* **Format**: Non-empty array of `chrome`, `safari`, `firefox`, `edge`, `opera`, `samsung_internet`, `android_webview`, `other`, or `unknown`
* **Examples**: `["chrome"]`, `["chrome", "firefox"]`, `["safari", "unknown"]`
* **Semantics**: Values use OR; when present, omitted families are ineligible. The field describes the impression rendering environment, not a post-click browser.
* **Discovery**: Require any later-selectable family with `required_overlay_support.browser: true`, or require a subset with `required_overlay_support.browser.families`. Products disclose unrestricted support as `true` or partial support with `overlay_support.browser.families`.
### browser_exclude
* **Description**: Exclude canonical browser families from impression delivery
* **Format**: Non-empty array using the same values as `browser`
* **Examples**: `["unknown"]`, `["safari", "android_webview"]`
* **Conflict rule**: Exclusion wins when the same family appears in both browser fields
* **Discovery**: Inclusion and exclusion support are independent; `required_overlay_support.browser_exclude` and `overlay_support.browser_exclude` use the same `true` or `{ "families": [...] }` capability form.
* **Failure rule**: A seller that cannot enforce the exclusion rejects the request instead of dropping it
### language
* **Description**: Restrict to users with specific language preferences
* **Format**: Array of canonical BCP 47 language ranges
* **Examples**: `["en"]`, `["fr-CA", "en"]`, `["zh-Hant-TW", "ja", "ko"]`
* **Matching**: RFC 4647 Basic Filtering in the direction buyer range → user language-preference tag. A broad `fr` range includes `fr-CA`; a narrow `fr-CA` range does not include `fr` or `fr-FR`.
* **Discovery**: If the seller publishes `execution.targeting.language.supported_languages`, each requested value must be an exact member of that list. Sellers reject unsupported values rather than widening or ignoring them.
* **Use cases**: Localized creative, language-specific campaigns
### keyword_targets
* **Description**: Target specific keywords for search and retail media platforms. Restricts delivery to queries matching the specified keywords.
* **Format**: Array of objects with `keyword`, `match_type` (`broad`, `phrase`, or `exact`), and optional `bid_price`
* **Identity**: Each keyword is identified by the tuple `(keyword, match_type)`. The same keyword string with different match types are distinct targets. Duplicate pairs in a single request SHOULD be rejected by sellers.
* **Match types**:
* `broad` — matches related and synonym queries
* `phrase` — matches queries containing the keyword phrase in order
* `exact` — matches the keyword query only
* **Per-keyword bid**: The optional `bid_price` overrides the package-level `bid_price` for that keyword. Inherits the `max_bid` interpretation from the pricing option: when `max_bid` is true, this is the keyword's bid ceiling; when false, this is the exact bid. If omitted, the package `bid_price` applies.
* **Use cases**: Search campaigns, retail media sponsored products, keyword-based intent targeting
* **Note**: Seller must declare `execution.targeting.keyword_targets` in `get_adcp_capabilities` with the `supported_match_types` it accepts. Only use match types the seller declares — sellers must reject unsupported match types. Use `keyword_targets_add` and `keyword_targets_remove` in `update_media_buy` to add or update keywords incrementally after launch. Keyword-level delivery data (`by_keyword` in reporting) requires `reporting_capabilities.supports_keyword_breakdown: true` on the product — these are independent capabilities. `by_keyword` is keyword-grain (one row per keyword+match_type pair), not search-term-grain.
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"keyword_targets": [
{ "keyword": "running shoes", "match_type": "broad", "bid_price": 0.45 },
{ "keyword": "trail running shoes womens", "match_type": "phrase", "bid_price": 0.85 },
{ "keyword": "acme cloudrunner 5", "match_type": "exact", "bid_price": 1.20 }
]
}
```
### negative_keywords
* **Description**: Exclude specific keywords from delivery. Queries matching these keywords will not trigger the ad.
* **Format**: Array of objects with `keyword` and `match_type` (`broad`, `phrase`, or `exact`)
* **Use cases**: Prevent wasteful spend on irrelevant queries, exclude competitor brand terms
* **Note**: Seller must declare `execution.targeting.negative_keywords` in `get_adcp_capabilities` with the `supported_match_types` it accepts. Use `negative_keywords_add` and `negative_keywords_remove` in `update_media_buy` to add/remove negatives incrementally after launch.
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"negative_keywords": [
{ "keyword": "free", "match_type": "broad" },
{ "keyword": "used running shoes", "match_type": "phrase" }
]
}
```
### store_catchments
* **Description**: Target users within store catchment areas from a synced store catalog
* **Format**: Array of objects, each referencing a store-type catalog synced via `sync_catalogs`
* **Required fields**: `catalog_id`
* **Optional fields**: `store_ids` (narrow to specific stores), `catchment_ids` (narrow to specific zones like `"walk"` or `"drive"`)
* **Use cases**: Drive-to-store campaigns, local inventory ads, proximity targeting
```json theme={null}
{
"targeting_overlay": {
"store_catchments": [
{
"catalog_id": "retail-locations",
"store_ids": ["store_nyc_001", "store_nyc_002"],
"catchment_ids": ["drive"]
}
]
}
}
```
When `store_ids` is omitted, all stores in the catalog are targeted. When `catchment_ids` is omitted, all catchment zones are targeted. The seller must declare support for store catchment targeting in `get_adcp_capabilities`.
### geo_proximity
* **Description**: Target users within travel time, distance, or a custom boundary around arbitrary geographic points
* **Format**: Array of objects, each with exactly one method: `travel_time` + `transport_mode`, `radius`, or `geometry`
* **Required fields**: `lat` + `lng` (for travel_time and radius methods), or `geometry` (for pre-computed boundaries)
* **Optional fields**: `label` (human-readable name for the entry)
* **Use cases**: Tourism campaigns (within 2hr drive of a city), event targeting (near a venue), airport catchment areas
* **Semantics**: Multiple entries use OR — a user within range of any listed point is eligible. Intersects with other geo targeting fields (e.g., combining with `geo_countries` restricts proximity to those countries)
Travel time (isochrone) example:
```json theme={null}
{
"targeting_overlay": {
"geo_proximity": [
{
"lat": 51.2277,
"lng": 6.7735,
"label": "Düsseldorf",
"travel_time": { "value": 2, "unit": "hr" },
"transport_mode": "driving"
}
]
}
}
```
Radius-based example:
```json theme={null}
{
"targeting_overlay": {
"geo_proximity": [
{
"lat": 51.4700,
"lng": -0.4543,
"label": "Heathrow Airport",
"radius": { "value": 30, "unit": "km" }
}
]
}
}
```
Pre-computed geometry example (buyer provides the polygon):
```json theme={null}
{
"targeting_overlay": {
"geo_proximity": [
{
"label": "2hr drive from Düsseldorf",
"geometry": {
"type": "Polygon",
"coordinates": [[[5.87, 50.35], [8.23, 50.35], [8.23, 52.10], [5.87, 52.10], [5.87, 50.35]]]
}
}
]
}
}
```
For travel time entries, the platform resolves the isochrone to a geographic boundary based on actual transportation networks. Transport modes: `driving`, `walking`, `cycling`, `public_transport`. The `geometry` method allows buyers who have already computed isochrones (via TravelTime, Mapbox, etc.) to pass the polygon directly — this also enables sellers without routing engines to participate.
For campaigns targeting 10+ locations, consider using `store_catchments` with a location catalog instead, which supports ongoing management and per-location reporting. `geo_proximity` does not have an exclusion variant — this is by design, as excluding "everyone near a point" is rarely a meaningful targeting constraint.
Sellers SHOULD enforce minimum area thresholds consistent with their privacy policies and applicable regulations. The seller must declare `geo_proximity` support in `get_adcp_capabilities`, specifying which methods (`radius`, `travel_time`, `geometry`) and transport modes are supported. Product `overlay_support.geo_proximity` is the binding package-level contract and may also include `max_values_per_package`. Buyers request the needed methods and transport modes in `required_overlay_support.geo_proximity`; the response-only numeric limit does not participate in matching. Because multiple proximity entries use OR, a create or update with more entries than the disclosed limit MUST be rejected with `UNSUPPORTED_FEATURE` before any mutation is applied.
Validated examples:
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"geo_proximity": [
{
"lat": 51.2277,
"lng": 6.7735,
"label": "Düsseldorf",
"travel_time": { "value": 2, "unit": "hr" },
"transport_mode": "driving"
}
]
}
```
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"geo_proximity": [
{
"lat": 51.4700,
"lng": -0.4543,
"label": "Heathrow Airport",
"radius": { "value": 30, "unit": "km" }
}
]
}
```
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/targeting.json",
"geo_proximity": [
{
"label": "2hr drive from Düsseldorf",
"geometry": {
"type": "Polygon",
"coordinates": [[[5.87, 50.35], [8.23, 50.35], [8.23, 52.10], [5.87, 52.10], [5.87, 50.35]]]
}
}
]
}
```
## Benefits for Different Stakeholders
### For Buyers
* **Simpler planning**: Describe audience needs naturally
* **Transparent pricing**: All costs included upfront
* **Reduced complexity**: No targeting configuration required
* **Better outcomes**: Publisher expertise optimizes delivery
### For Publishers
* **Pricing control**: Bundle targeting into product pricing
* **Expertise utilization**: Apply knowledge of inventory and audiences
* **Simplified integration**: Fewer technical targeting parameters
* **Market positioning**: Differentiate through targeting capabilities
### For Platforms
* **Reduced conflicts**: Single targeting source eliminates layering issues
* **Cleaner implementation**: Less complex targeting logic required
* **Better performance**: Optimized for publisher inventory characteristics
## Real-Time Targeting Signals
Orchestrators can provide **real-time targeting signals** to publishers for dynamic, high-cardinality targeting beyond what can be expressed in static overlays. These signals enable:
* **Brand safety** - Real-time content filtering and adjacency controls
* **Brand suitability** - Contextual alignment with brand values
* **Audience targeting** - Dynamic audience segments updated in real-time
* **Contextual targeting** - Page-level or moment-level targeting decisions
Real-time signals are provided through the [AdCP Signals Protocol](/dist/docs/3.2.8/signals/overview), which allows orchestrators to supply targeting data at impression time.
### Key Differences: Signals vs Overlays
* Signals are **evaluated at impression time**, not campaign setup
* Signals support **higher cardinality** (thousands of values vs. dozens)
* Signals can be **updated continuously** without modifying the media buy
* Signals enable **sophisticated contextual targeting** that briefs cannot express
### When to Use Real-Time Signals
✅ **Use Real-Time Signals For:**
* Brand safety filtering (block unsafe content)
* Brand suitability scoring (prefer suitable contexts)
* Dynamic audience targeting (real-time segment membership)
* Contextual targeting (page-level or moment-level decisions)
* High-cardinality targeting (thousands of values)
* Targeting that changes during campaign flight
## Managing keywords after launch
Both keyword targets and negative keywords support incremental operations in `update_media_buy`, avoiding replacement of the complete keyword dimension:
* **`keyword_targets_add`** — upserts by `(keyword, match_type)` identity. Adds new keywords or updates `bid_price` on existing ones.
* **`keyword_targets_remove`** — removes matching `(keyword, match_type)` pairs.
* **`negative_keywords_add`** — appends negatives. Duplicates are no-ops.
* **`negative_keywords_remove`** — removes matching pairs. Missing entries are no-ops.
```json theme={null}
{
"packages": [
{
"package_id": "pkg_sponsored_search_001",
"keyword_targets_add": [
{ "keyword": "trail running shoes", "match_type": "phrase", "bid_price": 0.95 }
],
"keyword_targets_remove": [
{ "keyword": "running shoes", "match_type": "broad" }
],
"negative_keywords_add": [
{ "keyword": "diy", "match_type": "broad" },
{ "keyword": "how to make running shoes", "match_type": "phrase" }
]
}
]
}
```
Sellers SHOULD return a validation error if `targeting_overlay.keyword_targets` is present in the same request as `keyword_targets_add` or `keyword_targets_remove` (and likewise for negative keywords). The incremental operations and the corresponding targeting-dimension replacement or clear are mutually exclusive within a single update.
To remove all keyword targeting while preserving other overlay fields, send
`targeting_overlay.keyword_targets: null`. Omitting `keyword_targets` preserves
the stored list.
## Implementation Requirements
### Publishers MUST:
1. **Support Geographic Targeting**: Handle geographic inclusion and exclusion parameters (`geo_countries`, `geo_countries_exclude`, `geo_regions`, `geo_regions_exclude`, `geo_metros`, `geo_metros_exclude`, `geo_postal_areas`, `geo_postal_areas_exclude`, `geo_places`, `geo_places_exclude`) to the extent your platform supports them. Declare supported metro, postal, and place systems in `get_adcp_capabilities`
2. **Interpret Briefs**: Use briefs to determine appropriate audience and content targeting
3. **Validate Targeting**: Reject media buys with targeting that cannot be supported
4. **Document Limitations**: Clearly communicate any geographic targeting limitations in product descriptions
### Buyers SHOULD:
1. **Use Briefs First**: Express most targeting needs in natural language briefs
2. **Minimize Overlays**: Only use technical targeting for geographic restrictions or RCT testing
3. **Trust Publishers**: Let publishers apply their inventory knowledge to brief interpretation
4. **Validate Early**: Check product capabilities before applying technical targeting
## Best Practices
1. **Default to briefs** - Start with natural language descriptions
2. **Write Clear Briefs**: Be specific about audience and context requirements
3. **Trust Publisher Expertise**: Publishers know their inventory capabilities best
4. **Use signals for dynamic targeting** - Real-time signals handle complex, high-cardinality targeting better than overlays
5. **Minimize Technical Overlays**: Use only for geographic restrictions or compliance
6. **Validate Audience Fit**: Ensure product descriptions match campaign goals
7. **Inclusive pricing** - Expect targeting costs to be built into product rates
## Future Evolution
* **Enhanced Brief Processing**: More sophisticated natural language understanding
* **Audience Discovery**: Better tools for exploring available audiences
* **Deeper Signal Integration**: More sophisticated real-time targeting capabilities
* **Performance Optimization**: AI-driven audience refinement based on campaign results
## Related Documentation
* **[Trusted Match Protocol (TMP)](/dist/docs/3.2.8/trusted-match)** - Real-time execution layer for impression-time targeting, frequency capping, and brand suitability
* **[Signals Protocol](/dist/docs/3.2.8/signals/overview)** - Real-time targeting signals for brand suitability and contextual targeting
* **[Product Discovery](/dist/docs/3.2.8/media-buy/product-discovery/)** - How briefs lead to targeted product recommendations
* **[Example Briefs](/dist/docs/3.2.8/media-buy/product-discovery/example-briefs)** - Real examples of effective targeting briefs
* **[Policy Compliance](/dist/docs/3.2.8/media-buy/media-buys/policy-compliance)** - Automated compliance checking and enforcement
# Implementing Standard Format Support
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/capability-discovery/implementing-standard-formats
How AdCP 3.2 sales agents declare standard creative acceptance with canonical product format options.
This guide is for sales agents declaring the creative contracts their inventory accepts. In AdCP 3.2, author canonical `Product.format_options[]`. `list_creative_formats`, recursive creative-agent catalogs, and compound named format IDs are deprecated compatibility surfaces.
## Choose the authority first
| Question | Authoritative surface |
| - | - |
| What does a publisher surface accept? | Publisher `adagents.json.formats[]` |
| What can this seller deliver for a product? | That product's closed `format_options[]` set |
| Which creative agent can produce or validate it? | `get_adcp_capabilities.creative.supported_formats[]` |
The seller declares deliverability; it does not nominate a creative producer. Buyers can use the AgenticAdvertising.org registry to find creative agents whose self-declared canonical envelope satisfies the product declaration.
Zero registry matches is a valid result: it means no protocol-exposed build, validation, or preview service currently advertises that contract. The buyer may still supply an already-conforming finished manifest or use a seller-returned preview, but MUST NOT infer a renderer from the publisher or product format declaration.
## Standard formats
For standard display, video, audio, and native shapes, use the canonical `format_kind` and narrow it with explicit parameters and slots. Do not create a new identifier merely because your product has a different price or placement name.
```json theme={null}
{
"product_id": "daily_pulse_homepage_display",
"name": "Daily Pulse homepage display",
"format_options": [
{
"format_option_id": "homepage_image_300x250",
"format_kind": "image",
"params": {
"width": 300,
"height": 250,
"slots": [
{ "asset_group_id": "image_main", "asset_type": "image", "required": true },
{ "asset_group_id": "landing_page_url", "asset_type": "url", "required": true }
]
}
}
]
}
```
`format_options[]` is a closed set. A package or creative selector outside it must be rejected. Price, floor, availability, and deal eligibility stay on the product or pricing option, not in format parameters.
## Publisher-owned formats
When a product sells a publisher-catalog format, repeat its namespace and canonical declaration inline:
```json theme={null}
{
"format_options": [
{
"publisher_domain": "shorts.streamhaus.example",
"format_option_id": "vertical_video",
"format_kind": "video_hosted",
"params": {
"width": 1080,
"height": 1920,
"duration_ms_range": [5000, 60000],
"slots": [
{ "asset_group_id": "video_main", "asset_type": "video", "required": true }
]
}
}
]
}
```
Resolve the publisher's `/.well-known/adagents.json` first. If the publisher has not adopted AdCP, use an explicitly identified AgenticAdvertising.org community mirror. Do not promote one sales agent's product declaration into a publisher fact.
## Custom formats
Use `format_kind: "custom"` only when the structural creative contract cannot be expressed by a canonical kind. Supply both `format_shape` and an immutable, digest-pinned `format_schema`.
```json theme={null}
{
"format_option_id": "homepage_takeover",
"format_kind": "custom",
"format_shape": "multi_placement_takeover",
"format_schema": {
"uri": "https://formats.daily-pulse.example/homepage-takeover.schema.json",
"digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
"canonical_formats_only": true,
"params": {}
}
```
## Multi-placement coverage
Product-level options are the upper bound. Placement-level options may narrow that set but cannot broaden it. For every included delivery placement, the selected package format set must have a non-empty compatible intersection. Reject or refine a package that cannot cover all included placements; never silently drop inventory.
## Finding a creative producer
Sales agents do not publish a recursive list of creative agents. A buyer can reverse-query the registry and then verify the selected agent directly:
```http theme={null}
GET /api/registry/agents?publisher_domain=shorts.streamhaus.example&format_option_id=vertical_video&creative_operation=build
```
The creative agent's `supported_formats[]` entry supplies its local `capability_id`. That string is passed to `build_creative.target_capability_id`; it is never copied onto the product or returned manifest.
## 3.x compatibility
A 3.2 seller may project canonical declarations into deprecated `format_ids[]` for an older peer. When both fields are emitted, they must describe the same underlying contracts and canonical fields win. Do not independently author or extend the legacy catalog.
## Related documentation
* [Canonical formats](/dist/docs/3.2.8/creative/canonical-formats)
* [Media products](/dist/docs/3.2.8/media-buy/product-discovery/media-products)
* [Creative-agent capabilities](/dist/docs/3.2.8/protocol/get_adcp_capabilities)
* [Deprecated `list_creative_formats`](/dist/docs/3.2.8/creative/task-reference/list_creative_formats)
# Capability Discovery
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/capability-discovery/index
AdCP capability discovery — understand what creative formats a seller supports and which properties they represent before buying media.
Before you can effectively buy advertising through AdCP, you need to understand two fundamental capabilities: **what creative formats are supported** and **which properties sales agents are authorized to represent**. This section covers the tools and concepts that form the foundation of AdCP's advertising ecosystem.
## What You'll Learn
### [Implementing Standard Format Support](/dist/docs/3.2.8/media-buy/capability-discovery/implementing-standard-formats) 🎨
Learn how sales agents can support standard creative formats through the reference creative agent. Learn how to:
* Reference standard IAB formats without replicating them
* Implement custom formats for unique inventory
* Use format ID namespacing to prevent conflicts
* Combine standard and custom format support
* Validate format compatibility with advertising products
* Leverage the Standard Creative Agent for standard formats
* Work with publisher-specific creative agents for custom formats
### [Understanding Authorization](/dist/docs/3.2.8/governance/property/authorized-properties) 🔐
Learn how AdCP prevents unauthorized resale and ensures sales agents are legitimate. Understand:
* The problem of unauthorized resale in digital advertising
* How publishers authorize sales agents via `adagents.json`
* How to validate sales agent authorization before purchasing
* Property tags and large-scale authorization management
> [!NOTE]
>
> **Cross-Protocol Foundation**: The `adagents.json` authorization system applies across ALL AdCP protocols (Media Buy, Signals, and future Curation). See the [adagents.json specification](/dist/docs/3.2.8/governance/property/adagents) for complete implementation details.
## Foundation Tasks
These capability discovery tasks provide the reference data needed for effective AdCP workflows:
### [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities)
The primary capability discovery task. Returns protocol versions, supported features, portfolio information, and governance capabilities in a single call. Use this as your first interaction with any AdCP agent.
### Canonical format sources
Read seller deliverability from `get_products` `Product.format_options[]`, publisher acceptance from `adagents.json.formats[]`, and creative production capabilities from `get_adcp_capabilities.creative.supported_formats[]`. `list_creative_formats` is deprecated in 3.2.
## Integration Pattern
Capability discovery typically happens early in your AdCP workflow:
1. **Discover Capabilities**: Call [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) to learn what the agent supports
2. **Understand Formats**: Read canonical `format_options[]` on returned products and resolve publisher declarations when referenced
3. **Validate Authorization**: Check the `media_buy.portfolio` from capabilities, then verify via publisher `adagents.json`
4. **Discover Products**: Search for advertising inventory with [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products)
5. **Plan Creatives**: Match product declarations to creative-agent `supported_formats[]` capabilities
6. **Execute Campaigns**: Create media buys with confidence in format compatibility and authorization
## Why This Matters
### Creative Formats
* **Production Planning**: Know requirements before creating assets
* **Creative Agents**: Leverage AI-powered agents to build and validate creatives
* **Platform Compatibility**: Ensure creatives work across advertising platforms
* **Cost Efficiency**: Avoid recreating assets due to specification mismatches
* **Quality Assurance**: Meet technical standards for optimal performance
* **Preview Capabilities**: Test creative rendering before campaign launch
### Authorized Properties
* **Fraud Prevention**: Avoid unauthorized sellers and inventory fraud
* **Brand Safety**: Ensure you're buying from legitimate property owners
* **Legal Compliance**: Maintain clear audit trails of authorized transactions
* **Trust Building**: Create confidence in the advertising supply chain
Together, these capabilities provide the foundation for safe, efficient, and effective advertising through AdCP.
## Related Documentation
* **[Task Reference](/dist/docs/3.2.8/media-buy/task-reference/)** - Complete API documentation
* **[Product Discovery](/dist/docs/3.2.8/media-buy/product-discovery/)** - Finding advertising inventory
* **[Creatives](/dist/docs/3.2.8/media-buy/creatives/)** - Creative asset management
* **[Creative Protocol](/dist/docs/3.2.8/creative/)** - Creative agents and manifests
* **[Creative Channel Guides](/dist/docs/3.2.8/creative/channels/video)** - Format examples and patterns
* **[Creative Manifests](/dist/docs/3.2.8/creative/creative-manifests)** - Understanding creative specifications
* **[adagents.json Specification](/dist/docs/3.2.8/governance/property/adagents)** - Publisher authorization system (applies across all AdCP protocols)
# Commerce Media
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/commerce-media
Commerce media in AdCP: why retail media networks should stand up agentic storefronts instead of building self-service platforms, and how to model sponsored products, in-store digital, and closed-loop attribution.
Every retail media network that builds a self-service ad platform ends up in the same place: competing for agency attention against the largest grocery, pharmacy, and general merchandise retailers — each asking brands to learn one more interface, manage one more login, reconcile one more set of reports.
There's an alternative. Stand up an agentic storefront: expose your inventory so buyer agents can discover, transact on, and measure it through the same protocol they use for every other seller. When agents handle discovery, the advantage shifts from UI quality to data quality — and data is where most retailers already have a moat.
## The storefront, not the platform

Daniel runs retail media at ShopGrid, a marketplace with 200M monthly shoppers and deterministic purchase data from its loyalty program. When he was tasked with building ShopGrid's ad business, the roadmap looked familiar: self-service campaign tool, proprietary audience builder, custom reporting dashboard, eventually a DSP.
He got halfway through the build before he realized the problem. The brands ShopGrid wanted to attract — CPG companies, health and beauty brands, consumer electronics — were already managing campaigns across a dozen retail media platforms. Each platform had its own API, its own audience taxonomy, its own reporting format. Asking brands to integrate yet another platform meant competing on UI quality against companies with 100x the engineering budget.

ShopGrid's moat wasn't going to be its dashboard. The moat was the data: deterministic purchase attribution from millions of loyalty members, real-time inventory across thousands of stores, and in-store digital screens at the point of purchase. The question was how to make that data and inventory accessible to the broadest possible set of buyers.

Daniel stood up an AdCP sales agent instead. ShopGrid's entire retail media catalog — sponsored products, on-site display, in-store screens — is exposed as products that any buyer agent can discover via `get_products`. The loyalty data powers closed-loop attribution reported through standard delivery metrics. The store locations are modeled as catalogs with catchment areas for proximity targeting.

The result: any buyer agent that speaks AdCP can transact on ShopGrid inventory without a custom integration. Sam at Pinnacle Agency discovered ShopGrid's sponsored products while running a cross-retailer campaign for Summit Foods — through the same protocol and brief he used for other retailers.
What every retail media team actually wants is the control of self-serve, the ease of managed service, and all the data in their own internal tools. A self-service platform gives you control but requires massive engineering investment. Managed service is easy for buyers but doesn't scale. An agentic storefront resolves the tension: the retailer defines the products, pricing, and rules (control); buyer agents handle discovery and execution without a sales rep in the loop (ease); and because the retailer runs the MCP server, every transaction flows through their infrastructure (data stays home).
This doesn't mean ShopGrid abandoned everything else. Brands that aren't using buyer agents still need basic self-service access. But the agentic storefront is the growth layer — it's how ShopGrid reaches buyers who would never have integrated a mid-size retailer's proprietary platform.
The table below maps familiar retail media concepts to their AdCP equivalents.
## Concept mapping
| Retail media concept | AdCP equivalent | Reference |
| - | - | - |
| Retailer / retail media network | Sales agent (MCP server) | [`adagents.json`](/dist/docs/3.2.8/media-buy/advanced-topics/accounts-and-security) |
| Advertiser account with retailer | `account_id` + `list_accounts` | [Accounts & Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) |
| Brand's product catalog | `brand.product_catalog` | [Brand identity](/dist/docs/3.2.8/brand-protocol/brand-json) |
| GTIN / SKU selection for promotion | Catalog selectors (`ids`, `gtins`, `tags`) on `Catalog` | [Catalogs](/dist/docs/3.2.8/creative/catalogs) |
| Sponsored product listing | Product with catalog-rendered creative | [Creative Formats](/dist/docs/3.2.8/creative/formats) |
| On-site display / video | Product with canonical `format_options` | [Media Products](/dist/docs/3.2.8/media-buy/product-discovery/media-products) |
| Retailer-owned shopper signal | Brief-based; optional named segments discovered in `signal_targeting_options` and selected with package-level `signal_targeting_groups` | [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) |
| ROAS target / max conversions | `optimization_goals` on package | [Optimization & Reporting](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting) |
| Closed-loop measurement | `outcome_measurement` + `conversion_tracking` on product | [Delivery Reporting](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) |
| Attribution window (14d click, 1d view) | `attribution_window` in delivery response | [Delivery Reporting](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) |
| ROAS / attributed revenue | `roas`, `conversion_value` in delivery metrics | [Delivery Reporting](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) |
| In-store attribution | `by_action_source` with `in_store` | [Delivery Reporting](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) |
| Store locations / store locator | Store catalog (seller-provided or buyer-synced) | [Catalogs — Stores](/dist/docs/3.2.8/creative/catalogs#stores) |
| Real-time inventory / in-stock | Inventory catalog via `sync_catalogs` | [Catalogs](/dist/docs/3.2.8/creative/catalogs) |
| Proximity / catchment targeting | Store catchment areas (isochrone, radius, GeoJSON) | [Catalogs — Catchment areas](/dist/docs/3.2.8/creative/catalogs#catchment-areas) |
Each retailer is a separate sales agent. Their media offerings are modeled as products. The buyer's brand identity carries the product catalog for SKU-level creative rendering. Account relationships between brands and retailers are managed via `list_accounts` and `account` on media buys — see [Accounts & Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents).
## The product spectrum
Retail media networks offer diverse product types — not just sponsored listings. All share the `retail_media` channel, but differ in format, pricing, and creative requirements. Daniel modeled ShopGrid's full portfolio as separate products so buyer agents can mix and match across the funnel.
### Sponsored product listings
The simplest commerce media product. The retailer renders the creative from the buyer's product catalog — no custom creative upload needed. Pricing is typically CPC.
```json theme={null}
{
"product_id": "shopgrid_sponsored_products",
"name": "Sponsored Products - Search & Browse",
"description": "Sponsored product listings in search results and category pages. Products are rendered from retailer catalog data.",
"channels": ["retail_media"],
"publisher_properties": [
{ "publisher_domain": "shopgrid.example", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "sponsored_product_listing", "format_kind": "sponsored_placement", "params": {} }
],
"delivery_type": "non_guaranteed",
"pricing_options": [
{
"pricing_option_id": "sp_cpc",
"pricing_model": "cpc",
"floor_price": 0.25,
"price_guidance": { "p50": 0.85, "p75": 1.20 },
"currency": "USD",
"min_spend_per_package": 50
}
],
"delivery_measurement": {
"provider": "ShopGrid deterministic purchase attribution",
"notes": "Deterministic purchase attribution from first-party shopper data. 14-day lookback."
},
"outcome_measurement": {
"type": "attributed_sales",
"attribution": "deterministic_purchase",
"window": { "interval": 14, "unit": "days" },
"reporting": "daily_api"
},
"conversion_tracking": {
"action_sources": ["website", "app", "in_store"],
"supported_targets": ["cost_per", "per_ad_spend"],
"platform_managed": true
},
"creative_policy": {
"co_branding": "none",
"landing_page": "any",
"templates_available": true
},
"catalog_types": ["product"],
"catalog_match": {
"matched_gtins": ["00013000006408", "00013000006415", "00013000006422"],
"matched_count": 3,
"submitted_count": 1200
}
}
```
The `catalog_types` field declares what catalog types this product supports. The `catalog_match` field tells the buyer which of their catalog items are eligible on this retailer. Buyers use these values as catalog selectors (`gtins`, `ids`) when creating media buys — the same way `publisher_properties` lists available properties for refinement. Sellers can include `matched_gtins`, `matched_ids`, or both.
Sponsored product listings are catalog-rendered — the retailer pulls title, price, image, and rating from its own catalog data matched via GTIN. Enhanced product content (comparison charts, lifestyle galleries, brand story modules) and brand stores are complementary content strategies managed through the retailer's content systems, not through the ad buy.
Key characteristics:
* **CPC pricing** with auction-based bidding
* **`platform_managed: true`** — the retailer provides always-on purchase attribution
* **`supported_targets`** — tells buyers which target kinds are available when setting `optimization_goals` on packages
* **`templates_available: true`** — the retailer renders creatives from catalog data
* **`action_sources`** includes `in_store` for omnichannel attribution
### On-site display and video
Display and video ads on retailer properties, targeted using retailer first-party shopper data. Buyers provide standard creatives. Higher minimums and CPMs reflect the value of retailer audience data and guaranteed placement.
```json theme={null}
{
"product_id": "shopgrid_onsite_display",
"name": "Category Shoppers - On-Site Display & Video",
"description": "Display and video ads on ShopGrid marketplace and app, targeting shoppers with relevant purchase history.",
"channels": ["retail_media"],
"publisher_properties": [
{ "publisher_domain": "shopgrid.example", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "display_300x250", "format_kind": "image", "params": { "width": 300, "height": 250 } },
{ "format_option_id": "display_728x90", "format_kind": "image", "params": { "width": 728, "height": 90 } },
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } }
],
"delivery_type": "guaranteed",
"pricing_options": [
{
"pricing_option_id": "onsite_cpm",
"pricing_model": "cpm",
"fixed_price": 14.00,
"currency": "USD",
"min_spend_per_package": 10000
}
],
"delivery_measurement": {
"provider": "Retailer ad server with IAS viewability",
"notes": "Impressions per IAB guidelines. MRC-accredited viewability."
},
"outcome_measurement": {
"type": "incremental_sales_lift",
"attribution": "deterministic_purchase",
"window": { "interval": 30, "unit": "days" },
"reporting": "weekly_dashboard"
},
"conversion_tracking": {
"action_sources": ["website", "app"],
"supported_targets": ["cost_per", "per_ad_spend"],
"platform_managed": true
},
"creative_policy": {
"co_branding": "required",
"landing_page": "retailer_site_only",
"templates_available": true
}
}
```
Note the creative policy: retailers commonly require co-branding and restrict landing pages to the retailer's own site.
### Off-site audience extension
The retailer uses first-party purchase data to target audiences on third-party inventory — extending reach beyond the retailer's own site. The product still belongs to the `retail_media` channel because the buying context is the retailer's data asset.
```json theme={null}
{
"product_id": "shopgrid_offsite_extension",
"name": "Shopper Audiences - Off-Site Display & Video",
"description": "Reach ShopGrid shoppers across premium display and video inventory using first-party purchase data.",
"channels": ["retail_media"],
"publisher_properties": [
{ "publisher_domain": "shopgrid.example", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "display_300x250", "format_kind": "image", "params": { "width": 300, "height": 250 } },
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } }
],
"delivery_type": "guaranteed",
"pricing_options": [
{
"pricing_option_id": "offsite_cpm",
"pricing_model": "cpm",
"fixed_price": 13.50,
"currency": "USD",
"min_spend_per_package": 10000
}
],
"delivery_measurement": {
"provider": "Self-reported impressions from proprietary ad server",
"notes": "Impressions counted per IAB guidelines. Viewability via IAS."
},
"outcome_measurement": {
"type": "incremental_sales_lift",
"attribution": "deterministic_purchase",
"window": { "interval": 30, "unit": "days" },
"reporting": "weekly_dashboard"
},
"conversion_tracking": {
"action_sources": ["website", "app", "in_store"],
"supported_targets": ["cost_per", "per_ad_spend"],
"platform_managed": true
}
}
```
### Premium placements
Homepage takeovers, category sponsorships, seasonal event placements. These high-visibility positions are sold at fixed rates with guaranteed delivery — often booked well in advance.
```json theme={null}
{
"product_id": "shopgrid_homepage_takeover",
"name": "Homepage Takeover - 24 Hours",
"description": "Exclusive homepage banner and hero placement for 24 hours.",
"channels": ["retail_media"],
"publisher_properties": [
{ "publisher_domain": "shopgrid.example", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "display_970x250", "format_kind": "image", "params": { "width": 970, "height": 250 } },
{ "format_option_id": "display_300x250", "format_kind": "image", "params": { "width": 300, "height": 250 } }
],
"placements": [
{
"kind": "seller_inline",
"seller_agent": { "agent_url": "https://ads.shopgrid.example/adcp" },
"placement_id": "homepage_hero",
"name": "Homepage Hero Banner",
"mode": "targetable",
"format_options": [{ "format_option_id": "display_970x250", "format_kind": "image", "params": { "width": 970, "height": 250 } }]
},
{
"kind": "seller_inline",
"seller_agent": { "agent_url": "https://ads.shopgrid.example/adcp" },
"placement_id": "homepage_sidebar",
"name": "Homepage Sidebar",
"mode": "targetable",
"format_options": [{ "format_option_id": "display_300x250", "format_kind": "image", "params": { "width": 300, "height": 250 } }]
}
],
"delivery_type": "guaranteed",
"pricing_options": [
{
"pricing_option_id": "takeover_flat",
"pricing_model": "flat_rate",
"fixed_price": 50000.00,
"currency": "USD"
}
],
"delivery_measurement": {
"provider": "Retailer ad server",
"notes": "Guaranteed impressions based on homepage traffic projections."
},
"outcome_measurement": {
"type": "attributed_sales",
"attribution": "deterministic_purchase",
"window": { "interval": 14, "unit": "days" },
"reporting": "daily_api"
},
"creative_policy": {
"co_branding": "required",
"landing_page": "retailer_site_only",
"templates_available": false
}
}
```
Premium placements use the `placements` array so buyers can assign different creatives to different positions within the same product.
### In-store digital
Digital screens in physical retail locations — checkout lanes, end-caps, entrance displays, and waiting areas. These bridge the digital-physical gap, with measurement tied to in-store purchases. When paired with a synced store catalog, in-store digital products can target specific locations and show inventory-aware creative.
In-store is where retail media networks have inventory that no one else can replicate. A retailer with thousands of physical locations has screens at the point of purchase — reaching shoppers while they're browsing aisles, comparing products at the shelf, and waiting in line. Many of these shoppers never see digital ads elsewhere: they shop in-store exclusively, making them unreachable through online channels.
```json theme={null}
{
"product_id": "shopgrid_instore_screens",
"name": "In-Store Digital Screens",
"description": "Digital screens at checkout lanes, end-cap displays, and pharmacy waiting areas across 2,000+ locations.",
"channels": ["retail_media"],
"publisher_properties": [
{ "publisher_domain": "shopgrid.example", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "display_1080x1920", "format_kind": "image", "params": { "width": 1080, "height": 1920 } },
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } }
],
"placements": [
{
"kind": "seller_inline",
"seller_agent": { "agent_url": "https://ads.shopgrid.example/adcp" },
"placement_id": "checkout_screen",
"name": "Checkout Lane Screens",
"mode": "targetable",
"format_options": [
{ "format_option_id": "display_1080x1920", "format_kind": "image", "params": { "width": 1080, "height": 1920 } },
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } }
]
},
{
"kind": "seller_inline",
"seller_agent": { "agent_url": "https://ads.shopgrid.example/adcp" },
"placement_id": "endcap_screen",
"name": "Aisle End-Cap Displays",
"mode": "targetable",
"format_options": [
{ "format_option_id": "display_1080x1920", "format_kind": "image", "params": { "width": 1080, "height": 1920 } }
]
},
{
"kind": "seller_inline",
"seller_agent": { "agent_url": "https://ads.shopgrid.example/adcp" },
"placement_id": "pharmacy_waiting",
"name": "Pharmacy Waiting Area",
"mode": "targetable",
"format_options": [
{ "format_option_id": "display_1080x1920", "format_kind": "image", "params": { "width": 1080, "height": 1920 } },
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } }
]
}
],
"delivery_type": "guaranteed",
"pricing_options": [
{
"pricing_option_id": "instore_cpm",
"pricing_model": "cpm",
"fixed_price": 12.00,
"currency": "USD",
"min_spend_per_package": 5000
}
],
"delivery_measurement": {
"provider": "Venue traffic sensors",
"notes": "Impressions estimated from foot traffic data. Updated weekly."
},
"conversion_tracking": {
"action_sources": ["in_store"],
"platform_managed": true
},
"creative_policy": {
"co_branding": "none",
"landing_page": "any",
"templates_available": true
}
}
```
Different screen placements have different creative requirements. Checkout screens offer 30-90 seconds of captive dwell time with a stationary shopper at close range. End-cap displays catch shoppers walking past with 2-3 seconds of glance time from further away. Pharmacy waiting areas have extended dwell time and a seated audience. Most in-store networks are silent — creative should be designed for sound-off unless the placement specifies otherwise.
In-store products pair with the retailer's store catalog. The catalog exposes store locations with catchment areas (radius, isochrone, or GeoJSON polygons), enabling buyer agents to target specific geographies or store clusters. When combined with the brand's product catalog, in-store screens can show contextually relevant creative — the right product, in the right store, near the right shelf.
### Beyond these examples
Retail media portfolios often extend beyond the five product types above. Sponsored brand ads — a headline, brand logo, and 2-3 featured products — sit between sponsored product listings and display, with a custom headline from the buyer and catalog-rendered product tiles. Digital coupons and cashback offers tie directly to purchase and don't fit neatly into impression-based models — they can be modeled as products with CPA pricing and `conversion_tracking`. Sponsored placements in retailer email newsletters and app push notifications are high-performing, low-funnel products modeled the same way as on-site display with different canonical `format_options`. Shoppable video — where products are tagged within the video frame and viewers can add items to cart — combines video formats with catalog-rendered product overlays. Keyword-level search sponsorships, sampling programs, and recipe integrations each have distinct economics but follow the same pattern: a product with the right pricing model, format, and measurement declarations.
## End-to-end workflow
### Brand with product catalog
The buyer provides a brand reference that includes their product catalog feed. This enables SKU-level targeting and catalog-rendered creatives:
```json theme={null}
{
"name": "Summit Foods",
"url": "https://summitfoods.example.com",
"product_catalog": {
"feed_url": "https://summitfoods.example.com/products.xml",
"feed_format": "google_merchant_center",
"categories": ["food/sauces", "food/condiments", "beverages"],
"update_frequency": "daily"
}
}
```
The feed contains GTINs, titles, prices, and images — everything needed to render sponsored product listings and match products across retailers.
### Sync catalogs to the account
Before creating media buys, sync the brand's data feeds to the retailer's account via `sync_catalogs`. This builds account state that creatives and targeting reference at serve time. See [Account state](/dist/docs/3.2.8/building/by-layer/L2/account-state) for how this fits the broader setup sequence.
```json theme={null}
{
"account": { "account_id": "acct_summitfoods_shopgrid_001" },
"catalogs": [
{
"catalog_id": "product-feed",
"name": "Summit Foods Product Catalog",
"type": "product",
"url": "https://summitfoods.example.com/products.xml",
"feed_format": "google_merchant_center",
"update_frequency": "daily"
},
{
"catalog_id": "inventory-feed",
"name": "Store-Level Inventory",
"type": "inventory",
"url": "https://feeds.summitfoods.example.com/inventory.json",
"feed_format": "custom",
"update_frequency": "hourly"
}
]
}
```
The platform ingests each feed:
* **Product catalog** — validates GTINs against the retailer's own catalog, reports item-level approval status
* **Inventory feed** — refreshes stock data hourly so creatives can show "In stock nearby"
> [!NOTE]
>
> **Store locations are seller-provided, not buyer-synced.** In retail media, the retailer owns their store locations — a CPG brand doesn't sync the retailer's stores to the retailer. The retailer's store catalog (with catchment areas for proximity targeting) is platform-side data that the buyer can reference in targeting. Buyers who operate their own physical locations (e.g., a DTC brand with retail stores, a restaurant chain) would sync their store catalogs to other platforms via `sync_catalogs`.
Formats that require synced catalogs declare `catalog` asset types in their `assets` array — the buying agent checks these before submitting creatives. A sponsored product carousel might require both a `product` and `inventory` catalog.
### Find products
Query `get_products` with `channels: ["retail_media"]` to find commerce media products. The brand identity enables the seller to filter by catalog eligibility, and the `keywords` filter signals search terms you want to target so the seller can assess availability and recommend products where those terms are actionable:
```json theme={null}
{
"brief": "Promote our organic ketchup line across grocery retailers. Focus on high-intent shoppers.",
"brand": {
"domain": "summitfoods.example.com"
},
"filters": {
"channels": ["retail_media"],
"keywords": [
{ "keyword": "organic ketchup", "match_type": "exact" },
{ "keyword": "condiments" }
]
}
}
```
The seller returns products where the buyer's GTINs have matches in the retailer's catalog. A multi-product retailer might return sponsored products, on-site display, and off-site extension as separate products.
For sponsored product listings, sellers include `catalog_match` on each product to indicate which of the buyer's catalog items are eligible:
```json theme={null}
{
"product_id": "shopgrid_sponsored_products",
"catalog_match": {
"matched_gtins": ["00013000006408", "00013000006415", "..."],
"matched_count": 3,
"submitted_count": 1200
}
}
```
This tells the buyer which GTINs are eligible on this retailer and how many of their total catalog items were evaluated. Buyers use `matched_gtins` values as catalog `gtins` selectors when creating media buys — or use broader selectors like `tags` and `category` knowing the catalog coverage.
> [!TIP]
>
> Sellers can also return [proposals](/dist/docs/3.2.8/media-buy/product-discovery/media-products#proposals) with recommended budget allocations across product types — encoding media planning expertise that traditionally required human sales reps.
### Create media buy
A single media buy can span multiple product types and retailers. Each package targets a different product:
```json theme={null}
{
"account": { "account_id": "acct_summitfoods_shopgrid_001" },
"brand": {
"domain": "summitfoods.example.com"
},
"start_time": "2026-04-01T00:00:00Z",
"end_time": "2026-04-30T23:59:59Z",
"packages": [
{
"product_id": "shopgrid_sponsored_products",
"pricing_option_id": "sp_cpc",
"budget": 15000,
"bid_price": 1.10,
"pacing": "even",
"optimization_goals": [{
"kind": "event",
"event_sources": [
{ "event_source_id": "shopgrid_purchases", "event_type": "purchase", "value_field": "value" }
],
"target": { "kind": "per_ad_spend", "value": 3.0 },
"priority": 1
}]
},
{
"product_id": "shopgrid_onsite_display",
"pricing_option_id": "onsite_cpm",
"budget": 25000,
"pacing": "even"
},
{
"product_id": "shopgrid_homepage_takeover",
"pricing_option_id": "takeover_flat",
"budget": 50000
}
]
}
```
The `account` identifies the brand's billing relationship with this retailer. The sponsored products package uses catalog selectors (`gtins`, `tags`) to specify which items to promote and `optimization_goals` with a `per_ad_spend` target to tell the retailer to optimize for 3x return on purchase value. The display and premium packages use standard creative workflows.
### Delivery reporting
Commerce media delivery reports include attribution metrics that traditional media lacks. The `attribution_window` makes the measurement methodology transparent for cross-platform comparison:
```json theme={null}
{
"reporting_period": {
"start": "2026-04-01T00:00:00Z",
"end": "2026-04-14T23:59:59Z"
},
"currency": "USD",
"attribution_window": {
"post_click": { "interval": 14, "unit": "days" },
"post_view": { "interval": 1, "unit": "days" },
"model": "last_touch"
},
"media_buy_deliveries": [
{
"media_buy_id": "mb_shopgrid_001",
"status": "active",
"totals": {
"impressions": 850000,
"spend": 10350
},
"by_package": [
{
"package_id": "pkg_sp_001",
"pricing_model": "cpc",
"rate": 0.92,
"currency": "USD",
"impressions": 850000,
"spend": 10350,
"clicks": 11250,
"conversions": 2100,
"conversion_value": 28500,
"roas": 2.75,
"cost_per_acquisition": 4.93,
"by_action_source": [
{ "action_source": "website", "count": 1500, "value": 20000 },
{ "action_source": "app", "count": 350, "value": 4800 },
{ "action_source": "in_store", "count": 250, "value": 3700 }
],
"delivery_status": "delivering"
}
]
}
]
}
```
The `by_action_source` breakdown shows where conversions happened — website, app, and physical store. This omnichannel view is unique to commerce media.
## Closed-loop attribution

Commerce media's defining advantage is deterministic purchase attribution. Retailers match ad exposure to transactions using loyalty card data, login state, and point-of-sale records. This is the asset that makes retail media fundamentally different from every other media channel — and it's exactly what an agentic storefront exposes to buyer agents through standard delivery reporting.
### How products declare it
Products signal closed-loop capability through two fields:
**`reporting_capabilities.available_metrics`** declares which outcome metrics the product reports. Closed-loop retail media products typically report `conversions`, `conversion_value`, `roas`, `cost_per_acquisition`, `units_sold`, `new_to_brand_rate`, and incremental-lift metrics like `incremental_sales_lift` and `conversion_lift`. The methodology and attribution window flow through the `qualifier` slot on `committed_metrics` and package-level delivery `metric_values` (`attribution_methodology: "deterministic_purchase"` for retail-media closed loop; `attribution_window: { interval: 14, unit: "days" }` for the 14-day match window).
```json theme={null}
{
"reporting_capabilities": {
"available_metrics": [
"conversions", "conversion_value", "roas", "cost_per_acquisition",
"units_sold", "new_to_brand_rate", "incremental_sales_lift"
]
}
}
```
The legacy `outcome_measurement` field is **deprecated** but continues to work for one minor. Existing payloads:
```json theme={null}
{
"outcome_measurement": {
"type": "attributed_sales",
"attribution": "deterministic_purchase",
"window": { "interval": 14, "unit": "days" },
"reporting": "daily_api"
}
}
```
…are equivalent to declaring `conversion_value` (the standardized name for "attributed sales") in `available_metrics` plus the matching qualifier on `committed_metrics`. Migrate by populating both fields during the transition window; remove `outcome_measurement` at the next major.
**`conversion_tracking`** declares action sources and whether the retailer manages measurement:
```json theme={null}
{
"conversion_tracking": {
"action_sources": ["website", "app", "in_store"],
"supported_targets": ["cost_per", "per_ad_spend"],
"platform_managed": true
}
}
```
When `platform_managed` is `true`, the retailer provides always-on measurement. No buyer-side pixel or event source configuration needed. If the product also declares an `event_source` [execution requirement](/dist/docs/3.2.8/media-buy/specification#product-execution-requirements-experimental), the package binds the seller-managed source: its ID is the `sync_event_sources` response entry with `managed_by: "seller"`.
> [!NOTE]
>
> Different retailers use different attribution windows (e.g., 14-day click vs. 7-day click). The `attribution_window` in delivery responses makes this transparent so buyers can normalize ROAS comparisons across retailers.
### Key delivery metrics
| Metric | Field | Description |
| - | - | - |
| Return on ad spend | `roas` | `conversion_value / spend` |
| Attributed revenue | `conversion_value` | Total purchase value attributed to ads |
| Conversions | `conversions` | Purchase events attributed to ads |
| Cost per acquisition | `cost_per_acquisition` | `spend / conversions` |
| New-to-brand rate | `new_to_brand_rate` | Fraction of conversions from first-time brand buyers |
| In-store sales | `by_action_source` | Breakdown by `website`, `app`, `in_store` |
| By event type | `by_event_type` | Breakdown by `purchase`, `add_to_cart`, etc. |

## Differences from traditional media buying
| Aspect | Traditional media | Commerce media |
| - | - | - |
| Attribution | Probabilistic, modeled | Deterministic, purchase-based |
| Targeting data | Third-party, contextual | First-party purchase/loyalty data |
| Primary KPIs | Impressions, clicks, CTR | ROAS, conversions, attributed revenue |
| Creative (sponsored) | Buyer-provided | Catalog-rendered by retailer |
| Measurement owner | Third-party (IAS, DV) | Retailer platform (`platform_managed`) |
| Conversion sources | Website only | Website + app + in-store |
| Landing page | Any destination | Often retailer site only |
| Pricing models | CPM, CPC, CPCV | CPC (sponsored), CPM (display), flat rate (premium) |
## Best practices
### For retailers: standing up an agentic storefront
The default retail media playbook — build a self-service platform, hire a sales team, grow managed service revenue, eventually build a DSP — works for the largest retailers. For everyone else, it means years of engineering investment competing against platforms with orders-of-magnitude more resources.
An agentic storefront changes the economics. Instead of building a platform that brands must learn, you expose your inventory through a standard protocol that buyer agents already speak. Your engineering investment goes into your actual differentiators — data quality, measurement accuracy, inventory breadth — not into dashboard UX.
1. **Model product types separately** — sponsored products, on-site display, off-site, premium placements, and in-store digital should be distinct products with appropriate pricing and formats. This is how buyer agents comparison-shop across retailers.
2. **Lead with your data** — declare `outcome_measurement` with `deterministic_purchase` attribution and `conversion_tracking` with `platform_managed: true`. This is what buyer agents optimize against. Retailers with weak measurement lose to retailers with strong measurement, regardless of UI quality.
3. **Expose your physical footprint** — provide store catalogs with catchment areas so buyer agents can target by geography. In-store digital inventory is something no online-only platform can offer. Make it discoverable.
4. **Return `catalog_match`** on sponsored product listings so buyers see which GTINs/SKUs are eligible. This is the equivalent of a sales rep saying "we carry 3 of your 1,200 products" — but it happens automatically at query time.
5. **Include `attribution_window`** in delivery responses — buyers comparing across retailers need to know your lookback windows and model.
6. **Report `by_action_source`** to show omnichannel impact — website, app, and in-store conversions. The cross-channel view is unique to commerce media and drives budget allocation.
7. **Use proposals** — return recommended budget allocations across product types with `get_products` responses. This encodes your media planning expertise into the protocol, replacing the sales rep conversation with structured data that buyer agents can evaluate.
8. **Set `channels: ["retail_media"]`** on all commerce media products so buyers can filter by channel.
### For brands
1. **Set up accounts early** — use `list_accounts` to confirm your billing relationship with each retailer before placing buys
2. **Sync product and inventory feeds early** — product and inventory catalogs should be synced to the account before creating buys. Inventory feeds update hourly; product feeds daily.
3. **Reference retailer store catalogs in targeting** — the retailer's store locations and catchment areas are platform-side data. Use them for proximity targeting without needing to sync your own store catalog.
4. **Use `optimization_goals`** — set event goals with `cost_per` or `per_ad_spend` targets on packages to let the retailer optimize delivery against their purchase data
5. **Use catalog selectors strategically** — `gtins` for specific products, `tags` or `category` for broad promotions
6. **Budget across the funnel** — sponsored products for conversion, on-site display for awareness, off-site for reach extension
7. **Compare attribution windows** — use `attribution_window` in delivery reports to normalize ROAS across retailers with different lookback windows
## Related documentation
* [Account state](/dist/docs/3.2.8/building/by-layer/L2/account-state) — How catalogs, event sources, and campaigns build on the account
* [Accounts & Agents](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents) — Account setup and billing relationships
* [Media Channel Taxonomy](/dist/docs/3.2.8/reference/media-channel-taxonomy) — `retail_media` channel definition
* [Media Products](/dist/docs/3.2.8/media-buy/product-discovery/media-products) — Product model reference
* [Catalogs](/dist/docs/3.2.8/creative/catalogs) — Product, inventory, store, and promotion feeds
* [Brand identity](/dist/docs/3.2.8/brand-protocol/brand-json) — Product catalog and brand identity
* [Pricing Models](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models) — CPC, CPM, flat rate details
* [Optimization & Reporting](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting) — `optimization_goals` and conversion optimization
* [Delivery Reporting](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) — Commerce attribution metrics
* [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) — Brief-based targeting approach
# Conversion Tracking & Optimization Goals
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/conversion-tracking/index
AdCP conversion tracking — configure pixels and event sources with sync_event_sources, send conversion events with log_event, and set optimization goals for campaign delivery.
Conversion tracking in AdCP connects advertising spend to business outcomes. Two tasks handle the lifecycle: [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) configures where events come from, and [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event) sends the events themselves.
Event data feeds into delivery reporting (conversions, ROAS, cost per acquisition) and enables optimization goals on media buy packages.
## The flow
```mermaid theme={null}
sequenceDiagram
participant B as Buyer
participant S as Seller
rect rgb(240, 248, 255)
Note over B,S: Setup
B->>S: sync_event_sources (configure sources)
S->>B: Setup instructions (snippets, pixel URLs)
B->>B: Install snippets on site/app
end
rect rgb(240, 255, 240)
Note over B,S: Event collection
B->>S: log_event (send conversions)
S->>S: Match users, attribute conversions
end
rect rgb(255, 248, 240)
Note over B,S: Optimization
B->>S: create_media_buy (with optimization_goals)
S->>S: Optimize delivery toward conversions
B->>S: get_media_buy_delivery
S->>B: Conversion metrics (ROAS, CPA)
end
```
This shows the recommended order. In practice, media buys can be created before events are flowing — the seller begins optimizing once sufficient event history accumulates.
## Event source
An event source represents a channel through which conversion or marketing events are collected — a website pixel, mobile SDK, server-to-server integration, CRM import, or seller- or platform-native owned property such as a channel, profile, feed, podcast, or newsletter list.
Configure event sources with [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources). You provide an `event_source_id`, optional `name`, `event_types`, `value_currencies`, `action_source`, `surface`, and `allowed_domains`. `value_currencies` is required when the source will feed canonical ROAS. A multi-currency source may list several currencies; each buy consumes only records matching its media-buy currency, with no conversion. The response includes additional fields for each source:
| Field | Type | Description |
| - | - | - |
| `seller_id` | string | Seller-assigned identifier in their ad platform |
| `action` | string | What happened: `created`, `updated`, `unchanged`, `deleted`, `failed` |
| `managed_by` | string | `buyer` (you configured it) or `seller` (always-on, seller-managed) |
| `value_currencies` | string\[] | Currencies accepted for monetary event values and eligible for canonical ROAS |
| `action_source` | [ActionSource](#action-sources) | Flat source type for legacy and broad compatibility (website pixel, app SDK, in-store, etc.) |
| `surface` | [EventSurface](#event-surfaces) | Optional structured surface, such as an owned channel, profile, feed, podcast, newsletter list, website, app, or store |
| `setup` | object | Implementation details — snippet code, snippet type, instructions |
### Buyer-managed vs seller-managed
**Buyer-managed** sources are ones you configure via `sync_event_sources`. You control the event types, domains, and lifecycle.
**Seller-managed** sources are always-on and appear in the response with `managed_by: "seller"`. These are common in commerce media where the retailer provides built-in attribution (e.g., purchase tracking on their own platform). Products with `conversion_tracking.platform_managed: true` indicate the seller provides these sources.
To discover all sources on an account (including seller-managed), call `sync_event_sources` without an `event_sources` array:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-event-sources-request.json",
"idempotency_key": "c9f3d6a7-5678-48e4-5678-9012345abcde",
"account": { "account_id": "acct_12345" }
}
```
## Event
An event represents a user action — a purchase, lead submission, page view, app install, or any of the [standard event types](#event-types).
Send events with [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event):
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/event.json",
"event_id": "evt_purchase_12345",
"event_type": "purchase",
"event_time": "2026-01-15T14:30:00Z",
"action_source": "website",
"event_source_url": "https://www.example.com/checkout/confirm",
"user_match": {
"hashed_email": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"click_id": "abc123def456",
"click_id_type": "gclid"
},
"custom_data": {
"value": 149.99,
"currency": "USD",
"order_id": "order_98765",
"num_items": 3
}
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `event_id` | string | Yes | Unique identifier for deduplication (scoped to event_type + event_source_id). Max 256 chars. |
| `event_type` | [EventType](#event-types) | Yes | Standard event type |
| `event_time` | date-time | Yes | ISO 8601 timestamp when the event occurred |
| `user_match` | [UserMatch](#user-match) | No | User identifiers for attribution matching |
| `custom_data` | [CustomData](#custom-data) | No | Event-specific data (value, currency, items) |
| `action_source` | [ActionSource](#action-sources) | No | Where the event occurred |
| `surface` | [EventSurface](#event-surfaces) | No | Structured surface context for the event, such as an owned channel, profile, feed, podcast, newsletter list, website, app, or store |
| `event_source_url` | uri | No | URL where the event occurred (required when action_source is `website`) |
| `custom_event_name` | string | No | Name for custom events (when event_type is `custom`) |
Events are deduplicated by `event_id` + `event_type` + `event_source_id`. Sending the same event multiple times is safe.
## User match
User identifiers enable the seller to attribute conversions to ad impressions. Provide the strongest identifiers available — more identifiers means higher match rates.
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/user-match.json",
"hashed_email": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
"uids": [
{ "type": "uid2", "value": "AbC123XyZ..." }
],
"click_id": "abc123def456",
"click_id_type": "gclid"
}
```
At least one identifier is required. The hierarchy from strongest to weakest:
| Field | Type | Match quality | Description |
| - | - | - | - |
| `uids` | UID\[] | Deterministic | Universal ID values (`rampid`, `id5`, `uid2`, `euid`, `pairid`, `maid`) |
| `hashed_email` | string | Deterministic | SHA-256 hash of lowercase, trimmed email (64-char hex) |
| `hashed_phone` | string | Deterministic | SHA-256 hash of E.164 phone number (64-char hex) |
| `click_id` | string | Deterministic | Platform click identifier (fbclid, gclid, ttclid, etc.) |
| `click_id_type` | string | — | Type of click identifier |
| `client_ip` | string | Probabilistic | Client IP address (requires `client_user_agent`) |
| `client_user_agent` | string | Probabilistic | Client user agent (requires `client_ip`) |
**Hashing**: Normalize before hashing — emails to lowercase with whitespace trimmed, phone numbers to E.164 format (e.g., `+12065551234`). Hash with SHA-256, output as 64-character lowercase hex.
Send multiple identifier types when available. The seller uses the best available match.
## Custom data
Event-specific data for attribution and reporting. Sources used for canonical ROAS declare `value_currencies`; monetary records from those sources require `currency` from that list. Legacy sources without the contract remain valid for non-ROAS use.
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/event-custom-data.json",
"value": 149.99,
"currency": "USD",
"order_id": "order_98765",
"content_ids": ["SKU-1234", "SKU-5678"],
"num_items": 3,
"contents": [
{ "id": "SKU-1234", "quantity": 2, "price": 49.99, "brand": "Acme" },
{ "id": "SKU-5678", "quantity": 1, "price": 50.01, "brand": "Nova" }
]
}
```
| Field | Type | Description |
| - | - | - |
| `value` | number | Monetary value of the event |
| `currency` | string | ISO 4217 currency code (e.g., `USD`, `EUR`, `GBP`) |
| `order_id` | string | Unique order or transaction identifier |
| `content_ids` | string\[] | Product or content identifiers |
| `content_type` | string | Category of content (product, service, etc.) |
| `content_name` | string | Name of the product or content |
| `content_category` | string | Category of the product or content |
| `num_items` | integer | Number of items in the event |
| `search_string` | string | Search query (for search events) |
| `progress_percent` | number | Content progress percentage reached, primarily for `watch_milestone` events |
| `progress_seconds` | number | Content progress duration reached in seconds, primarily for time-based `watch_milestone` events |
| `contents` | Content\[] | Per-item details: `id` (required), `quantity`, `price`, `brand` |
## Event types
Standard marketing event types, aligned with IAB ECAPI:
| Event type | Description |
| - | - |
| `page_view` | User viewed a page |
| `view_content` | User viewed specific content (product, article, etc.) |
| `select_content` | User selected or clicked on content |
| `select_item` | User selected a specific product or item from a list |
| `search` | User performed a search |
| `share` | User shared content via social or messaging |
| `add_to_cart` | User added an item to cart |
| `remove_from_cart` | User removed an item from cart |
| `viewed_cart` | User viewed their shopping cart |
| `add_to_wishlist` | User added an item to a wishlist |
| `initiate_checkout` | User started checkout process |
| `add_payment_info` | User added payment information |
| `purchase` | User completed a purchase |
| `refund` | A purchase was fully or partially refunded (adjusts ROAS) |
| `lead` | User expressed interest (form submission, signup, etc.) |
| `qualify_lead` | Lead qualified by sales or scoring criteria |
| `close_convert_lead` | Lead converted to a customer or closed deal |
| `disqualify_lead` | Lead disqualified or marked as not viable |
| `complete_registration` | User completed account registration |
| `subscribe` | User started a paid subscription or paid membership |
| `follow` | User made a free, durable opt-in to an account, channel, feed, list, podcast, or similar owned property |
| `content_view` | User meaningfully consumed a content unit, such as a watch, listen, stream, episode play, or read |
| `watch_milestone` | User reached a content progress threshold, such as 25%, 50%, 75%, 100%, or a seconds-viewed milestone |
| `start_trial` | User started a free trial |
| `app_install` | User installed an application |
| `app_launch` | User launched an application |
| `contact` | User initiated contact (call, message, etc.) |
| `schedule` | User scheduled an appointment or event |
| `donate` | User made a donation |
| `submit_application` | User submitted an application (loan, job, etc.) |
| `custom` | Custom event type (specify in `custom_event_name`) |
Use `view_content` for a product, article, or page content view where the view is mostly context for a lower-funnel goal. Use `content_view` when meaningful consumption of the content unit is itself the event being optimized or attributed. For `watch_milestone`, put the threshold in `custom_data.progress_percent` or `custom_data.progress_seconds`; reserve `custom_data.value` for monetary event value.
## Action sources
Where the conversion event originated:
| Action source | Description |
| - | - |
| `website` | Event occurred on a website |
| `app` | Event occurred in a mobile or desktop app |
| `offline` | Event occurred offline (imported data) |
| `phone_call` | Event originated from a phone call |
| `chat` | Event originated from a chat conversation |
| `email` | Event originated from an email interaction |
| `in_store` | Event occurred at a physical retail location |
| `system_generated` | Event generated by an automated system |
| `other` | Other source (specify in `ext`) |
## Event surfaces
`action_source` stays intentionally flat for compatibility. Use `surface` when the optimization-relevant source needs more structure, especially for creator and content engagement on owned platform properties.
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/event-surface.json",
"category": "owned_property",
"property_type": "channel",
"namespace": "video_platform",
"property_id": "channel_123"
}
```
| Field | Type | Description |
| - | - | - |
| `category` | enum | Closed generic category: `owned_property`, `website`, `app`, `offline`, `phone_call`, `chat`, `email`, `in_store`, `system_generated`, or `other` |
| `property_type` | string | Open vocabulary for the property kind, such as `channel`, `profile`, `feed`, `list`, `podcast`, `playlist`, or `newsletter` |
| `namespace` | string | Free-form platform, publisher, or system namespace, such as `video_platform`, `short_video_app`, or `audio_service`; this is not an enum |
| `property_id` | string | Optional identifier for the property within `namespace` |
For `owned_property`, set both `property_type` and `namespace`, and include `property_id` whenever the platform exposes a stable property identifier.
When `surface.category` matches an `action_source` value, producers should set `action_source` to the same value. For `owned_property`, keep the closest compatible flat value for older consumers, commonly `system_generated` for platform-native events or `other` when no closer value applies. Platform-native details such as a raw conversion origin can still ride in `ext`, but shared optimization meaning belongs in `event_type`, `action_source`, and `surface`.
## Event source health
Sellers that evaluate event source quality include a `health` object on each source in the [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) response. This is the AdCP equivalent of platform-specific quality scores like Snap's Event Quality Score (EQS) or Meta's Event Match Quality (EMQ).
The `status` field is the AdCP-standardized score — comparable across all sellers:
| Status | Meaning |
| - | - |
| `insufficient` | Setup incomplete or event quality too low — optimization cannot run |
| `minimum` | Functional but data quality limits optimization effectiveness |
| `good` | Meets quality thresholds for most optimization goals |
| `excellent` | Exceeds quality thresholds across all dimensions |
Buyer agents should key decisions off `status`, not `detail`. The optional `detail` object contains seller-specific scoring (e.g., Snap's 0-10 EQS, Meta's 0-10 EMQ) for human dashboards or advanced diagnostics, but scales vary by seller and cannot be compared across platforms.
| Field | Type | Description |
| - | - | - |
| `status` | string | AdCP-standardized health level. Use for cross-seller decisions. |
| `detail` | object | Seller-specific `score`, `max_score`, and optional `label`. Only present when the seller has a native quality score. |
| `match_rate` | number | Fraction of events matched to ad interactions (0.0-1.0). Low rates indicate weak user_match identifiers. Only available from sellers that compute match rates (Snap, Meta). |
| `last_event_at` | date-time | Timestamp of the most recent event received. |
| `evaluated_at` | date-time | When this health assessment was computed. Use to detect stale assessments. |
| `events_received_24h` | integer | Events received in the last 24 hours. |
| `issues` | array | Actionable problems with `severity` and `message`. Sellers should limit to the top 3-5 most actionable items. Buyer agents should sort by severity rather than relying on array position. |
Health is reported per event source, not per account. A buyer with a healthy website pixel and a broken app SDK will see different health on each.
**When `health` is absent**, the seller does not evaluate event source quality. Buyer agents should proceed without health gating — the seller handles quality internally. Do not treat absent health as `insufficient`.
### How sellers compute health
Sellers with native API-accessible quality scores (Snap EQS, Meta EMQ) relay them directly in `status` and `detail`. Most sellers do not have native scores — they derive `status` from operational metrics:
* **`insufficient`**: tag inactive, or `events_received_24h` is 0
* **`minimum`**: tag active, low volume or high error rate
* **`good`**: firing steadily, reasonable volume, core event types covered
* **`excellent`**: high volume, low errors, enhanced matching enabled
When sellers compute health from reporting data, the `evaluated_at` timestamp tells the buyer how fresh the assessment is. Assessments older than 24 hours may not reflect recent changes to tag configuration or event volume. The `detail` object is absent for these sellers — there is no native score to relay.
**Schema**: [`/schemas/3.2.8/core/event-source-health.json`](https://adcontextprotocol.org/schemas/3.2.8/core/event-source-health.json)
## Measurement readiness
Products that support event-based optimization can include a `measurement_readiness` object in [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) responses. This tells the buyer whether their event setup is sufficient for the product to optimize effectively.
| Field | Type | Description |
| - | - | - |
| `status` | string | AdCP-standardized level: `insufficient`, `minimum`, `good`, `excellent` |
| `required_event_types` | EventType\[] | Event types this product needs |
| `missing_event_types` | EventType\[] | Required types the buyer hasn't configured |
| `issues` | array | Actionable problems with `severity` and `message` |
| `notes` | string | Seller explanation or recommendations |
Measurement readiness is evaluated per product in the context of the buyer's account. The same product shows different readiness for different buyers depending on their event source configuration.
**When `measurement_readiness` is absent**, the product either does not use event-based optimization (CTV awareness, guaranteed display) or the seller does not provide readiness assessments. In both cases, the buyer agent should treat the product as viable. Do not treat absent readiness as `insufficient`.
Unlike event source health, measurement readiness has no `evaluated_at` timestamp — it is evaluated fresh on each `get_products` call using the buyer's current event source configuration.
### Cross-seller buyer agent pattern
A buyer agent talking to multiple sellers writes one set of rules that works everywhere. Any status other than `insufficient` means the product can optimize — the question is how well. The standardized `status` field means no per-seller integration code:
```javascript test=false theme={null}
// Works across all sellers — no seller-specific logic
for (const seller of sellers) {
const sources = await seller.syncEventSources({ account: seller.account });
// Surface issues from any seller — sort by severity, don't rely on array position
for (const source of sources.event_sources) {
if (source.health?.status === "insufficient") {
surfaceIssues(source.health.issues ?? []);
}
}
const products = await seller.getProducts({
idempotency_key: "550e8400-e29b-41d4-a716-446655442041",
account: seller.account,
buying_mode: "brief",
brief: campaign.brief,
});
for (const product of products.products) {
const mr = product.measurement_readiness;
// Absent = no event-based optimization needed (CTV, awareness), treat as viable
if (!mr) {
viable.push(product);
continue;
}
// For DR products, require good or better
if (campaign.goal === "conversions" && mr.status === "minimum") {
warnings.push({ product, reason: "Event setup is functional but limits optimization" });
viable.push(product); // Still viable, but flag it
} else if (mr.status !== "insufficient") {
viable.push(product);
} else {
skipped.push({ product, issues: mr.issues });
}
}
}
```
**Schema**: [`/schemas/3.2.8/core/measurement-readiness.json`](https://adcontextprotocol.org/schemas/3.2.8/core/measurement-readiness.json)
### Trust boundaries
The `issues[].message`, `measurement_readiness.notes`, and `detail.label` fields are seller-provided free text. Buyer agents should treat these as untrusted content — do not pass them directly into LLM system prompts or use them as decision-making inputs without a trust boundary. They are safe to display to humans or include in informational context, but should not influence agent control flow.
## Optimization goals
Optimization goals tell the seller what to optimize delivery toward. Set them on a package in [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy#campaign-with-conversion-optimization). A package accepts an array of goals — each with an optional `priority` (1 = highest). Products declare `max_optimization_goals` when they limit how many goals a package can carry (most social platforms accept only 1).
**Schema**: [`/schemas/3.2.8/core/optimization-goal.json`](https://adcontextprotocol.org/schemas/3.2.8/core/optimization-goal.json)
There are two kinds of goals, discriminated by `kind`:
* **`kind: "metric"`** — Optimize for a seller-tracked delivery metric (clicks, views, engagements, etc.). No event source or conversion tracking setup required. The product declares which metrics it supports in `metric_optimization`.
* **`kind: "event"`** — Optimize for advertiser-tracked conversion events. Requires event sources registered via `sync_event_sources`. The product declares support in `conversion_tracking`.
### kind: event
Optimize for advertiser-tracked conversion events. The `event_sources` array defines which source-type pairs feed this goal. When the seller supports `multi_source_event_dedup` (declared in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities)), they deduplicate by `event_id` across all entries — the same business event reported by multiple sources counts once, using `value_field` and `value_factor` from the first matching entry. When `multi_source_event_dedup` is absent or false, buyers should use a single event source per goal.
**Cost per conversion** (single source):
```json theme={null}
{
"kind": "event",
"event_sources": [
{ "event_source_id": "website_pixel", "event_type": "lead" }
],
"target": { "kind": "cost_per", "value": 25.00 },
"priority": 1
}
```
**Return on ad spend** (multiple sources with refunds):
```json theme={null}
{
"kind": "event",
"event_sources": [
{ "event_source_id": "web_pixel", "event_type": "purchase", "value_field": "order_total" },
{ "event_source_id": "app_sdk", "event_type": "purchase", "value_field": "order_total" },
{ "event_source_id": "web_pixel", "event_type": "refund", "value_field": "refund_amount", "value_factor": -1 }
],
"target": { "kind": "per_ad_spend", "value": 4.0 },
"attribution_window": { "post_click": { "interval": 28, "unit": "days" }, "post_view": { "interval": 1, "unit": "days" } },
"priority": 1
}
```
For `per_ad_spend` targets, each event source entry specifies a `value_field` (which field on `custom_data` carries the monetary value) and an optional `value_factor` (multiplier, defaults to 1). The seller computes `sum(value_field * value_factor) / spend` across all deduplicated events.
**Maximize conversion value** (no specific ROAS target):
```json theme={null}
{
"kind": "event",
"event_sources": [
{ "event_source_id": "web_pixel", "event_type": "purchase", "value_field": "value" }
],
"target": { "kind": "maximize_value" },
"priority": 1
}
```
A `maximize_value` target steers spend toward higher-value conversions without committing to a specific return ratio. Requires `value_field` on at least one event source entry.
| Field | Type | Required | Description |
| - | - | - | - |
| `kind` | `"event"` | Yes | Discriminator |
| `event_sources` | array | Yes | Source-type pairs feeding this goal. Seller deduplicates by `event_id` across entries — when the same `event_id` arrives from multiple sources with different `value_field`s, the seller uses the `value_field` and `value_factor` from the first matching entry in this array. |
| `event_sources[].event_source_id` | string | Yes | Event source (must be configured via `sync_event_sources`) |
| `event_sources[].event_type` | [EventType](#event-types) | Yes | Event type to include (e.g., `purchase`, `lead`, `refund`) |
| `event_sources[].custom_event_name` | string | When event_type is `custom` | Platform-specific custom event name |
| `event_sources[].value_field` | string | When target is `per_ad_spend` or `maximize_value` | Which field on `custom_data` carries the monetary value. The seller must use this for value extraction and aggregation — it is not passed directly to underlying platform APIs. |
| `event_sources[].value_factor` | number | No | Multiplier the seller must apply to `value_field` before aggregation (default 1). Use -1 for refunds, 0.01 for cents, 0 to zero out a source's value contribution while still counting it for dedup. |
| `target.kind` | `"cost_per"` \| `"per_ad_spend"` \| `"maximize_value"` | No | Target type. When omitted, the seller maximizes conversion count within budget (see [default behavior](#default-behavior-for-event-goals)). |
| `target.value` | number | Yes (if target set) | Cost per event in buy currency, or return ratio (e.g., 4.0 = \$4 per \$1 spent) |
| `attribution_window` | object | No | Click-through and view-through windows. When omitted, the seller uses their default. |
| `priority` | integer | No | Lower values rank first. Ties use array order; unprioritized goals follow explicitly prioritized goals. |
For canonical `bidding.roas`, every value-bearing source must declare the media-buy currency in `value_currencies` before buy creation. Monetary `log_event` records require `custom_data.currency` from the source's declared list. A USD buy uses only USD records; EUR records from the same source remain available to EUR buys. Sellers never convert value currencies.
### kind: metric
Optimize for a seller-tracked delivery metric. No event source needed — the seller tracks these natively. Products declare which metrics they support in `metric_optimization.supported_metrics`.
**Maximize clicks** (no target — seller optimizes for volume within budget):
```json theme={null}
{
"kind": "metric",
"metric": "clicks"
}
```
**Cost per click**:
```json theme={null}
{
"kind": "metric",
"metric": "clicks",
"target": { "kind": "cost_per", "value": 2.00 },
"priority": 2
}
```
**Minimum click-through rate**:
```json theme={null}
{
"kind": "metric",
"metric": "clicks",
"target": { "kind": "threshold_rate", "value": 0.001 },
"priority": 2
}
```
**Minimum viewability** (at least 70% of measurable impressions viewable under the MRC standard, as measured by a named vendor):
```json theme={null}
{
"kind": "metric",
"metric": "viewable_rate",
"standard": "mrc",
"vendor": { "domain": "acmeverify.example" },
"target": { "kind": "threshold_rate", "value": 0.7 },
"priority": 2
}
```
**Minimum attention from a specific vendor** (the `attention_seconds` / `attention_score` enum values on `kind: "metric"` are deprecated — vendor-attested metrics use `kind: "vendor_metric"` instead, which binds the goal to a specific measurement vendor):
```json theme={null}
{
"kind": "vendor_metric",
"vendor": { "domain": "adelaidemetrics.com" },
"metric_id": "attention_score",
"target": { "kind": "threshold_rate", "value": 70 },
"priority": 3
}
```
**Maximize engagements** (social reactions, comments, shares, story opens, overlay taps):
```json theme={null}
{
"kind": "metric",
"metric": "engagements"
}
```
**Completed views with duration threshold** (6-second views on TikTok):
```json theme={null}
{
"kind": "metric",
"metric": "completed_views",
"view_duration_seconds": 6,
"target": { "kind": "cost_per", "value": 0.02 },
"priority": 1
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `kind` | `"metric"` | Yes | Discriminator |
| `metric` | string | Yes | Seller-native metric (see metrics table below) |
| `standard` | `"mrc"` \| `"groupm"` | Conditional | Viewability standard the goal is judged against. Required when metric is `viewable_rate`; optional for `viewed_seconds` (the seller's default standard applies when omitted); rejected for other metrics. Must be listed in `metric_optimization.supported_viewability_standards` when the product declares that list. |
| `vendor` | BrandRef | No | Measurement vendor whose viewability measurement judges a `viewable_rate` or `viewed_seconds` goal; rejected for other metrics. The canonical 3.2 goal shape carries the BrandKey projection (`domain`, `brand_id`, `countries`). When omitted, the seller's default viewability measurement for the package applies. Sellers MUST reject a vendor they cannot optimize against rather than substituting another vendor's measurement. |
| `view_duration_seconds` | number | No | Minimum video view duration (in seconds) that qualifies as a `completed_views` event. Only applicable when metric is `completed_views`. When omitted, the seller uses their platform default. Must be a value listed in the product's `metric_optimization.supported_view_durations` — sellers reject unsupported values. |
| `target.kind` | `"cost_per"` \| `"threshold_rate"` | No | Target type. When omitted, the seller maximizes metric volume within budget. |
| `target.value` | number | Yes (if target set) | Cost per metric unit in buy currency, or minimum per-impression value |
| `priority` | integer | No | 1 = highest priority. When omitted, sellers use array position. |
**Metrics**:
| Metric | Unit | `threshold_rate` example | Description |
| - | - | - | - |
| `clicks` | count/impression | 0.001 (0.1% CTR) | Link clicks, swipe-throughs, CTA taps that navigate away |
| `views` | count/impression | — | Content views counted at the billable view threshold, as defined by delivery-metrics `views` (the quantity CPV bills on). For a viewability rate target, use `viewable_rate`, which names the standard and vendor. |
| `completed_views` | count/impression | 0.85 (85% VCR) | Video or audio completions. Use `view_duration_seconds` to control the qualifying threshold (e.g., 2s, 6s, 15s). |
| `viewed_seconds` | seconds/impression | 3.0 (3s in view) | Time in view per impression. Reported via `viewability.viewed_seconds`; governed by the viewability `standard`. Optionally set `standard` and `vendor` on the goal; otherwise the seller's default viewability measurement applies. |
| `viewable_rate` | proportion (0–1) | 0.70 (70% MRC viewable) | Viewable impressions / measurable impressions under the goal's `standard`, optionally judged by the goal's `vendor`. Requires `standard`; accepts only `threshold_rate` targets, and `threshold_rate.value` MUST NOT exceed 1. Same leaf identity reported as `viewability.viewable_rate`. See [viewability goals and performance standards](#viewability-goals-and-performance-standards). |
| `attention_seconds` | seconds/impression | — | **Deprecated** — has no industry-graduated definition. Use `kind: "vendor_metric"` with `vendor` + `metric_id: "attention_seconds"` instead. |
| `attention_score` | score/impression | — | **Deprecated** — has no industry-graduated definition. Use `kind: "vendor_metric"` with `vendor` + `metric_id: "attention_score"` instead. |
| `engagements` | count/impression | — | Direct interaction beyond viewing — social reactions/comments/shares, story/unit opens, interactive overlay taps on CTV, companion banner interactions on audio |
| `follows` | count/impression | — | New followers, page likes, artist/podcast/channel follows, or free channel/feed subscribes |
| `saves` | count/impression | — | Saves, bookmarks, playlist adds, pins — signals of intent to return |
| `profile_visits` | count/impression | — | Visits to the brand's in-platform page — profile, artist page, channel, or storefront. Does not include external website clicks (use `clicks` for that). |
| `reach` | unique entities/window | — | Unique audience reach within a frequency window. Requires `reach_unit` (e.g., `households`, `individuals`). Use `target_frequency` to set the frequency band for optimization. |
#### Viewability goals and performance standards
A `viewable_rate` goal and a `viewability` entry in the package's `performance_standards` are complementary. The performance standard is a pass/fail commitment the seller is held to; the goal tells the optimizer what to steer toward. A package can carry both — for example a 60% MRC standard and a 70% MRC goal.
When both are present for the same `standard`, buyers SHOULD NOT set the goal's `threshold_rate.value` below the performance standard's `threshold`. A lower goal never relaxes the standard: sellers MUST continue to evaluate the performance standard at its own threshold, and SHOULD treat the effective optimization floor as the higher of the two values.
Sellers that accept a `viewable_rate` goal SHOULD report `viewability` (or the `viewable_rate` leaf) for the package under the goal's `standard` and `vendor`, so the buyer can check the goal against delivery.
### kind: vendor_metric
For vendor-attested measurement where the metric has no industry-graduated definition — attention (DoubleVerify, IAS, Adelaide, TVision, Lumen), panel-based brand lift (Kantar, Upwave, Cint), emissions (Scope3, Good-Loop — see polarity caveat below), retail-media partner metrics — the goal binds a specific vendor + `metric_id` end-to-end. The seller's bidding stack steers toward that vendor's measurement; delivery reports the value via `vendor_metric_values[]` with the same `(vendor, metric_id)` key.
**Direction polarity** (upward-pushing only this minor). `cost_per` and `threshold_rate` are upward-pushing targets — the seller steers delivery toward higher metric values, or toward meeting a minimum threshold. Metrics where the buyer wants to *minimize* (emissions, IVT, latency) currently rely on seller-side polarity interpretation per the vendor's metric definition. First-class minimize semantics (a `direction: "minimize"` field on the goal or a `target.kind: "ceiling_rate"`) are under WG discussion — see [#4644](https://github.com/adcontextprotocol/adcp/issues/4644).
```json theme={null}
{
"kind": "vendor_metric",
"vendor": { "domain": "adelaidemetrics.com" },
"metric_id": "attention_score",
"target": {
"kind": "threshold_rate",
"value": 70
},
"priority": 1
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `kind` | `"vendor_metric"` | Yes | Discriminator |
| `vendor` | BrandRef | Yes | Vendor that defines and computes this metric. Anchored on the vendor's `brand.json` `agents[type='measurement']`. Same shape used across `vendor_metric_values`, `reporting_capabilities.vendor_metrics`, `committed_metrics` (vendor-scope entries), and `performance_standards.vendor`. |
| `metric_id` | string | Yes | Identifier in the vendor's vocabulary (e.g., `attention_score`, `awareness_lift`, `gco2e_per_impression`). MUST be in the vendor's published `measurement.metrics[]` catalog. |
| `target.kind` | `"cost_per"` \| `"threshold_rate"` | No | Target type. When omitted, the seller maximizes metric value within budget. |
| `target.value` | number | Yes (if target set) | Cost per metric unit (currency) or minimum per-impression value. Units are vendor-defined. |
| `priority` | integer | No | 1 = highest priority. When omitted, sellers use array position. |
**Three preconditions for goal acceptance.** Sellers MUST reject `vendor_metric` goals that fail the capability or reporting-coherence preconditions; sellers SHOULD verify the discovery precondition:
1. **Discovery** (SHOULD this minor; MUST at next minor) — `metric_id` is in the vendor's published `measurement.metrics[]` catalog (queried from the vendor's `brand.json` measurement agent). Softened to SHOULD while measurement-vendor adoption of AdCP-conformant capability publication catches up; tightens to MUST once two-plus vendors ship conformant agents.
2. **Capability** — the `(vendor, metric_id)` pair is in the product's `vendor_metric_optimization.supported_metrics[]`, and the goal's `target.kind` is in the matching entry's `supported_targets`.
3. **Reporting coherence** — the package's `committed_metrics[]` includes a matching `{ scope: "vendor", vendor, metric_id }` entry. **Optimization without committed reporting is unverifiable** — the buyer can't grade performance against a goal whose value the seller isn't contractually obligated to populate. This precondition is what makes the goal meaningful; the seller MUST reject (with `TERMS_REJECTED`) any goal whose metric isn't also committed for reporting on the same package.
**Distinct from `metric` kind.** The `metric` kind is for seller-native measurement (clicks, views, completed_views, reach, engagements, etc.) where no vendor binding is needed — the seller measures the metric natively. The `vendor_metric` kind is for vendor-attested measurement where the same metric name means different things across vendors and must be reconciled to a specific source. The deprecated `attention_seconds` / `attention_score` values on the `metric` kind enum predate this split and route through `vendor_metric` going forward.
**Full lifecycle reference.** See [Metric lifecycle](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting#metric-lifecycle) for the complete capability → commitment → optimization → delivery picture across both standard and vendor metric flows.
### Target kinds
All target kinds across the three goal kinds:
| `target.kind` | Metric goals | Vendor metric goals | Event goals | Description |
| - | - | - | - | - |
| `cost_per` | Cost per click/view/etc. | Cost per vendor metric unit | Cost per conversion event | `spend / count` |
| `threshold_rate` | Minimum per-impression value | Minimum per-impression vendor metric value | — | `at least X per impression` |
| `per_ad_spend` | — | — | Target return on ad spend | `sum(value_field * value_factor) / spend` |
| `maximize_value` | — | — | Maximize total conversion value | Steers spend toward higher-value conversions. Requires `value_field`. |
### Choosing a strategy
| Goal | When to use | What you set |
| - | - | - |
| Max conversions | As many conversions as possible within budget | `kind: "event"` + event sources, no target. `value_field` may be present for reporting but does not change the objective. |
| Target cost per conversion | Specific cost per event | `kind: "event"` + `target: { kind: "cost_per", value: 25.0 }` |
| Target return on ad spend | Specific return ratio on event values | `kind: "event"` + `value_field` on sources + `target: { kind: "per_ad_spend", value: 4.0 }` |
| Maximize conversion value | Steer toward higher-value conversions without a ROAS target | `kind: "event"` + `value_field` on sources + `target: { kind: "maximize_value" }` |
| Max clicks | Maximize clicks within budget | `kind: "metric"`, `metric: "clicks"`, no target |
| Target cost per click | Specific cost per click | `kind: "metric"`, `metric: "clicks"` + `target: { kind: "cost_per", value: 2.0 }` |
| Target CTR | Minimum click-through rate | `kind: "metric"`, `metric: "clicks"` + `target: { kind: "threshold_rate", value: 0.001 }` |
| Target viewability | Minimum viewability rate under a named standard | `kind: "metric"`, `metric: "viewable_rate"`, `standard: "mrc"` + `target: { kind: "threshold_rate", value: 0.70 }` (optionally `vendor`) |
| Target attention (vendor-bound) | Minimum attention from a specific vendor | `kind: "vendor_metric"`, `vendor: { domain: "adelaidemetrics.com" }`, `metric_id: "attention_score"` + `target: { kind: "threshold_rate", value: 70 }` |
| Target brand lift (vendor-bound) | Maximize awareness lift from a specific panel provider | `kind: "vendor_metric"`, `vendor: { domain: "kantar.com" }`, `metric_id: "awareness_lift"`, no target (maximize) |
| Target VCR | Minimum video completion rate | `kind: "metric"`, `metric: "completed_views"` + `target: { kind: "threshold_rate", value: 0.85 }` |
| Completed views with duration | Video views with specific duration threshold | `kind: "metric"`, `metric: "completed_views"` + `view_duration_seconds: 6` |
| Max engagements | Maximize social interactions within budget | `kind: "metric"`, `metric: "engagements"`, no target |
| Max follows | Maximize new followers, page likes, or free channel/feed subscribes | `kind: "metric"`, `metric: "follows"`, no target |
| Max saves | Maximize saves/bookmarks/playlist adds | `kind: "metric"`, `metric: "saves"`, no target |
| Max profile visits | Drive traffic to brand page/profile | `kind: "metric"`, `metric: "profile_visits"`, no target |
| Max unique reach | Maximize unique audience within budget | `kind: "metric"`, `metric: "reach"` + `reach_unit: "households"`, no target |
| Reach with frequency | Reach at 1-3x/week frequency band | `kind: "metric"`, `metric: "reach"` + `reach_unit` + `target_frequency: { min: 1, max: 3, window: "7d" }` |
### Multiple goals and priority
A package can have multiple goals. Priority controls which the seller treats as primary. A common pattern is to use metric goals as proxy signals when event data is sparse:
```json theme={null}
"optimization_goals": [
{
"kind": "metric",
"metric": "clicks",
"target": { "kind": "cost_per", "value": 2.00 },
"priority": 2
},
{
"kind": "event",
"event_sources": [
{ "event_source_id": "mobile_sdk", "event_type": "app_install" },
{ "event_source_id": "mmp_adjust", "event_type": "app_install" }
],
"target": { "kind": "cost_per", "value": 10.00 },
"priority": 1
}
]
```
The seller focuses on the `priority: 1` goal (installs at \$10 cost per, deduplicated across SDK and MMP) and uses clicks as a proxy signal until install data accumulates.
### Default behavior for event goals
When `target` is omitted from an event goal, the seller maximizes conversion count within budget. This is true regardless of whether `value_field` is present on event sources — `value_field` without an explicit value-oriented target enables reporting (conversion_value, ROAS in delivery reports) but does not change the optimization objective.
| `target` | `value_field` | Seller behavior |
| - | - | - |
| omitted | omitted | Maximize event count within budget |
| omitted | present | Maximize event count within budget. Value available for reporting only. |
| `cost_per` | either | Target cost per conversion. Value used for reporting if present. |
| `per_ad_spend` | present | Target return on ad spend. |
| `per_ad_spend` | **missing** | **Validation error** — seller must reject. No value dimension to compute return. |
| `maximize_value` | present | Steer toward higher-value conversions. |
| `maximize_value` | **missing** | **Validation error** — seller must reject. No value dimension to maximize. |
### Blending vs. sequencing goals
`value_factor` and `priority` both express "event type A matters more than event type B" but mean different things to the seller's optimization:
* **`value_factor`** blends multiple event sources into a **single objective function**. Set per event source entry *within* a single goal's `event_sources` array. The seller sees one goal with a composite value signal. Use this when purchases and page views should be optimized together with explicit relative weights.
* **`priority`** sequences **independent goals**. Set on separate goal objects in the `optimization_goals` array. The seller optimizes for goal 1 first; goal 2 is a secondary objective, not blended in. Use this when goals are conceptually separate (e.g., hit a CPA target first, then maximize reach with remaining budget).
Use `value_factor` to blend. Use `priority` to sequence. Mixing them up produces subtly wrong optimization — a blended goal that should be sequenced, or sequenced goals that should be blended — and the effect is hard to detect in delivery reports.
### Event type polarity
Most event types are positive signals — a purchase, lead, or install is something the buyer wants more of. Some event types are observation signals that should not be standalone optimization targets:
| Polarity | Event types | Notes |
| - | - | - |
| Positive | `purchase`, `lead`, `qualify_lead`, `close_convert_lead`, `app_install`, `complete_registration`, `subscribe`, `follow`, `content_view`, `watch_milestone`, `start_trial`, `contact`, `schedule`, `donate`, `submit_application` | Safe as standalone optimization targets when the event has enough volume and is the buyer's desired outcome |
| Upper funnel | `page_view`, `view_content`, `select_content`, `select_item`, `search`, `add_to_cart`, `viewed_cart`, `add_to_wishlist`, `initiate_checkout`, `add_payment_info`, `share`, `app_launch` | Valid optimization targets but typically used as proxy signals (`priority: 2`) when lower-funnel data is sparse |
| Observation | `refund`, `remove_from_cart`, `disqualify_lead` | Include in `event_sources` for attribution accuracy and ROAS adjustment, not as standalone optimization targets |
`custom` events are not classified here — their polarity depends on the buyer's definition. Buyer agents should apply the same reasoning when choosing whether a custom event is safe as a standalone target.
Observation events are useful inside a composite goal — `refund` with `value_factor: -1` adjusts ROAS downward, which is exactly what you want. The risk is a misconfigured buyer agent that creates a standalone goal optimizing toward `refund` or `remove_from_cart` count. This is a buyer-agent implementation concern, not a protocol constraint — the protocol intentionally does not restrict which event types can be optimization targets.
### Volume normalization with `value_factor`
When combining event sources at different volume scales (e.g., `page_view` in the tens of thousands vs. `purchase` in the hundreds), the aggregate value in `sum(value_field * value_factor) / spend` will be dominated by the highest-volume type without explicit weighting. Buyers should use `value_factor` to express relative weights across sources:
```json theme={null}
{
"kind": "event",
"event_sources": [
{ "event_source_id": "web_pixel", "event_type": "page_view", "value_field": "value", "value_factor": 0.01 },
{ "event_source_id": "web_pixel", "event_type": "purchase", "value_field": "value", "value_factor": 1 }
],
"target": { "kind": "per_ad_spend", "value": 4.0 }
}
```
Here `page_view` contributes 1% of its face value, preventing it from dominating the ROAS calculation despite being \~100x more frequent than `purchase`.
Automatic normalization is intentionally out of scope — it requires event history the seller may not have, and would make the ROAS formula opaque. Buyer agents that want to normalize across event types should do so on their end before setting `value_factor`.
### Pricing model vs. optimization goal
The pricing model (CPC, CPM, CPA, etc.) determines what the buyer pays. The optimization goal determines how the seller allocates impressions. These are independent — a package can use CPM pricing while optimizing toward a CPA target, or use CPA pricing while optimizing for ROAS. See [Pricing Models](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models) for details on billing.
### Reach and frequency
Reach-based optimization uses `metric: "reach"` with two additional fields:
* **`reach_unit`** (required): The unit of measurement — must be a value declared in the product's `metric_optimization.supported_reach_units` (e.g., `households`, `individuals`).
* **`target_frequency`** (optional): Frequency band that guides optimization. The seller treats impressions toward unreached entities as higher-value and impressions toward already-saturated entities as lower-value. Includes `min`, `max`, and `window` (e.g., `"7d"`, `"campaign"`). When omitted, the seller maximizes unique reach.
```json theme={null}
{
"kind": "metric",
"metric": "reach",
"reach_unit": "households",
"target_frequency": { "min": 1, "max": 3, "window": "7d" },
"priority": 1
}
```
For GRP-based buys, use [CPP pricing](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#cpp-cost-per-point). For hard frequency limits independent of optimization, use `frequency_cap` on the package. Reach and frequency metrics are available in delivery reporting via [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery).
### Prerequisites
**For metric goals** (`kind: "metric"`):
1. **Check product support** — The product must declare `metric_optimization` with the desired metric in `supported_metrics`. No event source or conversion tracking setup is required.
2. **Check target support** — If setting a target, verify the target kind is listed in `metric_optimization.supported_targets`.
3. **Check view durations** — If using `completed_views` with `view_duration_seconds`, verify the value is listed in `metric_optimization.supported_view_durations`.
4. **Check viewability standards** — If using `viewable_rate`, verify the goal's `standard` is listed in `metric_optimization.supported_viewability_standards` when the product declares it.
**For event goals** (`kind: "event"`):
1. **Configure event sources** — Call [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) to set up the event sources referenced in `event_sources`.
2. **Check product support** — The product must declare `conversion_tracking` with the desired target kind in `supported_targets`.
3. **Check dedup support** — If using multiple event sources per goal, verify the seller supports `multi_source_event_dedup` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). When unsupported, use a single event source per goal.
4. **Send events** — Use [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event) to send conversion data. The seller needs event history to optimize effectively.
### Attribution windows
Attribution windows control how far back the seller looks to credit an ad impression for a conversion. Common options:
| Window | Meaning |
| - | - |
| `post_click: {interval: 7, unit: "days"}` | Conversions within 7 days of a click |
| `post_click: {interval: 28, unit: "days"}` | Conversions within 28 days of a click |
| `post_view: {interval: 1, unit: "days"}` | Conversions within 1 day of viewing an ad |
| `post_view: {interval: 7, unit: "days"}` | Conversions within 7 days of viewing an ad |
Values must match an option in the seller's `conversion_tracking.attribution_windows` capability. When omitted, the seller applies their default window.
## Connection to delivery reporting
Once event sources are configured and events are flowing, conversion metrics appear in [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) responses:
* **`conversions`** — Post-click or post-view conversions attributed to the campaign
* **`conversion_value`** — Monetary value of attributed conversions
* **`roas`** — Return on ad spend (conversion_value / spend)
* **`cost_per_acquisition`** — Cost per conversion (spend / conversions)
These metrics are reported per-package when the package has `optimization_goals` set. Sellers that support `by_action_source` breakdowns can show conversions split by source (website, app, in_store, etc.).
## Catalog-item attribution
For catalog-driven packages, conversion events carry `content_ids` that identify which catalog items were involved. The catalog's `content_id_type` declares what identifier type to expect (`sku`, `gtin`, `job_id`, etc.).
Attribution is broad by design: a user might click on one item (job A) but convert on another (apply to job B). The event fires with the actual `content_id` of the conversion, not the clicked item. Per-item click-to-conversion path analysis is a platform optimization concern, not a protocol concern.
The `by_catalog_item` breakdown in [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) shows per-item metrics (impressions, spend, clicks, conversions).
## Related documentation
* [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) — Configure event sources
* [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event) — Send conversion events
* [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy#campaign-with-conversion-optimization) — Set optimization goals on packages
* [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) — Monitor conversion metrics
* [Pricing Models](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#cpa-cost-per-acquisition) — CPA billing (pay per conversion)
# Creative Lifecycle
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/creatives/index
AdCP creative lifecycle — discover supported formats, sync creative assets to sellers, manage libraries, and track approval status across campaigns.
Creative management is central to successful media buying campaigns. AdCP manages the complete creative lifecycle from initial format discovery through ongoing optimization, providing comprehensive tools for managing creative assets throughout their entire lifecycle.
## Overview
AdCP's creative management system handles:
* **Format specifications** for all supported creative types
* **Asset lifecycle management** from creation to optimization
* **Cross-platform synchronization** of creative libraries
* **Standard format support** for consistent delivery
## Key Creative Tasks
### Creative Synchronization
Use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) to upload and manage creative assets in the creative library hosted by your seller or creative platform. This ensures your creatives are available for assignment across platforms and campaigns.
For sellers that advertise `inline_creative_management: true` without `creative.has_creative_library: true`, creatives are supplied as package-scoped `packages[].creatives` on `create_media_buy` or `update_media_buy` instead of through a reusable library.
### Creative Library Management
Use [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) to view and manage your creative asset library, including status tracking and performance metadata.
## The Three Main Phases
AdCP manages creatives through three main phases:
### Phase 1: Format Discovery
Before producing assets, determine both the inventory contract and the creative operation that can satisfy it. AdCP 3.2 uses three explicit sources:
* Publisher acceptance: `adagents.json.formats[]`
* Seller deliverability: each `get_products` result's closed `format_options[]` set
* Creative-agent operations: `get_adcp_capabilities.creative.supported_formats[]`
`list_creative_formats` and recursive `creative_agents[]` discovery are deprecated. To find a producer for a publisher format, query the AgenticAdvertising.org registry by `{publisher_domain, format_option_id}` or by a compatible canonical `format_kind`, then confirm the selected agent directly with `get_adcp_capabilities`.
#### Inventory-first
"What products match my campaign, and what creative contracts do they accept?"
```javascript theme={null}
const products = await get_products({
idempotency_key: "550e8400-e29b-41d4-a716-446655442049",
buying_mode: "brief",
brand: { domain: "acmeoutdoor.example" },
brief: "Acme Outdoor product launch campaign"
});
const acceptedOptions = products.products.flatMap(product => product.format_options);
// Each option is already a complete canonical declaration: format_kind,
// params, slots, and optionally publisher_domain + format_option_id.
```
#### Creative-first
"Which creative agents can build this exact publisher contract?"
```javascript theme={null}
const { agents } = await fetch(
"/api/registry/agents?publisher_domain=shorts.streamhaus.example" +
"&format_option_id=vertical_video&creative_operation=build"
).then(response => response.json());
const creativeAgent = connectAdcpAgent(agents[0].url);
const capabilities = await creativeAgent.get_adcp_capabilities({ protocols: ["creative"] });
const capability = capabilities.creative.supported_formats.find(entry =>
entry.format.publisher_domain === "shorts.streamhaus.example" &&
entry.format.format_option_id === "vertical_video" &&
entry.operations.includes("build")
);
const result = await creativeAgent.build_creative({
target_capability_id: capability.capability_id,
message: "Produce a concise vertical launch video",
brand: { domain: "acmeoutdoor.example" }
});
```
### Phase 2: Creative Production
Once you understand format requirements, create the actual creative assets according to the specifications discovered in Phase 1.
### Phase 3: Creative Library Management
AdCP uses creative libraries hosted by creative-capable agents, where assets are uploaded once and assigned to multiple campaigns. This approach enables:
* Upload creatives to account-level library
* Assign creatives to specific campaigns/packages
* Reuse creatives across multiple media buys
* Track performance across all assignments
Asset management is handled through [brand identity](/dist/docs/3.2.8/brand-protocol/brand-json), which provides brand-level assets with tags for discovery.
## Platform Considerations
Different platforms have varying creative requirements:
### Google Ad Manager
* Supports standard IAB formats
* Requires policy compliance review
* Creative approval typically within 24 hours
### Kevel
* Supports custom template-based creatives
* Real-time creative decisioning
* Flexible format support
### Triton Digital
* Audio-specific platform
* Supports standard audio formats
* Station-level creative targeting
## Response Times
Creative operations have varying response times:
* **Format listings**: \~1 second (database lookup)
* **Creative sync**: Minutes to days (asset processing and approval)
* **Library queries**: \~1 second (database lookup)
## Best Practices
1. **Format Planning**: Review supported formats before creative production
2. **Early Upload**: Submit creatives well before campaign launch
3. **Adaptation Acceptance**: Consider publisher suggestions for better performance
4. **Asset Organization**: Use clear naming conventions for creative IDs
5. **Performance Monitoring**: Track creative effectiveness and iterate
6. **Quality Control**: Follow format specifications exactly
7. **File Optimization**: Optimize file sizes for fast loading
8. **Testing**: Test assets across different devices and platforms
## Related Documentation
* **[`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives)** - Bulk creative management with upsert semantics
* **[`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives)** - Advanced creative library querying and filtering
* **[Canonical formats](/dist/docs/3.2.8/creative/canonical-formats)** - Publisher, product, and creative-agent format authority
* **[Brand identity](/dist/docs/3.2.8/brand-protocol/brand-json)** - Brand identity and asset management
* **[Creative Formats](/dist/docs/3.2.8/creative/formats)** - Understanding format specifications and discovery
* **[Creative Channel Guides](/dist/docs/3.2.8/creative/channels/video)** - Format examples across video, display, audio, DOOH, and carousels
* **[Asset Types](/dist/docs/3.2.8/creative/asset-types)** - Understanding asset roles and specifications
# Media buy protocol
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/index
AdCP 3.2 media buy walkthrough — follow a seller-planned campaign from brief through proposal acceptance, creative supply, control, and delivery.

Sam Adeyemi is a senior media buyer at Pinnacle Agency. His client just
greenlit a USD 50,000 Q2 campaign for Acme Outdoor—premium video and display
across sports and outdoor lifestyle publishers. Three sellers to evaluate.
Creatives to match. A governance review before anything goes live.
Last time he ran a campaign this size, it took two weeks, four dashboards, and
a spreadsheet to compare plans that were never in the same format. This
walkthrough follows the same campaign through the AdCP 3.2 proposal lifecycle.
## First choose the buying path
Sam's agent reads `get_adcp_capabilities.media_buy.lifecycle_tools` before
planning. AdCP 3.2 exposes two distinct commercial paths:
| Path | Use it when | Lifecycle |
| - | - | - |
| Published offer | The buyer can select and price a seller's published products directly | `list_products` → `buy_products` |
| Seller-planned proposal | The seller should curate, price, or negotiate a plan from the brief | `request_proposals` → `refine_proposals` → finalize → `accept_proposal` |
Wholesale mirrors use the published-offer path: `list_products` bootstraps and
repairs the feed, while account-level product webhooks keep it current. They are
not proposal conversations. See [Product discovery and planning](/dist/docs/3.2.8/media-buy/product-discovery/)
for both paths.
StreamHaus advertises the proposal lifecycle, so Sam asks its sales agent—built
by Priya Nair's ad products team—to plan the campaign.
## Step 1: Request proposals

Sam keeps strategy and goals in the brief. Exact commercial filters and
delivery constraints use structured criteria:
```javascript theme={null}
const proposals = await Promise.all(
sellers.map((seller) =>
seller.requestProposals({
adcp_version: '3.2',
idempotency_key: 'acme-q2-proposals-001',
account: { account_id: 'account_123' },
brand: { domain: 'acme-outdoor.example' },
brief:
'Premium video and display on trusted sports and outdoor lifestyle properties for the Acme Outdoor Q2 launch. Prioritize reach within a USD 50,000 ceiling.',
criteria: {
offer_filters: {
channels: ['olv', 'display'],
pricing_currencies: ['USD'],
},
targeting_overlay: {
geo_countries: ['US', 'CA'],
demographics: {
age: { min: 25, max: 54, include_unknown: false },
},
},
},
})
)
);
```
One brief. Three sellers. The same structured constraints, proposal shape, and
task lifecycle everywhere.
> [accordion] Agency language → AdCP 3.2 terms
>
> | What Sam says | What the protocol calls it |
> | - | - |
> | Campaign brief | `brief` on `request_proposals` |
> | Exact product constraint | `criteria.offer_filters` |
> | Exact delivery targeting | `criteria.targeting_overlay` |
> | Targeting dimension chosen later | `criteria.required_overlay_support` |
> | Seller-authored media plan | Immutable proposal snapshot |
> | Inventory reservation | Committed proposal with `expires_at` |
> | IO / insertion order | `accept_proposal`, optionally with `io_acceptance` |
> | Operational campaign change | `control_media_buy` inside accepted terms |
> | Commercial amendment | Revise the accepted proposal, finalize, then accept |
> | Campaign report | `get_media_buy_delivery` |
## Step 2: Compare and refine

Draft proposals return priced purchases, flight dates, forecasts, targeting
resolution, and canonical creative format options. Sam can compare them without
normalizing seller-specific spreadsheets.
| Seller | Plan | CPM | Forecast | Format |
| - | - | - | - | - |
| StreamHaus | Premium sports video | \$28 | 890K impressions | SSAI 30s video |
| OutdoorNet | Adventure display | \$12 | 2.1M impressions | 300x250, 728x90 |
| PodTrail | Outdoor podcast | \$22 | 340K impressions | Audio 30s + companion |
Sam wants guaranteed delivery and a lower CPM ceiling. He creates a successor
draft with typed constraints:
```javascript theme={null}
const refined = await streamHaus.refineProposals({
adcp_version: '3.2',
idempotency_key: 'acme-q2-refine-001',
refinements: [
{
proposal_id: 'proposal_streamhaus_001',
action: 'revise',
constraints: {
total_budget: { max: 50000, currency: 'USD' },
cpm: { max: 25, currency: 'USD' },
},
ask: 'Keep guaranteed delivery and prioritize completed video views.',
},
],
});
```
Typed constraints are mechanically testable. Subjective commercial guidance
stays in `ask`. Each transition creates a new `proposal_id`; the source
snapshot never changes. Sam branches on each result's `outcome` and verifies
any `partial` result before continuing.
## Step 3: Check creative requirements

Every proposed product declares canonical `format_options[]`. Sam's platform
can therefore validate or produce assets before accepting commercial terms:
* StreamHaus needs SSAI-compatible 30-second video.
* OutdoorNet needs 300x250 and 728x90 images.
* PodTrail needs 30-second audio plus a companion image.
Sam's creative team already has the video and display assets. The platform
flags the missing audio cut early, while the proposal is still negotiable.
Creative bodies do not belong in `buy_products` or `accept_proposal`; they are
supplied through the seller's advertised creative workflow after commitment.
## Step 4: Finalize and accept

Once the terms are right, Sam finalizes the selected draft. Finalization
creates a committed successor and an inventory hold:
```javascript theme={null}
const finalized = await streamHaus.refineProposals({
adcp_version: '3.2',
idempotency_key: 'acme-q2-finalize-001',
refinements: [
{
proposal_id: 'proposal_streamhaus_002',
action: 'finalize',
},
],
});
```
Sam verifies the committed proposal's `terms_digest` and `expires_at`, then
accepts that exact snapshot:
```javascript theme={null}
const buy = await streamHaus.acceptProposal({
adcp_version: '3.2',
idempotency_key: 'acme-q2-accept-001',
account: { account_id: 'account_123' },
proposal_id: 'proposal_streamhaus_003',
proposal_terms_digest: 'sha256:Fy6Bo7wUa_FmXGJssc37kGyHNjzBiBZLB9rtVNz8I-E',
});
```
The ID and digest bind acceptance to the reviewed terms. If the task enters
`submitted`, `working`, or `input-required`, Sam follows the standard task
lifecycle until the completion artifact returns the `media_buy_id`.
## Step 5: Governance and creative supply

Pinnacle registers the campaign plan with `sync_plans` and checks the proposed
acceptance against Jordan Ochoa's governance policy. Budget, approved sellers,
targeting rules, and creative provenance are evaluated before money moves.
Seller-side governance can independently validate the committed action against
the same plan context.
After acceptance, Sam supplies the assets through `sync_creatives` and assigns
them to the returned packages. The buy remains `pending_creatives` until every
required format has coverage, then moves to `pending_start` or `active`.
> [accordion] A library-backed creative sync
>
> ```javascript theme={null}
> await streamHaus.syncCreatives({
> adcp_version: '3.2',
> idempotency_key: 'acme-q2-creatives-001',
> account: { account_id: 'account_123' },
> creatives: [
> {
> creative_id: 'video_30s_trail_pro',
> name: 'Trail Pro 3000 — 30s CTV spot',
> format_kind: 'video_hosted',
> assets: {
> video_main: {
> asset_type: 'video',
> url: 'https://cdn.pinnacle-agency.example/trail-pro-30s.mp4',
> width: 1920,
> height: 1080,
> duration_ms: 30000,
> container_format: 'mp4',
> codec: 'h264',
> },
> },
> },
> ],
> assignment_operations: [
> {
> operation: 'assign',
> creative_id: 'video_30s_trail_pro',
> package_id: buy.packages[0].package_id,
> },
> ],
> });
> ```
## Step 6: Match at serve time
When a user loads a StreamHaus surface, its Trusted Match router can evaluate
which packages should activate. Context Match asks whether the content fits
the package; Identity Match asks whether the user is eligible. The publisher
joins the two responses locally, so Sam's buyer agent does not receive identity
and page context together.
See [Trusted Match Protocol](/dist/docs/3.2.8/trusted-match) for the privacy architecture
and surface-specific flows.
## Step 7: Monitor and control delivery

Sam reads operational state and the current revision from `get_media_buys`, and
uses billing-grade `get_media_buy_delivery` for reporting. If he needs to pause
a package or adjust a budget inside the accepted commercial envelope, he uses
`control_media_buy` with the latest revision:
```javascript theme={null}
const controlled = await streamHaus.controlMediaBuy({
adcp_version: '3.2',
idempotency_key: 'acme-q2-control-001',
account: { account_id: 'account_123' },
media_buy_id: buy.media_buy_id,
revision: current.revision,
packages: [
{
package_id: current.packages[0].package_id,
paused: true,
},
],
});
```
If a requested change falls outside accepted terms, the seller returns
`REQUOTE_REQUIRED`. Sam starts an amendment from `accepted_proposal_id`, then
repeats revise → finalize → accept. Operational state and commercial agreement
remain separate and auditable.
## The full picture
```mermaid theme={null}
flowchart LR
C[Capabilities] --> P{Buying path}
P -->|Published offers| L[list_products]
L --> B[buy_products]
P -->|Seller-planned| R[request_proposals]
R --> F[refine_proposals]
F --> H[Finalize hold]
H --> A[accept_proposal]
B --> M[MediaBuy]
A --> M
M --> S[sync_creatives]
S --> G[get_media_buys and delivery]
G --> O[control_media_buy]
O -->|Outside terms| F
```
Sam still gets one protocol and one operational view across sellers, but 3.2
makes the commercial intent explicit: published offers are purchased directly;
seller-planned terms move through immutable proposals; live delivery is changed
with revision-checked controls.
## Continue
* [Product discovery and planning](/dist/docs/3.2.8/media-buy/product-discovery/) — choose
published offers, wholesale mirroring, or proposals
* [Proposal negotiation](/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation)
— implement immutable revisions and holds
* [Media buy lifecycle](/dist/docs/3.2.8/media-buy/media-buys/lifecycle) — state,
creatives, controls, and delivery
* [3.1 → 3.2 migration](/dist/docs/3.2.8/reference/migration/3-1-to-3-2) — isolate the
compatibility facade behind capability-driven adaptation
# MediaBuy lifecycle
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/media-buys/index
Create, operate, reconcile, amend, and complete AdCP 3.2 MediaBuys through explicit commercial and operational lifecycles.
A MediaBuy is the operational resource created from accepted commercial terms.
AdCP 3.2 keeps three concerns separate:
1. **Commercial formation** chooses or negotiates the terms.
2. **Creative supply** attaches approved assets to the resulting packages.
3. **Operational control** changes delivery inside the accepted envelope.
That separation gives buyers and sellers an immutable commercial record while
allowing normal campaign operations to remain fast and revision-safe.
## Form the commercial commitment
Read `get_adcp_capabilities.media_buy.lifecycle_tools`, then choose an
advertised path:
| Path | Formation | Commitment |
| - | - | - |
| Published offer | `list_products` returns versioned seller offers | `buy_products` accepts selected offer terms and feed versions |
| Seller-planned | `request_proposals` and `refine_proposals` create immutable drafts | Finalize a draft into a committed hold, then call `accept_proposal` |
Both paths produce a MediaBuy with seller-issued `media_buy_id`, packages,
commercial readback, lifecycle status, and revision.
```mermaid theme={null}
flowchart LR
L[list_products] --> B[buy_products]
R[request_proposals] --> V[refine_proposals]
V --> F[finalize]
F --> A[accept_proposal]
B --> M[MediaBuy]
A --> M
```
Use [Product discovery and planning](/dist/docs/3.2.8/media-buy/product-discovery/) to
choose a path, and [Proposal negotiation](/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation)
for immutable revision and hold semantics.
## MediaBuy and package model
A MediaBuy contains:
* the accepted commercial snapshot and digest when formed from a proposal;
* aggregate budget, pacing, bidding, and daily-cap policy;
* one or more packages representing purchased products and their executable
targeting, flight, pricing, and creative requirements;
* operational status, health, indicators, and revision history;
* correlation context and reporting configuration; and
* `revision`, `valid_actions`, and `available_actions` for safe routing.
Packages preserve the seller-confirmed execution contract. Important fields
include:
| Field | Meaning |
| - | - |
| `product_id` | Published or proposal-bound product that produced the package |
| `targeting_overlay` | Complete effective targeting, including seller resolution |
| `start_time` / `end_time` | Executable package flight |
| `budget` / `daily_budget_cap` | Package-level spend constraints when applicable |
| `formats_to_provide` | Immutable package-time format snapshots; contract-bearing entries remain after coverage and pin product, placement, execution version, and digests |
| `formats_pending` | Canonically equal subset of `formats_to_provide` that still lacks coverage |
| `creative_approvals[]` | Current assignment review state |
| `indicators[]` | Current seller observations such as pacing or inventory risk |
The buyer does not reconstruct package state from its original request. Read
the current seller snapshot through [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys).
## State machine
| State | Meaning | Terminal? |
| - | - | - |
| `pending_creatives` | Commercially accepted; required creative coverage is missing | No |
| `pending_start` | Ready to serve; waiting for the flight to begin | No |
| `active` | Eligible to deliver | No |
| `paused` | Delivery is intentionally held | No |
| `completed` | Flight ended, goal completed, or budget exhausted | Yes |
| `rejected` | Seller declined before activation | Yes |
| `canceled` | Buyer or seller terminated the buy | Yes |
```mermaid theme={null}
stateDiagram-v2
[*] --> pending_creatives : commitment lacks creative coverage
[*] --> pending_start : commitment ready, flight future
[*] --> active : commitment ready, flight started
[*] --> paused : direct purchase created held
pending_creatives --> pending_start : creative assignments complete
pending_start --> active : flight starts
active --> paused : control_media_buy pause
paused --> active : control_media_buy resume
active --> completed : flight, goal, or budget completes
paused --> completed : flight, goal, or budget completes
pending_creatives --> canceled : accepted cancellation path
pending_start --> canceled : accepted cancellation path
active --> canceled : accepted cancellation path
paused --> canceled : accepted cancellation path
pending_creatives --> rejected : seller decline
pending_start --> rejected : seller decline
completed --> [*]
rejected --> [*]
canceled --> [*]
```
Task status is separate. `buy_products`, `accept_proposal`, and
`control_media_buy` may return `submitted`, `working`, or `input-required`
while an operation awaits systems or human review. The MediaBuy changes only
when that task completes. See [Task lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle).
## Supply and assign creatives
Compact purchase calls do not carry creative bodies. Use
[`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) to create or
update library assets, then use `assignment_operations` to assign, unassign, or
replace package creatives.
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441050",
"account": { "account_id": "account_123" },
"assignment_operations": [
{
"operation": "assign",
"creative_id": "creative_trail_video_30",
"package_id": "package_streamhaus_video"
}
]
}
```
Package-level `creative_deadline` takes precedence over the MediaBuy-level
deadline. After the deadline, the seller rejects new or replacement creative
assignments for that package. Creative library state and package assignment
state remain distinct: ending a buy releases assignments but does not delete a
reusable library creative.
## Control delivery inside accepted terms
Use [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) for
operational changes already permitted by the accepted commercial envelope:
* pause or resume delivery;
* exercise an accepted unilateral cancellation right;
* change total, aggregate-daily, or package budget controls;
* update allocation, pacing, bidding, targeting, catalog references, keywords,
impression controls, or optimization goals; and
* change reporting-webhook configuration.
Every control includes the latest `revision` from `get_media_buys`:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441051",
"account": { "account_id": "account_123" },
"media_buy_id": "media_buy_789",
"revision": 4,
"packages": [
{
"package_id": "package_streamhaus_video",
"paused": true
}
]
}
```
The seller atomically rejects a stale revision with `CONFLICT`. Re-read the
snapshot, reconcile the prior operation, and decide whether the original intent
still applies before retrying.
## Amend commercial terms
`control_media_buy` does not add products, change negotiated pricing or billing
terms, attach creatives, or move a flight outside the accepted envelope. When
an otherwise valid control requires new terms, the seller returns
`REQUOTE_REQUIRED`.
The buyer then:
1. reads `accepted_proposal_id` and the current terms from `get_media_buys`;
2. calls `refine_proposals` with `change_kind: "amendment"`;
3. verifies the immutable successor draft;
4. finalizes it into a committed hold; and
5. calls `accept_proposal` to apply the amendment atomically.
A cancellation requiring counterparty agreement uses the same lifecycle with
`change_kind: "cancellation"`. A cancellation right already granted in the
accepted terms can use `control_media_buy` directly.
## Read, reconcile, and report
Use the surfaces for their intended consistency level:
| Surface | Use |
| - | - |
| `get_media_buys` | Operational snapshot: state, revision, accepted proposal, packages, approvals, health, and optional near-real-time delivery |
| `get_media_buy_delivery` | Billing-grade delivery and dimensional reporting |
| Reporting webhooks | Push hints that delivery or health changed; repair from snapshots after gaps |
| Revision history | Append-only audit context for accepted operational changes |
Webhook arrival order is not resource order. Treat the snapshot as the repair
surface and compare resource revisions rather than transport timestamps. See
[Snapshot and log contract](/dist/docs/3.2.8/protocol/snapshot-and-log).
## Seller implementation invariants
Sellers implementing the lifecycle should preserve these properties:
* Store MediaBuy status explicitly; do not recompute paused, canceled, or
rejected state from flight dates.
* Enforce the revision comparison atomically with every control.
* Return the accepted proposal ID, digest, and complete snapshot for
proposal-formed buys so restarted clients can amend safely.
* Keep creative assignment mutations separate from commercial controls.
* Persist account-scoped buys regardless of whether they were created through
AdCP or another seller surface.
* Expose current routing through `available_actions` rather than requiring
buyers to infer it from status.
## Compatibility boundary
Sellers without `media_buy.lifecycle_tools` continue to use the 3.x
`get_products`, `create_media_buy`, and `update_media_buy` facade. Keep that
translation in a version-adaptation layer. New business logic should reason in
terms of published offers, immutable proposals, accepted terms, and
revision-checked controls.
See [Migrating from 3.1 to 3.2](/dist/docs/3.2.8/reference/migration/3-1-to-3-2) for the
mapping and [Media buy lifecycle flow](/dist/docs/3.2.8/media-buy/media-buys/lifecycle) for
the detailed state and dependency reference.
## Continue
* [Optimization and reporting](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting)
* [Indicators and warnings](/dist/docs/3.2.8/media-buy/media-buys/indicators)
* [Accountability](/dist/docs/3.2.8/media-buy/advanced-topics/accountability)
* [Policy compliance](/dist/docs/3.2.8/media-buy/media-buys/policy-compliance)
# Indicators and Warnings
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/media-buys/indicators
How AdCP exposes immediate operation warnings and durable seller indicators through existing media-buy and creative reads.
AdCP separates an immediate successful-operation warning from a condition that remains current after the operation:
| Situation | Protocol surface |
| - | - |
| Operation failed | `errors[]` |
| Operation needs buyer input before success | `input-required` |
| Operation succeeded with noteworthy context | `warnings[]` on the success response |
| Seller identifies a current material risk or optimization opportunity warranting buyer attention | `indicators[]` on the authoritative read |
| Creative is approved, partially approved, pending, or rejected for one assignment | Assignment approval state and optional `approval_scopes[]` |
| Resource is serving with a quality or coverage gap | Resource defect surface |
| Buy/package cannot deliver correctly | Impairment or operational delivery issue |
A warning is an immediate receipt. It MUST NOT become the only home for a continuing condition: a persistent forecast, pacing, creative, or budget conclusion also appears as current resource state. An indicator is not a separate resource—there is no indicator ID, history API, sub-version, or `get_indicators` task.
An indicator says that the buyer should evaluate and probably address a condition. It does not claim that one universal remedy exists, authorize a mutation, or make seller-supplied text executable. Buyer products may translate an indicator into one or more recommendations, but any resulting change still uses its normal AdCP task, authorization, and governance path.
## Where indicators live
`get_media_buys` carries three levels of current indicator state:
```text theme={null}
media_buys[] buy indicators
└── packages[] package indicators
└── creative_approvals[] assignment indicators
```
Creative-library sellers may expose the same package–creative relationship in reverse:
```text theme={null}
creatives[]
└── assignments.assigned_packages[] assignment approval + indicators
```
When `media_buy.relationship_notifications.projection_tasks` includes `list_creatives`, the two assignment projections MUST agree on `media_buy_id`, `package_id`, `creative_id`, approval state, rejection reason, and scoped approval outcomes. Indicator state SHOULD converge, but separate reads can legitimately straddle a reevaluation; buyers reconcile toward the snapshot with the strictly newer `indicators_as_of`. The seller includes `media_buy_id` and `approval_status` on every creative assignment row, even when indicators are unknown. Inline-only sellers use `get_media_buys` without implementing this reverse projection.
Do not put assignment-specific fatigue or approval on the creative root. One creative can be fatigued or rejected on one publisher while remaining effective and approved elsewhere. When a multi-publisher assignment has mixed eligibility, the scalar is `partially_approved` and complete `approval_scopes[]` carries a disjoint partition: one row per normalized scope, using either publisher-wide or placement-specific rows for a publisher, never both. Uniform assignments omit the array.
## Standard 3.2 catalog
| Type | Valid placement | Broad meaning |
| - | - | - |
| `creative_fatigue` | Package–creative assignment | Repeated delivery is materially saturating the audience or degrading objective-relevant performance |
| `creative_quality_opportunity` | Package–creative assignment | The accepted creative has a material format, asset, composition, or quality improvement opportunity |
| `creative_diversity_low` | Package | Too few meaningfully distinct eligible creatives for effective rotation, learning, reach, or fatigue resistance |
| `audience_saturation` | Package | The reachable audience is materially saturated independent of one creative |
| `inventory_shortfall_forecast` | Package | Current forecast is materially below the requested delivery goal |
| `pacing_risk` | Package | Material over- or under-delivery is projected by flight end absent intervention |
| `budget_constrained` | Media buy or package | Budget or a spend cap materially limits otherwise eligible delivery |
The negotiated AdCP release defines these broad meanings, not a universal algorithm. Provider scores, thresholds, evaluation windows, native labels, suggested actions, deep links, and upstream attribution remain in namespaced `ext`. A generic action dispatcher is intentionally absent; applying a recommendation still uses normal AdCP authorization, governance, idempotency, and readback.
## Evaluated snapshot shape
```json theme={null}
{
"creative_id": "cr_summer_video",
"approval_status": "approved",
"indicator_types_evaluated": [
"creative_fatigue",
"creative_quality_opportunity"
],
"indicators_as_of": "2026-08-04T12:00:00Z",
"indicators_evaluated_scope": [
{ "publisher_domain": "publisher-a.example" }
],
"indicators": [
{
"type": "creative_fatigue",
"detected_at": "2026-08-03T09:00:00Z",
"scope": [
{
"publisher_domain": "publisher-a.example",
"placement_id": "feed"
}
],
"ext": {
"seller_example": {
"fatigue_rate": 0.47,
"window_days": 7
}
}
}
]
}
```
`indicator_types_evaluated` is required with `indicators`. It prevents an empty fatigue result from being misread as an evaluation of pacing, budget, or another type. Every returned `indicator.type` MUST appear in this list; omitted types remain unknown.
`indicators_as_of` records when this evaluation completed. `indicators_evaluated_scope` optionally limits publisher or placement coverage. Omit scope coverage only when the named types were evaluated across the whole enclosing buy, package, or assignment. With partial coverage, every indicator includes a contained `scope`; unlisted scopes remain unknown.
Only `type` is required inside each indicator. `detected_at`, when known, remains stable throughout one uninterrupted occurrence. A relationship contains at most one item per `(type, normalized scope set)`.
## Unknown, clear, and monotonic state
* Omitted `indicators` means unknown or not evaluated.
* `indicators: []` means evaluated-clear only for `indicator_types_evaluated` and the declared coverage.
* A non-empty array is the current assertion set for those types and coverage.
* A prior key clears only when absent from a successful direct snapshot with coverage containing the key and a strictly newer `indicators_as_of`.
* Equal-timestamp conflicting snapshots are invalid; buyers retain stored state.
* Filtered disappearance, incomplete pagination, a failed read, or uncovered scope never clears state.
* A successful direct unfiltered read showing that an assignment was deleted retires all keys for that relationship.
For serve-time generative creative, assignment indicators describe the stable brief-or-creative × package aggregate. Variant/render diagnostics belong in `get_creative_delivery`.
## Querying
Use `list_creatives` for portfolio-wide assignment indicator discovery:
```json theme={null}
{
"include_assignments": true,
"filters": {
"indicator_types": ["creative_fatigue", "creative_quality_opportunity"]
},
"fields": ["creative_id", "assignments"],
"pagination": {
"max_results": 100
}
}
```
The outer cursor limits creatives. For bounded portfolio discovery, request `assignment_projection: "matching"` and `assignment_limit`; each result reports `returned_assignment_count` and `assignments_truncated`. A truncated reverse projection is discovery-only—repair complete state through `get_media_buys`. Reread known relationships without `indicator_types` when reconciling clearing.
`get_media_buys.indicator_types` matches an indicator at any of the three levels and returns the selected full buy. Use it for buy/package conclusions such as budget, inventory, audience, diversity, or pacing. Buyers MUST NOT send the filter unless every requested type appears in `supported_indicator_types`; a seller MAY reject a violation with `UNSUPPORTED_FEATURE`. This avoids an undetectable unfiltered superset on a response that has no `filters_applied` receipt.
## Webhooks
`supported_indicator_types` declares polling readback independently of webhook support. A seller may expose indicators through `get_media_buys` and omit `relationship_notifications` entirely. Sellers that support push additionally declare `media_buy.relationship_notifications`; `indicators.changed` requires an indicator catalog, while `creative.assignment_changed` may be declared alone when the seller can detect assignment or approval changes. A creative-library seller may advertise the bounded `list_creatives` reverse projection inside that block. The capability also declares whether activity logs are available:
```json theme={null}
{
"subscriber_id": "optimization-worker",
"url": "https://buyer.example/webhooks/adcp",
"event_types": [
"indicators.changed",
"creative.assignment_changed"
],
"active": true
}
```
`indicators.changed` fires after the seller observes a semantic assertion-set or evaluation-coverage change. It does not fire because only `indicators_as_of` advanced. `creative.assignment_changed` fires when an assignment is added, removed, or its assignment-specific approval state/reason changes. Removing an assignment with stored indicators also fires `indicators.changed` with `change_kind: "assignment_removed"`; the two fires have no ordering guarantee.
Subscriptions are prospective and do not replay already-current indicators. After activation or reactivation, establish a complete baseline through `get_media_buys`: either enumerate known `media_buy_ids`, or request all seven `status_filter` values and follow pagination to exhaustion. Do not use `indicator_types` for this baseline. A material in-place creative-content update retires the prior assignment evaluation: the seller fires `indicators.changed` with `change_kind: "invalidated"` and omits the stale snapshot as unknown until reevaluated, or atomically publishes a strictly newer evaluation and fires `updated`.
Both payloads are small signed invalidations containing account, media-buy, package, and—when applicable—creative identity. Buyers:
1. verify the registered webhook signature;
2. dedupe by `idempotency_key`;
3. reread `get_media_buys` without an indicator filter (the bounded `list_creatives` projection may assist discovery but cannot prove complete state); and
4. reconcile from the snapshot, never from the webhook payload.
Retries reuse the same `idempotency_key`. Poll-based upstream integrations fire when they detect a change; capability support does not promise native-platform detection latency. Relevant delivery attempts appear on the declared repair reads when `supports_webhook_activity` is true and activity was requested.
## Success warnings
Completed `buy_products` and `accept_proposal` commitments and completed `control_media_buy` controls may return structured `warnings[]`. The 3.x `create_media_buy` and `update_media_buy` compatibility facades mirror the warning returned by the canonical operation they map to. Proposal planning (`request_proposals` and `refine_proposals`) carries forecasts in proposal state rather than using commitment warnings. Initial codes are:
| Code | Typical durable readback |
| - | - |
| `inventory_shortfall_forecast` | Package indicator of the same name |
| `flight_change_creates_pacing_risk` | Package `pacing_risk` |
| `fields_ignored_due_to_precedence` | Operation-relative receipt; no continuing condition. `details` identifies ignored fields |
Canonical commitments use the first two codes: direct or newly accepted purchases may report `inventory_shortfall_forecast`, and an accepted flight amendment may report `flight_change_creates_pacing_risk`. `control_media_buy` does not change flight dates and therefore only uses `inventory_shortfall_forecast` from this initial catalog. `fields_ignored_due_to_precedence` remains a compatibility-facade receipt; canonical inputs reject conflicting intent instead of silently applying legacy precedence.
Every warning includes typed `affected_resource` identity so buyers can join it to durable state in multi-package and multi-creative responses. On compact commitment responses, package IDs come from `purchase_bindings[]`. Warnings never change success, never appear on terminal or submitted arms, and never grant action authority. Codes are the closed vocabulary of the negotiated AdCP release. `details` is seller-specific in 3.2; portable handling relies only on `code` and `affected_resource`. Whether `inventory_shortfall_forecast` surfaces as a warning on a completed commitment or instead blocks via `input-required` is seller discretion; a buyer unconditionally carries delivery risk on a MediaBuy committed with that warning.
A seller MUST NOT emit `inventory_shortfall_forecast` unless it advertises that indicator type, or `flight_change_creates_pacing_risk` unless it advertises `pacing_risk`. This keeps the promised durable readback available; `fields_ignored_due_to_precedence` is operation-relative and needs no indicator capability.
# Media Buy Lifecycle Flow
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/media-buys/lifecycle
Step-by-step sequence from product discovery through delivery, including the guaranteed-deal IO acceptance path and creative sync timing.
This page is the canonical sequence reference for media buy lifecycle. For conceptual background on the full lifecycle — campaign structure, package model, property targeting, and async operations — see [Media Buy Lifecycle](/dist/docs/3.2.8/media-buy/media-buys/).
## AdCP 3.2 flow
Capability discovery determines how the commercial commitment is formed. The
two compact paths converge on the same MediaBuy lifecycle:
```mermaid theme={null}
flowchart TD
C[get_adcp_capabilities] --> P{commercial path}
P -->|published offer| L[list_products]
L --> B[buy_products]
P -->|seller-planned| R[request_proposals]
R --> V[refine_proposals]
V --> H[finalize committed hold]
H --> A[accept_proposal]
B --> M{initial MediaBuy state}
A --> M
M -->|creatives missing| D[pending_creatives]
M -->|flight in future| E[pending_start]
M -->|ready to deliver| F[active]
D --> S[sync_creatives and assign]
S --> E
E --> F
F --> O[control_media_buy]
O -->|pause| J[paused]
J -->|resume| F
F -->|goal met, budget spent, or flight ended| I[completed]
```
1. **Discover capabilities** — read `media_buy.lifecycle_tools` and related
creative capabilities.
2. **Form the commercial commitment** — purchase a versioned published offer
with `buy_products`, or accept a committed immutable proposal with
`accept_proposal`. Either request may set the buyer's MediaBuy `name`; the
completed commitment echoes it outside `accepted_proposal` and its digest.
3. **Supply creatives** — use `sync_creatives` and explicit assignment
operations. Compact purchase calls never carry creative bodies.
4. **Operate and reconcile** — read `get_media_buys`, apply in-envelope changes
with `control_media_buy`, and use `get_media_buy_delivery` for reporting.
Commercial changes outside the accepted envelope return `REQUOTE_REQUIRED`.
When `error.details.decline_reason` is present, use the coarse seller-policy
dimension to inform recovery. The reason may select a typed refinement, but
some policies still require the buyer-safe message, a free-text `ask`, or human
negotiation. Begin the amendment from the snapshot's `accepted_proposal_id`,
then revise, finalize, and accept the successor proposal. Sellers retain
disclosure control and may omit `decline_reason` when even the coarse
classification would expose private thresholds or enforcement controls.
### Compact operations form a saga
Each compact mutation is atomic by itself, but a workflow containing more than
one mutation is not atomic as a group. In particular, purchase followed by
creative sync has this boundary:
1. `buy_products` or `accept_proposal` commits the MediaBuy and returns
`purchase_bindings[]` with seller-assigned package IDs.
2. `sync_creatives` uploads library creatives and applies assignment operations.
3. A failure in step 2 leaves step 1 committed. The buyer reads the MediaBuy,
fixes and retries trafficking, or exercises an available cancellation right.
The same rule applies when a legacy `update_media_buy` request is decomposed
into proposal acceptance, operational control, and creative sync. Those calls
have independent validation, authorization, idempotency, async-task, and
failure boundaries. A commercial amendment can succeed while the following
control or creative assignment fails, and a control can succeed while a later
assignment fails. Implementations MUST NOT describe such a sequence as an
atomic translation of the compatibility facade.
Some compatibility requests therefore require the facade itself. A placement
targeting patch that removes a placement used by an assignment must
replace or reroute that assignment in the same `update_media_buy` mutation.
`control_media_buy` cannot carry creative assignments, so `control_media_buy`
followed by `sync_creatives` is not equivalent. Inline-only creative sellers
also have no compact creative continuation and use `create_media_buy` or
`update_media_buy` for package-scoped bodies.
Other facade-only or explicitly lossy create shapes include
`artifact_webhook`, per-package initial pause, inline catalog bodies or filters,
and a buyer-authored exact `committed_metrics` set. Compact callers synchronize
catalogs before purchase and accept that a catalog can remain after a failed
purchase. Direct compact purchase derives reporting commitments from published
terms; an exact set is lossless only when it is already captured by the
proposal being accepted. The MediaBuy `name` is not lossy: both compact
commitment requests accept the buyer's display label and return the persisted
value outside the accepted commercial terms.
## State machine
### Media buy states
| State | Meaning | Terminal? |
| - | - | - |
| `pending_creatives` | Approved; no creatives assigned yet | No |
| `pending_start` | Creatives assigned; waiting for flight date | No |
| `active` | Delivering impressions | No |
| `paused` | Temporarily halted | No |
| `completed` | Flight ended, goal met, or budget exhausted | Yes |
| `rejected` | Seller declined the buy | Yes |
| `canceled` | Buyer or seller terminated before completion | Yes |
> [!NOTE]
>
> `submitted`, `working`, and `input-required` are **task-level** statuses. They
> describe an operation such as `buy_products` or `accept_proposal`, not the
> MediaBuy itself. The completion artifact creates or updates the MediaBuy, whose
> state is then read through `get_media_buys`. See [task status and MediaBuy state](/dist/docs/3.2.8/media-buy/media-buys#state-machine).
### Transitions
```mermaid theme={null}
stateDiagram-v2
[*] --> pending_creatives : buy_products / accept_proposal\n(creatives missing)
[*] --> pending_start : buy_products / accept_proposal\n(flight future)
[*] --> active : buy_products / accept_proposal\n(ready to deliver)
[*] --> paused : buy_products\n(paused: true)
pending_creatives --> pending_start : sync_creatives assignment
pending_creatives --> paused : sync_creatives assignment\n(buy held)
pending_start --> active : flight date reached
pending_start --> paused : flight date reached\n(create held)
active --> paused : control_media_buy\n(paused: true)
paused --> active : control_media_buy\n(paused: false)
active --> completed : flight ended /\ngoal met / budget exhausted
paused --> completed : flight ended /\ngoal met / budget exhausted
pending_creatives --> rejected : seller declines
pending_start --> rejected : seller declines
pending_creatives --> canceled : control_media_buy\n(accepted unilateral right)
pending_start --> canceled : control_media_buy\n(accepted unilateral right)
active --> canceled : control_media_buy\n(accepted unilateral right)
paused --> canceled : control_media_buy\n(accepted unilateral right)
completed --> [*]
rejected --> [*]
canceled --> [*]
```
### Discovering valid actions at runtime
Rather than hardcoding the state machine, read `valid_actions` from `get_media_buys`. The seller returns exactly what the buyer can do in the current state:
```json theme={null}
{
"media_buy_id": "mb_12345",
"status": "active",
"revision": 3,
"valid_actions": ["pause", "cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"]
}
```
`control_media_buy` requires the latest `revision`. The seller rejects a stale
revision with `CONFLICT`, so concurrent controls cannot silently overwrite one
another. `available_actions` tells compact clients whether the next change
routes to `control_media_buy`, proposal refinement, creative assignment, or
another task. Prefer it over inferring routing from the state enum.
A display name may be set on `buy_products` or `accept_proposal` when the
MediaBuy is committed. A later display-name-only change routes to
`control_media_buy`. `name` is revision-checked non-commercial metadata:
changing it increments the MediaBuy revision without changing the accepted
terms or creating an accepted-proposal successor.
Use `sync_creatives.assignment_operations` for creative changes. Creative
assignment is independent from commercial control and does not increment the
MediaBuy revision merely because an assignment changed. There is no shared
optimistic-concurrency fence between `sync_creatives` and
`control_media_buy`: a successful sync can change assignment state while the
MediaBuy `revision` remains unchanged. By contrast, a creative-assignment or
inline-creative mutation performed inside the `update_media_buy` compatibility
facade is part of that atomic MediaBuy update and MUST increment `revision`.
Clients mixing the two surfaces must re-read both package assignments and the
MediaBuy before computing a replacement; the revision alone cannot prove that
assignment state is unchanged.
## Guaranteed / PG deal variation
Guaranteed products require contractual commitment before delivery begins. In
the compact lifecycle, sellers normally express negotiated guaranteed terms as
a committed proposal:
```mermaid theme={null}
flowchart TD
A[request_proposals] --> B[refine proposal terms]
B --> C[finalize committed hold]
C --> D[accept_proposal\nwith IO acceptance when required]
D --> E{task status}
E -->|human or counterparty review| F[submitted / input-required]
E -->|completed| G[pending_creatives or pending_start]
F --> G
G --> H[sync_creatives and assign]
H --> I[active — guaranteed delivery]
I --> J{performance}
J -->|standards met| K[completed]
J -->|under-delivery| L[makegood or remediation]
L --> K
```
### What makes a guaranteed buy different
**Accountability terms are part of the accepted commercial snapshot.** A
guaranteed proposal can carry:
* `performance_standards` — viewability, IVT, completion rate, and other thresholds with measurement vendor
* `measurement_terms` — who counts the billing metric, acceptable variance, and makegood remedies
* `cancellation_policy` — notice period and cancellation fee for early termination
Omitting any of these on a guaranteed package causes the seller to return `TERMS_REJECTED`.
**IO acceptance** — `accept_proposal` can include structured `io_acceptance`
when the committed terms require it. The operation may still return
`submitted` or `input-required` while the seller completes human or
counterparty review. Poll with `get_task_status` or use the configured task
webhook. The completion artifact carries the `media_buy_id`.
**Makegoods** — if the seller under-delivers against agreed `performance_standards`, they propose a remedy from the `makegood_policy`: `additional_delivery`, `credit`, or `invoice_adjustment`. The buyer accepts or disputes.
> [!NOTE]
>
> A seller who accepts without under-delivering earns a favorable accountability
> signal. See [Accountability](/dist/docs/3.2.8/media-buy/advanced-topics/accountability) for
> performance standards, measurement terms, and makegood resolution.
## Creative sync timing
### When creatives are required
`buy_products` and `accept_proposal` do not accept creative bodies. After
commitment, supply or update library creatives with `sync_creatives`, then use
explicit `assignment_operations` to assign them to packages. A compact seller
advertises the creative workflow it supports; callers should not infer an
inline-creative path from older tool availability.
This sequence does not move request-time validation across the commitment
boundary. On the compatibility facades, one invalid inline creative or
assignment fails the complete create or update without mutation. On the compact
path, the buy already exists when package-aware creative validation runs. A
strict sync prevents partial creative or assignment mutation within that sync,
but it cannot undo the preceding purchase. Later policy review is different
from either validation case: a review rejection does not roll back a valid
facade mutation or compact purchase.
When required formats lack creative coverage, the buy enters
`pending_creatives`. After assignments cover the package's effective
`format_options[]`, it moves to `pending_start` when the flight is in the future
or `active` when delivery can begin. A direct `buy_products` call may set
`paused: true`; resume it later with `control_media_buy` and the latest
revision.
### The `creative_deadline`
The MediaBuy snapshot can carry a `creative_deadline`; individual packages may
carry their own. **Package-level deadlines take precedence over the MediaBuy
deadline.** This matters for mixed-channel orders—a print package may have a
material deadline days before digital packages in the same buy.
After the deadline, new or replacement assignments for that package return
`CREATIVE_REJECTED`. Delivery continues with the currently assigned creatives,
or the package remains `pending_creatives` if none were accepted.
```
Deadline hierarchy:
package.creative_deadline (if present — wins)
↓ else
media_buy.creative_deadline
```
### Effect on creatives when a buy ends
When a media buy reaches `rejected`, `canceled`, or `completed`, creative assignments are released. For library-backed sellers, the creatives themselves are not deleted — they remain in the library with their existing review status and are available for assignment to other media buys. Inline-only sellers may retain package-scoped creative records for audit and reporting without exposing reusable library entries.
## Health and dependency impairment
`status` describes operational state — is the buy serving, paused, or terminal? **`health`** is a separate orthogonal field describing whether upstream dependencies are intact:
| Field | Tracks | Values |
| - | - | - |
| `status` | Operational state | `pending_creatives`, `pending_start`, `active`, `paused`, `completed`, `rejected`, `canceled` |
| `health` | Dependency state | `ok`, `impaired` |
The two are orthogonal. A buy can be `paused`-and-impaired, `pending_creatives`-and-impaired, or `active`-and-impaired. Health does not change `status`; `valid_actions` is unaffected.
### When `health` is `impaired`
`health` transitions to `impaired` when an upstream dependency referenced by the buy enters an offline state that affects delivery for at least one package:
* An audience the buy targets transitions to `suspended` (consent expiry, TTL, policy enforcement).
* A creative the buy uses transitions from `approved` to `suspended` (recoverable dependency/authorization loss), from `suspended` to `rejected` (terminal dependency/authorization loss), or from `approved` to `rejected` (post-approval revocation).
* A catalog item the buy targets transitions to `withdrawn` (seller-initiated removal).
* An event source the buy depends on enters `insufficient` (zero events received).
* A property the buy targets is depublished via brand.json / adagents.json.
The buy's `impairments[]` array carries one entry per affected dependency:
```json theme={null}
{
"media_buy_id": "mb_456",
"status": "active",
"health": "impaired",
"impairments": [
{
"impairment_id": "imp_01HZX9...",
"resource_type": "audience",
"resource_id": "aud_123",
"package_ids": ["pkg_a"],
"transition": { "from": "ready", "to": "suspended" },
"reason_code": "consent_expired",
"reason": "Hashed identifier consent basis expired on 2026-06-01.",
"observed_at": "2026-06-02T14:11:00Z",
"remediation": "Re-sync audience after refreshing consent upstream."
}
]
}
```
### Materiality
Each entry in `impairments[]` MUST list at least one package whose ability to serve is degraded. Cosmetic effects (one rejected creative in a package that still has serviceable peers) MUST NOT be reported as impairments — they're surfaced via the resource's own status, not the buy's.
### Reverse direction
When the underlying resource returns to a serviceable state (audience re-syncs, creative re-approved), the seller MUST remove the corresponding entry from `impairments[]` and flip `health` to `ok` if no other impairments remain. The buyer sees the recovered state on the next snapshot read or via the next `impairment` push (which carries the closure).
### Pushed via `impairment` webhook
When a buy's `health` transitions or an impairment is added/removed, the seller fires an `impairment` notification against the buy's `push_notification_config`. The payload reuses the `impairment` object shape plus the buy's updated `health`. See the [persistent webhook contract](/dist/docs/3.2.8/building/by-layer/L3/webhooks#persistent-channel-contract) for delivery semantics (at-least-once, no-ordering, coalescence, replay via snapshot).
Impairment webhooks identify affected packages with `package_ids[]` by design. Buyers that need package-level correlation context, such as `context.buyer_ref`, should call `get_media_buys` after receiving an impairment fire and read the package snapshot.
### Materiality coverage
The MUST-strength materiality rule applies to resource types where the resource → buy join is cheap and 1:N — audience, event_source, property. For creative and catalog_item, materiality is SHOULD-strength: a creative in a large pool may not degrade serving when removed, and the join is more expensive for sellers to compute. Implementers SHOULD report conservatively when uncertain and MUST NOT report when serving is provably unaffected.
### Remediation by `reason_code`
Each `reason_code` has a typical buyer remediation path. Sellers don't fill this in per-impairment — buyer agents key remediation off `reason_code` directly. The table below is the protocol-level guidance; the per-impairment free-text `remediation` field carries seller-specific context that doesn't fit the typical path (e.g., "we restored this audience yesterday; sync now to pick up the refresh").
| `reason_code` | Typical buyer remediation |
| - | - |
| `consent_expired` | Refresh upstream consent (e.g., hashed-id consent renewal on a clean-room flow), then re-sync the audience via `sync_audiences`. |
| `ttl_expired` | Re-sync the audience via `sync_audiences` to renew. |
| `pii_audit_failed` | Address audit findings upstream (hashing, identifier hygiene). Re-sync only **after** the seller signals the audit is cleared — a buyer agent that loops `sync_audiences` against an uncleared audit will not converge. |
| `content_rejected` | Fix or replace the asset through `sync_creatives`, then use an explicit assignment operation. Campaign-level replace-versus-wait policy stays with the buyer. |
| `identity_authorization_revoked` | Restore the downstream identity/post authorization through the seller's connection flow, or replace the affected `published_post` creative if authorization cannot be restored. |
| `identity_authorization_expired` | Renew the downstream identity/post authorization through the seller's connection flow, then let the seller re-check or re-review the creative. |
| `source_private` | Restore source post visibility or replace the affected `published_post` reference. |
| `source_offline` | Verify the tag is firing on the buyer's properties (this is often a buyer/publisher integration issue, not a seller-side outage), then re-sync via `sync_event_sources`. |
| `seller_removed` | No buyer-side resubmit path. Find a replacement through `list_products` or `request_proposals`, inspect canonical product format options, or contact the seller for restoration ETA. |
| `policy_violation` | Seller-side enforcement; buyer-side resubmit unlikely to clear. Await resolution or escalate per the seller's standard contact path. |
| `property_depublished` | No buyer-side fix — property publication is controlled by the publisher's `brand.json` / `adagents.json`. Find a replacement through product listing or proposal planning, or remove it from targeting. |
### Triage ordering
Buyer agents triaging a non-empty `impairments[]` SHOULD sort entries by `observed_at` ascending — the oldest open impairment is the most likely to have already eaten into delivery. Webhook arrival time is not a reliable proxy: under the coalescence rule (see [webhooks § Coalescence](/dist/docs/3.2.8/building/by-layer/L3/webhooks#coalescence)) the seller MAY batch multiple state changes into one fire, and re-emission under a fresh `idempotency_key` resets the transport timestamp without changing `observed_at`.
### Impairments are operational signals, not commercial events
An `impairment` reports degraded delivery from upstream dependency change. It is **not** a billing event, makegood trigger, or credit dispute. Commercial remedies for under-delivery are governed by `accountability_terms` on guaranteed buys and remain out of scope for this surface. Integrators building dispute pipelines should drive them from delivery reports and accountability terms, not from `impairments[]`.
### Compliance
The `impairment.coherence` assertion verifies that the buy's `impairments[]` surface stays in sync with the underlying resources it references. It is a cross-resource invariant — it observes both the resource transition and the buy snapshot in the same compliance run.
**Forward rule.** Every entry in a buy's `impairments[]` MUST reference a resource whose current status is an offline state — `audience: suspended` (on `audience-status`), `creative: suspended` or `creative: rejected` (on `creative-status`), `catalog_item: withdrawn` (on `catalog-item-status`), `event_source: insufficient` (the `assessment-status` value surfaced through `event-source-health.status`), or a property depublished via `brand.json` / `adagents.json`. A buy reporting an impairment whose referenced resource is no longer offline fails the check — the seller has stale state on the buy.
**Inverse rule.** Any resource in an offline state that is referenced by a non-terminal buy MUST appear in that buy's `impairments[]`. A seller that transitions a resource without propagating to the affected buys fails the check — the seller has stale state on the resource.
**Health-iff rule.** A non-terminal buy's `health` MUST be `impaired` whenever `impairments[]` is non-empty, and MUST be `ok` whenever `impairments[]` is empty. This is a strict iff — stale `health: "impaired"` with an empty `impairments[]` (or `health: "ok"` with a non-empty `impairments[]`) violates the rule even when the forward and inverse rules are individually satisfied.
**Out of scope.** All three rules relax on buys in terminal status (`completed`, `canceled`, `rejected`). Sellers MAY leave `impairments[]` and `health` in whatever state they held at the terminal transition — they are not required to clean up. Buyers MUST NOT treat post-terminal drift as a coherence violation; the buy is no longer serving and synchronisation is wasted effort. Materiality (the requirement that `package_ids` be non-empty) is enforced at the schema layer by `package_ids: minItems: 1` on `impairment.json` — `impairment.coherence` does not re-check it.
**Snapshot is one of several propagation surfaces.** Sellers declare which surfaces they use via [`capabilities.media_buy.propagation_surfaces`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-adcp-capabilities-response.json) on `get_adcp_capabilities` — a non-exclusive array, so a seller mirroring impairments on both the buy snapshot AND firing webhooks declares `["snapshot", "webhook"]` (the common case for premium guaranteed sellers). The three surface values:
* **`snapshot`** — seller populates `health` + `impairments[]` on `get_media_buys` reads. The contract above governs this surface; `impairment.coherence` storyboards grade it when declared, `not_applicable` otherwise.
* **`webhook`** — seller fires `notification-type: impairment` webhooks via `push_notification_config`. Subject to the persistent-channel webhook contract.
* **`out_of_band`** — seller propagates via channels outside the AdCP protocol surface (email, dashboard, partner-specific feeds). Long-tail and enterprise-bundled platforms commonly use this when impairment workflows are managed in human channels. Sellers declaring only `["out_of_band"]` are not graded by snapshot or webhook compliance — their bar is the offline agreement.
Default when absent is `["snapshot"]`. Each surface is independent of the others; declare the actual mix of surfaces buyers will observe on the agent. A seller with impairment data in their API under a non-AdCP field name (a mapping gap) SHOULD document the mapping rather than declare `out_of_band` — the spec's gap is what `out_of_band` legitimately covers.
**Relationship to other invariants.** `impairment.coherence` complements `status.monotonic`, which observes single-resource transitions only. The two run together on every specialism whose storyboard exercises both a resource-state transition and a media-buy snapshot read — audience-sync, creative-ad-server, creative-template, creative-generative, sales-catalog-driven. The cross-resource exercise that drives non-NA grading is the dependency-impairment storyboard (`media_buy_seller/dependency_impairment`, creative-track), which forces a creative on an active buy into an offline state (`approved → suspended` for recoverable dependency loss or `approved/suspended → rejected` for terminal revocation), verifies the buy reflects `health: impaired` with a matching `impairments[]` entry, recovers or replaces the creative, and verifies the buy returns to `health: ok` with `impairments[]` cleared. Audience-track and catalog-track variants are follow-ups, pending `force_audience_status` / `force_catalog_item_status` support in the compliance test controller.
See the [Snapshot and log contract](/dist/docs/3.2.8/protocol/snapshot-and-log) for the read-side rules that tie `impairments[]` (snapshot) to the `impairment` push (log).
> [!TIP]
>
> For library-backed sellers, creative library state and creative assignment state are tracked independently. A creative that was assigned to a canceled buy still has whatever review status it earned and can be immediately assigned to a new buy. Inline-only sellers expose package-scoped creative status on `get_media_buys` but do not advertise reusable library creatives. See [creative state and assignment state](/dist/docs/3.2.8/creative/creative-libraries#creative-state-and-assignment-state-are-separate).
## See also
* [Media Buy Lifecycle](/dist/docs/3.2.8/media-buy/media-buys/) — full lifecycle reference: campaign structure, package model, async operations
* [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) — purchase versioned published offers directly
* [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) — accept committed new-buy, amendment, or cancellation terms
* [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) — apply revision-checked operational controls
* [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) — upload and update library creatives when the seller advertises `creative.has_creative_library: true`
* [Accountability](/dist/docs/3.2.8/media-buy/advanced-topics/accountability) — performance standards, measurement terms, makegood resolution
* [Optimization & Reporting](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting) — delivery monitoring, dimensional reporting, campaign updates
# Optimization & Reporting
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting
AdCP optimization and reporting — monitor delivery metrics, analyze dimensional breakdowns, share performance feedback, and optimize active media buys.
Continuous improvement through data-driven monitoring and optimization. AdCP provides comprehensive reporting tools and optimization features to help you track performance, analyze delivery, and improve campaign outcomes.
Reporting in AdCP aligns with the [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) system used for campaign setup, enabling consistent analysis across the campaign lifecycle. This unified approach means you can report on exactly what you targeted.
Performance data feeds into AdCP's [Accountability & Trust Framework](/dist/docs/3.2.8/media-buy/index.mdx#accountability--trust-framework), enabling publishers to build reputation through consistent delivery and helping buyers make data-driven allocation decisions.
## Key Optimization Tasks
### Delivery Reporting
Use [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) to retrieve comprehensive performance data including impressions, spend, clicks, and conversions across all campaign packages.
Alternatively, configure **webhook-based reporting** during media buy creation to receive automated delivery notifications at regular intervals.
### Campaign Updates
Use [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) to modify campaign settings, budgets, and configurations based on performance insights.
## Optimization Workflow
The typical optimization cycle follows this pattern:
1. **Monitor Delivery**: Track campaign performance against targets
2. **Analyze Performance**: Identify optimization opportunities
3. **Make Adjustments**: Update budgets, targeting, or creative assignments
4. **Track Changes**: Monitor impact of optimizations
5. **Iterate**: Continuous improvement through regular analysis
## Metric lifecycle
Every optimization metric in AdCP — whether seller-native (clicks, views, reach), graduated vendor-attested (viewability), or vendor-defined (attention, brand lift, emissions) — flows through the same set of surfaces. Buyers reason about a metric by asking three questions in order:
* **Can you?** — Is the product capable of optimizing for this metric? *(Discovery)*
* **Will you?** — For this package, are you committing to optimize and report it? *(Commitment)*
* **Did you?** — In delivery, what was the value, and did you meet the commitment? *(Reporting)*
Each question maps to a specific protocol surface. The same `metric_id` (or `(vendor, metric_id)` tuple for vendor-attested metrics) flows through every layer — discovery, capability declarations, package commitments, and delivery — so buyers reconciling delivery against a goal never need a translation table.
### Standard metric flow (e.g., `clicks`, `viewable_rate`)
| Question | Surface | Field |
| - | - | - |
| Can the product report it? | Product capability | `reporting_capabilities.available_metrics` |
| Can the product optimize for it? | Product capability | `metric_optimization.supported_metrics` |
| Will the seller commit to reporting it? | Package | `committed_metrics[]` (scope: `standard`) |
| Does the buyer want it optimized? | Package | `optimization_goals[]` (kind: `metric`) |
| Does the buyer want accountability? | Package | `performance_standards[]` |
| What was the value? | Delivery | Standard scalar (e.g., `clicks`, `viewability.viewable_rate`) |
| Did the seller fail to deliver a committed metric? | Delivery | `missing_metrics[]` (scope: `standard`) |
### Vendor-attested metric flow (e.g., Adelaide attention, Scope3 emissions, Kantar brand lift)
Same lifecycle, with the `(vendor, metric_id)` tuple replacing the plain `metric_id` everywhere:
| Question | Surface | Field |
| - | - | - |
| Does the vendor define this metric? | Vendor's capabilities | `get_adcp_capabilities.measurement.metrics[]` |
| Can the product report this vendor metric? | Product capability | `reporting_capabilities.vendor_metrics[]` |
| Who produced the number, relative to the seller? | Product capability | `reporting_capabilities.vendor_metrics[].vendor_relationship` (`first_party` / `affiliated` / `third_party`) |
| Can the product optimize for this vendor metric? | Product capability | `vendor_metric_optimization.supported_metrics[]` |
| Will the seller commit to reporting it? | Package | `committed_metrics[]` (scope: `vendor`) |
| Which methodology version is contracted? | Package | `committed_metrics[].methodology_version` (pins the vendor catalog's `methodology_version`) |
| Does the buyer want it optimized? | Package | `optimization_goals[]` (kind: `vendor_metric`) |
| Does the buyer want accountability? | Package | `performance_standards[]` (with `vendor` field) |
| What was the value? | Delivery | `vendor_metric_values[]` |
| Did the seller fail to deliver a committed metric? | Delivery | `missing_metrics[]` (scope: `vendor`) |
### Why both flows matter
The two flows aren't a duplication — they encode the difference between *standardized* and *vendor-specific* measurement. Clicks mean the same thing across every seller; attention does not. Vendor binding is the wire-level evidence that the buyer and seller agreed on *which* attention model is being optimized and reported. See [`measurement/taxonomy.mdx`](/dist/docs/3.2.8/measurement/taxonomy) for the Tier 0 → Tier 1 graduation policy that decides which flow a given metric uses.
### Required coherence between layers
`optimization_goals` define the objective function: what the seller should optimize, its units, and priority. They do not define 3.2 bidding policy. Currency-bearing execution controls live in `bidding` at media-buy or package scope. All monetary amounts use the media-buy currency; a selected pricing option contributes the auction unit but MUST declare that same currency:
* seller-optimized media-buy `cost_per`/`roas` bind to the primary `budget_allocation.optimization_goals` goal;
* package-authored `cost_per`/`roas` bind to that package's primary goal;
* fixed media-buy `cost_per` binds to every inheriting package and requires compatible primary-goal result units; fixed inherited `roas` requires value-bearing primary goals;
* `bid_amount` and `max_bid` are expressed per the selected pricing option's auction unit; and
* `{automatic: true}` explicitly overrides inherited policy with provider automatic bidding.
The separation matters when the units differ—for example, a seller can optimize toward conversions using a target CPA while also enforcing a max-CPC auction ceiling, with both amounts denominated in the media-buy currency. Legacy goal targets `cost_per` and `per_ad_spend` remain accepted during 3.2 migration but cannot be combined with canonical `bidding` on the same effective package. Their conservative normalization remains `cost_per` → `strength: "target"` and `per_ad_spend` → `strength: "target"`.
Four rules connect the layers and prevent orphaned goals:
1. **Optimization requires capability.** A package's `optimization_goals[]` entry MUST match a product capability — `metric_optimization.supported_metrics` for `kind: "metric"`, or `vendor_metric_optimization.supported_metrics` for `kind: "vendor_metric"`. Sellers reject mismatches with `TERMS_REJECTED`.
2. **Optimization requires reporting commitment.** For `kind: "vendor_metric"` goals, the matching `(vendor, metric_id)` MUST also appear in the package's `committed_metrics[]`. Optimizing for a metric the seller isn't committed to reporting is unverifiable — the buyer has no way to grade the goal. Sellers reject uncommitted vendor_metric goals with `TERMS_REJECTED`. (This rule is normative for vendor metrics specifically; for seller-native `metric` goals, the metric is usually always reported by virtue of being seller-native, so the coherence is implicit.) A third precondition — discovery, that `metric_id` appears in the vendor's published `measurement.metrics[]` catalog — is SHOULD this minor and tightens to MUST at the next minor while measurement-vendor adoption of AdCP-conformant capability publication catches up.
3. **Performance accountability is independent.** `performance_standards[]` lives in parallel — buyers MAY add a threshold commitment on any metric the seller commits to reporting, regardless of whether they also set an optimization goal on it. The three surfaces (goal / commitment / standard) compose:
* Goal only — "push toward this," no accountability floor
* Standard only — "you owe me ≥ X," seller decides how to hit it
* Both — optimization steers; standard backstops
4. **Priority is ordinal, lowest-value-first.** When `optimization_goals[]` carry explicit `priority` values, the seller treats the goal with the **lowest** priority value as primary — even when no goal is `priority: 1` (priorities of `2` and `3` mean `2` is primary). When all priorities are omitted, the first array entry is primary. Duplicate priority values are undefined.
### Worked example: Adelaide attention end-to-end
A buyer wants to optimize against Adelaide's `attention_score` with a threshold of 70. Here's how the four surfaces line up:
**1. Product capability** (discovered via `get_products`):
```json theme={null}
{
"product_id": "premium_ctv_video",
"vendor_metric_optimization": {
"supported_metrics": [
{
"vendor": { "domain": "adelaidemetrics.com" },
"metric_id": "attention_score",
"supported_targets": ["cost_per", "threshold_rate"]
}
]
},
"reporting_capabilities": {
"vendor_metrics": [
{ "vendor": { "domain": "adelaidemetrics.com" }, "metric_id": "attention_score" }
]
}
}
```
**2. Package proposal on `create_media_buy`** — the buyer commits to reporting AND sets the optimization goal (both required by the reporting-coherence rule):
```json theme={null}
{
"product_id": "premium_ctv_video",
"committed_metrics": [
{
"scope": "vendor",
"vendor": { "domain": "adelaidemetrics.com" },
"metric_id": "attention_score"
}
],
"optimization_goals": [
{
"kind": "vendor_metric",
"vendor": { "domain": "adelaidemetrics.com" },
"metric_id": "attention_score",
"target": { "kind": "threshold_rate", "value": 70 },
"priority": 1
}
]
}
```
A `performance_standard` MAY be layered on top if the buyer wants a contractual floor — e.g., `{ "metric": "attention_score", "vendor": { "domain": "adelaidemetrics.com" }, "threshold": 65 }` — but it's independent of the goal.
**3. Delivery** (`by_package` excerpt from a `get_media_buy_delivery` response):
```json theme={null}
{
"by_package": [{
"package_id": "pkg_ctv_001",
"impressions": 1000000,
"spend": 25000,
"pricing_model": "cpm",
"rate": 25,
"currency": "USD",
"metric_values": [{
"scope": "standard",
"metric_id": "viewable_rate",
"qualifier": { "viewability_standard": "mrc" },
"value": 0.72,
"measurable_impressions": 700000,
"viewable_impressions": 504000
}],
"vendor_metric_values": [{
"vendor": { "domain": "adelaidemetrics.com" },
"metric_id": "attention_score",
"value": 73.2,
"measurable_impressions": 420000
}]
}]
}
```
The seller's bidding stack steered toward higher Adelaide attention scores; the reported value `73.2` is above the threshold `70`, so the goal is met. The `measurable_impressions` denominator (`420000` out of, say, 1M delivered impressions) is the coverage figure for Adelaide's measurement — vendor SDKs rarely fire on 100% of delivered impressions, and attention-vendor coverage on CTV today is typically 30–60% depending on app-SDK presence. Always compute coverage from `measurable_impressions / impressions` before reasoning about the reported value.
**4. Accountability gap reporting** (also in the `get_media_buy_delivery` response, when commitment isn't met):
```json theme={null}
{
"by_package": [{
"package_id": "...",
"missing_metrics": [
{
"scope": "vendor",
"vendor": { "domain": "adelaidemetrics.com" },
"metric_id": "attention_score"
}
]
}]
}
```
If Adelaide's coverage on the inventory dropped below the seller's confidence threshold and they couldn't populate `vendor_metric_values` for this period, the same `(vendor, metric_id)` shows up in `missing_metrics` — same key across the entire lifecycle, so buyer reconciliation is a row-level join.
## Performance Monitoring
### Real-Time Metrics
Track campaign delivery as it happens:
* **Impression delivery** vs. targets
* **Spend pacing** against budget
* **Click-through rates** and engagement
* **Conversion tracking** for business outcomes
### Historical Analysis
Understand performance trends over time:
* **Daily/hourly breakdowns** of key metrics
* **Performance comparisons** across time periods
* **Trend identification** for optimization opportunities
### Alerting and Notifications
Stay informed of important campaign events:
* **Delivery alerts** for pacing issues
* **Performance notifications** for significant changes
* **Budget warnings** before limits are reached
## Delivery Methods
Publishers can proactively push reporting data to buyers through webhook notifications or offline file delivery. This eliminates continuous polling and provides timely campaign insights.
**Webhook Push (Real-time)** - HTTP POST to buyer endpoint
* Best for: Most buyer-seller relationships
* Latency: Near real-time (seconds to minutes)
* Cost: Standard webhook infrastructure
**Offline File Delivery (Batch)** - Cloud storage bucket push
* Best for: Large buyer-seller pairs (high volume)
* Latency: Scheduled batch delivery (hourly/daily)
* Cost: Significantly lower (\$0.01-0.10 per GB vs. \$0.50-2.00 per 1M webhooks)
* Format: JSON Lines, CSV, or Parquet files
* Storage: S3, GCS, Azure Blob Storage
### Webhook-Based Reporting
#### Webhook Configuration
For AdCP 3.2 scheduled delivery, coordinate support for the interim `reporting_webhook.operation_id` field with your seller and ensure your SDK preserves it. See [AdCP 3.2 interim reporting correlation](/dist/docs/3.2.8/building/by-layer/L3/webhooks#adcp-3-2-interim-reporting-correlation), including the steps for updating existing registrations. This additional field is opt-in until the proposed 3.3 core addition is released.
Configure reporting webhooks when creating a media buy using the `reporting_webhook` parameter:
```json theme={null}
{
"packages": [...],
"reporting_webhook": {
"url": "https://buyer.example.com/webhooks/reporting",
"authentication": {
"schemes": ["Bearer"],
"credentials": "secret_token_min_32_chars"
},
"reporting_frequency": "daily"
}
}
```
**Or with HMAC signature (recommended for production):**
```json theme={null}
{
"packages": [...],
"reporting_webhook": {
"url": "https://buyer.example.com/webhooks/reporting",
"authentication": {
"schemes": ["HMAC-SHA256"],
"credentials": "shared_secret_min_32_chars"
},
"reporting_frequency": "daily"
}
}
```
**Security is Required:**
* `authentication` configuration is mandatory (minimum 32 characters)
* **Bearer tokens**: Simple, good for development (Authorization header)
* **HMAC-SHA256**: Production-recommended, prevents replay attacks (signature headers)
* Credentials exchanged out-of-band during publisher onboarding
* See [Security](/dist/docs/3.2.8/building/by-layer/L1/security) for implementation details
#### Supported Frequencies
Publishers declare supported reporting frequencies in the product's `reporting_capabilities`. Publishers are **not required** to support all frequencies - choose what makes operational sense for your platform.
* **`hourly`**: Receive notifications every hour during campaign flight (optional, consider cost/complexity)
* **`daily`**: Receive notifications once per day (most common, recommended for Phase 1)
* **`weekly`**: Receive notifications once per week — the native cadence for audience-currency channels reporting weekly increments (OOH, radio)
* **`monthly`**: Receive notifications once per month (timezone specified by publisher)
* **`quarterly`**: Receive notifications once per quarter — matches quarterly measurement-currency publication cycles
* **`post_campaign`**: A single report after the flight ends — for channels where delivery is only knowable in arrears
**Cadence gates optimization eligibility (normative, introduced in 3.2).** Buy-side agents MUST treat a product's declared `available_reporting_frequencies` as an optimization-eligibility gate: a buyer MUST NOT make mid-flight optimization decisions against metrics whose declared cadence is `quarterly` or `post_campaign`. Weekly-cadence channels (OOH and radio audience currencies) support at most week-grain adjustment. This is not advice about statistical power — data on those cadences describes a period that has already closed, so an agent optimizing on it is acting on a model of the channel that is false at decision time. Sellers are not obligated to police buyer behavior; the buyer-side obligation is graded through buyer-artifact testing.
**Cost Consideration:** Hourly webhooks generate 24x more traffic than daily. Large buyer-seller pairs may prefer offline reporting mechanisms (see below) for cost efficiency.
#### Available Metrics
Metric availability is declared at two levels:
1. **Product level**: `reporting_capabilities.available_metrics` declares what the platform can report
2. **Format level**: `reported_metrics` on a creative format declares what the format can produce (see [Reported Metrics](/dist/docs/3.2.8/creative/formats#reported-metrics))
Buyers receive the intersection of both. `impressions` and `spend` are always reported regardless of the intersection. Standard metrics include:
* **`impressions`**: Ad views (always available)
* **`spend`**: Amount spent (always available)
* **`clicks`**: Click events
* **`ctr`**: Click-through rate
* **`views`**: Views at platform-defined threshold
* **`completed_views`**: Video/audio completions (or threshold-based completion when an optimization goal sets a custom view duration)
* **`completion_rate`**: Completion rate (`completed_views` / `impressions`); `null` when not applicable (e.g. a non-video buy)
* **`conversions`**: Post-click or post-view conversions
* **`conversion_value`**: Monetary value of attributed conversions
* **`commissionable_value`**: Settled portion of attributed conversion value eligible for revenue-share commission. Distinct from `conversion_value` when the agreement excludes taxes, shipping, discounts, returns, cancellations, or ineligible items.
* **`roas`**: Return on ad spend
* **`cost_per_acquisition`**: Cost per conversion
* **`new_to_brand_rate`**: Fraction of conversions from first-time brand buyers
* **`leads`**: Leads generated
* **`reach`**: Unique reach (paired with `reach_unit`). Measurement window declared via `reach_window` (`cumulative` / `period` / `rolling`). When `reach_window` is omitted, the window is unspecified — buyers MUST NOT sum reach across rows.
* **`reach_window`**: Window semantics for reach/frequency — object with `kind` (`cumulative` since campaign start, `period` for non-overlapping snapshot, `rolling` for trailing window) and `period: Duration` (required for `period` and `rolling`)
* **`frequency`**: Average frequency per reach unit, measured over `reach_window`
* **`grps`**: Gross Rating Points (for CPP billing)
* **`engagements`**: Direct ad interactions beyond viewing (reactions, taps, opens)
* **`engagement_rate`**: Platform-specific engagement rate
* **`follows`**: New followers, page likes, artist/podcast/channel follows, or free channel/feed subscribes attributed to delivery. Paid subscriptions are conversion events with `event_type: "subscribe"`.
* **`saves`**: Saves, bookmarks, playlist adds attributed to delivery (platforms vary in name — Pinterest "repins", TikTok "video_saves" — all report under this canonical key)
* **`profile_visits`**: Visits to the brand's in-platform page
* **`viewability`**: Viewability data (measurable_impressions, viewable_impressions, viewable_rate, viewed_seconds, optional viewed_seconds_percentiles / viewed_seconds_histogram, standard, vendor). Separates MRC and GroupM standards. `viewed_seconds` is the average in-view duration per measurable impression — reporting-side counterpart to the `viewed_seconds` optimization goal, governed by the same `standard` threshold as `viewable_rate`. `viewed_seconds_percentiles` adds the nearest-rank p25/p50/p75/p90/p95 summary; `viewed_seconds_histogram` adds seller-declared half-open duration buckets whose counts sum to `measurable_impressions`. Both distributions use the exact same measurable population, vendor, standard, and reporting row as the mean. Buyers combine histogram counts only when the full boundary sequence, vendor, and standard match. Histogram buckets need not be contiguous; a gap is valid only when no impressions fall within it — the sum constraint enforces this, and validators MUST NOT require contiguity independently. The optional `vendor` field carries a `BrandRef` so the row is self-describing — buyer agents reading delivery in isolation can attribute the numbers to a measurement vendor without joining back to `package.committed_metrics` or `package.performance_standards`.
* **`quartile_data`**: Video quartile completion data (q1-q4); `null` when not applicable (e.g. a non-video buy)
* **`time_based_views`**: Time-threshold view counts, one entry per (threshold_seconds, basis). `play_time` (platform-counted playback time, no independent viewability qualification) and `in_view` (IAB/MRC viewable-video clock, 50% of pixels) are not comparable and must not be summed. 2s and 6s are RECOMMENDED cross-platform reporting points; sellers may report other thresholds. Primarily an autoplay/skippable-video metric (social, olv, in-feed video) — completion (`quartile_data`) remains the currency for lean-back CTV/cinema inventory. Disclosure-grade: a `committed_metrics` entry for `time_based_views` contracts the array's presence, not specific thresholds.
* **`dooh_metrics`**: DOOH-specific metrics (loop plays, screens, venue breakdown)
* **`ooh_metrics`**: Classic (static) OOH metrics — panels, posting period, posting records with photo evidence, and modeled `estimated_impressions` with a declared `estimation_basis`; the channel has no play events
* **`cost_per_click`**: Cost per click (`spend / clicks`)
* **`cost_per_completed_view`**: Cost per completed view (`spend / completed_views`); CPCV pricing scalar for video/audio inventory
* **`cpm`**: Cost per thousand impressions (`(spend / impressions) × 1000`); universal pricing scalar across CTV, display, mobile/web video, native, audio, and DOOH
* **`downloads`**: Audio/podcast downloads (IAB Podcast Measurement Technical Guidelines methodology); distinct from `views`
* **`units_sold`**: Items sold attributed to delivery (retail-media commerce scalar; distinct from `conversions` — one transaction may carry multiple units; attribution-window declared via `measurement_terms`)
* **`new_to_brand_units`**: Unit-volume parallel to `new_to_brand_rate` — count of units sold to first-time brand buyers
* **`plays`**: Raw play count for DOOH/broadcast inventory (mirrors `forecastable-metric.plays`); distinct from `dooh_metrics.loop_plays` (per-screen rotation) and `impressions` (multiplied audience figure)
The numeric values inside `viewability` and `quartile_data` are individually addressable through leaf metric identities — `viewable_rate`, `viewable_impressions`, `measurable_impressions`, `viewed_seconds`, and `quartile_25`/`quartile_50`/`quartile_75`/`quartile_100` (which resolve to `quartile_data.q1_views`–`q4_views`). The structured `viewed_seconds_percentiles` and `viewed_seconds_histogram` identities similarly name their nested distribution carriers, but are not numeric aggregate rows or sort keys. Nested identities appear in `available_metrics` declarations, `committed_metrics` contracts, and metric selection; numeric leaf identities additionally support package-level `metric_values` rows and breakdown `sort_by`. The nested object remains the only flat carrier in delivery reports.
Container subsumption applies only to numeric leaves: `viewability` covers its four numeric leaf identities, and `quartile_data` covers its four quartile identities. Optional structured distributions are additive capabilities and MUST be declared explicitly. A product or format that declares only `viewability` does not satisfy `viewed_seconds_percentiles` or `viewed_seconds_histogram`; a format intersection includes a structured distribution only when both sides declare it (unless `reported_metrics` is omitted and the format defers to the product). When a distribution has no `standard`, its standard is unspecified and buyers MUST NOT combine it with any other row, including another row whose standard is unspecified. Note that `quartile_100` counts 100%-of-duration completions (VAST `complete`), which is distinct from `completed_views` when the buy defines a shorter billable view threshold.
Buyers can optionally request a subset via `requested_metrics` to reduce payload size and focus on relevant KPIs. The same field exists on the [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery#requesting-a-metric-subset) request with identical narrowing semantics, giving the GET path the same control the webhook already has.
For `completion_rate` and `quartile_data`, sellers MAY return `null` to signal the metric does not apply (e.g. on a non-video buy), and clients MUST accept `null` as a valid value for these two fields. Every other metric signals "not applicable" by omission — sellers omit it rather than sending `null`.
#### Vendor-Defined Metrics
The standard `available_metrics` enum is the closed protocol vocabulary. Vendor-defined metrics — proprietary attention scores, emissions per impression, panel-based demographics, brand-lift surveys, in-flight attention panels, custom viewability variants — live in a parallel structured surface:
* **Declaration** (`reporting_capabilities.vendor_metrics`): each entry is a pointer (`{ vendor: BrandRef, metric_id }`) into the vendor's metric catalog. Sellers say "I support this vendor's metric"; everything else (category, methodology, standard alignment, human-readable documentation) lives at the vendor. Identifiers are namespaced by the vendor — the same `metric_id` may mean different things in different vendors' vocabularies. The one thing the vendor catalog cannot tell a buyer is the seller's relationship to the vendor, so the declaration carries it: `vendor_relationship` is `first_party` (the seller or its own measurement agent produced the number), `affiliated` (a distinct legal entity under common ownership or control with the seller), or `third_party` (independent vendor). It is **required** whenever the vendor resolves to the seller's own `brand.json` or to an entity under common ownership or control with the seller — self-measurement is permitted only when disclosed — and recommended otherwise. Absence means *undeclared*, never `third_party`; buyers MAY exclude undeclared rows from reconciliation. `affiliated` is defined on structural facts only (parent/subsidiary, controlling stake, joint venture, board overlap), not on commercial dependency. This is a relationship disposition, not a trust ranking: a third-party vendor on a seller-paid, terminable contract is not automatically more independent than an attested first-party measurement, and the quality question belongs to the catalog's `accreditations[]` and `standard_reference`. Not to be confused with `measurement_source` on delivery and forecast rows, which names the audience-measurement provider behind a measured-channel row.
* **Discovery anchor**: the vendor's `brand.json` `agents[type='measurement']` is the canonical place to find the measurement agent's URL, capability profile, the methodology, the standards each metric implements, and per-metric documentation. AdCP does not duplicate that metadata on every seller's per-product extension; buyers resolve it once per vendor (cacheable) when they need it.
* **Filter** (`get_products` `filters.required_vendor_metrics`): each entry pins `vendor` and/or `metric_id` — at least one. Cross-vendor queries (e.g., "any attention measurement from a vendor that supports it") are the buyer agent's responsibility: the agent resolves which vendors offer a category via their `brand.json` records, then enumerates them as filter entries. Same filter-not-fail convention as the other `required_*` filters.
* **Reporting** (`vendor_metric_values` on each `by_package` delivery row): each value carries `{ vendor, metric_id, value, unit?, measurable_impressions?, measurable_plays?, measurable_play_seconds?, vendor_relationship?, qualifier?, breakdown? }`. `measurable_impressions` is the coverage denominator — vendor measurement is rarely 100% of delivered impressions. When the field is present, buyers compute coverage as `measurable_impressions / impressions`; when absent, coverage is unspecified (do not compute a rate or assume full coverage). Channels whose atomic observation unit is a play or screen-second rather than an impression (DOOH, cinema, place-based) report `measurable_plays` (coverage = `measurable_plays / plays`) or `measurable_play_seconds` (coverage = `measurable_play_seconds / dooh_metrics.screen_time_seconds` on screen networks, or against the seller's reported playout seconds on place-based audio) instead — there `impressions` is itself a modelled figure, so dividing a measured count by it has no interpretation. A row SHOULD carry exactly one denominator. `vendor_relationship` MAY echo the product declaration so the row is self-describing without a discovery hop; when present it MUST equal the declared value. It is deliberately not a `qualifier` key — the relationship is constant across every row for a (seller, vendor) pair and does not partition rows. The `breakdown` slot is the place vendors put structured payloads beyond a single scalar (panel demographics, co-view ratios, incremental decompositions); it is the only escape hatch — the rest of the value envelope is closed.
* **Seller as its own vendor**: the `vendor` BrandRef MAY resolve to the selling party's own `brand.json`. Sensor-instrumented DOOH, in-store retail media, cinema audience counting, and walled gardens all have the seller owning the instrument, and that is often what makes the number good — no panel can see who is standing in front of a bus shelter. The protocol supports this topology without new machinery (see [Closed-loop topologies](/dist/docs/3.2.8/measurement/taxonomy#closed-loop-topologies-seller-as-measurement-agent)), on two conditions: the seller publishes the metric in an `agents[type='measurement']` catalog with `description`, `unit`, `methodology_url`, and `methodology_version` like any other vendor, and it declares `vendor_relationship: "first_party"` on the `vendor_metrics[]` entry. First-party measurement is a disclosure, not an exemption from the catalog contract. Buyers wanting independent corroboration look to the catalog's `accreditations[]` and `standard_reference`, not to prose on the row.
* **Promotion path**: when the industry converges on a metric via a published standard, the spec adds it to the closed `available_metrics` enum and the vendor extensions become historical aliases. Promotion is anchored on standards-body publication, not on ad-hoc vendor convergence counts.
* **Accountability scope**: when the seller stamps a vendor metric in `package.committed_metrics` (with `scope: "vendor"`), it is subject to the same `missing_metrics` contract on `get_media_buy_delivery` as standard metrics. Sellers who can't credibly attest to a vendor metric SHOULD NOT stamp it in `committed_metrics`; absence keeps the metric advisory and reconciliation falls back to `vendor_metric_values.measurable_impressions` coverage plus out-of-band verification via the vendor's measurement agent. The advisory-vs-accountable distinction is now explicit at the contract layer rather than asymmetric across metric scopes.
#### Publisher Commitment
When a reporting webhook is configured, publishers commit to sending:
**(campaign_duration / reporting_frequency) + 1** notifications
* One notification per frequency period during the campaign
* One final notification when the campaign completes
* If reporting data is delayed beyond the expected delay window, a `"delayed"` notification will be sent
#### Webhook Payload
Reporting webhooks send a full MCP webhook envelope. The delivery report itself uses the same payload structure as [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) with additional metadata, but it is nested under `result`. Do not send the inner delivery object as the top-level POST body.
```json theme={null}
{
"idempotency_key": "whk_20240205_example_000005",
"operation_id": "delivery_report_mb001_2024_02_05",
"task_id": "delivery_report_mb001_2024_02_05_000005",
"task_type": "media_buy_delivery",
"status": "completed",
"timestamp": "2024-02-06T08:00:00Z",
"message": "Scheduled media buy delivery report available",
"result": {
"notification_type": "scheduled",
"sequence_number": 5,
"next_expected_at": "2024-02-06T08:00:00Z",
"reporting_period": {
"start": "2024-02-05T00:00:00Z",
"end": "2024-02-06T00:00:00Z"
},
"currency": "USD",
"media_buy_deliveries": [
{
"media_buy_id": "mb_001",
"currency": "USD",
"status": "active",
"totals": {
"impressions": 125000,
"spend": 5625.0,
"clicks": 250,
"ctr": 0.002
},
"by_package": []
}
]
}
}
```
The inner `result` object can be shown or stored separately, but this shape is not valid as the top-level webhook POST body:
```json theme={null}
{
"notification_type": "scheduled",
"sequence_number": 5,
"reporting_period": {
"start": "2024-02-05T00:00:00Z",
"end": "2024-02-06T00:00:00Z"
},
"currency": "USD",
"media_buy_deliveries": [
{
"media_buy_id": "mb_001",
"currency": "USD",
"status": "active",
"totals": {
"impressions": 125000,
"spend": 5625.0
},
"by_package": []
}
]
}
```
**Fields:**
* **`idempotency_key`**: Unique per webhook event and stable across retries of that same event. Receivers dedupe by this field.
* **Top-level `status`**: Async webhook status, such as `"completed"` for a delivered report.
* **`notification_type`**: `"scheduled"` (regular update), `"final"` (campaign complete), `"delayed"` (data not yet available), `"adjusted"` (corrected data for the same window), or `"window_update"` (a wider measurement window supersedes an earlier one)
* **`sequence_number`**: Sequential notification number (starts at 1)
* **`next_expected_at`**: ISO 8601 timestamp for next notification (omitted for final notifications)
* **`currency`**: Deprecated response-wide compatibility field. It is not an aggregation currency and does not imply conversion.
* **`media_buy_deliveries[].currency`**: ISO 4217 denomination for that media-buy row's monetary values. Sellers SHOULD populate it whenever the row has one currency. Legacy or external mixed-currency buys omit row currency and monetary row totals, then report monetary values at package grain.
* **`media_buy_deliveries[].status`**: Media buy lifecycle or reporting status, distinct from the top-level async webhook status.
* **`media_buy_deliveries`**: Array of media buy delivery data (may contain multiple media buys aggregated by publisher)
Webhook signatures and content digests are computed over the exact raw bytes of the full envelope being sent, not over a reserialized `result` object.
#### Timezone Handling
Each product declares its reporting timezone in `reporting_capabilities.timezone`, as `UTC` or an IANA identifier. It may differ from `Account.timezone`. Delivery reporting uses this timezone for calendar periods:
* `get_media_buy_delivery` `start_date`/`end_date` and `daily_breakdown[].date` are calendar dates in the reporting timezone.
* `reporting_period.start`/`end` are RFC 3339 instants on reporting-timezone boundaries. They fall on UTC midnight only when the reporting timezone is `UTC`.
* Daily, weekly, monthly, and quarterly periods follow reporting-timezone calendar days, so a day can be 23 or 25 hours long across a DST change. Weekly periods start Monday 00:00 in the reporting timezone (ISO 8601 weeks). Quarterly periods are calendar quarters starting 1 January, 1 April, 1 July and 1 October. Hourly periods are always one hour.
* Sellers SHOULD echo the applied timezone in `reporting_period.timezone`.
```json theme={null}
{
"reporting_capabilities": {
"timezone": "America/New_York",
"available_reporting_frequencies": ["daily"],
"date_range_support": "date_range"
}
}
```
**Example `get_media_buy_delivery` period** for `start_date: "2024-02-05"`, `end_date: "2024-02-06"` in `America/New_York`:
```json theme={null}
{
"reporting_period": {
"start": "2024-02-05T00:00:00-05:00",
"end": "2024-02-06T00:00:00-05:00",
"timezone": "America/New_York"
}
}
```
#### Delayed Reporting
If reporting data is not available within the product's `expected_delay_minutes`, publishers send a notification with `notification_type: "delayed"`:
```json theme={null}
{
"notification_type": "delayed",
"sequence_number": 3,
"next_expected_at": "2024-02-06T10:00:00Z",
"message": "Reporting data delayed due to upstream processing. Expected availability in 2 hours."
}
```
This prevents buyers from incorrectly assuming a missed notification.
#### Measurement Maturation Windows
For channels where billing-grade data is produced in **phases** rather than arriving final on day one, sellers declare `measurement_windows` on their products. Each window describes a maturation stage with its own expected availability. This pattern is used across channels:
| Channel | Typical windows |
| - | - |
| Broadcast / linear TV | `live` (same day) → `c3` (\~4 days) → `c7` (\~15–22 days, guarantee basis) |
| DOOH | `tentative` (same day) → `final` post-IVT/fraud-check (\~1 day, guarantee basis) |
| Digital with IVT filtering | raw → `post_givt` → `post_sivt` (\~2–3 days, guarantee basis) |
| Podcast | `downloads_7d` → `downloads_30d` (guarantee basis) |
Each window's numbers supersede the previous one. One window is typically the `is_guarantee_basis` — the number both sides reconcile against. The measurement vendor's processing time is captured in `expected_availability_days` on each window (it includes both accumulation and processing).
For broadcast, delayed or sparse early-window data is usually a measurement-vendor settlement issue, not a seller-side metadata problem. Nielsen, Comscore, VideoAmp, or another named vendor may publish Live, C3, C7, Live+5, or market-level results in waves. During that period, sellers should label delivery as provisional or awaiting measurement-vendor finalization, preserve the `measurement_window`, and use `is_final`, `finalized_at`, `supersedes_window`, and delayed/window-update notifications to show what changed. Buyers should not fork creative records or product metadata to represent partial affiliate or station visibility; aggregate the seller's delivery rows by market, placement, daypart, creative, and measurement window instead.
Sellers set `expected_delay_minutes` on their products to reflect the first-available data pipeline. The `measurement_windows` array on `reporting_capabilities` provides per-window timelines.
Delivery data for products with measurement windows includes three fields on each package:
* **`is_final`** — `true` when the seller considers this data closed for the reporting period. `false` when the data will be updated (wider window, more processing). Absent when the seller doesn't distinguish provisional from final.
* **`measurement_window`** — which window this data represents (e.g., `"c3"`). References a `window_id` from the product's `measurement_windows`. Absent for standard digital reporting without windowed maturation.
* **`supersedes_window`** — which previous window this report replaces (e.g., `"live"` when C3 data arrives). Absent on the first report for a period.
When the seller sends updated data for the same period with a wider window, they use `notification_type: "window_update"`. This is distinct from `adjusted` (a correction within the same window).
**Measurement window lifecycle example** — a broadcast spot airing March 1:
**March 2** — Live data arrives (notification_type: `scheduled`):
```json theme={null}
{
"notification_type": "scheduled",
"media_buy_deliveries": [{
"media_buy_id": "mb_nova_q4",
"currency": "USD",
"by_package": [{
"package_id": "primetime_30s",
"impressions": 980000,
"spend": 24500,
"is_final": false,
"measurement_window": "live"
}]
}]
}
```
**March 5** — C3 data supersedes live (notification_type: `window_update`):
```json theme={null}
{
"notification_type": "window_update",
"media_buy_deliveries": [{
"media_buy_id": "mb_nova_q4",
"currency": "USD",
"by_package": [{
"package_id": "primetime_30s",
"impressions": 1050000,
"spend": 26250,
"is_final": false,
"measurement_window": "c3",
"supersedes_window": "live"
}]
}]
}
```
**March 16** — C7 data arrives, final for this period (notification_type: `window_update`):
```json theme={null}
{
"notification_type": "window_update",
"media_buy_deliveries": [{
"media_buy_id": "mb_nova_q4",
"currency": "USD",
"by_package": [{
"package_id": "primetime_30s",
"impressions": 1120000,
"spend": 28000,
"is_final": true,
"measurement_window": "c7",
"supersedes_window": "c3"
}]
}]
}
```
The buyer replaces stored data each time a `window_update` arrives. When `is_final: true`, this is the number to reconcile against the guarantee. The same lifecycle shape applies to DOOH (`tentative` → `final`), digital with IVT filtering (`post_givt` → `post_sivt`), podcast (`downloads_7d` → `downloads_30d`), and any other channel where data matures in phases — only the window IDs and timing differ.
For how `measurement_window` appears on billing terms and drives reconciliation and invoicing clocks, see [Accountability](/dist/docs/3.2.8/media-buy/advanced-topics/accountability).
#### Webhook Aggregation
Publishers SHOULD aggregate webhooks to reduce call volume when multiple media buys share:
* Same webhook URL
* Same reporting frequency
* Same reporting period
**Example**: Buyer has 100 active campaigns with daily reporting to the same endpoint. Publisher sends:
* **Without aggregation**: 100 webhooks per day (inefficient)
* **With aggregation**: 1 webhook per day containing all 100 campaigns (optimal)
The `media_buy_deliveries` array may contain 1 to N media buys per webhook. Buyers should iterate through the array to process each campaign's data.
**Aggregated webhook example:**
```json theme={null}
{
"notification_type": "scheduled",
"reporting_period": {
"start": "2024-02-05T00:00:00Z",
"end": "2024-02-06T00:00:00Z"
},
"media_buy_deliveries": [{
"media_buy_id": "mb_external_001",
"status": "active",
"totals": { "impressions": 98500 },
"by_package": [
{
"package_id": "pkg_us",
"impressions": 50000,
"spend": 1750,
"pricing_model": "cpm",
"rate": 35,
"currency": "USD"
},
{
"package_id": "pkg_eu",
"impressions": 48500,
"spend": 1695,
"pricing_model": "cpm",
"rate": 34.95,
"currency": "EUR"
}
]
}]
}
```
This legacy/external mixed-currency example intentionally omits response-wide and row-level `currency`, row-level monetary totals, and `daily_breakdown`; no single code could denominate both packages. Window totals follow the same rule. Buyers process package monetary values independently. The response-wide `currency` and cross-buy `aggregated_totals` are deprecated in 3.2 and removed in 4.0. Buyers calculate an aggregate only after verifying compatible currencies, qualifiers, measurement windows, finality, and deduplication semantics; AdCP does not perform currency conversion.
#### Partial Failure Handling
When aggregating multiple media buys into a single webhook, publishers must handle cases where some campaigns have data available while others don't.
**Approach: Best-Effort Delivery with Status Indicators**
Publishers SHOULD send aggregated webhooks containing all available data, using status fields to indicate partial availability:
```json theme={null}
{
"notification_type": "scheduled",
"sequence_number": 5,
"reporting_period": {
"start": "2024-02-05T00:00:00Z",
"end": "2024-02-06T00:00:00Z"
},
"currency": "USD",
"media_buy_deliveries": [
{
"media_buy_id": "mb_001",
"currency": "USD",
"status": "active",
"totals": {
"impressions": 50000,
"spend": 1750
},
"by_package": []
},
{
"media_buy_id": "mb_002",
"currency": "USD",
"status": "active",
"totals": {
"impressions": 48500,
"spend": 1695
},
"by_package": []
},
{
"media_buy_id": "mb_003",
"status": "reporting_delayed",
"totals": {},
"by_package": [],
"message": "Reporting data temporarily unavailable for this campaign",
"expected_availability": "2024-02-06T02:00:00Z"
}
],
"partial_data": true,
"unavailable_count": 1
}
```
**Key Fields for Partial Failures:**
* `partial_data`: Boolean indicating if any campaigns are missing data
* `unavailable_count`: Number of campaigns with delayed/missing data
* `status`: Per-campaign status (`"active"`, `"reporting_delayed"`, `"failed"`)
* `expected_availability`: When delayed data is expected (if known)
**When to Use Partial Delivery:**
1. **Upstream delays**: Some data sources are slower than others
2. **System degradation**: Partial system outage affects subset of campaigns
3. **Data quality issues**: Specific campaigns fail validation, others proceed
4. **Rate limiting**: API limits prevent fetching all campaign data
**When NOT to Use Partial Delivery:**
1. **Complete system outage**: Send `"delayed"` notification instead
2. **All campaigns affected**: Use `notification_type: "delayed"`
3. **Buyer endpoint issues**: Circuit breaker handles this (don't send at all)
**Buyer Processing Logic:**
```javascript theme={null}
function processAggregatedWebhook(webhook) {
if (webhook.partial_data) {
console.warn(`Partial data: ${webhook.unavailable_count} campaigns delayed`);
}
for (const delivery of webhook.media_buy_deliveries) {
if (delivery.status === 'reporting_delayed') {
// Mark campaign as pending, retry via polling or wait for next webhook
markCampaignPending(delivery.media_buy_id, delivery.expected_availability);
} else if (delivery.status === 'active') {
// Process normal delivery data
processCampaignMetrics(delivery);
} else {
console.error(`Unexpected status for ${delivery.media_buy_id}: ${delivery.status}`);
}
}
}
```
**Best Practices:**
* Always include all campaigns in array, even if data unavailable (with status indicator)
* Set `partial_data: true` flag when any campaigns are delayed/failed
* Provide `expected_availability` timestamp if known
* Don't retry the entire webhook - buyers can poll individual campaigns if needed
* Track partial delivery rates in monitoring to detect systemic issues
#### Privacy and Compliance
##### PII Scrubbing for GDPR/CCPA
Publishers MUST scrub personally identifiable information (PII) from all webhook payloads to ensure GDPR and CCPA compliance. Reporting webhooks should contain only aggregated, anonymized metrics.
**What to Scrub:**
* User IDs, device IDs, IP addresses
* Email addresses, phone numbers
* Precise geolocation data (latitude/longitude)
* Cookie IDs, advertising IDs (unless aggregated)
* Any custom dimensions containing PII
**What to Keep:**
* Aggregated metrics (impressions, spend, clicks, etc.)
* Coarse geography (city, state, country - not street address)
* Device type categories (mobile, desktop, tablet)
* Browser/OS categories
* Time-based aggregations
**Example - Before PII Scrubbing (❌ DO NOT SEND):**
```json theme={null}
{
"media_buy_id": "mb_001",
"user_events": [
{
"user_id": "user_12345",
"ip_address": "192.168.1.100",
"device_id": "abc-def-ghi",
"impressions": 1,
"lat": 40.7128,
"lon": -74.0060
}
]
}
```
**Example - After PII Scrubbing (✅ CORRECT):**
```json theme={null}
{
"media_buy_id": "mb_001",
"totals": {
"impressions": 125000,
"spend": 5625.00,
"clicks": 250
},
"by_package": [
{
"package_id": "pkg_001",
"impressions": 125000,
"spend": 5625.00,
"by_geo": [
{
"geo_level": "region",
"geo_code": "US-NY",
"geo_name": "New York",
"impressions": 45000,
"spend": 2025.00
}
],
"by_geo_truncated": false
}
]
}
```
**Publisher Responsibilities:**
* Implement PII scrubbing at the data collection layer, not at webhook delivery
* Ensure aggregation thresholds prevent re-identification (e.g., minimum 10 users per segment)
* Document what data is collected vs. what is shared in webhooks
* Provide data processing agreements (DPAs) for GDPR compliance
* Support GDPR/CCPA data deletion requests
**Buyer Responsibilities:**
* Do not request PII in `requested_metrics` or custom dimensions
* Understand that webhook data is aggregated and anonymized
* Implement proper data retention policies
* Include webhook data in privacy policies and user disclosures
#### Implementation Best Practices
1. **Handle Arrays**: Always process `media_buy_deliveries` as an array, even if it contains one element
2. **Idempotent Handlers**: Process duplicate notifications safely (webhooks use at-least-once delivery)
3. **Sequence Tracking**: Use `sequence_number` to detect missing or out-of-order notifications
4. **Fallback Polling**: Continue periodic polling as backup if webhooks fail
5. **Timezone Awareness**: Store publisher's reporting timezone for accurate period calculation
6. **Validate Frequency**: Ensure requested frequency is in product's `available_reporting_frequencies`
7. **Validate Metrics**: Ensure requested metrics are in product's `available_metrics`
8. **PII Compliance**: Never include user-level data in webhook payloads
#### Webhook Health Monitoring
Webhook delivery status is tracked through **AdCP's global task management system** (see [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle)).
When a media buy is created with `reporting_webhook` configured, the publisher creates an ongoing task for webhook delivery. Buyers can monitor webhook health using standard task queries.
**Benefits of using task management:**
* Consistent status tracking across all AdCP operations
* Standard polling/webhook notification patterns
* Existing infrastructure for task status, history, and errors
* No need for media-buy-specific webhook health endpoints
If webhook delivery fails persistently (circuit breaker opens), publishers update the task status to indicate the issue. Buyers detect this through normal task monitoring.
### Offline-File-Delivery-Based Reporting
**Example: Offline Delivery**
Publisher pushes daily report files to buyer's cloud storage:
```
s3://buyer-reports/publisher_name/2024/02/05/media_buy_delivery.json.gz
```
File contains same structure as webhook payload but aggregated across all campaigns. Buyer processes files on their schedule.
**When to Use Offline Delivery:**
* \>100 active campaigns with same buyer
* Hourly reporting requirements (24x cost reduction)
* High data volume (detailed breakdowns, dimensional data)
* Buyer has batch processing infrastructure
Sellers declare their supported push-based delivery methods and protocols in `get_adcp_capabilities`. Polling via `get_media_buy_delivery` is always available — it is a required task for all `media_buy` sellers.
```json theme={null}
{
"media_buy": {
"reporting_delivery_methods": ["webhook", "offline"],
"offline_delivery_protocols": ["s3", "gcs"]
}
}
```
Buyers express a protocol preference when syncing accounts. The seller provisions the bucket using the preferred protocol if supported:
```json theme={null}
{
"accounts": [{
"brand": { "domain": "nova-brands.com" },
"operator": "pinnacle-media.com",
"billing": "operator",
"preferred_reporting_protocol": "s3"
}]
}
```
Products declare supported cadence and metrics in `reporting_capabilities`:
```json theme={null}
{
"reporting_capabilities": {
"available_reporting_frequencies": ["daily"],
"supports_webhooks": true,
"available_metrics": ["impressions", "spend", "clicks"],
"date_range_support": "date_range"
}
}
```
For offline delivery, the seller provisions storage per account and grants the buyer read access out-of-band. Sellers may use a dedicated bucket per account or a shared bucket with per-account `prefix` isolation — either way, the buyer can only access data under their account's path. When multiple buying platforms operate on the same brand, each gets a separate account (scoped by operator/agent), so their data is isolated by prefix.
The bucket location appears on the account object returned by `sync_accounts`:
```json theme={null}
{
"account_id": "acc_pinnacle_001",
"status": "active",
"reporting_bucket": {
"protocol": "s3",
"bucket": "seller-reports",
"prefix": "accounts/pinnacle/adcp",
"region": "us-east-1",
"format": "jsonl",
"compression": "gzip",
"file_retention_days": 30,
"setup_instructions": "https://seller.example.com/docs/bucket-access"
}
}
```
Buyers read from the bucket on their own schedule. The seller pushes files at the product's reporting frequency.
**Delivery method determines the reporting path:**
* `get_media_buy_delivery` is a required task for all `media_buy` sellers. Polling is always available as a baseline, regardless of which push methods the seller supports.
* When `reporting_delivery_methods` includes `offline` and a `reporting_bucket` is present on the account, the seller also pushes detailed delivery data to the bucket. Buyers with batch infrastructure should read from the bucket for efficiency.
* Files in the bucket are retained for `file_retention_days` (declared on the `reporting_bucket`). Buyers must read files within this window.
* `get_media_buys` always returns the media buy object with status, totals, and pacing snapshots. Use it for status checks, not detailed reporting.
For offline file delivery, publishers can provide reporting data in JSON Lines (JSONL), CSV, Parquet, Avro, or ORC format. All formats preserve the nested JSON structure from webhook payloads, making them ideal for batch processing.
JSONL and CSV files can be compressed with gzip (`.jsonl.gz`, `.csv.gz`) to reduce storage and transfer costs. Parquet, Avro, and ORC use internal compression — the top-level `compression` field is ignored for these formats.
#### JSON Lines (JSONL)
One media buy delivery per line (newline-delimited JSON). Each line contains a single media buy delivery object with its reporting period and package-level data. Preserves full nested structure. Easy to parse line-by-line for streaming processing.
**Example JSONL file:**
```jsonl theme={null}
{"notification_type": "scheduled", "sequence_number": 5, "next_expected_at": "2024-02-06T08:00:00Z", "reporting_period": {"start": "2024-02-05T00:00:00Z", "end": "2024-02-06T00:00:00Z"}, "currency": "USD", "media_buy_id": "mb_001", "status": "active", "totals": {"impressions": 50000, "spend": 1750.00, "clicks": 100, "ctr": 0.002}, "by_package": [{"package_id": "pkg_001", "impressions": 30000, "spend": 1050.00, "pacing_index": 0.95, "pricing_model": "cpm", "rate": 0.035, "currency": "USD"}, {"package_id": "pkg_002", "impressions": 20000, "spend": 700.00, "pacing_index": 0.98, "pricing_model": "cpm", "rate": 0.035, "currency": "USD"}]}
{"notification_type": "scheduled", "sequence_number": 5, "next_expected_at": "2024-02-06T08:00:00Z", "reporting_period": {"start": "2024-02-05T00:00:00Z", "end": "2024-02-06T00:00:00Z"}, "currency": "USD", "media_buy_id": "mb_002", "status": "active", "totals": {"impressions": 200000, "spend": 9000.00, "clicks": 400, "ctr": 0.002}, "by_package": [{"package_id": "pkg_003", "impressions": 200000, "spend": 9000.00, "pacing_index": 1.02, "pricing_model": "cpm", "rate": 45.00, "currency": "USD"}]}
{"notification_type": "scheduled", "sequence_number": 5, "next_expected_at": "2024-02-06T08:00:00Z", "reporting_period": {"start": "2024-02-05T00:00:00Z", "end": "2024-02-06T00:00:00Z"}, "currency": "USD", "media_buy_id": "mb_003", "status": "active", "totals": {"impressions": 75000, "spend": 3375.00, "clicks": 150, "ctr": 0.002}, "by_package": [{"package_id": "pkg_004", "impressions": 75000, "spend": 3375.00, "pacing_index": 0.96, "pricing_model": "cpcv", "rate": 0.045, "currency": "USD"}]}
```
#### CSV
**For tabular analysis**
CSV files require unnesting nested arrays. Each record should be unnested to the `by_package` level, meaning one row per package with parent-level data (reporting period, media buy info, totals) duplicated.
**Example CSV structure:**
```csv theme={null}
notification_type,sequence_number,next_expected_at,reporting_period_start,reporting_period_end,currency,media_buy_id,status,totals_impressions,totals_spend,totals_clicks,totals_ctr,by_package_package_id,by_package_impressions,by_package_spend,by_package_clicks,by_package_pacing_index,by_package_pricing_model,by_package_rate,by_package_currency
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-06T00:00:00Z,USD,mb_001,active,50000,1750.00,100,0.002,pkg_001,30000,1050.00,60,0.95,cpm,0.035,USD
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-06T00:00:00Z,USD,mb_001,active,50000,1750.00,100,0.002,pkg_002,20000,700.00,40,0.98,cpm,0.035,USD
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-06T00:00:00Z,USD,mb_002,active,200000,9000.00,400,0.002,pkg_003,200000,9000.00,400,1.02,cpm,45.00,USD
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-06T00:00:00Z,USD,mb_003,active,75000,3375.00,150,0.002,pkg_004,75000,3375.00,150,0.96,cpcv,0.045,USD
```
#### Parquet
**For high-volume analytics**
Columnar format optimized for analytics workloads. Excellent compression ratios. Supports nested structures natively. Best for data warehouses and big data processing.
**Example Parquet schema:**
```json theme={null}
{
"type": "record",
"name": "MediaBuyDelivery",
"fields": [
{"name": "notification_type", "type": "string"},
{"name": "sequence_number", "type": "int"},
{"name": "next_expected_at", "type": "string"},
{"name": "reporting_period", "type": {
"type": "record",
"name": "ReportingPeriod",
"fields": [
{"name": "start", "type": "string"},
{"name": "end", "type": "string"}
]
}},
{"name": "currency", "type": "string"},
{"name": "media_buy_id", "type": "string"},
{"name": "status", "type": "string"},
{"name": "totals", "type": {
"type": "record",
"name": "Totals",
"fields": [
{"name": "impressions", "type": "long"},
{"name": "spend", "type": "double"},
{"name": "clicks", "type": "long"},
{"name": "ctr", "type": "double"}
]
}},
{"name": "by_package", "type": {
"type": "array",
"items": {
"type": "record",
"name": "PackageDelivery",
"fields": [
{"name": "package_id", "type": "string"},
{"name": "impressions", "type": "long"},
{"name": "spend", "type": "double"},
{"name": "pacing_index", "type": "double"},
{"name": "pricing_model", "type": "string"},
{"name": "rate", "type": "double"},
{"name": "currency", "type": "string"}
]
}
}}
]
}
```
#### Avro
**For schema-rich streaming pipelines**
Row-oriented format with embedded schema. Self-describing — readers don't need external schema files. Handles schema evolution (adding/removing fields) gracefully. Common in Kafka and Hadoop ecosystems. Uses internal compression (snappy, deflate, or zstd).
**Example Avro schema:**
```json theme={null}
{
"type": "record",
"name": "MediaBuyDelivery",
"namespace": "org.example.reporting",
"fields": [
{"name": "notification_type", "type": "string"},
{"name": "sequence_number", "type": "int"},
{"name": "next_expected_at", "type": "string"},
{"name": "reporting_period", "type": {
"type": "record",
"name": "ReportingPeriod",
"fields": [
{"name": "start", "type": "string"},
{"name": "end", "type": "string"}
]
}},
{"name": "currency", "type": "string"},
{"name": "media_buy_id", "type": "string"},
{"name": "status", "type": "string"},
{"name": "totals", "type": {
"type": "record",
"name": "Totals",
"fields": [
{"name": "impressions", "type": "long"},
{"name": "spend", "type": "double"},
{"name": "clicks", "type": "long"},
{"name": "ctr", "type": "double"}
]
}},
{"name": "by_package", "type": {
"type": "array",
"items": {
"type": "record",
"name": "PackageDelivery",
"fields": [
{"name": "package_id", "type": "string"},
{"name": "impressions", "type": "long"},
{"name": "spend", "type": "double"},
{"name": "pacing_index", "type": "double"},
{"name": "pricing_model", "type": "string"},
{"name": "rate", "type": "double"},
{"name": "currency", "type": "string"}
]
}
}}
]
}
```
#### ORC
**For Hive/Spark analytics**
Columnar format optimized for read-heavy analytics on Hadoop-ecosystem tools (Hive, Spark, Presto). Predicate pushdown, built-in indexes, and lightweight compression (snappy, zlib, or zstd) reduce I/O. Supports nested structures via struct and array types.
ORC uses the same logical schema as Parquet. Choose ORC when your data warehouse is Hive-native; choose Parquet for broader tool compatibility.
**File Structure:**
Each file contains one media buy delivery per line (JSONL), row (CSV/Parquet/ORC), or record (Avro). Files may contain:
* Multiple media buy deliveries (one per line/row)
* Multiple reporting periods for the same media buy (separate rows)
* Multiple media buys (each with its own rows)
**Processing Recommendations:**
* Process files in chronological order using file timestamps
* Handle duplicate files gracefully (idempotent processing)
* Validate file integrity using checksums if provided
* Monitor for missing files and alert on gaps
### Security considerations for offline delivery
Offline files sit at rest for `file_retention_days`, so a misconfigured IAM policy leaks historical reporting across tenants. The [general security controls](/dist/docs/3.2.8/building/by-layer/L1/security) apply; the offline-specific requirements:
* **Scope access at the IAM layer, not by obscurity.** Buyer read access MUST be scoped to `{bucket}/{prefix}/*` (S3 bucket policy condition, GCS conditional IAM binding on `resource.name.startsWith(...)`, or Azure SAS scoped to the prefix). A bucket-wide read grant is non-compliant even when the seller only writes under one prefix per account.
* **Scope listing as well as reads.** Prefix scoping MUST cover both object-level operations (`s3:GetObject`) and listing (`s3:ListBucket` with an `s3:prefix` condition). A policy that scopes `GetObject` to the prefix but leaves `ListBucket` unscoped lets a buyer enumerate other tenants' prefix names — a cross-tenant isolation failure even without read access to their objects. The same applies to GCS `storage.objects.list` and Azure `list` SAS permissions.
* **Revoke access when the account closes.** When the seller emits an `account.status` transition to `inactive`, `suspended`, or `closed`, the seller MUST stop honoring the associated credentials, and buyers SHOULD treat that status change as the trigger to remove matching IAM trust on their end. A seller IAM role left granted to a decommissioned bucket is a lateral-movement risk.
PII scrubbing requirements (see [above](#pii-scrubbing-for-gdpr-ccpa)) apply to offline files identically — scrub at the collection layer, not at delivery, because the files accumulate at rest.
`setup_instructions` is a seller-provided URL. It is operator-facing documentation, not agent-consumable content. Buyer agents MUST NOT auto-fetch the URL; they SHOULD surface it to a human operator. If an implementation chooses to fetch it (for example, to preview the target before showing it to the operator), apply [webhook URL SSRF validation](/dist/docs/3.2.8/building/by-layer/L1/security#webhook-url-validation-ssrf), and the fetched content MUST NOT be passed into an LLM context without indirect-prompt-injection guarding — seller-controlled text in this field can contain instructions to rotate credentials, change billing, or alter downstream agent behavior.
## Data Reconciliation
**The `get_media_buy_delivery` API is the authoritative source of truth for all campaign metrics.** Polling is always available as a baseline. When the seller also supports push-based delivery (webhooks or offline buckets), those methods provide timely data but `get_media_buy_delivery` remains the reconciliation path.
Reconciliation is important for **any reporting delivery method** because:
* **Webhooks**: May be missed due to network failures or circuit breaker drops
* **Offline files**: May be delayed, corrupted, or fail to process
* **Polling**: May miss data during API outages
* **Late-arriving data**: Impressions can arrive 24-48+ hours after initial reporting (all methods)
#### Reconciliation Process
Buyers SHOULD periodically reconcile delivered data against API to ensure accuracy:
**Recommended Reconciliation Schedule:**
* **Hourly delivery**: Reconcile via API daily
* **Daily delivery**: Reconcile via API weekly
* **Monthly delivery**: Reconcile via API at month end + 7 days
* **Campaign close**: Always reconcile after campaign_end + attribution_window
**Reconciliation Logic:**
```javascript theme={null}
async function reconcileWebhookData(mediaBuyId, startDate, endDate) {
// Get authoritative data from API
const apiData = await adcp.getMediaBuyDelivery({
media_buy_id: mediaBuyId,
date_range: { start: startDate, end: endDate }
});
// Compare with webhook data in local database
const webhookData = await db.getWebhookTotals(mediaBuyId, startDate, endDate);
const discrepancy = {
impressions: apiData.totals.impressions - webhookData.impressions,
spend: apiData.totals.spend - webhookData.spend,
clicks: apiData.totals.clicks - webhookData.clicks
};
// Acceptable discrepancy thresholds
const impressionVariance = Math.abs(discrepancy.impressions) / apiData.totals.impressions;
const spendVariance = Math.abs(discrepancy.spend) / apiData.totals.spend;
if (impressionVariance > 0.02 || spendVariance > 0.01) {
// Significant discrepancy (>2% impressions or >1% spend)
console.warn(`Reconciliation discrepancy for ${mediaBuyId}:`, discrepancy);
// Update local database with authoritative API data
await db.updateCampaignTotals(mediaBuyId, apiData.totals);
// Alert if discrepancy is unusually large
if (impressionVariance > 0.10 || spendVariance > 0.05) {
await alertOps(`Large reconciliation discrepancy detected`, {
media_buy_id: mediaBuyId,
webhook_totals: webhookData,
api_totals: apiData.totals,
discrepancy
});
}
}
return {
status: impressionVariance < 0.02 ? 'reconciled' : 'discrepancy_found',
api_data: apiData.totals,
webhook_data: webhookData,
discrepancy
};
}
```
**Why Discrepancies Occur:**
1. **Delivery failures**: Webhooks missed, offline files corrupted, API timeouts during polling
2. **Late-arriving data**: Impressions attributed after initial reporting (all delivery methods)
3. **Data corrections**: Publisher adjusts metrics after initial reporting
4. **Processing errors**: Buyer-side failures to process delivered data
5. **Timezone differences**: Period boundaries may differ between delivery and API query
**Source of Truth Rules:**
* **For billing**: Always use `get_media_buy_delivery` API at campaign end + attribution window
* **For real-time decisions**: Use delivered data (webhook/file/poll) for speed, reconcile later
* **For discrepancies**: API data wins, update local records accordingly
* **For audits**: API provides complete historical data, delivered data is ephemeral
**Best Practices:**
* Store webhook `sequence_number` to detect missed notifications
* Run automated reconciliation daily for active campaigns
* Alert on discrepancies >2% for impressions or >1% for spend
* Use API data for all financial reporting and invoicing
* Document reconciliation process for audit compliance
#### Late-Arriving Impressions
Ad serving data often arrives with delays due to attribution windows, offline tracking, and pipeline latency. Publishers declare `expected_delay_minutes` in `reporting_capabilities`:
* **Display/Video**: Typically 4-6 hours
* **Audio**: Typically 8-12 hours
* **CTV**: May be 24+ hours
This represents when **most** data is available, not **all** data.
#### Handling Late Arrivals
When late data arrives for a previously reported period, **resend that period** with `is_adjusted: true`:
```json theme={null}
{
"notification_type": "adjusted",
"reporting_period": {
"start": "2024-02-01T00:00:00Z",
"end": "2024-02-02T00:00:00Z"
},
"media_buy_deliveries": [{
"media_buy_id": "mb_001",
"currency": "USD",
"is_adjusted": true,
"totals": {
"impressions": 51000, // Updated total (was 50000)
"spend": 1785 // Updated spend (was 1750)
}
}]
}
```
**Buyer Processing:**
```javascript theme={null}
function processWebhook(webhook) {
for (const delivery of webhook.media_buy_deliveries) {
if (delivery.is_adjusted) {
// Replace entire period with updated totals
db.replaceCampaignPeriod(
delivery.media_buy_id,
webhook.reporting_period,
delivery.totals
);
} else {
// Normal new period data
db.insertCampaignPeriod(delivery.media_buy_id, webhook.reporting_period, delivery.totals);
}
}
}
```
**When to send adjusted periods:**
* Significant data changes (>2% impression variance or >1% spend variance)
* Final reconciliation at campaign_end + attribution_window
* Data quality corrections
With polling-only, buyers detect adjustments through reconciliation by comparing API results over time.
#### Webhook Reliability
Reporting webhooks follow AdCP's standard webhook reliability patterns:
* **At-least-once delivery**: Same notification may be delivered multiple times
* **Best-effort ordering**: Notifications may arrive out of order
* **Timeout and retry**: Limited retry attempts on delivery failure
See [Webhooks](/dist/docs/3.2.8/building/by-layer/L3/webhooks) for detailed implementation guidance.
## Optimization Strategies
### Conversion optimization
Set optimization goals on media buy packages to direct delivery toward specific outcomes — target CPC, CPV, ROAS, or CPA. Metric goals (clicks, views) work without event setup. Event goals require configured event sources and conversion data.
See [Conversion Tracking](/dist/docs/3.2.8/media-buy/conversion-tracking/) for the complete setup flow, and [Optimization Goals](/dist/docs/3.2.8/media-buy/conversion-tracking/#optimization-goals) for the `optimization_goals` array reference.
### Budget optimization
* **Reallocation** between high and low performing packages via [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy)
* **Pacing adjustments** — switch between `even`, `asap`, or `front_loaded` delivery
* **Spend efficiency** — compare cost per acquisition across packages and shift budget to the best performers
### Creative optimization
* **Performance analysis** by creative asset via [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) with by-creative breakdowns
* **A/B testing** — assign multiple creatives with weights via `creative_assignments`
* **Refresh strategies** — swap creatives via [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) for library-backed sellers, or inline `packages[].creatives` on [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) for inline-only sellers, to prevent fatigue
### Targeting refinement
* **Geographic optimization** — adjust `targeting_overlay` based on delivery data by region
* **Frequency management** — tune `frequency_cap` (suppress cooldown or max_impressions/per/window cap) based on delivery patterns
## Performance Feedback Loop
The performance feedback system enables AI-driven optimization by feeding back business outcomes to publishers. See [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) for detailed API documentation.
### Performance Index Concept
A normalized score indicating relative performance:
* `0.0` = No measurable value or impact
* `1.0` = Baseline/expected performance
* `> 1.0` = Above average (e.g., 1.45 = 45% better)
* `< 1.0` = Below average (e.g., 0.8 = 20% worse)
### Sharing Performance Data
Buyers can voluntarily share performance outcomes using the [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) task:
```json theme={null}
{
"media_buy_id": "gam_1234567890",
"measurement_period": {
"start": "2024-01-15T00:00:00Z",
"end": "2024-01-21T23:59:59Z"
},
"performance_index": 1.35,
"metric_type": "conversion_rate"
}
```
### Supported Metrics
* **overall_performance**: General campaign success
* **conversion_rate**: Post-click or post-view conversions
* **brand_lift**: Brand awareness or consideration lift
* **click_through_rate**: Engagement with creative
* **completion_rate**: Video or audio completion rates
* **viewability**: Viewable impression rate
* **brand_safety**: Brand safety compliance
* **cost_efficiency**: Cost per desired outcome
### How Publishers Use Performance Data
Publishers can leverage performance indices to:
1. **Optimize Delivery**: Shift impressions to high-performing segments
2. **Adjust Pricing**: Update CPMs based on proven value
3. **Improve Products**: Refine product definitions based on performance patterns
4. **Enhance Algorithms**: Train ML models on actual business outcomes
### Privacy and Data Sharing
* Performance feedback sharing is voluntary and controlled by the buyer
* Aggregate performance patterns may be used to improve overall platform performance
* Individual campaign details remain confidential to the buyer-publisher relationship
### Dimension breakdowns
Delivery data can be broken down across multiple dimensions within each package. Buyers request specific breakdowns via the `reporting_dimensions` parameter on `get_media_buy_delivery`. Each breakdown appears as a `by_*` array within `by_package` items, following the same composition pattern as `by_creative`.
| Dimension | Breakdown field | Required fields | Additional fields | Capability declaration |
| - | - | - | - | - |
| Geography | `by_geo` | `geo_level`, `geo_code`, `impressions`, `spend` | `system`, `country`, `geo_name` | `supports_geo_breakdown` |
| Device type | `by_device_type` | `device_type`, `impressions`, `spend` | — | `supports_device_type_breakdown` |
| Device platform | `by_device_platform` | `device_platform`, `impressions`, `spend` | — | `supports_device_platform_breakdown` |
| Creative format | `by_format` | `format_kind`, `impressions`, `spend` | Other delivery metrics | `supports_format_breakdown` |
| Audience | `by_audience` | `audience_id`, `audience_source`, `impressions`, `spend` | `audience_name` | `supports_audience_breakdown` |
| Demographic | `by_demographic` | `demographic`, `demographic_system`, `impressions`, `spend` | `age`, other delivery metrics | `supports_demographic_breakdown` |
| Placement | `by_placement` | `placement_id`, `impressions`, `spend` | `placement_identity`, `placement_name`, `publisher_domain` | `supports_placement_breakdown` |
| Property | `by_property` | `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, `property_name` | `supports_property_breakdown` |
| Collection | `by_collection` | `collection_ref`, `impressions`, `spend` | `collection_name` | `supports_collection_breakdown` |
| Installment | `by_installment` | `installment_ref`, `impressions`, `spend` | `installment_name`, `scheduled_at` | `supports_installment_breakdown` |
| Collection × property | `by_collection_property` | `collection_ref`, `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, `collection_name`, `property_name` | `supports_collection_property_breakdown` |
| Installment × property | `by_installment_property` | `installment_ref`, `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, `installment_name`, `scheduled_at`, `property_name` | `supports_installment_property_breakdown` |
| Placement × property | `by_placement_property` | `placement_id`, `placement_identity`, `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, convenience names | `supports_placement_property_breakdown` |
| Creative | `by_creative` | `creative_id`, `impressions`, `spend` | `creative_name`, `weight`, other delivery metrics | `supports_creative_breakdown` |
| Spot/as-run | `by_spot` | `spot_id`, `aired_at` | `creative_id`, `impressions`, `network`, `station`, `daypart`, other delivery metrics | `supports_spot_breakdown` |
Each breakdown entry inherits all fields from `delivery-metrics` (clicks, conversions, and other optional metrics) plus its dimension-specific fields. Every entry requires the fields shown in the required fields column. Check `reporting_capabilities` on the product to discover which dimensions are available; product-level capabilities are authoritative because different products from the same seller may support different breakdowns. `supports_geo_breakdown`, `supports_demographic_breakdown`, and `supports_spot_breakdown` are structured declarations; the other capability declarations in this table are boolean flags. Within `supports_geo_breakdown`, `country` and `region` are booleans, while `metro` is keyed by `metro-system` values and native `postal_area` is keyed by ISO 3166-1 alpha-2 country with arrays of country-local `postal-system` values. Geo rows use `system` for `geo_level: "metro"` and `"postal_area"`; native postal rows also include `country`. Deprecated country-fused postal systems remain accepted for compatibility.
Format breakdowns use the AdCP 3.1 canonical `format_kind` vocabulary and are negotiated on the GET path. Reporting webhook configuration does not negotiate or guarantee dimensional breakdowns, although webhook payloads may carry the same fields as extensions. They compare creative shapes such as `video_hosted`, `native_in_feed`, and `image`; duration, dimensions, and other format-option parameters are outside this grain. Sellers combine adopter-defined shapes into one `custom` row. When `by_format_truncated` is false, additive metrics such as impressions and spend should reconcile to package totals, subject to each metric's measurement and attribution semantics. Buyers must not expect row-level correspondence between `by_format` and `by_creative` because they are independently produced at different grains.
Demographic targeting and demographic reporting are separate product capabilities. A product may execute an exact buyer predicate while its measurement source reports only fixed buckets. For example, a social product might declare continuous targeting for ages 18–65 but the following reporting capability:
```json test=false theme={null}
{
"supports_demographic_breakdown": {
"age": {
"reporting_modes": ["enumerated_intervals"],
"intervals": [
{
"age": { "min": 25, "max": 34, "include_unknown": false },
"demographic": "25-34",
"demographic_system": "custom"
}
]
},
"demographic_systems": ["custom"],
"may_suppress_small_cells": true
}
}
```
That product can target 26–30 if its separate `demographic_targeting` declaration allows it, but it cannot report 26–30. The buyer sees the 25–34 reporting interval before purchase and MUST NOT treat that wider row as delivery against the requested target. `reporting_dimensions.demographic.age_ranges` requests exact output ranges; every range must be supported by `exact_predicates` or equal a declared interval. Omitting `age_ranges` asks for the seller's native declared breakdown.
Demographic rows pair a free-form `demographic` code with its `demographic_system`, such as `P25-54` with `nielsen`. When the capability or request identifies an age interval, the row also carries canonical `age`; that structured predicate, not a parsed label, is authoritative. `by_demographic_suppressed` discloses privacy or measurement-threshold omissions separately from `by_demographic_truncated`.
Placement identity names its authority. `placement_identity.kind: "publisher_ref"` uses `{publisher_domain, placement_id}` and resolves in the publisher's `adagents.json`; `kind: "seller_inline"` uses `{seller_agent, placement_id}`. The flat `placement_id` remains required for 3.1 consumers, and `placement_name` is convenience metadata. Legacy `by_placement` rows without `placement_identity` are valid but only package-scoped. The new `by_placement_property` row always requires `placement_identity`.
Property rows require `publisher_domain` plus an operational `identifier`; that tuple remains unambiguous even when the surface is not cataloged. `property_ref` enriches a row when it resolves to `adagents.json` and MUST use the same domain. Collection and installment reporting is publisher-scoped through `collection_ref` and `installment_ref`. Marginal arrays cannot establish correlation: `by_collection_property` proves which host property carried a collection, `by_installment_property` proves where a specific airing or programming block ran, and `by_placement_property` proves which web, app, social, or assistant property carried an aggregate placement. Catalog metadata describes eligibility or carriage, not delivery. If an intersection is truncated or suppressed, a returned row is affirmative evidence, but an absent row proves nothing. Each property-grain array discloses privacy, policy, or measurement-threshold omissions through its own `by_*_suppressed` flag; suppression and top-N truncation may both apply.
Spot rows are channel-neutral as-run records: TV sellers commonly populate `network`, radio sellers commonly populate `station`, and either may populate both. `spot_id` is stable across measurement-window updates; `aired_at` proves the airing. Sellers MUST order rows by `aired_at` ascending. An empty `reporting_dimensions.spot` request asks for the complete log for the reporting period; an optional `limit` may bound the response. `by_spot_truncated` indicates whether the log is complete.
The optional `creative_id` identifies the creative that aired, matching the package's creative asset or assignment. For library-backed sellers this is the [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) identifier; inline-only sellers use the `creative_id` supplied through `packages[].creatives`. Sellers SHOULD populate it whenever they can associate a specific airing with a creative, particularly when the package could serve more than one creative during any part of the reporting period, including a mid-period replacement. Sellers that cannot make that association MUST omit the field rather than emit a default or placeholder. Buyers MUST NOT aggregate `by_spot` rows by `creative_id` and expect the result to equal `by_creative[]` impressions for the same creative: the two dimensions are independently produced at different granularities and are subject to different metric-maturation and attribution semantics within the package `measurement_window`. `by_creative` is the authoritative creative-performance aggregate; `creative_id` on a spot row identifies which creative aired, not an independent metric roll-up source.
Spot metrics are optional because airing evidence and audience measurement mature independently. `supports_spot_breakdown.available_metrics` tells the buyer which metrics the product can eventually produce at spot grain. A Live row may contain only `{ spot_id, aired_at }`; the same `spot_id` can reappear under C3 or C7 with `impressions`. An absent `impressions` field means unavailable at that measurement window or not declared at spot grain. `impressions: 0` means a measured zero and is never interchangeable with omission; sellers do not emit `null`.
Breakdowns are opt-in — no dimension data is returned unless explicitly requested. Sellers that don't support a requested dimension silently omit it. An unsupported `demographic.age_ranges` value on a product that otherwise supports the dimension returns `UNSUPPORTED_FEATURE`; sellers never widen or narrow it silently. Each breakdown array has a sibling `by_*_truncated` boolean indicating whether additional non-suppressed rows exist beyond the requested `limit`.
## Targeting Consistency
Reporting aligns with AdCP's [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) approach, enabling:
* **Consistent analysis** across campaign lifecycle
* **Granular breakdowns** by targeting parameters
* **Cross-campaign insights** for portfolio optimization
### Target → Measure → Optimize
The power of consistent targeting and reporting creates a virtuous cycle:
1. **Target**: Define your audience using briefs and overlays (e.g., "Mobile users in major metros")
2. **Measure**: Report on the same attributes (Track performance by device type and geography)
3. **Optimize**: Feed performance back to improve delivery (Shift budget to high-performing segments)
## Standard Metrics
All platforms must support these core metrics:
* **impressions**: Number of ad views
* **spend**: Amount spent in currency
* **clicks**: Number of clicks (if applicable)
* **ctr**: Click-through rate (clicks/impressions)
Optional standard metrics:
* **conversions**: Post-click/view conversions
* **viewability**: Percentage of viewable impressions
* **completion_rate**: Video/audio completion percentage
* **engagement_rate**: Platform-specific engagement metric
## Platform-Specific Considerations
Different platforms offer varying reporting and optimization capabilities:
### Google Ad Manager
* Comprehensive dimensional reporting, real-time and historical data, advanced viewability metrics
### Kevel
* Real-time reporting API, custom metric support, flexible aggregation options
### Triton Digital
* Audio-specific metrics (completion rates, skip rates), station-level performance data, daypart analysis
## Advanced Analytics
### Cross-Campaign Analysis
* **Portfolio performance** across multiple campaigns
* **Audience overlap** and frequency management
* **Budget allocation** optimization across campaigns
### Predictive Insights
* **Performance forecasting** based on historical data
* **Optimization recommendations** from AI analysis
* **Trend prediction** for proactive adjustments
## Response Times
Optimization operations have predictable timing:
* **Delivery reports**: \~60 seconds (data aggregation)
* **Campaign updates**: Minutes to days (depending on changes)
* **Performance analysis**: \~1 second (cached metrics)
## Best Practices
1. **Report Frequently**: Regular reporting improves optimization opportunities
2. **Track Pacing**: Monitor delivery against targets to avoid under/over-delivery
3. **Analyze Patterns**: Look for performance trends across dimensions
4. **Consider Latency**: Some metrics may have attribution delays
5. **Normalize Metrics**: Use consistent baselines for performance comparison
## Integration with Media Buy Lifecycle
Optimization and reporting is the ongoing phase that runs throughout active campaigns:
* **Connects to Creation**: Use learnings to improve future campaign setup
* **Guides Updates**: Data-driven decisions for campaign modifications
* **Enables Scale**: Proven strategies can be applied to similar campaigns
* **Feeds AI**: Performance data improves automated optimization
## Related Documentation
* **[`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)** - Retrieve delivery reports
* **[`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy)** - Modify campaigns based on performance
* **[Media Buy Lifecycle](/dist/docs/3.2.8/media-buy/media-buys)** - Complete campaign management workflow
* **[Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting)** - Brief-based targeting and overlays
# Policy compliance
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/media-buys/policy-compliance
AdCP policy compliance — how publishers enforce brand safety and regulatory checks during product discovery and media buy creation. Includes policy types and violation handling.
AdCP includes comprehensive policy compliance features to ensure brand safety and regulatory compliance across all advertising operations. This document explains how publishers should implement and enforce policy checks throughout the media buying lifecycle.
## Acceptance-policy discovery
Seller acceptance policy answers a narrower question than buyer governance: **what business, campaign, creative, targeting, destination, and format will this seller accept?** It does not give the seller authority over the buyer's plan and does not expose the seller's internal review workflow.
A seller that supports structured discovery publishes `media_buy.acceptance_policy_discovery` from `get_adcp_capabilities`:
```json theme={null}
{
"catalog_url": "https://seller.example/.well-known/adcp-acceptance-policies.json",
"catalog_digest": "sha256:54f04c3e2e8dfdf682b0da0cd0ee4d5265e54a6e0f72b9260785dfc1526fd08a",
"default_profile_ids": ["seller-default", "us-political"]
}
```
The HTTPS document at `catalog_url` conforms to `acceptance-policy-catalog.json`. Each local `profiles[]` entry declares `coverage: "partial"` or `"complete"` and contains rules with a `disposition` of `allowed`, `conditional`, or `prohibited`. Conditional rules carry typed requirements such as advertiser verification, prior authorization, disclosure, targeting restrictions, or sales-assisted setup. Every `policy_ids[]` value resolves through that profile's digest- and version-pinned `policy_refs[]`. The profile's own `content_digest` covers its RFC 8785 canonical form with that field omitted, making a profile ID/version immutable. Registry-published platform policies may include a reusable `acceptance_profile`; a seller adopts it through `registry_profiles[]`, which pins both policy and profile versions and digests. For each adoption, resolve the exact policy version, RFC 8785-canonicalize the resolver's `canonical_content`, and require its SHA-256 to equal both the resolver `content_digest` and the pinned `policy_digest`; null canonical content or a mismatch fails closed. Verify `profile_digest` separately against the embedded profile. The seller MUST NOT copy and alter a registry profile under the same identity; seller-specific restrictions use a separate local profile and compose restrictively. A profile ID may occur only once across a catalog's local and registry lists. Registry publication alone never binds a seller.
Products may add `acceptance_policy_profile_ids[]`. Resolve the seller defaults and every product profile referenced by the contemplated purchase. All selected profiles apply; for matching rules, `prohibited` wins over `conditional`, which wins over `allowed`. A missing capability, an omitted rule in a partial profile, or missing buyer facts means **unknown**, never allowed. `complete` is exhaustive only for that profile's declared scope and version; the scope explicitly names countries, declared region aliases, or `all_jurisdictions: true` so omission cannot be mistaken for worldwide coverage.
A rule matches the decision surface when `applies_to[]` contains that surface and its `subject_category` equals a declared subject. Omitted `subject_facets`, `advertiser_roles`, `jurisdictions`, or `jurisdiction_groups` are wildcards; when present, each dimension must intersect the corresponding buyer fact. Expand `jurisdiction_groups` only through the containing profile's `region_aliases`; an unknown alias invalidates the profile and never matches permissively. Evaluate every matching rule independently, then choose the most restrictive disposition. Platforms with an exception to a broad prohibition represent it with non-overlapping facets or roles—for example, prohibit persuasive election facets while making `government_information` conditional for an `election_authority`. A request carrying both the exception facet and a prohibited advocacy facet remains prohibited.
Buyers may send `acceptance_context` on discovery with registry category IDs, optional category facets, advertiser roles, industry, advertiser jurisdictions, and delivery jurisdictions. `advertiser_jurisdictions` says where the advertiser is established; `delivery_jurisdictions` says where ads will run and is the field matched by rule `jurisdictions` and `jurisdiction_groups`. For example, `political_advertising` is the broad category; facets distinguish candidate or party ads, election or ballot-measure ads, issue advocacy, legislation or regulation, government information, political merchandise, and incidental or news references. This avoids a single ambiguous `political: true` flag while allowing future registry categories and facets without changing the protocol schema.
Discovery is advisory. Sellers may intentionally publish only partial rules, may apply account-specific or newly effective policies at execution time, and remain authoritative for an exact request. Buyer declarations are untrusted hints: sellers MUST classify creatives, destinations, advertiser identity, and targeting independently when those facts affect acceptance. Omitting or mislabeling a category or facet cannot bypass seller enforcement. A buyer MUST therefore handle a later structured `POLICY_VIOLATION` even when discovery appeared to allow the campaign. The catalog digest detects stale or substituted catalogs; it is not an acceptance guarantee.
Fetch `catalog_url` as untrusted remote configuration: require HTTPS, apply the shared URL canonicalization and public-network fetch protections, do not follow redirects, do not send seller or buyer credentials, pin DNS through connection, and bound time and response size. Verify the digest over the exact received bytes before parsing or caching. Resolve every `registry_profiles[]` reference from the shared registry at the exact policy and profile versions and verify both digests; a missing or mismatched reference is unknown and cannot fall back to a same-named local profile. Profile and rule descriptions are display-only untrusted text; matching uses typed fields only, and implementations MUST NOT place that prose into a privileged instruction context. Cache by canonical URL plus digest, never by URL alone. Buyers can request `acceptance_policy_profile_ids` explicitly through either discovery surface's `fields` projection.
## Overview
Policy compliance in AdCP uses the `brand` field when advertiser-specific context is available. `brand` is optional for `get_products` unless the request includes `catalog`; it is required for `create_media_buy`. Brand context enables publishers to:
* Filter inappropriate advertisers before showing inventory
* Enforce category-specific restrictions
* Maintain brand safety standards
* Comply with regulatory requirements
## Brand
Buyers should include `brand` in `get_products` when the advertiser is known so sellers can return context-rich recommendations and apply advertiser-specific policy checks. A catalog-bearing `get_products` request must include `brand`, and every `create_media_buy` request must include `brand`.
```json theme={null}
{
"brand": {
"domain": "acmecorp.com"
}
}
```
The brand domain resolves `/.well-known/brand.json`. On a single-brand domain, `brand_id` can be omitted. On a house or portfolio domain, use `brand_id` to select the intended entry. The selected entry provides:
* **Brand name and identity** for verification
* **Industries** for policy filtering
* **Brand assets** for creative compliance
Callers can supply `brand.industries` as a per-request override when the canonical entry is missing or does not describe the campaign's current industry context. When that field is absent, sellers and governance agents resolve `industries` from the selected `brand.json` entry.
Combined with the `brief` field (which describes what's being promoted), publishers have fuller context for policy decisions. When `brand` is absent from a non-catalog discovery request, a seller may apply general policy rules or limit the products it returns rather than perform advertiser-specific checks.
For comprehensive guidance on briefs and brand information, see [Brief Expectations](/dist/docs/3.2.8/media-buy/product-discovery/brief-expectations).
## Policy check implementation
Publishers must implement policy checks at two key points in the workflow:
### 1. During product discovery (`get_products`)
When a `get_products` request is received, the publisher should:
1. Require `brand` when `catalog` is present
2. When `brand` is present, validate it and resolve the selected brand entry and its `industries`
3. Apply advertiser-specific policy checks when that context is available
4. Otherwise, apply general policy rules or limit discovery
5. Filter out unsuitable products
**Example policy context resolution:**
```python theme={null}
def resolve_policy_industries(brand: dict | None) -> list[str] | None:
if brand is None:
return None
manifest = fetch_brand_json(brand["domain"])
brand_entry = select_brand_entry(manifest, brand.get("brand_id"))
if "industries" in brand:
return brand["industries"]
return brand_entry.get("industries", [])
```
If this function returns `None`, apply general discovery policy or limit the returned products. Otherwise, evaluate policy against the resolved industries and any other applicable request context.
### 2. During media buy creation (`create_media_buy`)
When creating a media buy, the publisher must first require `brand`, then:
1. Validate the `brand` against publisher policies
2. Ensure consistency with the campaign brief
3. Apply the seller's internal review policy if needed
4. Return appropriate errors for violations
## Policy outcomes
AdCP does not define a separate policy-compliance status or response field. Use the task status and error model that matches the outcome.
### Products can be returned
When policy checks pass, return the ordinary completed response. An empty `products` array means the search completed but no products matched.
```json theme={null}
{
"status": "completed",
"products": [],
"cache_scope": "public",
"message": "No products matched the request."
}
```
### More information is needed
Use `input-required` only when the buyer must supply information before the seller can continue. Include `task_id` when the operation has durable task identity; the transport or SDK must separately supply a verified continuation descriptor. A response `context_id` alone never authorizes continuation.
```json theme={null}
{
"status": "input-required",
"task_id": "task_policy_clarification_001",
"context_id": "ctx_policy_clarification_001",
"message": "Which country will this campaign target?",
"reason": "CLARIFICATION_NEEDED",
"suggestions": ["United States", "Canada"]
}
```
### Seller-side review continues asynchronously
Seller-internal review does not require buyer input or protocol-level approval orchestration. When a well-formed `brief` or `refine` request cannot finish within the current time budget, return `submitted` with a `task_id`; use `working` for subsequent progress. Those states communicate task completion only—the seller may use people, automation, or both internally. Wholesale discovery is synchronous and does not use these async states.
### The seller declines a well-formed request
When the request is valid and understood but the seller makes a business decision not to offer products, use the typed `rejected` outcome. This remains a successful transport response.
```json theme={null}
{
"status": "rejected",
"reason": "This publisher does not offer inventory for the requested campaign.",
"suggestions": ["Try a different channel or publisher."]
}
```
### The request violates a policy
When the request itself violates an applicable content or advertising policy and can be corrected, return a failed response with `POLICY_VIOLATION`. Populate `errors[]` and mirror the fatal error in `adcp_error` so clients can handle both response layers.
```json theme={null}
{
"status": "failed",
"message": "The request violates an applicable advertising policy.",
"errors": [
{
"code": "POLICY_VIOLATION",
"message": "The requested campaign is not permitted on this inventory.",
"field": "brand",
"recovery": "correctable",
"details": {
"seller_policy_ref": "restricted-industries-rule-4",
"policy_url": "https://publisher.example/policies/restricted-industries",
"violated_rules": ["restricted-industry"]
}
}
],
"adcp_error": {
"code": "POLICY_VIOLATION",
"message": "The requested campaign is not permitted on this inventory.",
"field": "brand",
"recovery": "correctable"
}
}
```
## Creative Validation
All uploaded creatives should be validated against the declared brand identity:
1. **Automated Analysis**: Use creative recognition to verify brand consistency
2. **Human Review**: Manual verification for sensitive categories
3. **Continuous Monitoring**: Ongoing checks during campaign delivery
This ensures:
* Creative content matches the declared brand
* No misleading or deceptive advertising
* Brand safety for all parties
## Common Policy Categories
Publishers typically implement restrictions for:
### Blocked Categories
* Illegal products or services
* Prohibited content (varies by region)
* Categories requiring special licensing
### Restricted Categories (Conditional Acceptance)
* Alcohol (may require age-gating)
* Gambling/Gaming
* Cryptocurrency/Financial services
* Political advertising
* Healthcare/Pharmaceuticals
* Dating services
### Special Requirements
* Political ads may require disclosure
* Healthcare may need disclaimers
* Financial services need compliance review
## Implementation Best Practices
1. **Clear Communication**: Provide specific reasons for restrictions
2. **Contact Information**: Include sales contact for restricted categories
3. **Consistent Enforcement**: Apply policies uniformly across all advertisers
4. **Documentation**: Maintain clear policy documentation for advertisers
5. **Appeals Process**: Allow advertisers to request policy exceptions
## Internal review and buyer interaction
Keep the two human-in-the-loop paths distinct:
* **Buyer clarification:** Return `input-required` only when the buyer must answer a question. Include `task_id` for durable task identity, then resume only through a verified transport or SDK continuation descriptor.
* **Seller-internal review:** Keep the review mechanism private. For `brief` or `refine`, return `submitted` when the task cannot finish within the current time budget and `working` while it remains active. Do not use `input-required` merely because a seller-side process is involved.
After review, return the canonical completed, rejected, or failed outcome.
## Related Documentation
* [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) - Product discovery with policy checks
* [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) - Media buy creation with validation
* [Accounts & Security](/dist/docs/3.2.8/media-buy/advanced-topics/accounts-and-security) - Authentication and authorization
# Brief expectations
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/product-discovery/brief-expectations
How buyers and sellers use briefs alongside offer filters, targeting overlays, future targeting requirements, and refinement.
A brief gives a seller the campaign meaning needed for curation. It is not a
second schema written in prose. Buyers preserve goals, context, semantic intent,
preferences, and requirements without a structured AdCP representation in the
brief; they put machine-representable facts in typed fields.
## When a brief is used
| Task | Brief rule | Purpose |
| - | - | - |
| `list_products` | Not accepted | Read matching product offers without seller curation |
| `request_proposals` | Required | Ask the seller to curate one or more draft plans |
| `refine_proposals` | Not repeated | Revise a proposal with structured fields, a semantic `ask`, or both; or finalize a draft without changing terms |
| `get_products` | Depends on `buying_mode` | Compatibility facade for the same list, proposal, and refinement behaviors |
For `buying_mode: "brief"`, `brief` is required.
For `buying_mode: "wholesale"`, omit `brief`.
For `buying_mode: "refine"`, omit `brief` and use the `refine` array instead.
The `brand` field is optional for `get_products` unless the request includes `catalog`. When supplied, the seller may use it to apply general policy rules or limit discovery. A `create_media_buy` request always must include `brand`.
Offer filters remain hard in every lifecycle. The task changes curation and
state behavior, not whether filters apply. The split tasks name them
`criteria.offer_filters`; legacy `get_products` names the equivalent field
`filters`.
## Decompose the buyer request
| Input | Use it for | Example |
| - | - | - |
| `brief` | Goals, semantic audience descriptions, context, soft preferences, untyped hard requirements | “Build consideration among outdoor enthusiasts in trusted adventure contexts” |
| `criteria.offer_filters` | Which offers may be returned: channel, format, commercial terms, dates, budget, reporting | `channels: ["ctv"]` |
| `criteria.targeting_overlay` | Which inventory or impressions may deliver; values known now | `geo_countries: ["US"]` |
| `criteria.required_overlay_support` | Targeting dimensions the buyer must select independently on packages later | Nielsen DMA support |
| refinement `criteria` | Structured changes to a referenced proposal | Replace the country overlay |
| refinement `ask` | Semantic changes without a structured field | Favor premium adventure contexts |
Anything that has a structured AdCP field SHOULD use it. This costs fewer
tokens, can be validated and applied by code, and avoids lossy prose extraction.
### Structured-first example
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441001",
"brand": { "domain": "acmeoutdoor.example" },
"brief": "Launch a premium trail shoe to outdoor enthusiasts. Favor trusted adventure and fitness contexts and optimize for completed video views.",
"criteria": {
"offer_filters": {
"channels": ["ctv", "olv"],
"pricing_currencies": ["USD"],
"required_metrics": ["completed_views"],
"start_date": "2027-03-01",
"end_date": "2027-03-31",
"budget_range": { "max": 50000, "currency": "USD" }
},
"targeting_overlay": {
"geo_countries": ["US"],
"demographics": {
"age": { "min": 25, "max": 44, "include_unknown": false }
}
},
"required_overlay_support": {
"geo_metros": { "systems": ["nielsen_dma"] }
}
}
}
```
The seller curates for the semantic audience and contexts, excludes offers that
fail the product filters, scopes every returned forecast and price to the US
age predicate, and returns only products that let packages select Nielsen DMA
values later. The request does not ask for one product per DMA.
## Hard requirements in prose
An explicit hard requirement remains binding even when the buyer puts it only
in the brief. A seller MUST NOT downgrade “US only” or “must exclude news” to a
preference merely because it was written in prose.
When hard targeting came from prose and the seller's structured interpretation
materially affects product eligibility, pricing, or forecasting, the seller
MUST confirm that interpretation in response-root
`targeting_resolution.brief_targeting` for `request_proposals` and
`get_products`, or in the affected `refine_proposals.results[]` entry when the
interpretation came from the refinement `ask`. In other cases the
seller SHOULD still confirm it as a best practice. Requirements without a typed
AdCP representation remain visible in the natural-language response.
`brief_targeting` is confirmation, not a counteroffer. If a product cannot
honor the seller's literal interpretation of a hard prose constraint, the
seller omits that product. Structured `modifications` apply only to a buyer's
explicit `targeting_overlay` proposal flow.
If prose contradicts a structured field, the seller MUST reject the request as
`INVALID_REQUEST` rather than silently choose one interpretation. The buyer
corrects the contradiction and retries.
## How buyers evaluate targeting resolution
| Response state | Buyer conclusion and action |
| - | - |
| Structured overlay; no `targeting_resolution` | Overlay accepted exactly |
| `targeting_resolution.modifications` | Compare the ordered proposed changes; selecting the configured product accepts them |
| Hard prose plus `brief_targeting` | Verify the seller’s structured interpretation before selection |
| Hard prose without confirmation | Do not infer acceptance; inspect the seller’s prose or clarify before purchase |
Unchanged structured overlays are not repeated. This prevents large values such
as hundreds of postal codes from bouncing through discovery responses.
## What belongs in the brief
Useful brief content includes:
* business objective and why the campaign exists;
* semantic audience meaning such as “outdoor enthusiasts” or “IT decision
makers modernizing cloud infrastructure”;
* creative and product context;
* success priorities and tradeoffs not captured by typed metrics;
* sensitive adjacency or competitive context without a typed control;
* soft preferences, clearly distinguished from hard requirements.
Do not duplicate exact dates, budget, currency, channels, formats, geography,
demographic predicates, or other values already carried in structured fields.
## Seller processing
For `request_proposals`, sellers:
1. Validate structured fields before natural-language interpretation.
2. Reject contradictions between hard prose and structured fields.
3. Apply filters, targeting, and required future-support matching.
4. Interpret the remaining brief for curation and relevance.
5. Scope product pricing and forecasts to effective targeting.
6. Return draft proposals with `brief_relevance` where useful and disclose targeting resolution.
Sellers may ask focused clarification questions when semantic intent is too
ambiguous to curate responsibly. They do not need clarification for exact
values already supplied structurally.
```mermaid theme={null}
graph TD
A[Receive discovery task] --> B[Validate structured fields]
B --> C{Contradiction?}
C -->|Yes| D[INVALID_REQUEST]
C -->|No| E[Apply filters and targeting]
E --> F{Task}
F -->|list_products| G[Return matching feed products]
F -->|request_proposals| H[Interpret semantic brief and curate]
F -->|refine_proposals| I[Resolve proposal IDs and apply refinement]
H --> J[Return configured products and resolution]
I --> J
```
## Listing and refinement
Listing is not “targeting later.” It is non-curated product-feed behavior.
Buyers may still send `offer_filters`, `targeting_overlay`, and
`required_overlay_support`; returned products must honor them exactly as in
proposal mode. The legacy `get_products` wholesale mode has the same rule.
For `action: "revise"`, refine requests are self-contained through opaque
product/proposal IDs plus structured fields, a semantic `ask`, or both.
`action: "finalize"` changes no commercial or targeting terms and cannot carry
revision fields. See [Refining products and proposals](/dist/docs/3.2.8/media-buy/product-discovery/refinement).
## Implementation checklist
### Buyers
* Preserve business language and semantic intent in `brief`.
* Extract machine-representable facts into structured fields.
* Mark hard versus preferred requirements clearly.
* Inspect every targeting resolution before selecting a product.
* Treat configured product IDs as opaque and context-bound until `expires_at`.
### Sellers
* Apply hard requirements in every request surface.
* Never infer a structured value when the buyer already supplied it.
* Never silently resolve a contradiction or unsupported constraint.
* Confirm brief-derived targeting when possible.
* Bind effective targeting, price, forecast, and terms to the returned product.
# Collections and installments
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments
AdCP collections and installments — model podcast, CTV, and streaming content as dimensions on media products. Enables collection-level targeting and installment-specific ad placement.
A [product](/dist/docs/3.2.8/media-buy/product-discovery/media-products) describes inventory along three independent axes:
* **Publisher properties** — WHERE the ad runs (youtube.com, spotify.com)
* **Collections / installments** — WHAT CONTENT the ad runs in or around (a specific series and its installments)
* **Placements** — WHAT POSITION the ad appears in (pre-roll, mid-roll, host read)
Collections and placements are parallel dimensions, not hierarchical. "Pre-roll" is a position. "Pinnacle Challenge" is content. A product combines them: "pre-roll on Pinnacle Challenge on Acme Streaming."
## Channel mapping
The collection/installment model maps to familiar concepts across media channels:
| Channel | Collection = | Installment = | Example |
| - | - | - | - |
| Podcast | Program | Episode | "Serial" → "Chapter 1" |
| Linear TV / CTV | Series | Episode / Airing | "Monday Night Football" → "Week 12" |
| Programmed audio/video channel | Channel stream | Scheduled airing / programming block | "Acme Retro" → "Tuesday 20:00 movie" |
| Print / Magazine | Publication | Issue | "Vogue Germany" → "May 2026" |
| Newsletter | Publication | Edition | "Money Stuff" → "Tuesday March 24" |
| YouTube / Social | Series | Video / Post | "Hot Ones" → "Gordon Ramsay" |
| DOOH | Network / Loop | Rotation | "Times Square Loop" → "March Rotation" |
| Influencer | Campaign | Post / Drop | "Spring Collection" → "Launch Post" |
| Cinema | Run | Screening | "Summer Blockbuster Run" → "Opening Weekend" |
| Radio | Program | Broadcast | "Morning Drive" → "March 24 Broadcast" |
The `kind` field on each collection indicates how to interpret it and its installments.
## The collection object
A collection is a persistent, publisher-controlled content program that produces installments over time. It is not a social “collection ad,” user conversation, session, prompt, turn, or inferred topic cluster. Collections work like properties — publishers declare them in their `adagents.json`, and products reference them via `collections` selectors with `publisher_domain` and `collection_ids`.
| Field | Type | Required | Description |
| - | - | - | - |
| `collection_id` | string | Yes | Publisher-assigned identifier. Declared in the publisher's `adagents.json`. Products reference collections via `collections` selectors. Use distribution identifiers for cross-seller matching. |
| `publisher_domain` | string | Conditional | Owning publisher namespace. Required when a collection is served from a cross-origin shared authoritative document; optional in a publisher-origin document. |
| `kind` | string | No | What kind of content program: `series` (TV/podcast), `publication` (print issues), `event_series` (live events), `rotation` (DOOH), `channel` (continuously programmed audio/video stream). Defaults to `series`. |
| `name` | string | Yes | Human-readable collection name |
| `description` | string | No | What the collection is about |
| `genre` | string\[] | No | Genre tags. When `genre_taxonomy` is present, values are taxonomy IDs (e.g., IAB Content Taxonomy 3.0). Otherwise free-form. |
| `genre_taxonomy` | string | No | Taxonomy system for genre values (e.g., `iab_content_3.0`). Recommended for machine-readable brand safety. |
| `language` | string | No | Primary language (BCP 47) |
| `content_rating` | object | No | Baseline rating: `system` + `rating`. Systems: `tv_parental`, `mpaa`, `podcast`, `esrb`, `bbfc`, `fsk`, `acb`, `custom`. Episodes can override. |
| `cadence` | string | No | `daily`, `weekly`, `monthly`, `seasonal`, `event`, `irregular`. Continuously programmed `channel` collections typically omit it. |
| `season` | string | No | Current or most recent season identifier (e.g., `"3"`, `"2026"`) |
| `status` | string | No | `active`, `hiatus`, `ended`, `upcoming` |
| `production_quality` | string | No | `professional`, `prosumer`, `ugc`. Seller-declared. Maps to OpenRTB `content.prodq`. |
| `talent` | array | No | Hosts, recurring cast, creators. Each entry has `role`, `name`, and optional `brand_url` linking to [brand.json](/dist/docs/3.2.8/brand-protocol/brand-json). |
| `special` | object | No | When present, this collection is a special — content anchored to a real-world event or occasion. See [specials and limited series](#specials-and-limited-series). |
| `limited_series` | object | No | When present, this collection is a limited series — a bounded run with a defined arc and end date. See [specials and limited series](#specials-and-limited-series). |
| `distribution` | array | No | Where this collection is distributed, with host `property_ids`, identifiers, or both per publisher. For `channel` collections this is the carriage map, not proof of sales authorization. |
| `deadline_policy` | object | No | Default deadline rules for installments. Agents compute absolute deadlines from `scheduled_at` minus `lead_days`. Episodes with explicit `deadlines` override. See [deadline policy](#deadline-policy). |
| `related_collections` | array | No | Relationships to other collections: `spinoff`, `companion`, `sequel`, `prequel`, `crossover`. Each entry has `collection_id` + `relationship`. References are scoped to the same publisher's `adagents.json`. Symmetric types (`companion`, `crossover`) do not require both collections to declare. |
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/collection.json",
"collection_id": "pinnacle_challenge",
"name": "The Pinnacle Challenge",
"description": "Competition reality collection with extreme physical and mental challenges",
"genre": ["IAB1", "IAB1-6"],
"genre_taxonomy": "iab_content_3.0",
"language": "en",
"content_rating": {
"system": "tv_parental",
"rating": "TV-PG"
},
"cadence": "weekly",
"season": "1",
"status": "active",
"production_quality": "professional",
"talent": [
{
"role": "host",
"name": "Jordan Vega",
"brand_url": "https://jordanvega.example.com/brand.json"
}
],
"distribution": [
{
"publisher_domain": "youtube.com",
"identifiers": [
{ "type": "youtube_channel_id", "value": "UCexample123456" }
]
},
{
"publisher_domain": "acmestreaming.example.com",
"identifiers": [
{ "type": "imdb_id", "value": "tt9876543" }
]
}
]
}
```
## Programmed channels and owner-sold carriage
FAST describes a channel's carriage and monetization model, not a distinct kind
of inventory. AdCP represents the underlying programmed audio or video stream
as a `channel` collection. The same structure applies to FAST, virtual linear,
and syndicated audio channels. This preserves three independent inventory axes:
* the host CTV app is the **property** where the ad runs;
* the programmed channel is the **collection** whose content surrounds the ad;
* pre-roll, mid-roll, or another avail is the **placement** within the product.
The channel owner declares the canonical collection in its own `adagents.json`.
Each `distribution` entry can name both the host properties carrying the
channel and identifiers used by the host or an independent metadata system:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/collection.json",
"collection_id": "retro_news",
"kind": "channel",
"name": "Acme Retro News",
"status": "active",
"distribution": [{
"publisher_domain": "hoststream.example",
"property_ids": ["hoststream_ctv"],
"identifiers": [
{ "type": "platform_channel_id", "value": "channel_942" },
{ "type": "gracenote_id", "value": "example-channel-id" }
]
}]
}
```
`platform_channel_id` is the generic fallback for a host-assigned channel
identifier. Its namespace is the enclosing `publisher_domain`; the stable
identity is therefore `(publisher_domain, value)`. Because the tuple is what
identifies the channel, this type is only meaningful inside a distribution
entry: it MUST NOT appear in bare `{type, value}` identifier lists
(`distribution_ids` sources, `exclude_distribution_ids` filters), where a
value like `1005` would silently collide across hosts. Use the platform's
stable catalog identifier, not an EPG position number — hosts renumber
lineups. Use a more specific identifier type when one exists.
A distribution entry carries `property_ids`, `identifiers`, or both.
Distributions SHOULD include `identifiers` whenever the host assigns one, and
consumers MUST NOT assume `identifiers` is present — a property-only entry is
valid, and is the shape an owner ships when the host has not yet published
identifiers to cite.
The owner's distribution declaration is a discoverability claim, not sales
authorization. For verified owner-sold carriage, the host's `adagents.json`
authorizes the owner's sales agent for the host property and narrows that grant
to the owner's canonical collection:
```json theme={null}
{
"url": "https://sales.channel-owner.example",
"authorized_for": "Owner-sold avails for Acme Retro News",
"authorization_type": "property_ids",
"property_ids": ["hoststream_ctv"],
"collections": [{
"publisher_domain": "channel-owner.example",
"collection_ids": ["retro_news"]
}],
"delegation_type": "direct"
}
```
The seller's product then combines the same host property and owner collection.
The placement may be `seller_inline`, so the host does not have to enumerate
the channel owner's avail definitions:
```json theme={null}
{
"publisher_properties": [{
"publisher_domain": "hoststream.example",
"selection_type": "by_id",
"property_ids": ["hoststream_ctv"]
}],
"collections": [{
"publisher_domain": "channel-owner.example",
"collection_ids": ["retro_news"]
}],
"placements": [{
"kind": "seller_inline",
"seller_agent": {
"agent_url": "https://sales.channel-owner.example"
},
"publisher_domain": "channel-owner.example",
"placement_id": "owner_avails",
"name": "Channel-owner avails",
"mode": "included"
}]
}
```
Buyers MUST NOT treat a seller as authorized for owner-sold carriage absent a
host `authorized_agents` entry matching the host property scope and the owner's
collection selector. Missing host authorization fails closed. Dangling
references fail closed the same way: a `distribution[].property_ids` value that
does not resolve to a property in the host's `adagents.json` MUST be treated as
unverified carriage.
A host that carries many of one owner's channels does not need to track the
owner's collection IDs. A collection selector without `collection_ids` is a
**bulk grant**: it scopes the authorization to every collection declared in
that publisher's `adagents.json`. This matches how carriage deals are
structured — the host's contract is with the owner, not with each channel —
and avoids a cross-company ID-sync dependency that would silently break the
supply path when the owner renames a collection:
```json theme={null}
"collections": [{ "publisher_domain": "channel-owner.example" }]
```
Position-specific host narrowing has a namespace rule. Host `placement_ids`
and `placement_tags` resolve against placements published in the host's own
`adagents.json`; they never match a seller's `seller_inline` placements, which
live in the owner's namespace. A host that must constrain positions therefore
publishes those placement definitions itself, and owner products MUST reference
them via `kind: "publisher_ref"` into the host namespace. `seller_inline`
placements and host placement narrowing are mutually exclusive on the same
supply path — owner-sold carriage without position constraints is the shape
that keeps hosts out of the owner's avail definitions.
### Verification states
The host attestation will roll out unevenly — channel owners have a direct
incentive to publish; hosts publish on their own schedule. Buyer agents SHOULD
distinguish three states rather than inventing their own interim policy:
1. **Verified owner-sold.** The host's `adagents.json` authorizes the seller
for the host property, narrowed by the owner's collection selector (exact
or bulk grant). Full supply-path verification; suitable for enforcement.
2. **Host-delegated.** The host has not published a collection-narrowed
`adagents.json` entry, but its `app-ads.txt` (or `ads.txt`) names the owner
via `inventorypartnerdomain=`, and the owner's own `adagents.json` names
the sales agent and the channel collection. The `inventorypartnerdomain`
line is host-authored, so it is genuine host-side evidence that the owner
sells some of this property's inventory — but it binds neither the agent
URL nor the collection, so it MUST NOT be treated as equivalent to the
collection-narrowed entry. Buyers MAY accept this state under their own
policy, the way DSPs ran ads.txt grace periods.
3. **Owner-attested.** Only the owner's `distribution[]` entry asserts
carriage. This is discovery data with no host-side corroboration; buyers
MUST NOT treat it as sales authorization.
For hosts, the collection-narrowed entry is not a new favor to a competitor's
sales path: it is the machine-readable form of the carriage contract's
existing owner-sales clause, and the upgrade path from an
`inventorypartnerdomain` line they typically already publish.
### Canonical verification semantics
The registry supply-path endpoint returns `semantics_version: "1"`. Its evaluator and authoritative SDK implementations consume the same [canonical golden vectors](https://github.com/adcontextprotocol/adcp/blob/main/static/compliance/source/test-vectors/supply-path/vectors.json). Consumers MUST NOT treat results from older evaluator semantics as equivalent to version 1.
Version 1 requires an affirmative host `collections` selector naming the owner. A broad property grant with no collection constraint does not attest owner-sold carriage. Every claimed host property ID must resolve, and the matching grant must cover all of them. Identifier-only distribution entries remain valid discovery data, but cannot prove a host property binding. Missing or unknown authorization discriminators and their companion selectors fail closed on both the owner's and host's agent declarations. Malformed selectors and country, effective-time or placement constraints that cannot be evaluated in the supplied context also fail closed. Revocations take precedence over declarations. Agent URL identity follows the protocol canonicalization rules and preserves case-sensitive paths and query values.
A query omitting `collection_id` returns the strongest complete individual collection path. It never combines one collection's carriage with another collection's authorization. The weaker `host_delegated` state retains its documented owner declarations plus host inventory-partner evidence requirements; it does not require a host `adagents.json`, prove concrete property coverage, or override revocation.
Two verified paths can legitimately overlap. In a revenue-share deal the
host's agent and the owner's agent may both offer avails on the same property
and collection; in an inventory-split deal they sell disjoint avails.
Verification implies neither exclusivity nor disjointness — buyers dedup at
delivery and measurement, as with any multi-path supply. A host that wants the
split machine-readable can tag its retained avails with `placement_tags`.
Multiple parties with sales rights do not require a new concurrency primitive.
The host publishes one `authorized_agents[]` entry per sales path and narrows
each entry to the relevant collection. A technology provider does not become a
rights-holder merely by operating the path. If it supplies software behind the
owner's endpoint, the path may remain `direct`; if it operates the sales
endpoint on the owner's behalf, the host names that endpoint and marks the path
`delegated`.
Syndication chains with an aggregator in the middle (owner → playout/ad-tech
aggregator → host, common for FAST outside the owner's home market) collapse
to the same shape: the host attests each terminal sales path directly. When
the aggregator holds the sales rights for its inventory share, the host
authorizes the aggregator's agent — `delegated`, narrowed to the owner's
collection (the bulk-grant selector fits here, since the host may know the
owner only through the aggregator). There is no transitive attestation: a host
entry naming the aggregator does not authorize agents the aggregator engages
downstream; each selling endpoint the buyer can transact with needs its own
host entry. The aggregator, holding both contracts, is the natural broker of
the collection selector values.
Internal allocation terms such as revenue shares, buyback rights, and backfill
priority are not discovery or authorization data. Each seller applies those
terms when constructing and pricing its products; buyers see the resulting
offer, not how the participating parties divide the proceeds.
The registry admits cached manifests for supply-path legs only when their provenance is a direct publisher-origin fetch or a publisher `authoritative_location` delegation, the observation is no older than seven days, and its cache expiry has not elapsed. Manager and community discovery results need additional publisher authority proofs and are not enforcement evidence. Successful-fetch provenance is stored atomically with the manifest, separately from last-attempt diagnostics; cache rows created before this provenance was recorded must refresh before they can establish authority. Registry sources expose `owner_fetched_at`, `host_fetched_at`, and resolved URLs separately from the verdict's `checked_at`.
Both authoritative verification and the registry retain observed revocations by authority and publisher domain for seven days from first observation; changing `revoked_at` does not restart that clock. The registry uses the existing persistent SDK document store so workers and restarts share the hold and authoritative-location pin. A changed pin rejects until an operator independently confirms the publisher migration; an operator can run `npx tsx server/scripts/approve-supply-path-authority.ts --confirm-publisher-migration` with `DATABASE_URL` after independently confirming the migration. This calls `approveSupplyPathAuthorityChange` while preserving revocations. Never run it from an automatic retry. Properties read from a cross-origin shared authoritative document must explicitly attribute their publisher. IAB evidence allows at most three exact-HTTPS-origin redirects, with bounded bytes and time per fetch.
Collections in a cross-origin authoritative document must explicitly name their owning `publisher_domain`, just as shared host properties must identify their publisher. A domain pointing at an unrelated public catalog cannot borrow that catalog's collections, including through weaker inventory-partner evidence. Publisher-origin collection declarations may omit the field. Owner agent grants in shared cross-origin documents must also explicitly select that owner through `collections[].publisher_domain`; an absent `collections` constraint cannot authorize every member. Within that owner namespace, omitted `collection_ids` still grants all collections.
## The installment object
An installment is a specific installment of a collection. Not all installments will be known in advance — a weekly podcast may only have next week's installment scheduled, and some installments may be tentative (a playoff Game 7 depends on Game 6).
| Field | Type | Required | Description |
| - | - | - | - |
| `installment_id` | string | Yes | Unique identifier within the collection |
| `collection_ref` | object | Conditional | Canonical parent identity: `{publisher_domain, collection_id}`. Required when the product spans multiple collections or publisher namespaces. |
| `collection_id` | string | Deprecated | Legacy parent shorthand, unambiguous only within one publisher namespace. |
| `name` | string | No | Episode title |
| `season` | string | No | Season identifier (e.g., `"1"`, `"2026"`) |
| `installment_number` | string | No | Episode number within the season |
| `scheduled_at` | datetime | No | When the installment airs or publishes |
| `status` | string | No | `scheduled`, `tentative`, `live`, `postponed`, `cancelled`, `aired`, `published` |
| `duration_seconds` | integer | No | Expected duration |
| `flexible_end` | boolean | No | Whether end time is approximate (live events) |
| `valid_until` | datetime | No | When this data expires. Agents should re-query before committing budget to tentative installments. |
| `content_rating` | object | No | Overrides the collection's baseline when present |
| `topics` | string\[] | No | Installment-level content topics for brand safety. Uses collection's `genre_taxonomy` when present. |
| `special` | object | No | Installment-specific event context. When present, this installment is anchored to a real-world event. Overrides the collection-level `special`. |
| `guest_talent` | array | No | Installment-specific guests. Additive to the collection's recurring `talent`. |
| `ad_inventory` | object | No | Break-based ad inventory configuration |
| `deadlines` | object | No | Booking, cancellation, and material submission deadlines for this installment. See [installment deadlines](#installment-deadlines). |
| `derivative_of` | object | No | When this installment is a clip, highlight, or recap derived from a full installment. Has `installment_id` + `type` (`clip`, `highlight`, `recap`, `trailer`, `bonus`). Source `installment_id` must be in the same response. |
### Episode status lifecycle
| Status | Meaning |
| - | - |
| `scheduled` | Confirmed, will happen |
| `tentative` | May not happen (depends on external conditions) |
| `live` | Currently airing or streaming right now |
| `postponed` | Was scheduled but delayed to a future date |
| `cancelled` | Will not happen |
| `aired` | Already broadcast — for back-catalog and replay inventory |
| `published` | Already released — for on-demand catch-up inventory |
Expected transitions: `scheduled` or `tentative` → `live` → `aired` or `published`. A `scheduled` installment may become `postponed` (delayed) or `cancelled`. A `postponed` installment returns to `scheduled` when rescheduled. A `tentative` installment resolves to `scheduled`, `cancelled`, or `postponed`.
### Inheritance from collections
Episodes inherit collection-level fields they do not override:
* **`content_rating`**: Episode value overrides collection baseline. When absent, the collection's rating applies.
* **`special`**: Episode value overrides collection-level special. When absent, the collection's special applies. A regular collection can have event-anchored installments (e.g., a daily news collection with an election night special).
* **`guest_talent`**: Additive to the collection's recurring `talent` — does not replace it.
* **`topics`**: Additive context for brand safety, not a replacement for the collection's `genre`.
Buyer agents evaluate both levels: the collection baseline provides the default safety profile, and installment fields refine it for specific installments.
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/installment.json",
"installment_id": "s1e03_the_wall",
"collection_id": "pinnacle_challenge",
"name": "The Wall",
"season": "1",
"installment_number": "3",
"scheduled_at": "2026-04-07T20:00:00Z",
"status": "scheduled",
"duration_seconds": 3600,
"valid_until": "2026-04-06T20:00:00Z",
"content_rating": {
"system": "tv_parental",
"rating": "TV-14"
},
"topics": ["IAB17-18"],
"guest_talent": [
{
"role": "guest",
"name": "Samira Okafor",
"brand_url": "https://samiraokafor.example.com/brand.json"
}
],
"ad_inventory": {
"expected_breaks": 4,
"total_ad_seconds": 480,
"max_ad_duration_seconds": 120,
"unplanned_breaks": false,
"supported_formats": ["video", "audio"]
}
}
```
## Installment deadlines
Episodes can carry booking, cancellation, and material submission deadlines. These apply to any channel where inventory is tied to a scheduled unit — print issues, podcast installments, influencer posts, linear TV airings, DOOH rotations.
| Field | Type | Description |
| - | - | - |
| `booking_deadline` | datetime | Last date/time to book a placement in this installment |
| `cancellation_deadline` | datetime | Last date/time to cancel without penalty |
| `material_deadlines` | array | Ordered stages for creative material submission |
Deadlines MUST be chronologically ordered: `booking_deadline` ≤ `cancellation_deadline` ≤ each `material_deadlines[n].due_at` (ascending by array index) ≤ the installment's `scheduled_at`. Buyer agents SHOULD reject installments where deadlines violate this ordering.
Each material deadline has:
| Field | Type | Required | Description |
| - | - | - | - |
| `stage` | string | Yes | Stage identifier (`draft`, `final`, or seller-defined) |
| `due_at` | datetime | Yes | When materials for this stage are due |
| `label` | string | No | What the seller needs (e.g., "Talking points", "Press-ready PDF with bleed") |
The two-stage pattern — draft then final — covers a wide range of channels:
| Channel | Draft stage | Final stage |
| - | - | - |
| Print | Raw artwork for review | Press-ready PDF with bleed |
| Podcast (host read) | Talking points and brief | Approved script |
| Influencer | Brand guidelines and key messages | Approved post content |
| Linear TV | Rough cut | Encoded broadcast spot |
| DOOH | Draft creative for review | Final assets per screen specs |
### Podcast with deadlines
```json theme={null}
{
"installment_id": "ep47",
"name": "The future of autonomous supply chains",
"scheduled_at": "2026-04-07T10:00:00Z",
"status": "scheduled",
"guest_talent": [
{ "role": "guest", "name": "Kai Tanaka" }
],
"deadlines": {
"booking_deadline": "2026-03-28T17:00:00Z",
"cancellation_deadline": "2026-03-31T17:00:00Z",
"material_deadlines": [
{
"stage": "draft",
"due_at": "2026-04-01T17:00:00Z",
"label": "Talking points and brand guidelines for host read"
},
{
"stage": "final",
"due_at": "2026-04-04T17:00:00Z",
"label": "Approved script"
}
]
}
}
```
### Print issue with deadlines
```json theme={null}
{
"installment_id": "2026-05",
"name": "Mai 2026",
"season": "2026",
"installment_number": "5",
"scheduled_at": "2026-05-01T00:00:00+02:00",
"status": "scheduled",
"deadlines": {
"booking_deadline": "2026-03-15T17:00:00+01:00",
"cancellation_deadline": "2026-03-22T17:00:00+01:00",
"material_deadlines": [
{
"stage": "draft",
"due_at": "2026-03-29T17:00:00+01:00",
"label": "Raw artwork for review and color proofing"
},
{
"stage": "final",
"due_at": "2026-04-05T17:00:00+02:00",
"label": "Press-ready PDF/X-4, CMYK, 300 DPI, 3mm bleed"
}
]
}
}
```
### Influencer post with deadlines
```json theme={null}
{
"installment_id": "post_2026_04_10",
"name": "Spring campaign post",
"scheduled_at": "2026-04-10T12:00:00Z",
"status": "scheduled",
"deadlines": {
"cancellation_deadline": "2026-04-03T17:00:00Z",
"material_deadlines": [
{
"stage": "draft",
"due_at": "2026-04-05T17:00:00Z",
"label": "Key messages, product images, and brand guidelines"
},
{
"stage": "final",
"due_at": "2026-04-08T17:00:00Z",
"label": "Approved post content and caption"
}
]
}
}
```
Deadlines are optional. Run-of-collection digital products typically omit them. The pattern is most valuable for guaranteed inventory with advance material requirements.
## Deadline policy
High-frequency collections (daily newspapers, weekly podcasts) would generate large payloads if every installment carried explicit deadlines. The `deadline_policy` on a collection declares lead-time rules that agents use to compute deadlines from each installment's `scheduled_at`.
| Field | Type | Description |
| - | - | - |
| `booking_lead_days` | integer | Days before `scheduled_at` by which the placement must be booked |
| `cancellation_lead_days` | integer | Days before `scheduled_at` by which cancellation is penalty-free |
| `material_stages` | array | Default material submission stages with `stage`, `lead_days`, and optional `label` |
| `business_days_only` | boolean | When true, lead_days counts Mon-Fri only. Defaults to false. |
### Daily newspaper with policy
Instead of enumerating deadlines for every issue, the collection declares the rule once:
```json theme={null}
{
"collection_id": "bergedorfer_zeitung",
"name": "Bergedorfer Zeitung",
"kind": "publication",
"cadence": "daily",
"status": "active",
"deadline_policy": {
"booking_lead_days": 4,
"cancellation_lead_days": 3,
"material_stages": [
{ "stage": "final", "lead_days": 2, "label": "Druckfertige PDF" }
],
"business_days_only": true
}
}
```
For the April 1 issue (`scheduled_at: "2026-04-01"`), an agent computes:
* **Booking deadline**: 4 business days before = March 26
* **Cancellation deadline**: 3 business days before = March 27
* **Material due**: 2 business days before = March 28
Episodes with explicit `deadlines` override the policy. A special edition with tighter turnaround declares its own deadlines; regular issues inherit from the policy.
### Weekly podcast with policy
```json theme={null}
{
"collection_id": "wonderstruck_weekly",
"name": "Wonderstruck Weekly",
"kind": "series",
"cadence": "weekly",
"deadline_policy": {
"booking_lead_days": 10,
"cancellation_lead_days": 7,
"material_stages": [
{ "stage": "draft", "lead_days": 5, "label": "Talking points and brand guidelines" },
{ "stage": "final", "lead_days": 3, "label": "Approved script for host read" }
]
}
}
```
### Policy vs explicit deadlines
| Scenario | Use |
| - | - |
| Daily newspaper, consistent deadlines | `deadline_policy` on collection |
| Weekly podcast, consistent deadlines | `deadline_policy` on collection |
| Monthly magazine, varying lead times per issue | Explicit `deadlines` on each installment |
| One-off special with tight turnaround | Explicit `deadlines` on that installment, policy covers the rest |
When both are present, explicit installment `deadlines` take precedence. An agent SHOULD NOT compute deadlines from the policy for installments that have their own.
## Specials and limited series
Collections can carry optional annotations that signal their nature to buyer agents. These are composable — a collection can be both a special and a limited series (e.g., a 4-installment Olympics documentary).
### Specials
A special is content anchored to a real-world event or occasion. The `special` object can appear on both collections and installments. On a collection, it means the entire collection is event-anchored. On an installment, it means that specific installment is event-anchored (and overrides the collection-level special when present, following the same inheritance pattern as `content_rating`).
| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Name of the event (e.g., "Olympics 2028", "Super Bowl LXI") |
| `category` | string | No | `awards`, `championship`, `concert`, `conference`, `election`, `festival`, `gala`, `holiday`, `premiere`, `product_launch`, `reunion`, `tribute` |
| `starts` | datetime | No | When the event starts |
| `ends` | datetime | No | When the event ends. Omit for single-day events. |
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/collection.json",
"collection_id": "apex_finals_2026",
"name": "Apex Championship Finals 2026",
"genre": ["IAB17", "IAB17-12"],
"genre_taxonomy": "iab_content_3.0",
"cadence": "event",
"status": "upcoming",
"special": {
"name": "Apex Championship Finals 2026",
"category": "championship",
"starts": "2026-05-18T19:00:00Z",
"ends": "2026-05-25T23:00:00Z"
},
"talent": [
{ "role": "host", "name": "Deshawn Moreaux" }
]
}
```
The `special` field is distinct from `cadence`. Cadence describes release frequency (`event` = one-time or occasional). The `special` object describes what real-world event anchors the content and when it happens — information a buyer agent needs to evaluate timing relevance and premium pricing.
### Limited series
A limited series is a bounded content run with a defined arc. Unlike ongoing series, limited series have a planned end.
| Field | Type | Required | Description |
| - | - | - | - |
| `total_installments` | integer | No | Planned number of installments |
| `starts` | datetime | No | When the series begins |
| `ends` | datetime | No | When the series ends |
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/collection.json",
"collection_id": "ember_s3",
"name": "The Ember",
"description": "Award-winning drama following a chef navigating the pressure of running a top restaurant",
"genre": ["IAB1", "IAB1-7"],
"genre_taxonomy": "iab_content_3.0",
"cadence": "weekly",
"status": "active",
"limited_series": {
"total_installments": 8,
"starts": "2026-02-28T21:00:00Z",
"ends": "2026-04-18T21:00:00Z"
}
}
```
This tells buyer agents that The Ember is a finite opportunity — 8 installments over 7 weeks. The `limited_series` field is distinct from `season`: a collection can have seasons without being limited (ongoing series have seasons too), and a limited series is a structural commitment that the collection has a planned end.
## How products reference collections
Products reference collections via `collections` — an array of `{publisher_domain, collection_ids}` selectors that point to collections declared in the publisher's `adagents.json`. This is the same pattern as `publisher_properties`. Buyers resolve full collection objects from the publisher's `adagents.json`. Episodes are listed per-product in the `installments` array, since different products may scope different installments of the same collection.
### Reporting actual delivery
Discovery and delivery answer different questions. A collection's `distribution` metadata or a product's property selectors say where content is carried or sellable. After purchase, `get_media_buy_delivery` can report `by_collection`, `by_property`, and `by_installment` marginals. Those independent arrays do not prove a relationship between their rows. Products that declare `supports_collection_property_breakdown` can return `by_collection_property`, whose rows are affirmative evidence that a collection actually delivered on a specific property. For a scheduled airing, episode, issue, or programming block, `supports_installment_property_breakdown` enables `by_installment_property`, proving that the specific installment delivered on the host property. This is the grain needed to distinguish the same programmed airing across two host apps without inferring delivery from catalog carriage. Collections and installments use publisher-scoped references; property rows use a publisher-scoped operational identifier and add a catalog property reference when one exists. If the response is truncated or suppressed, an absent intersection row proves nothing.
### Run-of-collection (no specific installments)
A product can reference a collection without listing installments. This means "inventory across this collection, whatever installments air during the flight dates":
```json theme={null}
{
"product_id": "pinnacle_run_of_collection",
"name": "Pinnacle Challenge Run of Show",
"collections": [{ "publisher_domain": "acmestreaming.example.com", "collection_ids": ["pinnacle_challenge"] }],
"placements": [
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.acmestreaming.example.com/adcp" }, "placement_id": "pre_roll", "name": "Pre-roll", "mode": "targetable" }
],
"delivery_type": "non_guaranteed",
"pricing_options": [
{ "pricing_option_id": "cpm", "pricing_model": "cpm", "floor_price": 25.00, "currency": "USD" }
]
}
```
### Specific installments
For premium or guaranteed buys, the seller scopes to specific installments:
```json theme={null}
{
"product_id": "pinnacle_finale",
"name": "Pinnacle Challenge Season Finale Sponsorship",
"collections": [{ "publisher_domain": "acmestreaming.example.com", "collection_ids": ["pinnacle_challenge"] }],
"installments": [
{
"installment_id": "s1e10_finale",
"name": "The Grand Finale",
"scheduled_at": "2026-06-02T20:00:00Z",
"status": "scheduled",
"ad_inventory": {
"expected_breaks": 6,
"total_ad_seconds": 720,
"unplanned_breaks": false
}
}
],
"delivery_type": "guaranteed",
"pricing_options": [
{ "pricing_option_id": "flat", "pricing_model": "flat_rate", "fixed_price": 2000000, "currency": "USD" }
]
}
```
## get_products response structure
Products reference collections via `collections` selectors — the same pattern as `publisher_properties`. Each selector has a `publisher_domain` and `collection_ids` array pointing to collections declared in that publisher's `adagents.json`. Buyers resolve full collection objects from `adagents.json`.
```json theme={null}
{
"products": [
{
"product_id": "pinnacle_april_bundle",
"name": "Pinnacle Challenge April Sponsorship",
"collections": [{ "publisher_domain": "acmestreaming.example.com", "collection_ids": ["pinnacle_challenge"] }],
"installments": [
{
"installment_id": "s1e03",
"name": "The Wall",
"scheduled_at": "2026-04-07T20:00:00Z",
"status": "scheduled",
"content_rating": { "system": "tv_parental", "rating": "TV-14" },
"guest_talent": [{ "role": "guest", "name": "Samira Okafor" }],
"valid_until": "2026-04-06T20:00:00Z"
},
{
"installment_id": "s1e04",
"name": "TBD",
"scheduled_at": "2026-04-14T20:00:00Z",
"status": "tentative",
"valid_until": "2026-04-07T20:00:00Z"
}
],
"placements": [
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.acmestreaming.example.com/adcp" }, "placement_id": "pre_roll", "name": "Pre-roll", "mode": "targetable" },
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.acmestreaming.example.com/adcp" }, "placement_id": "mid_roll", "name": "Mid-roll", "mode": "targetable" }
],
"delivery_type": "guaranteed",
"pricing_options": [
{ "pricing_option_id": "flat", "pricing_model": "flat_rate", "fixed_price": 500000, "currency": "USD" }
]
}
]
}
```
## Canonical collection identity
A collection's identity is **`{publisher_domain, collection_id}`** — scoped to the publisher that declares it in their `adagents.json`. This means any collection creator can serve as their own canonical registry.
### Creator as canonical publisher
A creator like MrBeast declares collections in `mrbeast.com/adagents.json`. Any seller packaging that creator's inventory — a YouTube sales house, a CTV distributor, the creator's own team — references the same canonical source:
```json theme={null}
{
"products": [
{
"product_id": "beast_games_youtube",
"name": "Beast Games - YouTube Pre-roll",
"collections": [
{ "publisher_domain": "mrbeast.com", "collection_ids": ["beast_games"] }
],
"publisher_properties": [
{ "publisher_domain": "youtube.com", "property_ids": ["UCX6OQ3DkcsbYNE6H8uQQuVA"] }
],
"delivery_type": "non_guaranteed",
"pricing_options": [
{ "pricing_option_id": "cpm", "pricing_model": "cpm", "floor_price": 18.00, "currency": "USD" }
]
}
]
}
```
The buyer sees `mrbeast.com` + `beast_games` regardless of which seller or platform the inventory comes from. No cross-referencing of IMDb IDs or distribution identifiers needed — the creator's domain **is** the registry.
### When creators don't publish adagents.json
Not every collection has a creator-owned domain. A streaming platform's original series may only exist in that platform's `adagents.json`. In that case, the platform is the canonical publisher and `collections` points to their domain. Distribution identifiers on the collection object handle cross-seller matching when the same collection appears on multiple platforms without a single canonical source.
### Identity resolution priority
Buyer agents should resolve collection identity in this order:
1. **Canonical publisher** — `publisher_domain` + `collection_id` from the creator's own `adagents.json`. Strongest signal.
2. **Platform-independent identifiers** — `imdb_id`, `gracenote_id`, `eidr_id` from the collection's `distribution` array. Reliable cross-reference when no canonical publisher exists.
3. **Platform-specific identifiers** — Spotify, Apple, YouTube IDs. Useful within a platform but not universal.
## Discovery examples
### CTV collection with installments
A streaming platform selling sponsorships against a known collection with upcoming installments:
```json theme={null}
{
"products": [
{
"product_id": "nova_kitchen_april",
"name": "Nova Kitchen - April Episodes",
"collections": [{ "publisher_domain": "novastreaming.example.com", "collection_ids": ["nova_kitchen"] }],
"publisher_properties": [{
"publisher_domain": "novastreaming.example.com",
"selection_type": "all"
}],
"installments": [
{
"installment_id": "s3e09",
"name": "Fire and Ice",
"scheduled_at": "2026-04-05T21:00:00Z",
"status": "scheduled",
"duration_seconds": 2700,
"ad_inventory": {
"expected_breaks": 3,
"total_ad_seconds": 360,
"max_ad_duration_seconds": 30,
"unplanned_breaks": false,
"supported_formats": ["video"]
}
},
{
"installment_id": "s3e10",
"scheduled_at": "2026-04-12T21:00:00Z",
"status": "tentative",
"valid_until": "2026-04-06T00:00:00Z"
}
],
"placements": [
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.novastreaming.example.com/adcp" }, "placement_id": "pre_roll", "name": "Pre-roll (15s)", "mode": "targetable" },
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.novastreaming.example.com/adcp" }, "placement_id": "mid_roll", "name": "Mid-roll (30s)", "mode": "targetable" }
],
"delivery_type": "guaranteed",
"pricing_options": [
{ "pricing_option_id": "cpm_fixed", "pricing_model": "cpm", "fixed_price": 38.00, "currency": "USD" }
]
}
]
}
```
### Related collections and derivative content
A streaming platform offering a main collection and its companion after-collection, plus highlight clips:
```json theme={null}
{
"products": [
{
"product_id": "nova_highlights",
"name": "Nova Kitchen Highlights Package",
"collections": [{ "publisher_domain": "novastreaming.example.com", "collection_ids": ["nova_kitchen"] }],
"installments": [
{
"installment_id": "s3e09",
"name": "Fire and Ice",
"status": "aired",
"duration_seconds": 2700
},
{
"installment_id": "s3e09_highlights",
"name": "Fire and Ice - Best Moments",
"status": "published",
"duration_seconds": 180,
"derivative_of": {
"installment_id": "s3e09",
"type": "highlight"
}
}
],
"placements": [
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.novastreaming.example.com/adcp" }, "placement_id": "pre_roll", "name": "Pre-roll (15s)", "mode": "targetable" }
],
"delivery_type": "non_guaranteed",
"pricing_options": [
{ "pricing_option_id": "cpm", "pricing_model": "cpm", "floor_price": 12.00, "currency": "USD" }
]
}
]
}
```
The highlight clip references its source installment via `derivative_of`. The companion after-collection is linked via `related_collections` on the main collection — buyers targeting Nova Kitchen can discover the after-collection as an additional reach opportunity.
### Podcast with distribution
A podcast network selling across multiple distribution platforms. The collection's `distribution` array in `adagents.json` captures the full distribution footprint; buyers use distribution identifiers for cross-seller matching:
```json theme={null}
{
"products": [
{
"product_id": "wonderstruck_april",
"name": "Wonderstruck Weekly - April Episodes",
"collections": [{ "publisher_domain": "wonderstruck.example.com", "collection_ids": ["wonderstruck_weekly"] }],
"installments": [
{
"installment_id": "ep47",
"name": "The future of autonomous supply chains",
"scheduled_at": "2026-04-07T10:00:00Z",
"status": "scheduled",
"guest_talent": [
{ "role": "guest", "name": "Kai Tanaka", "brand_url": "https://kaitanaka.example.com/brand.json" }
]
},
{
"installment_id": "ep48",
"scheduled_at": "2026-04-14T10:00:00Z",
"status": "tentative"
},
{
"installment_id": "ep49",
"scheduled_at": "2026-04-21T10:00:00Z",
"status": "tentative"
}
],
"placements": [
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.wonderstruck.example.com/adcp" }, "placement_id": "pre_roll", "name": "Pre-roll (30s)", "mode": "targetable" },
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.wonderstruck.example.com/adcp" }, "placement_id": "mid_roll", "name": "Mid-roll host read (60s)", "mode": "targetable" }
],
"delivery_type": "guaranteed",
"pricing_options": [
{ "pricing_option_id": "flat_monthly", "pricing_model": "flat_rate", "fixed_price": 15000, "currency": "USD" },
{ "pricing_option_id": "per_episode", "pricing_model": "flat_rate", "fixed_price": 5000, "currency": "USD" }
]
}
]
}
```
Tentative installments (ep48, ep49) have no names or guest info — they have not been produced yet. The buyer evaluates based on the collection's baseline profile and the known details of ep47.
### Live event with tentative installments
A sports league selling sponsorships against a live event series. Live broadcasts use `flexible_end` because game duration is unpredictable, and `unplanned_breaks` because ad breaks follow game flow (timeouts, period breaks) rather than a fixed schedule. The tentative Game 5 depends on the series outcome — it only happens if neither team wins in four games.
```json theme={null}
{
"products": [
{
"product_id": "apex_finals_sponsorship",
"name": "Apex Championship Finals — Category Sponsorship",
"collections": [{ "publisher_domain": "apexleague.example.com", "collection_ids": ["apex_championship_2026"] }],
"installments": [
{
"installment_id": "finals_game4",
"name": "Game 4: Titan City vs Coastal FC",
"scheduled_at": "2026-05-18T19:00:00Z",
"status": "scheduled",
"flexible_end": true,
"ad_inventory": {
"expected_breaks": 8,
"total_ad_seconds": 960,
"max_ad_duration_seconds": 30,
"unplanned_breaks": true,
"supported_formats": ["video"]
}
},
{
"installment_id": "finals_game5",
"name": "Game 5 — If necessary",
"scheduled_at": "2026-05-21T19:00:00Z",
"status": "tentative",
"flexible_end": true,
"valid_until": "2026-05-19T06:00:00Z",
"ad_inventory": {
"expected_breaks": 8,
"total_ad_seconds": 960,
"max_ad_duration_seconds": 30,
"unplanned_breaks": true,
"supported_formats": ["video"]
}
}
],
"placements": [
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.apexleague.example.com/adcp" }, "placement_id": "in_game_overlay", "name": "In-game overlay (10s)", "mode": "targetable" },
{ "kind": "seller_inline", "seller_agent": { "agent_url": "https://sales.apexleague.example.com/adcp" }, "placement_id": "halftime", "name": "Halftime feature (60s)", "mode": "targetable" }
],
"delivery_type": "guaranteed",
"exclusivity": "category",
"pricing_options": [
{ "pricing_option_id": "per_game", "pricing_model": "flat_rate", "fixed_price": 750000, "currency": "USD" }
]
}
]
}
```
This pattern combines several features designed for live inventory: `cadence: "event"` signals a non-recurring series, `flexible_end` tells buyers the broadcast length is approximate, and `unplanned_breaks: true` indicates ad breaks follow game flow rather than a predetermined schedule. The tentative Game 5 includes `valid_until` so buyer agents know when to re-query — if the series ends in four games, that installment will resolve to `cancelled`. Buyers should always check `valid_until` on tentative installments before committing budget.
### Discovering collections
Buyers discover collections through the standard `get_products` workflow. Natural language briefs drive collection selection:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442011",
"buying_mode": "brief",
"brief": "Podcast sponsorships for technology collections reaching startup founders in April",
"filters": {
"channels": ["podcast"],
"start_date": "2026-04-01",
"end_date": "2026-04-30"
}
}
```
The seller returns products with `collections` selectors. The buyer resolves full collection objects from each publisher's [adagents.json](/dist/docs/3.2.8/governance/property/adagents). Registry clients can also bootstrap and look up the crawled collection catalog through `/api/registry/catalog/collections/sync` and `/api/registry/catalog/collections/distribution`, which is useful for cross-referencing platform aliases such as YouTube channel IDs back to the publisher-declared collection.
For community-maintained entries, registry moderators can seed a publisher-scoped collection with `PUT /api/registry/catalog/collections/{publisher_domain}/{collection_id}`. This creates a contributed registry record and emits the same `collection.created` / `collection.updated` feed events. It does not replace publisher-origin proof: once the publisher declares the collection in their own `adagents.json`, the authoritative declaration wins.
## Brand safety
Collections provide a two-level brand safety model: a collection baseline and per-installment overrides.
### Collection baseline
A collection's default brand safety profile comes from:
* `content_rating` — the collection's declared rating system and value
* `genre` — content categories (ideally using `genre_taxonomy` for machine-readable evaluation)
* `talent` — hosts and recurring cast, with optional [brand.json](/dist/docs/3.2.8/brand-protocol/brand-json) references for deeper evaluation
This is what buyers evaluate when individual installment content is not yet known.
### Installment overrides
When installment details are available, they can shift the safety profile:
* A `content_rating` that differs from the collection baseline (this week is TV-14 instead of TV-PG)
* `guest_talent` that changes the talent profile (a controversial guest)
* `topics` that add installment-specific content signals
### What is not modeled
AdCP does not predict content safety for unknown future installments. A buyer who commits to "all April installments" buys based on the collection's baseline profile, accepting variation. The seller's content standards and the collection's track record are the buyer's basis for that decision.
## Distribution identifiers
Each collection's `distribution` array maps it to specific publisher platforms using host `property_ids`, platform identifiers, or both. Identifiers enable cross-seller matching: when two different sellers both offer products for the same collection, a buyer agent can match them via shared identifiers.
### Cross-seller matching
Platform-independent identifiers are the most reliable for deduplication:
| Type | Example | Notes |
| - | - | - |
| `imdb_id` | `tt1234567` | Universal cross-platform reference |
| `gracenote_id` | `EP012345678` | Industry standard for TV metadata |
| `eidr_id` | `10.5240/XXXX-XXXX-XXXX-XXXX-XXXX-C` | ISO 10528 for audiovisual content |
Collections SHOULD include at least one platform-independent identifier when available.
### Platform-specific identifiers
```json Podcast theme={null}
{
"distribution": [
{
"publisher_domain": "spotify.com",
"identifiers": [{ "type": "spotify_collection_id", "value": "4rOoJ6Egrf8K2IrywzwOMk" }]
},
{
"publisher_domain": "apple.com",
"identifiers": [{ "type": "apple_podcast_id", "value": "1234567890" }]
},
{
"publisher_domain": "feeds.example.com",
"identifiers": [{ "type": "rss_url", "value": "https://feeds.example.com/collection.xml" }]
}
]
}
```
```json Video / CTV theme={null}
{
"distribution": [
{
"publisher_domain": "youtube.com",
"identifiers": [{ "type": "youtube_channel_id", "value": "UCexample123456" }]
},
{
"publisher_domain": "acmestreaming.example.com",
"identifiers": [{ "type": "amazon_title_id", "value": "B0DFBT5GBP" }]
}
]
}
```
Available podcast types: `apple_podcast_id`, `spotify_collection_id`, `rss_url`, `podcast_guid`, `amazon_music_id`, `iheart_id`, `podcast_index_id`. Available video/CTV types: `youtube_channel_id`, `youtube_channel_handle`, `youtube_channel_url`, `youtube_playlist_id`, `amazon_title_id`, `platform_channel_id`, `roku_channel_id`, `pluto_channel_id`, `tubi_id`, `peacock_id`, `tiktok_id`, `twitch_channel`. Other: `domain`, `substack_id`. For YouTube channels, `youtube_channel_id` is the preferred canonical identifier; handles and URLs are aliases for discovery and matching when the channel ID is not yet resolved.
## Ad inventory
Episodes declare break-based ad inventory in the `ad_inventory` object:
| Field | Type | Description |
| - | - | - |
| `expected_breaks` | integer | Number of planned ad breaks |
| `total_ad_seconds` | integer | Total seconds of ad time across all breaks |
| `max_ad_duration_seconds` | integer | Maximum duration for a single ad within a break |
| `unplanned_breaks` | boolean | `false`: all breaks pre-defined. `true`: breaks driven by live conditions (sports timeouts, live news). |
| `supported_formats` | string\[] | Format types supported in breaks (e.g., `"video"`, `"audio"`) |
For non-break ad formats like host reads, custom integrations, or sponsorships, use product [placements](/dist/docs/3.2.8/media-buy/product-discovery/media-products#placements) instead. A podcast product might have a placement for "mid-roll host read (60s)" — that is a placement on the product, not part of `ad_inventory`.
## Relationship to LEAP
The installment model aligns with IAB Tech Lab's LEAP Forecasting API for live streaming events:
| LEAP concept | AdCP equivalent |
| - | - |
| UpcomingEvent | Episode (`scheduled_at` + `status`) |
| Content (AdCOM 1.0) | Show metadata (`genre`, `content_rating`, `talent`) |
| AdInventoryConfiguration | Episode `ad_inventory` + product placements |
| Event status | Episode `status` (`scheduled`, `tentative`, `cancelled`) |
| Unplanned breaks | `ad_inventory.unplanned_breaks` |
| Flexible end time | Episode `flexible_end` |
LEAP targets SSP-to-DSP plumbing. AdCP operates at the agent-to-agent negotiation layer where buying decisions happen.
## Collection targeting
Products with multiple collections default to bundles — the buyer gets all listed collections. Sellers can set `collection_targeting_allowed: true` to let buyers target a subset, the same pattern as `property_targeting_allowed` for properties.
| `collection_targeting_allowed` | Meaning |
| - | - |
| `false` (default) | Bundle — buyer gets all collections |
| `true` | Buyer can select specific collections in the media buy |
Selection travels in `targeting_overlay.collection_selection`, mirroring
`placement_selection`: `mode: "selected"` names the complete required set as
domain-qualified selectors with explicit `collection_ids` (the domain-only
bulk-grant form is authorization scoping, not selection), and
`mode: "default"` accepts the product's full bundle. Buyers who manage
selection through lists keep using `collection_list` /
`collection_list_exclude` refs.
```json theme={null}
"targeting_overlay": {
"collection_selection": {
"mode": "selected",
"collections": [{
"publisher_domain": "channel-owner.example",
"collection_ids": ["retro_news"]
}]
}
}
```
On package readback, `collection_selection` is also the audit surface: sellers
MUST echo the committed collection selection there as concrete selectors —
including the materialized result of any `collection_list` composition — so a
buyer can verify what content programming a package runs against without
re-resolving mutable lists or re-fetching the product catalog. A purchase made
with `mode: "default"` therefore reads back as `mode: "selected"` naming the
product's complete bundle; the `default` branch carries no selectors and
cannot satisfy the echo. For a channel
buy this is the readback of the one axis that makes the product distinct: the
channel itself.
## Multi-collection bundles
A single product can span multiple collections by listing multiple collection IDs in `collections`. When a product has multiple collections, each installment MUST include canonical `collection_ref` so the buyer agent knows both the parent collection and its publisher namespace. The deprecated `collection_id` shorthand is only unambiguous for single-namespace products.
```json theme={null}
{
"products": [
{
"product_id": "technet_april_bundle",
"name": "TechNet Podcast Bundle - April",
"collections": [{ "publisher_domain": "technet.example.com", "collection_ids": ["tech_weekly", "startup_hour"] }],
"installments": [
{ "installment_id": "tw_ep12", "collection_ref": { "publisher_domain": "technet.example.com", "collection_id": "tech_weekly" }, "scheduled_at": "2026-04-07T10:00:00Z", "status": "scheduled" },
{ "installment_id": "tw_ep13", "collection_ref": { "publisher_domain": "technet.example.com", "collection_id": "tech_weekly" }, "scheduled_at": "2026-04-14T10:00:00Z", "status": "tentative" },
{ "installment_id": "sh_ep30", "collection_ref": { "publisher_domain": "technet.example.com", "collection_id": "startup_hour" }, "scheduled_at": "2026-04-09T14:00:00Z", "status": "scheduled" },
{ "installment_id": "sh_ep31", "collection_ref": { "publisher_domain": "technet.example.com", "collection_id": "startup_hour" }, "scheduled_at": "2026-04-16T14:00:00Z", "status": "tentative" }
],
"delivery_type": "guaranteed",
"pricing_options": [
{ "pricing_option_id": "bundle", "pricing_model": "flat_rate", "fixed_price": 25000, "currency": "USD" }
]
}
]
}
```
### Print publication with issues
A magazine publisher selling display ads across upcoming issues. Each issue is an installment with deadlines for booking, cancellation, and material delivery:
```json theme={null}
{
"products": [
{
"product_id": "vogue_de_display_q2",
"name": "Vogue Germany — Display Ads, Q2 2026",
"channels": ["print"],
"collections": [{ "publisher_domain": "vogue.de", "collection_ids": ["vogue_de"] }],
"installments": [
{
"installment_id": "2026-04",
"name": "April 2026",
"season": "2026",
"installment_number": "4",
"scheduled_at": "2026-04-01T00:00:00+02:00",
"status": "scheduled",
"deadlines": {
"booking_deadline": "2026-02-15T17:00:00+01:00",
"cancellation_deadline": "2026-02-22T17:00:00+01:00",
"material_deadlines": [
{ "stage": "draft", "due_at": "2026-03-01T17:00:00+01:00", "label": "Artwork for color proofing" },
{ "stage": "final", "due_at": "2026-03-08T17:00:00+01:00", "label": "Press-ready PDF/X-4, CMYK, 300 DPI" }
]
}
},
{
"installment_id": "2026-05",
"name": "Mai 2026",
"season": "2026",
"installment_number": "5",
"scheduled_at": "2026-05-01T00:00:00+02:00",
"status": "scheduled",
"deadlines": {
"booking_deadline": "2026-03-15T17:00:00+01:00",
"cancellation_deadline": "2026-03-22T17:00:00+01:00",
"material_deadlines": [
{ "stage": "draft", "due_at": "2026-03-29T17:00:00+01:00", "label": "Artwork for color proofing" },
{ "stage": "final", "due_at": "2026-04-05T17:00:00+02:00", "label": "Press-ready PDF/X-4, CMYK, 300 DPI" }
]
}
}
],
"placements": [
{ "kind": "seller_inline", "placement_id": "full_page", "name": "Full Page", "mode": "targetable" },
{ "kind": "seller_inline", "placement_id": "dps", "name": "Double Page Spread", "mode": "targetable" },
{ "kind": "seller_inline", "placement_id": "ifc", "name": "Inside Front Cover", "mode": "targetable" }
],
"delivery_type": "guaranteed",
"delivery_measurement": {
"provider": "IVW",
"notes": "Verified circulation, updated quarterly"
},
"pricing_options": [
{ "pricing_option_id": "full_page", "pricing_model": "flat_rate", "fixed_price": 28000, "currency": "EUR" },
{ "pricing_option_id": "dps", "pricing_model": "flat_rate", "fixed_price": 48000, "currency": "EUR" }
]
}
]
}
```
The collection/installment model works identically for print publications and audio/video content. The installment's `deadlines` object replaces what the German OBS system handles through separate message exchanges — booking, cancellation, and material delivery are all visible upfront.
## See also
* [Media products](/dist/docs/3.2.8/media-buy/product-discovery/media-products) — the full product model
* [Print ads](/dist/docs/3.2.8/creative/channels/print) — print-specific creative formats, physical dimensions, bleed, and DPI
* [brand.json](/dist/docs/3.2.8/brand-protocol/brand-json) — talent identity and brand safety evaluation
* [Product discovery](/dist/docs/3.2.8/media-buy/product-discovery) — how buyers discover inventory via `get_products`
# Example campaign discovery requests
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/product-discovery/example-briefs
Worked examples showing how buyer agents decompose natural-language campaign requests into briefs, filters, targeting overlays, and future targeting support.
The examples below start with what a human says, then show the structured
`request_proposals` request an agent should send. The goal is not to make the brief
verbose. Preserve campaign meaning in prose and move exact values into typed
fields.
## Local service launch
### Human request
> Help Acme Home Services drive appointment calls from homeowners in Colorado
> during October. We have \$8,000 and only want display inventory priced in USD.
### AdCP request
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441101",
"brand": { "domain": "acmehome.example" },
"brief": "Drive appointment calls from homeowners who may need urgent or planned home repairs. Favor trusted local and home-improvement contexts.",
"criteria": {
"offer_filters": {
"channels": ["display"],
"pricing_currencies": ["USD"],
"start_date": "2027-10-01",
"end_date": "2027-10-31",
"budget_range": { "max": 8000, "currency": "USD" }
},
"targeting_overlay": {
"geo_regions": ["US-CO"]
}
}
}
```
The seller interprets “homeowners” and contextual fit. It does not infer the
state, channel, currency, dates, or budget.
## Multi-country B2B campaign
### Human request
> Pinnacle Cloud wants qualified leads from technical leaders at growing
> businesses in the US, Canada, UK, and Germany. We need display or online
> video, USD or EUR pricing, and completed-view reporting where video is used.
### AdCP request
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441102",
"brand": { "domain": "pinnaclecloud.example" },
"brief": "Generate qualified leads from technical leaders modernizing multi-cloud infrastructure. Favor trusted technology, security, and business contexts.",
"criteria": {
"offer_filters": {
"channels": ["display", "olv"],
"pricing_currencies": ["USD", "EUR"],
"required_metrics": ["completed_views"]
},
"targeting_overlay": {
"geo_countries": ["US", "CA", "GB", "DE"]
}
}
}
```
The brief carries job-function meaning because AdCP does not impose one global
taxonomy for “technical leader.” Geography and product requirements are exact.
## Known country, cities selected later
### Human request
> Nova Meals is launching nationally to parents ages 25–44. After we compare
> forecasts, our planners will choose separate DMAs and placements for each
> package. We do not want one product returned per city.
### AdCP request
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441103",
"brand": { "domain": "novameals.example" },
"brief": "Launch a premium family meal service to time-pressed parents. Favor trusted family, food, and lifestyle contexts.",
"criteria": {
"targeting_overlay": {
"geo_countries": ["US"],
"demographics": {
"age": { "min": 25, "max": 44, "include_unknown": false }
}
},
"required_overlay_support": {
"geo_metros": { "systems": ["nielsen_dma"] },
"placement_selection": true
}
}
}
```
`targeting_overlay` is applied now and participates in every returned forecast.
`required_overlay_support` filters to products that let packages select DMAs
and placements later. It does not create a product or package per value.
## Hard prose fallback
Structured-first authoring is a SHOULD, not permission for sellers to ignore
prose. If a buyer sends:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441104",
"brand": { "domain": "acmeoutdoor.example" },
"brief": "Hard requirements: US delivery only and ages 25–44. Favor outdoor enthusiasts."
}
```
the seller still applies the hard constraints and, because they affect product
eligibility, pricing, and forecasting, must confirm the structured interpretation
in `targeting_resolution.brief_targeting`. The buyer should not infer
confirmation from a missing resolution.
Legacy callers can express the same decomposition through `get_products` with
`buying_mode: "brief"`, top-level `filters`, `targeting_overlay`, and
`required_overlay_support`. The split tasks are preferred because they make
the listing, proposal, and refinement lifecycle explicit.
## Practice
Decompose this request before revealing the answer:
> Acme Audio has \$75,000 for a six-week US podcast launch. Only USD pricing.
> We need completion reporting, want music and technology enthusiasts, and will
> choose individual shows after reviewing the publisher's recommendations.
> [accordion] Show one valid decomposition
>
> * Brief: launch context plus music and technology enthusiast intent.
> * Offer filters: podcast channel, USD currency, six-week dates, \$75,000 budget, and
> required completion metric.
> * Targeting overlay: US.
> * Required overlay support: placement or collection selection later, depending
> on how the seller models public shows.
## Review every response
Before purchase:
1. Confirm offer filters excluded ineligible offers.
2. Confirm forecast and price reflect the structured overlay.
3. Verify `overlay_support` covers every later-selectable requirement.
4. Review `targeting_resolution.modifications` and any `brief_targeting`.
5. Accept a configured product only when its complete targeting resolution is
acceptable.
# Product discovery and planning
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/product-discovery/index
Choose the AdCP 3.2 path for published product offers, wholesale feed synchronization, or seller-planned proposals.
AdCP 3.2 separates reading published offers from asking a seller to build a
plan. Start by reading `get_adcp_capabilities.media_buy.lifecycle_tools`, then
choose the path the seller advertises.
| Buyer intent | Start with | Commit with |
| - | - | - |
| Browse or filter published offers | [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) | [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) |
| Maintain a wholesale product mirror | `list_products`, feed versions, and account-level product webhooks | `buy_products`, or pass selected IDs into `request_proposals` |
| Ask the seller to build or negotiate a plan | [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) | Finalize with `refine_proposals`, then [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) |
> [!NOTE]
>
> Wholesale is a product-feed topology, not a proposal mode. A mirror tracks the
> seller's published offers and pricing. Proposal tasks create immutable,
> seller-authored commercial snapshots for a specific planning conversation.
## Both surfaces are optional; neither outranks the other
Sellers choose which discovery surfaces to offer, and `lifecycle_tools` is the
complete statement of that choice. A seller that omits `list_products` offers
no wholesale feed — like a company that quotes through a sales conversation
rather than a self-serve signup page. A seller that omits `request_proposals`
sells only published offers. Both are fully conformant; no conformance
scenario requires the wholesale path, and the advertised subset carries no
implication about inventory breadth or planning capability.
The two surfaces serve different buying modes. The wholesale feed is the
self-serve, lower-resolution surface: the buyer brings its own intelligence
and selects published offers directly, much as it would on an open exchange.
A brief through `request_proposals` is the higher-resolution surface: the
seller plans against the buyer's actual intent. Buyers SHOULD use both
surfaces where the seller advertises them. A wholesale feed is a seller's
published-offer subset, not a capability assessment, and buyers SHOULD NOT
rank or filter sellers by feed breadth or feed absence.
Every product in a feed is a purchasable offer: `buy_products` transacts it
exactly as listed under its `feed_version`. Sellers demonstrate built-to-brief
capability by answering briefs, not by publishing representative products that
cannot be bought as listed.
## 1. Discover the available lifecycle
Do not infer compact-tool support from the protocol version alone. Use the
seller's advertised lifecycle tools:
```javascript theme={null}
const capabilities = await seller.getCapabilities();
const lifecycleTools = new Set(capabilities.mediaBuyLifecycleTools ?? []);
const canBuyPublishedOffers =
lifecycleTools.has('list_products') && lifecycleTools.has('buy_products');
const canNegotiate =
lifecycleTools.has('request_proposals') &&
lifecycleTools.has('refine_proposals') &&
lifecycleTools.has('accept_proposal');
```
The field names above use the TypeScript SDK's normalized capability view.
On the wire, inspect `media_buy.lifecycle_tools`.
## 2. Express criteria once
Both `list_products` and `request_proposals` accept
`ProductDiscoveryCriteria`. Keep three concerns separate:
* `offer_filters` select commercial and product characteristics such as
channel, delivery type, currency, and reporting support.
* `targeting_overlay` contains concrete delivery constraints that must affect
the returned product, price, and forecast.
* `required_overlay_support` asks for targeting dimensions that the buyer will
select later; it is a capability requirement, not a current target value.
```json theme={null}
{
"offer_filters": {
"channels": ["olv"],
"pricing_currencies": ["USD"]
},
"targeting_overlay": {
"geo_countries": ["US", "CA"]
},
"required_overlay_support": {
"demographics": { "age": true }
}
}
```
Products return canonical `format_options[]` as their closed accepted creative
set. Resolve publisher-backed definitions from `adagents.json.formats[]`; use a
creative agent's capability IDs to choose production operations.
## Published offers and wholesale mirrors
Use `list_products` when the buyer wants to inspect seller-published offers
without asking the seller to author a media plan:
```javascript theme={null}
const result = await seller.listProducts({
adcp_version: '3.2',
account: { account_id: 'account_123' },
criteria: {
offer_filters: {
channels: ['olv'],
pricing_currencies: ['USD'],
},
targeting_overlay: { geo_countries: ['US', 'CA'] },
},
max_results: 25,
});
```
The response contains products only—never proposals—and carries an opaque
`feed_version`. A direct buyer passes that version and selected product terms
to `buy_products` so the seller can reject stale offers instead of silently
applying changed terms.
When discovery includes concrete `targeting_overlay` values, inspect each
returned product before purchase:
* No product-level `targeting_resolution` means the product accepts the
requested structured overlay exactly.
* `targeting_resolution.modifications` is an ordered, sparse disclosure of the
alternative the seller can execute. Selecting that `product_id` accepts the
modified result.
* A request-specific configured product carries `expires_at`; compact
products have no `is_custom` flag. Purchase that exact ID before expiry; do
not substitute the baseline product ID or send a conflicting overlay at
commitment.
After `buy_products`, verify that the package readback preserves the accepted
targeting. If the buyer requested only `required_overlay_support`, rediscover
with concrete values before purchase when it needs a value-specific price or
forecast; support alone does not promise inventory for every later value.
A catalog mirror uses the same read as its bootstrap and repair surface. Store
`feed_version`, `pricing_version`, and `cache_scope`; subscribe to `product.*`
and `wholesale_feed.bulk_change` through account notification configuration;
then use conditional `list_products` reads to repair gaps. Do not poll the full
feed when the webhook stream is healthy.
See [`list_products` wholesale feed webhooks](/dist/docs/3.2.8/media-buy/task-reference/list_products#wholesale-feed-webhooks)
for the complete mirror contract.
## Seller-planned proposals
Use `request_proposals` when the seller should translate a campaign brief into
one or more priced plans. Sam at Pinnacle Agency can send the same
structured criteria to StreamHaus while keeping strategy in prose:
```javascript theme={null}
const response = await seller.requestProposals({
adcp_version: '3.2',
idempotency_key: 'acme-q2-proposals-001',
account: { account_id: 'account_123' },
brand: { domain: 'acme-outdoor.example' },
brief:
'Premium video on trusted sports and outdoor lifestyle properties for the Acme Outdoor Q2 launch. Prioritize reach within a USD 50,000 ceiling.',
criteria: {
offer_filters: {
channels: ['olv'],
pricing_currencies: ['USD'],
},
targeting_overlay: { geo_countries: ['US', 'CA'] },
},
});
```
The seller returns immutable draft proposals. Each revision creates a new
`proposal_id` and preserves its parent:
1. Use `refine_proposals` with `action: "revise"` for typed budget, CPM,
flight, product, alternative, or targeting changes.
2. Verify every returned typed constraint; a `partial` outcome identifies the
exact unsatisfied fields.
3. Use `refine_proposals` with `action: "finalize"` to create a committed,
expiring inventory hold.
4. Call `accept_proposal` with both the committed `proposal_id` and
`terms_digest` before `expires_at`.
The criteria and any configured product targeting are part of the proposal's
commercial terms. Before finalizing, verify the selected product IDs, effective
targeting or disclosed modifications, price, forecast assumptions, and expiry;
after acceptance, confirm the same targeting on package readback.
Commercial changes after acceptance use the same proposal lineage to create an
amendment or negotiated cancellation. Operational changes inside the accepted
envelope use [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy).
When the seller offers post-acceptance change rights, it places them in
`commercial_terms.change_terms[]`. Each entry names one canonical action, its
service mode, lifecycle statuses, an optional elapsed-time processing SLA,
portable constraints, stable conditions, and an optional contract reference.
Because the array is inside `commercial_terms`, the proposal `terms_digest`
binds those rights. When the array is present, an omitted action was not
negotiated; omission of the entire array preserves the legacy
unspecified-rights behavior.
Treat the three action surfaces as a narrowing sequence:
| Surface | Buyer question | Meaning |
| - | - | - |
| Product `allowed_actions[]` | Could this product support the change? | Advisory selection template |
| Proposal `commercial_terms.change_terms[]` | What change rights does this deal promise? | Binding contractual ceiling |
| MediaBuy `available_actions[]` | What can I invoke now? | Authoritative current-state projection |
The proposal must restate any product constraint that becomes binding. A live
action links back through `change_term_id`; product and change-term `terms_ref`
remain document references, not identities or authority grants.
The accepted rights bind to the resulting media buy and account, not to the
individual agent that accepted the proposal. A delegated operator
may exercise a right only when both gates admit the call: seller-side account
authorization (`allowed_tasks` and any `field_scopes`) and the buyer's signed
governance delegation. Neither gate expands the other.
See [Proposal negotiation](/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation)
for request shapes, failure planes, finalization, and recovery.
## Catalog-driven campaigns
Retail media, travel, job, and other catalog-driven campaigns pass a compact
catalog selection in `criteria.catalog`. The seller matches the buyer-managed
catalog to eligible offers; ingest or update the underlying feed separately
through [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs).
## Compatibility path
If `media_buy.lifecycle_tools` is absent, use the established `get_products`,
`create_media_buy`, and `update_media_buy` facade documented in the
[3.1 → 3.2 migration guide](/dist/docs/3.2.8/reference/migration/3-1-to-3-2). Keep this
branch at the version-adaptation boundary so new planning code works in terms
of published offers, proposal snapshots, and revision-checked controls.
## Next steps
* [Media buy lifecycle](/dist/docs/3.2.8/media-buy/media-buys/lifecycle) — commitment,
creative supply, control, and delivery
* [Media products](/dist/docs/3.2.8/media-buy/product-discovery/media-products) — product,
pricing, targeting, and format semantics
* [Brief expectations](/dist/docs/3.2.8/media-buy/product-discovery/brief-expectations) —
what belongs in prose versus structured criteria
* [Task reference](/dist/docs/3.2.8/media-buy/task-reference/) — compact lifecycle request
and response contracts
# Media Products
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/product-discovery/media-products
AdCP media products — the core sellable unit in the protocol. Covers product structure, pricing options, delivery types, format references, and catalog-driven inventory.
A **Product** is the core sellable unit in AdCP. This document details the Product model, including its pricing and delivery types, and how products are discovered and structured in the system.
> [!TIP]
>
> **Pricing Models**
> Products declare which pricing models they support. Buyers select a specific pricing option when creating media buys. See the complete [Pricing Models Guide](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models) for details on CPM, CPCV, CPP, CPC, CPA, vCPM, flat rate, and time-based pricing.
## The Product Model
* `product_id` (string, required): Opaque buyable identifier. Non-custom wholesale IDs remain stable for the same logical offer within seller and declared cache scope, including across reads and webhooks. Custom IDs remain stable only within their issuing discovery/refinement lineage.
* `name` (string, required)
* `description` (string, required)
* `publisher_properties` (list\[PublisherPropertySelector], required): Publisher properties covered by this product. See [Property Targeting](#property-targeting).
* `channels` (list\[MediaChannel], optional in 3.x): Advertising channels this product is sold as (e.g., `["retail_media"]`, `["display", "olv"]`). Sellers SHOULD explicitly declare at least one channel on every product. Products inherit from their properties' `supported_channels` but may narrow the scope; product channels SHOULD be a subset of the union of those property channels. See [Media channel taxonomy](/dist/docs/3.2.8/reference/media-channel-taxonomy).
* `video_placement_types` (list\[string], optional): Declared video placement types that may be included in this product, using IAB Tech Lab/OpenRTB 2.6 `video.plcmt` definitions with AdCP-native names: `instream`, `accompanying_content`, `interstitial`, and `standalone`. Aggregate products and ad-network products may include multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
* `audio_distribution_types` (list\[string], optional): Declared audio distribution types that may be included in this product, using IAB Tech Lab/OpenRTB 2.6 `audio.feed` definitions with AdCP-native names: `music_streaming_service`, `fm_am_broadcast`, `podcast`, `catch_up_radio`, `web_radio`, `video_game`, and `text_to_speech`. Aggregate products and ad-network products may include multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
* `sponsored_placement_types` (list\[string], optional): Declared sponsored-placement types for catalog-driven retail-media products: `sponsored_search`, `sponsored_display`, and `sponsored_native`. Aggregate products and ad-network products may include multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
* `social_placement_surfaces` (list\[string], optional): Declared social-placement surfaces for social products: `feed`, `stories`, `short_video`, `explore`, and `search`. Aggregate products and ad-network products may include multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
* `format_options` (list\[ProductFormatDeclaration], required for 3.2 authoring): Canonical format declarations accepted by this product. Product-level formats are the upper bound for the sellable product; placement-level formats can narrow this set but cannot add formats or `locale_policy` ranges the product does not accept. A declaration's optional `locale_policy.accepted_language_ranges` exposes seller-enforced creative-language eligibility before purchase. Buyer `FormatOptionRef` selectors use `{scope: "publisher", publisher_domain, format_option_id}` for publisher-declared options and `{scope: "product", format_option_id}` for product-local options.
* `format_ids` (list\[FormatID], deprecated compatibility only): Optional projection for older 3.x peers. A 3.2 seller must not use this field as its only authored creative contract. When both fields are emitted, every legacy reference must resolve to the same underlying declaration in `format_options`. See [Creative Formats](/dist/docs/3.2.8/creative/formats).
* `placements` (list\[Placement], optional): Specific public ad placements within this product. Each placement declares `kind` (`publisher_ref` or `seller_inline`) and `mode` (`targetable` or `included`); seller-private delivery objects are not exposed here. See [Placements](#placements).
* `collections` (list\[CollectionSelector], optional): Collections covered by this product, grouped by publisher. Each entry has `publisher_domain` and `collection_ids` referencing collections declared in that domain's `adagents.json` — which may be an external channel owner's domain, not the seller's. See [Collections and installments](/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments).
* `installments` (list\[Installment], optional): Specific installments available within this product. See [Collections and installments](/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments).
* `delivery_type` (string, required): Either `"guaranteed"` or `"non_guaranteed"`.
* `exclusivity` (string, optional): Whether this product offers exclusive access. `"none"` (default when absent) — multiple advertisers can buy simultaneously. `"category"` — one advertiser per industry category. `"exclusive"` — sole sponsorship. Most relevant for guaranteed products tied to specific shows or placements.
* `pricing_options` (list\[PricingOption], required): Array of available pricing models for this product. A binding option applies uniformly across later values permitted by `overlay_support`; a changed fixed price, floor, currency, model, or priced applicability receives a new `pricing_option_id`. Sellers with value-dependent rates use concretely targeted configured products, separate rate-tier products, or non-binding guidance. See [Pricing Models](#pricing-models).
* `delivery_measurement` (object, optional): Who measures ad delivery — the ad server and viewability vendor used to count impressions. New implementations populate `vendors` as a structured `BrandRef` array (e.g., `[{ "domain": "googleadmanager.com" }, { "domain": "integralads.com" }]`); the legacy `provider` string is deprecated. When absent, buyers should apply their own measurement defaults. See [Delivery Measurement](#delivery-measurement).
* `outcome_measurement` (OutcomeMeasurement, **deprecated**): Legacy field for declaring business outcome measurement (lift, brand lift, foot traffic). New implementations declare outcome metrics via `reporting_capabilities.available_metrics` and pin attribution methodology + window via the `qualifier` slot on `committed_metrics`. Retained for one-minor backwards compatibility; removed at the next major. See [Commerce Media](/dist/docs/3.2.8/media-buy/commerce-media) for the migration pattern.
* `creative_policy` (CreativePolicy, optional): Creative requirements and restrictions.
* `is_custom` (bool, optional): `true` for any request-specific configured offer, including exact structured targeting, disclosed targeting changes, or request-bound price, forecast, inventory, or terms.
* `expires_at` (datetime, conditionally required): Required for a request-specific product issued through targeting-aware discovery and whenever `targeting_resolution` is present. Earlier custom products remain schema-valid when it is absent. After this time, a recognized expired ID issued to the authenticated account and lineage returns `PRODUCT_EXPIRED`; an ID whose tombstone is no longer retained or belongs to another account/lineage returns `PRODUCT_NOT_FOUND`, preventing cross-tenant existence disclosure.
* `overlay_support` (TargetingOverlaySupport, optional): Product-scoped targeting dimensions whose values may be selected later. Required when requested through `required_overlay_support`. It guarantees selectable capability subject to disclosed limits, not inventory or a forecast for every value.
* `identity` (object, optional, experimental): Product-scoped persistent-identifier and custom-reach-methodology facts. A product declaring `persistent_identifier: false` omits `overlay_support.frequency_cap` and `overlay_support.frequency_cap_support`; `devices`, `accounts`, and `cookies` are not valid delivery reach units for it, while modeled `individuals` and `households` remain valid. Its frequency-only delivery rows carry `reach_unit`; a custom unit reported with either reach or frequency requires `identity.reach_methodology`. Sellers using this surface list `media_buy.product_identity` in `experimental_features`; see [Product identity absence and reach reporting](/dist/docs/3.2.8/media-buy/specification#product-identity-absence-and-reach-reporting-experimental).
* `execution_requirements` (list\[ProductExecutionRequirement], optional, experimental): Account resources a package on this product needs before `create_media_buy` succeeds — an `event_source` bound through `optimization_goals[].event_sources[]`, a `catalog` of one of the listed types bound through `packages[].catalogs[]` (use `"app"` for app promotion), or a `downstream_connection` such as the publisher identity the ads run as. Every entry is required. The declaration is account-independent and does not change `cache_scope`; when present, together with the selected formats' `required_connections`, it is complete for these kinds. Sellers using this surface list `media_buy.execution_requirements` in `experimental_features`; see [Product execution requirements](/dist/docs/3.2.8/media-buy/specification#product-execution-requirements-experimental).
* `targeting_resolution` (ProductTargetingResolution, optional): Sparse differences from a structured overlay. Absence confirms exact acceptance of that product's structured overlay, but not how prose was interpreted; response-level `targeting_resolution.brief_targeting` confirms hard brief interpretation once for the result set when that interpretation materially affects eligibility, pricing, or forecasting. Presence requires `is_custom: true` and `expires_at`.
* `list_applications` (list\[InventoryListApplication], conditionally required): One product-scoped receipt for every effective property- or collection-list targeting reference, regardless of field projection. Exclusion applications receive a receipt even when they match zero entries; zero matches for any inclusion application make the product ineligible, so it is not returned. Each receipt identifies the list without echoing separately supplied fetch credentials, records `resolved_at` and `evaluated_at`, and partitions the resolved snapshot into `summary.matched` and `summary.unmatched`. Counts apply to this product only; pricing and forecasts reflect the eligible inventory after all effective lists are composed.
* `property_targeting_allowed` (bool, optional, default: false): Whether buyers can filter this product to a subset of its `publisher_properties`. When `false` (default), the product is "all or nothing" - buyers must accept all properties or the product is excluded from `property_list` filtering results. See [Property Targeting](#property-targeting).
* `collection_targeting_allowed` (bool, optional, default: false): Whether buyers can target a subset of this product's `collections`. When `false` (default), the product is a bundle — buyers get all listed collections. When `true`, buyers can select specific collections in the media buy.
* `data_provider_signals` (list\[DataProviderSignalSelector], **deprecated**): Legacy/non-selectable metadata for data-provider signals already bundled into or associated with this product. New implementations should use `included_signals`.
* `included_signals` (list\[SignalListing], optional): Non-selectable signal metadata for signals already included in, bundled with, or planned into this product. These describe what the product is; buyers do not select them in package `signal_targeting_groups`.
* `signal_targeting_allowed` (bool, optional, default: false): Whether this product has a package-level signal targeting surface. Editability is controlled by `signal_targeting_rules`.
* `signal_targeting_options` (list\[ProductSignalTargetingOption], optional): Inline seller-offered signals that may be buyer-selected or seller-applied for this product. These may be product-local signal options or data-provider signals the seller is authorized to apply. See [Signal Targeting](#signal-targeting).
* `signal_targeting_rules` (SignalTargetingRules, optional): Composition rules such as single/multi-select limits for the selectable signals.
* `audience_evidence` (list\[AudienceEvidence], optional): Immutable, digest-pinned population evidence explaining audience composition, affinity, or estimated reach. This is planning evidence, not exact targeting or legal-age verification. See [Audience evidence](#audience-evidence).
* `audience_evidence_selections` (list\[AudienceEvidenceSelection], optional): Exact evidence snapshots that satisfied a required evidence policy or affected ranking for this discovery result.
* `catalog_types` (list\[string], optional): Catalog types this product supports for catalog-driven campaigns. A sponsored product listing declares `["product"]`, a job board declares `["job", "offering"]`. Buyers match synced catalogs to products via this field. See [Catalogs](/dist/docs/3.2.8/creative/catalogs).
* `catalog_match` (object, optional): When the buyer provides a `catalog` on `get_products`, indicates which catalog items are eligible for this product. Contains `matched_gtins` (cross-retailer GTIN matches), `matched_ids` (generic item ID matches), `matched_count`, and `submitted_count`.
* `metric_optimization` (object, optional): Metric optimization capabilities for this product. Presence indicates the product supports `optimization_goals` with `kind: "metric"`. See [Metric optimization](#metric-optimization).
* `max_optimization_goals` (integer, optional): Maximum number of `optimization_goals` this product accepts on a package. When absent, no limit is declared. Most social platforms accept only 1.
* `conversion_tracking` (object, optional): Conversion event tracking capabilities. Presence indicates the product supports `optimization_goals` with `kind: "event"`. See [Conversion tracking](#conversion-tracking-1).
* `product_card` (object, optional): Visual card definition for displaying this product in user interfaces. See [Product Cards](#product-cards).
## Product channel declarations
An explicit product declaration distinguishes the buying context from the broader channels its properties support. The existing 3.x property-based inheritance remains unchanged, but sellers SHOULD explicitly declare a nonempty `channels` array on every product so buyers do not have to rely on that fallback. Creative formats and seller-wide `portfolio.primary_channels` do not independently declare a product's channels: the same VAST video format can serve both online video (`olv`) and connected TV (`ctv`). Buyers can use explicit product channels for channel-specific discovery, proposal routing, and planning. These declarations are seller metadata, not independent verification of delivery context or proof of per-channel delivery totals for a multi-channel product.
When using a `fields` projection, buyers should include `channels` before classifying the product. Omission from a projection that did not request `channels` does not establish that the seller failed to declare it. A missing or empty array supplies no explicit product channel values; this guidance does not replace the existing 3.x inheritance behavior or require buyers to exclude legacy products that rely on it. Omission is not a wildcard for every channel in the taxonomy.
A format option's optional `applies_to_channels` narrows the product's declared channels and must be a subset of them. Omitting `applies_to_channels` makes that option applicable to every channel declared on the product, not every channel in the taxonomy. The option does not independently declare the product's channels.
The [4.0 proposal in #7869](https://github.com/adcontextprotocol/adcp/issues/7869) would require `channels` with at least one `MediaChannel` value on every Product. This is a proposed breaking change; 3.x still accepts omitted or empty arrays. Sellers can prepare now by declaring each product's actual channels. See [Preparing product channels for 4.0](/dist/docs/3.2.8/reference/migration/channels#preparing-product-channels-for-4-0).
## Property and collection list application receipts
Property and collection lists are resolved outside the seller, but their inventory effect is product-specific. Whenever effective discovery targeting contains `property_list`, `property_list_exclude`, `collection_list`, or `collection_list_exclude`, the seller MUST return one `list_applications` receipt for each targeting reference on every returned product. This requirement overrides a narrow `fields` projection. An exclusion application returns a zero-match receipt; zero matches for any inclusion application leave no eligible inventory, so the seller MUST omit that product. If the same list is referenced for both inclusion and exclusion, those are separate applications and produce separate receipts on any product that remains eligible.
```json theme={null}
{
"product_id": "streamhaus_ctv_01",
"list_applications": [
{
"list_type": "collection",
"effect": "exclude",
"agent_url": "https://governance.pinnacleagency.com",
"list_id": "cl_novamotors_dna_2026",
"resolved_at": "2026-08-24T09:00:00Z",
"evaluated_at": "2026-08-24T09:00:02Z",
"summary": {
"matched": 59,
"unmatched": 141
}
}
]
}
```
`list_type` and `effect` identify which targeting field was applied: `property` + `include` corresponds to `property_list`, `property` + `exclude` to `property_list_exclude`, and likewise for collection lists. `agent_url` and `list_id` MUST equal the effective request reference. The seller MUST NOT echo `auth_token` or any other fetch credential.
Every receipt independently partitions all entries in its resolved snapshot against the same product inventory before any effective list is applied. This common baseline makes overlapping lists and array order irrelevant. The counts do not assert the seller's library-wide coverage or another product's result. Product price and forecast reflect the eligible inventory after all effective lists are composed.
`resolved_at` identifies the complete snapshot the seller evaluated. When the governance response supplies `resolved_at`, the seller copies it; otherwise the seller records when it completed assembling the snapshot, including all fetched pages. `evaluated_at` records the later product-inventory comparison. A later discovery response, or a proposal revision that reevaluates products, returns fresh timestamps and counts. Finalizing unchanged proposal terms does not reevaluate products and MAY repeat the receipts already bound to that proposal.
### Pass-through product sources
Schema validity is not the same as format resolvability. The shared 3.x Product schema still accepts a legacy-only `format_ids[]` product so older sellers remain readable, but each `{agent_url, id}` is only useful when the consuming path also fetches and resolves that named-format catalog.
AdCP 3.2 intermediaries that import or pass through upstream products MUST require upstream `format_options[]`, or fetch and authoritatively resolve every referenced legacy format before translating it into canonical declarations. That translation MUST preserve the resolved constraints losslessly or narrow them explicitly; intermediaries MUST NOT guess dimensions, slots, codecs, durations, or other constraints from a format ID. If authoritative resolution or safe translation fails, omit or reject the product with an actionable error. Intermediaries MUST NOT pass through a legacy-only product on a source path that does not resolve its format catalog, and buyers MUST NOT infer legacy resolvability from schema validation alone.
### Metric optimization
Products that support `optimization_goals` with `kind: "metric"` declare their capabilities in `metric_optimization`. No event source or conversion tracking setup is required for metric goals — the seller tracks these metrics natively.
```json theme={null}
{
"metric_optimization": {
"supported_metrics": ["clicks", "views", "completed_views", "engagements"],
"supported_view_durations": [2, 6, 15],
"supported_targets": ["cost_per", "threshold_rate"]
}
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `supported_metrics` | string\[] | Yes | Metric kinds this product can optimize for. Buyers should only request metric goals for kinds listed here. |
| `supported_view_durations` | number\[] | No | Video view duration thresholds (in seconds) supported for `completed_views` goals. When absent, the seller uses their platform default. |
| `supported_viewability_standards` | string\[] | No | Viewability standards (`mrc`, `groupm`) supported for `viewable_rate` goals. When present, the goal's `standard` must be listed here. |
| `supported_targets` | string\[] | No | Target kinds available: `cost_per`, `threshold_rate`. Values match `target.kind` on the optimization goal. Only listed kinds are accepted. When omitted, buyers can set target-less metric goals (maximize volume) but cannot set specific targets. |
### Conversion tracking
Products that support `optimization_goals` with `kind: "event"` declare their capabilities in `conversion_tracking`. Seller-level capabilities (supported event types, UID types, attribution windows) are declared in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities).
```json theme={null}
{
"conversion_tracking": {
"action_sources": ["website", "app"],
"supported_targets": ["cost_per", "per_ad_spend", "maximize_value"],
"platform_managed": false
}
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `action_sources` | string\[] | No | Action sources relevant to this product (e.g., a retail media product might have `in_store` and `website`). |
| `supported_targets` | string\[] | No | Target kinds available for event goals: `cost_per`, `per_ad_spend`, `maximize_value`. Values match `target.kind` on the optimization goal. Only listed kinds are accepted. When omitted, buyers can still set target-less event goals. |
| `platform_managed` | boolean | No | Whether the seller provides always-on measurement (e.g., retailer purchase attribution). When true, `sync_event_sources` returns seller-managed event sources. |
See [Conversion Tracking & Optimization Goals](/dist/docs/3.2.8/media-buy/conversion-tracking) for the full optimization goals reference.
### Audience evidence
`audience_evidence[]` gives a buyer structured reasons that inventory may suit an audience even when the seller cannot deterministically identify or target every user in that audience. Each item identifies an immutable `snapshot_id`, provider version, canonical `content_digest`, audience characteristic, relationship, baseline population, evidence type, population-level methodology, provider, measurement window, and freshness.
```json theme={null}
{
"audience_evidence": [
{
"evidence_id": "evidence_northstar_age_affinity",
"snapshot_id": "evidence_snapshot_2026_q2",
"version": "2026-q2",
"content_digest": "sha256:2a9cba3b29a6804e53bdb15a348b5e9741cfc613c210a91f61b0276655c5f1df",
"audience": {
"dimension": "age",
"range": { "min": 25, "max": 34 }
},
"relationship": "index",
"value": 1.8,
"unit": "ratio",
"baseline": {
"system": "https://measurement.example/populations",
"population_id": "us_adults",
"version": "2026-q2"
},
"evidence_type": "measured",
"methodology": "projected",
"subject_type": "individual",
"provider": { "domain": "measurement.example" },
"measurement_window": { "start": "2026-04-01", "end": "2026-06-30" },
"sample_size": 12000,
"confidence": 0.92,
"last_updated": "2026-07-15T00:00:00Z",
"methodology_url": "https://measurement.example/methodology/audience-projection"
}
]
}
```
The three concepts remain separate:
* `audience_evidence` says something about an inventory population.
* `demographic_targeting` and package targeting overlays say what the seller can execute for individual delivery decisions.
* age-restriction and identity-attestation surfaces handle legal compliance for a particular subject.
`content_digest` is SHA-256 over the RFC 8785 canonical evidence core with both `content_digest` and `attestation_refs` omitted. References are excluded so a later independent credential can be attached without changing the immutable evidence snapshot or creating a recursive digest. The built-in `age` characteristic uses completed years: values and range bounds are non-negative integers and `range.min` cannot exceed `range.max`.
`projected` is deliberately defined only for population evidence. It does not expand the user-level signal methodology vocabulary. Optional `attestation_refs[]` use the shared portable-attestation contract as an independent verification layer; they do not change `evidence_type`. Their subject identifies the exact evidence `snapshot_id` and carries the evidence `content_digest`. Evaluators still apply their own issuer and resolver allowlists.
When a buyer supplies evidence requirements and evidence affects product inclusion or rank, the returned Product carries `audience_evidence_selections[]` with the exact matching snapshots and `decision_use` of `eligibility` or `recommendation`. This decision readback is mandatory even when the buyer's `fields` projection omitted `audience_evidence_selections`; projection may omit the optional full evidence payload, not the explanation of an applied policy.
At buy time, a package can repeat `audience_evidence_requirements` and can carry `audience_evidence_pins[]` copied from discovery. Every pin includes `evidence_id`, `snapshot_id`, `version`, and `content_digest`; the seller rejects a missing or mutated snapshot instead of substituting current catalog content. The confirmed Package returns a matching `audience_evidence_selections[]` entry with `decision_use: "package_construction"` for every accepted pin and every snapshot used to satisfy package requirements, and preserves that readback on later package reads.
When an attestation affected either decision, readback preserves the exact reference and its `AttestationEvaluation` as one pair. That pair is valid only when the reference is published on the selected snapshot, its claim and issuer satisfy both buyer and seller policy, `reference_digest` covers that same reference, the outcome is `verified`, and both the subject digest and action-binding digest equal the evidence `content_digest`. An evaluation for one reference cannot verify a different reference. Sellers retain the full immutable snapshot and evaluations for at least as long as the package remains readable. Buyers should cache the evidence returned during discovery; AdCP 3.2 does not introduce a buyer-controlled snapshot fetch URL. Sellers may embed the full snapshot in readback, but need not duplicate it on every product or package.
### Audience activation
> [!NOTE]
>
> **Experimental** (`media_buy.audience_activation`). This surface is approved for AdCP 3.2 as experimental so implementers can try it: schemas carry `x-status: experimental`, sellers implementing it MUST list `media_buy.audience_activation` in `experimental_features`, and it may change between 3.x releases with notice. See [Experimental status](/dist/docs/3.2.8/reference/experimental-status).
The [`audience_targeting`](/dist/docs/3.2.8/protocol/get_adcp_capabilities#audience_targeting) capability describes *what identifiers* a seller matches on; `audience_activation` describes *how the data moves*. Two parties can both support audiences and remain practically incompatible — a buyer built around Snowflake sharing and a seller that only accepts API pushes discover that today at integration time, or worse, at activation time. Products that accept buyer audiences declare their activation paths so that mismatch surfaces during discovery.
```json theme={null}
"audience_activation": {
"methods": [
{ "pattern": "sync_audiences" },
{
"pattern": "dataset_query",
"vendor": { "domain": "data-cloud.example" },
"consumer_identities": [
{ "cloud": "aws", "region": "us-east-1", "identity": "SELLERORG.ADCP_INGEST" }
]
},
{
"pattern": "platform_distribution",
"vendor": { "domain": "activation-hub.example" },
"destination_ref": "dest_12345",
"bind_expiry_days": 14
}
],
"preferred_method": { "pattern": "sync_audiences" },
"notes": "Dataset ingestion runs daily at 06:00 UTC."
}
```
`methods` is an unordered set of activation capabilities. Entries are usually independent options; `clean_room` may compose with `dataset_query` or `platform_distribution` to declare the output rail. `preferred_method` (optional) names the seller's preference and MUST also appear in `methods`. Absence of `audience_activation` means undeclared — treat it as needs-clarification rather than non-support, except under an `audience_activation_methods` filter, where sellers MUST exclude undeclared products.
Schema: [`core/audience-activation-method.json`](https://adcontextprotocol.org/schemas/3.2.8/core/audience-activation-method.json)
#### Activation method patterns
Each entry declares a `pattern` plus pattern-specific fields. Vendor identity is a [BrandRef](/dist/docs/3.2.8/brand-protocol/brand-json) domain — new platforms declare a domain, no enum change required.
| Pattern | Required fields | Meaning |
| - | - | - |
| `sync_audiences` | — | Inline audience member pushes via the AdCP [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) task. Any AdCP-speaking buyer can use it. |
| `tmp_identity_match` | `buyer_agent.agent_url` | The seller has wired TMP identity-match calls to this specific buyer agent. Entries MUST be consistent with `trusted_match.providers[]` where both are present. |
| `file_transfer` | `transport`, `vendor` | Bucket-addressed file exchange (`s3`, `gcs`, `azure_blob`). Optional `directions` (`buyer_to_seller`, `seller_to_buyer`); absent means unspecified, not neither. |
| `dataset_query` | `vendor` | The seller reads a dataset the buyer shares through the vendor's grantee-identified sharing mechanism (Snowflake Secure Data Sharing, Databricks Delta Sharing, BigQuery authorized views). Optional `consumer_identities[]` lists the principals to grant. `identity` is required; paired `cloud` and `region` metadata is optional for deployment-scoped identities and omitted for global principals. Location semantics are vendor-specific: they can constrain direct-share reachability, select fulfillment, or provide routing/cost hints, but are not compliance boundaries. |
| `clean_room` | `vendor` | Privacy-preserving match in the named vendor's room. Declare this under audience activation only when the collaboration can produce an audience targetable on this product; analytics-only or measurement-only room access does not qualify. The declaration does not promise portable output. Room setup remains bilateral. |
| `platform_distribution` | `vendor` | The vendor's rails deliver segments to the seller's destination. The buyer initiates distribution in the vendor's system, then binds the arriving segment with a [`platform_segment` source reference](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences#external-audience-sources-experimental) on `sync_audiences`. Optional `destination_ref` is an opaque account-scoped destination or seat reference; omit it until bilateral setup establishes the destination. Optional `bind_expiry_days` declares when an unfulfilled bind may expire. |
Clean-room activation composes with the output rail rather than assuming every room behaves alike. Platform-native and partner-distributed audiences pair `clean_room` with `platform_distribution`; queryable outputs pair it with `dataset_query`. Cryptographic hashing protocols (such as PAIR) coordinate hashing with no centralized query environment and activate through a DSP: declare them as `clean_room` (pairing provider as vendor) + `platform_distribution` (DSP vendor) — not as `tmp_identity_match`, which covers request-time TMP matching, not batch cryptographic reconciliation. A room that only returns aggregate insights belongs in measurement or reporting capabilities, not `audience_activation`. This covers walled-garden rooms, independent collaboration providers, warehouse-native rooms, and cryptographic-hashing protocols.
A grant-based path is in-protocol only when the vendor flow is **grantee-identified** — the grant names a principal and no secret is conveyed. Token-bearer flows (presigned URLs, bearer-token activation links) remain out-of-band integrations.
Buyers filter discovery with [`filters.audience_activation_methods`](/dist/docs/3.2.8/media-buy/task-reference/get_products): OR across requested entries, AND within an entry, omitted optional fields are wildcards, `directions` matches on non-empty intersection (a method that omits `directions` matches any requested directions), and `vendor` matches on `domain` plus `brand_id` when specified.
**The runtime leg.** These declarations are the discovery half. The runtime step — telling the seller which share or arriving segment maps to which targetable audience — is an [external source reference on `sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences#external-audience-sources-experimental) (`dataset` for `dataset_query` grants, `platform_segment` for `platform_distribution` deliveries), under the same experimental feature id. Inline push works on any seller declaring `sync_audiences`; source references work on sellers declaring the corresponding grant/distribution patterns.
### Pricing Models
Publishers declare which pricing models they support for each product. Buyers select from the available options when creating a media buy. This approach supports:
* **Multiple pricing models per product** - Publishers can offer the same inventory via different pricing structures
* **Multi-currency support** - Publishers declare supported currencies per `pricing_options` entry; buyers can use `filters.pricing_currencies` during discovery to narrow media product transaction currencies and must use a supported currency at buy time
* **Flexible pricing** - Support for CPM, CPCV, CPP (GRP-based), CPA, and more
#### Supported Pricing Models
* **CPM** (Cost Per Mille) - Cost per 1,000 impressions (traditional display)
* **CPC** (Cost Per Click) - Cost per click on the ad
* **CPCV** (Cost Per Completed View) - Cost per 100% video/audio completion
* **CPV** (Cost Per View) - Cost per view at publisher-defined threshold
* **CPA** (Cost Per Acquisition) - Cost per conversion event (purchase, lead, signup, etc.)
* **Revenue Share** - Commission rate applied to settled attributed conversion value
* **CPP** (Cost Per Point) - Cost per Gross Rating Point (TV/audio)
* **Flat Rate** - Fixed cost regardless of delivery volume
* **Time** - Cost per time unit (day, week, month) that scales with campaign duration
#### PricingOption Structure
Each pricing option includes:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpcv-option.json",
"pricing_option_id": "cpcv_usd_guaranteed",
"pricing_model": "cpcv",
"fixed_price": 0.15,
"currency": "USD",
"min_spend_per_package": 5000
}
```
For auction-based pricing (no `fixed_price`), use `floor_price` for the seller's minimum and optional `price_guidance` for non-binding percentile hints. The buyer expresses execution intent separately through `bidding.bid_amount`, `bidding.max_bid`, `bidding.cost_per`, or `bidding.roas` on `create_media_buy`. Pricing-option `max_bid` and package `bid_price` are deprecated legacy migration fields in 3.2:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/pricing-options/cpm-option.json",
"pricing_option_id": "cpm_usd_auction",
"pricing_model": "cpm",
"currency": "USD",
"floor_price": 10.00,
"price_guidance": {
"p25": 12.50,
"p50": 15.00,
"p75": 18.00,
"p90": 22.00
}
}
```
`revenue_share` is the exception to the old "no fixed price means auction" shortcut: it is contingent pricing, uses `commission_rate`, and never uses auction bidding fields.
#### Delivery Measurement
Products SHOULD declare their measurement provider when available:
```json theme={null}
{
"delivery_measurement": {
"provider": "Google Ad Manager with IAS viewability verification",
"notes": "MRC-accredited viewability. 50% in-view for 1s display / 2s video."
}
}
```
Common provider examples:
* `"Google Ad Manager with IAS viewability"`
* `"Nielsen DAR for P18-49 demographic measurement"`
* `"Geopath DOOH traffic counts updated monthly"`
* `"Comscore vCE for video completion tracking"`
* `"Self-reported impressions from proprietary ad server"`
Guaranteed products can also declare `performance_standards`, `measurement_terms`, and `cancellation_policy` that define accountability obligations at the buy level. See [Accountability](/dist/docs/3.2.8/media-buy/advanced-topics/accountability).
### Outcome Measurement Object
For products that include outcome measurement (common in retail media):
```json theme={null}
{
"type": "incremental_sales_lift",
"attribution": "deterministic_purchase",
"window": { "interval": 30, "unit": "days" },
"reporting": "weekly_dashboard"
}
```
### CreativePolicy Object
Defines creative requirements and restrictions:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/creative-policy.json",
"co_branding": "required",
"landing_page": "retailer_site_only",
"templates_available": true
}
```
### Placements
Products can optionally declare specific public ad placements within their inventory. `kind` identifies who owns the placement ID. A `publisher_ref` has canonical `{publisher_domain, placement_id}` identity and resolves in the publisher's `adagents.json`. A `seller_inline` placement is defined by the sales agent; new 3.2 products include `seller_agent` so `{seller_agent, placement_id}` is self-contained. Legacy inline placements without it remain valid but are scoped to the enclosing seller and product. A `publisher_domain` on an inline placement describes inventory context—it does not let the seller mint an ID in that publisher's catalog namespace.
* **`kind: "publisher_ref"`** - Publisher-scoped placement reference resolved from the named publisher's `adagents.json`; requires `publisher_domain`
* **`kind: "seller_inline"`** - Public buyer-facing placement metadata defined inline by the sales agent; requires `name` and should include `seller_agent`
* **`publisher_domain`** - For `publisher_ref`, the domain whose `adagents.json` defines the placement. For `seller_inline`, optional inventory-publisher attribution only.
* **`seller_agent`** - Defining sales-agent identity for a self-contained inline placement
* **`placement_id`** - ID within the authority selected by `kind`. Legacy product-context references remain accepted.
* **`mode: "targetable"`** - The buyer may select this publisher-scoped placement with `targeting_overlay.placement_selection`
* **`mode: "included"`** - The public placement is fixed product inventory and cannot be cherry-picked. Across discovery, create, and update, a selected request exactly equal to the product's complete included set is an inherent match and may be echoed without `overlay_support.placement_selection`; partial selection requires a selectable product.
* **`video_placement_types`** - Declared video placement types for OLV and other video placements. Concrete placements usually declare one value; aggregate placements may declare multiple.
* **`audio_distribution_types`** - Declared audio distribution types for radio, streaming-audio, podcast, gaming, and other audio placements. Concrete placements usually declare one value; aggregate placements may declare multiple.
* **`sponsored_placement_types`** - Declared sponsored-placement types for catalog-driven retail-media placements. Concrete placements usually declare one value; aggregate placements may declare multiple.
* **`social_placement_surfaces`** - Declared social-placement surfaces for social placements. Concrete placements usually declare one value; aggregate placements may declare multiple.
* **Publisher reference rule** - Publisher-referenced product placements resolve to `{publisher_domain, placement_id}` in the publisher's `adagents.json`
* **Private inventory rule** - Seller-private delivery objects, ad-server mappings, and source/origin details must stay out of `get_products`
* **Creative assignment** - Different creatives can be routed to selected placements with `creative_assignments[].placement_refs`; assignment does not select inventory
* **Omitting placement targeting** - `placement_selection.mode: "default"` leaves the product's default placement composition intact. Creatives without placement refs run across the package's selected/default placements.
* **Use registered IDs when available** - If the publisher declares canonical `placements` in `adagents.json`, product placements SHOULD use the catalog ID as `placement_id`
* **Preserve registry semantics** - When a product references a registered placement, it is referring to that same placement. The product may narrow canonical `format_options` or add operational detail, but it should not change the placement's meaning incompatibly
* **Tags stay useful at product level** - Product placements can carry `tags` for grouping and should align with registry tags when the placement comes from the publisher registry
`mode` is required for new senders as of May 25, 2026. During the six-month migration window ending November 25, 2026, buyers may tolerate legacy products where `placements[]` entries omit `mode` and treat those placements as targetable for creative assignment. After November 25, 2026, buyers should fail closed on missing `mode`.
Publishers can authorize agents for specific placements in `adagents.json` with `authorized_agents[].placement_ids` or `authorized_agents[].placement_tags`. Sales agents should only return publisher-referenced placements they are authorized to sell.
#### Video placement types
Video products can declare `video_placement_types` at the product level, placement level, or both. The vocabulary follows the IAB Tech Lab/OpenRTB 2.6 `video.plcmt` definitions, but AdCP uses readable field and value names rather than the OpenRTB wire name:
| Value | Meaning |
| - | - |
| `instream` | Video ads before, during, or after streaming video content requested by the user |
| `accompanying_content` | Video ads in a player with accompanying video content associated with the page or app content |
| `interstitial` | Video ads shown as an interstitial experience, typically between content or app states |
| `standalone` | Video ads shown without associated video content, also called no-content or standalone video |
The field is an array because a sellable product can aggregate multiple placement types. For example, an OLV network product might include both `instream` and `accompanying_content`, while individual targetable placements narrow to one type. When both product and placement declarations are present, the product-level array should be the union of the video placement types the seller may deliver under that product.
This is a discovery signal, not a verification claim. Buyers can filter for products that can satisfy a requested type with `get_products.filters.video_placement_types`, but sellers should not return mixed, non-targetable bundles for an instream-only filter unless they can constrain delivery to instream inventory during planning or purchase.
#### Audio distribution types
Audio products can declare `audio_distribution_types` at the product level, placement level, or both. The vocabulary follows the IAB Tech Lab/OpenRTB 2.6 `audio.feed` definitions, but AdCP uses readable field and value names rather than the OpenRTB numeric codes:
| Value | Meaning |
| - | - |
| `music_streaming_service` | Music streaming service |
| `fm_am_broadcast` | FM/AM broadcast, including live content broadcast over the air and also available via online streaming |
| `podcast` | Original, pre-recorded content distributed as episodes in a series |
| `catch_up_radio` | Recorded segment of a radio show that was originally broadcast live |
| `web_radio` | Live audio content only available via online streaming, not as FM/AM broadcast |
| `video_game` | Background audio in video games |
| `text_to_speech` | Text-to-speech audio such as audio books or website/plugin article narration |
This field describes execution and distribution details inside buyer-facing audio inventory, including `radio`, `streaming_audio`, `podcast`, `gaming`, and audio-only `dooh` products. It does not rename channels and it does not change `adagents.json` `property_type` semantics, which remain tied to authorizable inventory surfaces and their operator. The field describes the underlying feed, not the endpoint operator: a venue-operated player remains `dooh` even when an existing feed value also applies, and its property may support several buyer-facing channels. The field is an array because a sellable product can aggregate multiple audio distribution types. When both product and placement declarations are present, the product-level array should be the union of the audio distribution types the seller may deliver under that product.
This is a discovery signal, not a verification claim. Buyers can filter for products that can satisfy a requested type with `get_products.filters.audio_distribution_types`, but sellers should not return mixed, non-targetable bundles unless they can constrain delivery to the requested audio distribution type during planning or purchase.
#### Sponsored placement types
Catalog-driven retail-media products can declare `sponsored_placement_types` at the product level, placement level, or both, distinguishing where the sponsored placement renders on the retailer surface:
| Value | Meaning |
| - | - |
| `sponsored_search` | Sponsored placements rendered against retailer on-site search results, keyed to the shopper's query |
| `sponsored_display` | Sponsored placements rendered in display slots across browse, category, and product-detail pages outside the search results stream |
| `sponsored_native` | Sponsored placements rendered using the retailer's native in-grid product template, blending into the organic listing |
These values describe placement surfaces for products under the catalog-driven `sponsored_placement` canonical, whose `source_catalog` slot is required; an off-site value is intentionally excluded because off-site placements are not catalog-keyed. The field is an array because a sellable product can aggregate multiple surfaces; when both product and placement declarations are present, the product-level array should be the union the seller may deliver under that product.
This is a discovery signal, not a verification claim. Buyers can filter for products that can satisfy a requested type with `get_products.filters.sponsored_placement_types`, but sellers should not return mixed, non-targetable bundles unless they can constrain delivery to the requested type during planning or purchase.
#### Social placement surfaces
Social products can declare `social_placement_surfaces` at the product level, placement level, or both, distinguishing the in-app surface where the social placement renders:
| Value | Meaning |
| - | - |
| `feed` | The primary scrolling home or timeline surface |
| `stories` | The full-screen, ephemeral tap-through story surface |
| `short_video` | The full-screen vertical algorithmically-recommended short-video surface (branded Reels, Shorts, Spotlight, etc.) |
| `explore` | The discovery or browse surface outside the followed graph |
| `search` | The in-app search-results surface, keyed to the user's query |
The field is an array because a sellable product can aggregate multiple surfaces; when both product and placement declarations are present, the product-level array should be the union the seller may deliver under that product.
This is a discovery signal, not a verification claim. Buyers can filter for products that can satisfy a requested surface with `get_products.filters.social_placement_surfaces`, but sellers should not return mixed, non-targetable bundles unless they can constrain delivery to the requested surface during planning or purchase.
#### DOOH placement attributes
Digital out-of-home placements can declare structured selling-unit metadata via `dooh_placement_attributes` at the placement level (both in product placements and in `adagents.json` placement definitions). These fields describe an installed surface and its ad-loop characteristics. Visual placements use the screen fields for creative production and share-of-voice calculations; audio-only placements omit them:
| Field | Type | Meaning |
| - | - | - |
| `slot_duration_seconds` | integer | Duration of one ad slot in seconds (e.g., 10, 15, 30) |
| `loop_duration_seconds` | integer | Duration of the full ad loop rotation in seconds. Buyers derive nominal slot share as `slot_duration_seconds / loop_duration_seconds`. This is the canonical source; the pricing-layer field in `flat-rate-option` is superseded |
| `screen_resolution` | object | Physical screen resolution (`{ width, height }` in pixels). Buyers derive aspect ratio from `width / height`. Omit for audio-only placements |
| `motion` | string | Motion capability of a visual screen: `full_motion` (video), `partial_motion` (animated stills), or `static` (images only). Omit for audio-only placements |
All fields are optional. A single visual screen/frame placement can include all fields; an audio-only placement can declare only its slot and loop timing. A package or network placement should include only fields that are uniform across the included inventory. After publisher and product declarations are resolved, `slot_duration_seconds` MUST NOT exceed `loop_duration_seconds`.
These are inventory facts, not an alternative creative contract. Effective canonical `format_options` remains authoritative for accepted dimensions, durations, asset types, and codecs. A physical screen can therefore report a larger `screen_resolution` than the content region declared by its formats, a full-motion screen can still offer a static-only product, and an audio-only DOOH placement declares `audio_hosted` or `audio_daast` without manufacturing visual attributes.
For `kind: "publisher_ref"`, resolve the publisher placement before applying product detail. Product-level `slot_duration_seconds` and `loop_duration_seconds` override publisher defaults for that specific offer; omitted values inherit. `screen_resolution` and `motion` are intrinsic publisher facts, so repeated product values MUST match the publisher declaration. Treat mismatches and an invalid effective slot-to-loop ratio as conformance errors rather than silently choosing one source.
Placements can also carry `identifiers[]` using the same `{ type, value }` shape as property identifiers. DOOH placements commonly use `venue_id` and `openooh_venue_type`; visual placements can also use `screen_id`. Externally governed IDs should be authority-prefixed (e.g., `geopath:30961`). OpenOOH classifications include the taxonomy version (`openooh-1.1:20501`), since a bare category number does not identify which revision defined it. For publisher references, union publisher and product identifiers by exact `(type, value)`; product omission does not remove a publisher identifier.
#### Format precedence with placements
Product-level `format_options` define the creative formats accepted by the product as a whole. Placement-level `format_options`, whether returned inline on the product placement or inherited from a public publisher placement declaration, only narrow that product-wide set for the specific placement. Deprecated `format_ids` may appear only as a 3.x compatibility projection of the same declarations.
For a multi-publisher or multi-placement product, the product-level list is the union of formats the seller can traffic somewhere in the product. It is not a promise that every option works on every placement. Compute each placement's effective set independently by intersecting the product declaration with that placement's publisher declaration.
If both product and placement format declarations are present, buyers compute the effective accepted formats for that placement as their intersection. For legacy `format_ids`, first project named formats to canonical declarations through `canonical`, `v1_format_ref`, or the canonical mapping registry; do not compare raw `(agent_url, id)` values after projection. A legacy 300x250 display ID and a canonical `image` declaration with `width: 300` and `height: 250` are compatible. For 3.1+ `format_options`, match publisher-declared options by `{publisher_domain, format_option_id}`, match product-local options by `format_option_id` when `publisher_domain` is omitted, and otherwise match declarations with the same `format_kind` whose placement parameters narrow the product declaration.
For a multi-publisher product without explicit `placements[]`, each `publisher_properties[]` selector is an eligibility slice. A publisher-scoped format option applies only to slices for the matching `publisher_domain`; a product-local option applies to every slice. One creative intended for the entire product must satisfy the intersection across all slices. A set of distinct creatives may use the union only when it covers every slice. If a seller or buyer cannot determine a slice's effective formats from the product and resolved publisher catalog, it must fail closed and require the seller to add placements or return a refined product.
Product gating is stricter than equivalence matching. When the product or placement declares fixed constraints such as `width`, `height`, `duration_ms_exact`, or a duration range, the buyer's selected format or creative manifest must declare and satisfy those constraints. A broad request (`format_kind: "image"` with no dimensions, or `video_hosted` with no duration) does not satisfy a fixed-size or fixed-duration product. For ranges, satisfaction means containment: a range-based request satisfies a product only when every value it permits falls within the product's accepted range; overlap alone is insufficient. An exact duration satisfies a range when the exact value falls inside it. The reverse is allowed: a broad product declaration can accept a specific 300x250 image or 30-second video unless another product constraint excludes it. See [format matching vs product satisfaction](/dist/docs/3.2.8/creative/canonical-formats#format-matching-vs-product-satisfaction).
If a placement has no format declaration, it inherits the product-level formats. A placement-only format that is absent from the product-level declaration is a seller conformance error, not an expansion of the product's creative contract; buyers should fail closed for that format and not treat it as accepted.
For a product or selected package containing multiple included placements, a single creative intended to run everywhere must be in the intersection of all selected placements' effective sets. If distinct creatives may be assigned by placement, the package can expose the union, but the selected creative set must cover every included delivery placement. If any placement has an empty intersection or remains uncovered, the seller must reject or refine the product/package; it must not silently remove that inventory after purchase. Price, floor, availability, and deal eligibility stay on the product or pricing option—they are commercial facts, not creative-format parameters.
#### Creative locale constraints
A format option may carry `locale_policy.accepted_language_ranges` when the
seller can execute only particular creative languages. The policy narrows the
same base format; it does not create a locale-specific `format_kind` or a
synthetic ID such as `display_image_fr_only`.
Ranges use RFC 4647 Basic Filtering. Seller range `fr` accepts materialized
creative variants tagged `fr`, `fr-CA`, or `fr-FR`; seller range `fr-CA` does
not accept bare `fr` or `fr-FR`. Buyers SHOULD compare planned or existing
creative locale topology during discovery and discard incompatible products
before `create_media_buy`. A source-only locale topology is sufficient for a
monolingual creative.
At assignment, the seller computes the effective product-and-placement format
declaration and rejects with `CREATIVE_LOCALE_NOT_ACCEPTED` when no materialized
variant matches. The check runs independently for every placement where the
assignment may serve. A placement may introduce a locale policy when the
product option is unconstrained; when both carry policies, placement ranges may
narrow product ranges (`fr-CA` under `fr`) but cannot broaden them. The seller filters eligible variants before
buyer Lookup, explicit fallback, or default behavior; `serve_default` is valid
only when the default is eligible. Nonmatching variants remain reusable on
other products.
The effective locale policy is snapshotted when the seller accepts an
assignment. Later product-catalog changes apply only to new or changed
assignments; they do not silently rewrite or remove an existing assignment.
Sellers exposing a locale-constrained product or placement MUST advertise
`creative.localization` and `creative.has_creative_library: true`; buyers sync
the locale topology before assigning because inline media-buy creatives cannot
carry it. Locale-constrained effective options are canonical-only. No product
or placement `format_id` may project to one, including when only a placement
introduces the policy. Buyers use a format-options-aware canonical path:
`format_option_refs` when published or required for disambiguation, otherwise a
direct `format_kind`/`params` selector. They never rely on `format_ids` for the
constrained route.
#### Placement Object Structure
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/core/placement.json",
"kind": "publisher_ref",
"publisher_domain": "daily-pulse.example",
"placement_id": "homepage_banner",
"name": "Homepage Banner",
"description": "Above-the-fold banner on the homepage",
"mode": "targetable",
"tags": ["homepage", "display", "premium"],
"format_options": [
{"format_option_id": "display_728x90", "format_kind": "image", "params": {"width": 728, "height": 90}},
{"format_option_id": "display_970x250", "format_kind": "image", "params": {"width": 970, "height": 250}}
]
}
```
#### Example: Product with Placements
```json theme={null}
{
"product_id": "news_site_premium",
"name": "News Site Premium Package",
"description": "Premium placements across news site",
"format_options": [
{"format_option_id": "display_728x90", "format_kind": "image", "params": {"width": 728, "height": 90}},
{"format_option_id": "display_300x250", "format_kind": "image", "params": {"width": 300, "height": 250}}
],
"placements": [
{
"kind": "publisher_ref",
"placement_id": "homepage_banner",
"publisher_domain": "daily-pulse.example",
"name": "Homepage Banner",
"mode": "targetable",
"tags": ["homepage", "display", "premium"],
"format_options": [{"format_option_id": "display_728x90", "format_kind": "image", "params": {"width": 728, "height": 90}}]
},
{
"kind": "publisher_ref",
"placement_id": "article_sidebar",
"publisher_domain": "daily-pulse.example",
"name": "Article Sidebar",
"mode": "targetable",
"tags": ["article", "display"],
"format_options": [{"format_option_id": "display_300x250", "format_kind": "image", "params": {"width": 300, "height": 250}}]
},
{
"kind": "seller_inline",
"publisher_domain": "daily-pulse.example",
"seller_agent": { "agent_url": "https://sales.daily-pulse.example/adcp" },
"placement_id": "premium_rotation",
"name": "Premium rotation",
"mode": "included",
"tags": ["premium"]
}
],
"delivery_type": "guaranteed",
"pricing_options": [...]
}
```
When creating a media buy, buyers can assign different creatives to different placements:
```json theme={null}
{
"packages": [
{
"product_id": "news_site_premium",
"creative_assignments": [
{
"creative_id": "creative_1",
"placement_refs": [
{
"publisher_domain": "daily-pulse.example",
"placement_id": "homepage_banner"
}
]
},
{
"creative_id": "creative_2",
"placement_refs": [
{
"publisher_domain": "daily-pulse.example",
"placement_id": "article_sidebar"
}
]
}
]
}
]
}
```
See [Creative Assignment and Placement Targeting](/dist/docs/3.2.8/media-buy/media-buys/index.mdx#creative-assignment-and-placement-targeting) for more details.
### Collections and installments
Collections are a third product dimension alongside formats and placements. While placements describe *where* an ad appears and formats describe *what* the ad looks like, collections describe the *content context* — the programming a viewer is watching. Products can declare `collections` and `installments` so buyers can target specific programs, channels, or installments when purchasing inventory.
See [Collections and installments](/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments) for the full model, examples, and targeting details.
### Exclusivity
The `exclusivity` field indicates whether a product offers exclusive access to its inventory. Defaults to `"none"` when absent.
| Value | Meaning |
| - | - |
| `none` | Multiple advertisers can buy this product simultaneously |
| `category` | One advertiser per industry category (e.g., one auto brand per collection sponsorship) |
| `exclusive` | Sole sponsorship — only one advertiser can buy this product |
Exclusivity is most relevant for guaranteed products tied to specific shows or placements, where advertisers want brand separation or sole ownership of a content association.
#### When to use each level
* **`none`**: Programmatic inventory, run-of-network, open auction products. Multiple advertisers sharing the same inventory is expected.
* **`category`**: Podcast or CTV sponsorships where competitive separation matters. One auto brand per collection, one fintech brand per installment — but multiple non-competing advertisers can buy simultaneously.
* **`exclusive`**: Sole sponsorship of a single collection or event. The advertiser is the only brand associated with the content.
Publishers SHOULD include `exclusivity` on guaranteed products with `collections`. The implicit default of `"none"` is ambiguous for collection-level inventory — buyers cannot tell whether the publisher intends shared inventory or simply omitted the field.
#### Content sponsorship pattern
A product combining `delivery_type: "guaranteed"`, `exclusivity: "exclusive"`, and `collections` represents a content sponsorship — the advertiser becomes the sole sponsor of specific content. This is the standard pattern for podcast title sponsorships, CTV collection sponsorships, and event-based takeovers.
```json theme={null}
{
"product_id": "signal_noise_sponsor",
"name": "Signal & Noise — Exclusive Sponsorship",
"description": "Sole sponsorship of Signal & Noise, a weekly technology podcast. Includes pre-roll and mid-roll placements across all episodes.",
"publisher_properties": [
{ "publisher_domain": "crestnetwork.example", "property_ids": ["crest_podcasts"] }
],
"format_options": [
{ "format_option_id": "audio_pre_roll_30s", "format_kind": "audio_hosted", "params": { "duration_ms_exact": 30000 } },
{ "format_option_id": "audio_mid_roll_60s", "format_kind": "audio_hosted", "params": { "duration_ms_exact": 60000 } }
],
"collections": [{ "publisher_domain": "crestnetwork.example", "collection_ids": ["signal_noise"] }],
"delivery_type": "guaranteed",
"exclusivity": "exclusive",
"pricing_options": [
{
"pricing_option_id": "flat_monthly",
"pricing_model": "flat_rate",
"fixed_price": 25000,
"currency": "USD"
}
]
}
```
Category exclusivity works for multi-collection bundles where the publisher separates competing brands across a network but still sells to multiple non-competing advertisers:
```json theme={null}
{
"product_id": "crest_business_bundle",
"name": "Crest Business Podcast Bundle — Category Sponsorship",
"description": "Sponsorship across three business podcasts. One advertiser per industry category across all shows.",
"publisher_properties": [
{ "publisher_domain": "crestnetwork.example", "property_ids": ["crest_podcasts"] }
],
"format_options": [
{ "format_option_id": "audio_pre_roll_30s", "format_kind": "audio_hosted", "params": { "duration_ms_exact": 30000 } },
{ "format_option_id": "audio_mid_roll_60s", "format_kind": "audio_hosted", "params": { "duration_ms_exact": 60000 } }
],
"collections": [{ "publisher_domain": "crestnetwork.example", "collection_ids": ["signal_noise", "market_beat", "founder_stories"] }],
"delivery_type": "guaranteed",
"exclusivity": "category",
"pricing_options": [
{
"pricing_option_id": "flat_quarterly",
"pricing_model": "flat_rate",
"fixed_price": 60000,
"currency": "USD"
}
]
}
```
### Property Targeting
The `property_targeting_allowed` flag indicates whether buyers can filter a product to a subset of its `publisher_properties` when using property list filtering via `get_products`.
#### Behavior
* **`property_targeting_allowed: false` (default)**: The product is "all or nothing." If the buyer's `property_list` doesn't include all of the product's properties, the product is excluded from results entirely.
* **`property_targeting_allowed: true`**: Buyers can filter the product to properties matching their `property_list`. The product is included in results if there is any intersection between its properties and the buyer's list.
#### Use Cases
| Use Case | `property_targeting_allowed` | Why |
| - | - | - |
| Run of Network | `false` | Buyers must accept the entire network |
| Premium Bundles | `false` | Sports + News bundle sold together |
| Flexible Inventory | `true` | Buyers can target specific sites within a category |
#### Examples
**All-or-nothing product** (`property_targeting_allowed: false`):
```json theme={null}
{
"product_id": "premium_news_bundle",
"name": "Premium News Bundle",
"publisher_properties": [
{ "publisher_domain": "news.example.com", "property_ids": ["site_a", "site_b", "site_c"] }
],
"property_targeting_allowed": false
}
```
When a buyer calls `get_products` with a `property_list` containing only `site_a` and `site_b`, this product is **excluded** because the buyer's list doesn't include all properties (`site_c` is missing).
**Flexible product** (`property_targeting_allowed: true`):
```json theme={null}
{
"product_id": "news_category_flexible",
"name": "News Category - Flexible Targeting",
"publisher_properties": [
{ "publisher_domain": "news.example.com", "property_ids": ["tech", "sports", "finance", "politics"] }
],
"property_targeting_allowed": true
}
```
When a buyer calls `get_products` with a `property_list` containing only `tech` and `sports`, this product is **included** because there is an intersection. The buyer can then purchase this product and target only the matching properties via `targeting_overlay.property_list` in the package.
### Signal Targeting
Products use three different signal fields with different meanings:
* **`data_provider_signals`** is deprecated legacy/non-selectable metadata for data-provider signals already bundled into or associated with the product. New implementations should use `included_signals`.
* **`included_signals`** is the structured, non-selectable surface. Use it when a signal is already bundled into, included in, or planned into the product. It has no per-product targeting price and no seller activation handle.
* **`signal_targeting_options`** is the inline selectable/composable surface. Use it when a seller-offered signal can appear on a package and the product needs to expose a product-specific menu, price, activation handle, default/fixed choice, grouping hint, or brief/refine-selected subset.
`Product.signal_targeting_allowed` and `signal_targeting_rules` are the canonical product contract for signal composition. `get_signals` is the canonical broad signal discovery surface; wholesale products can use `signal_targeting_allowed: true` with no inline `signal_targeting_options` to tell buyers to call `get_signals` for the selectable signal feed. Brief/refine responses can return inline `signal_targeting_options` for the relevant subset or product-specific overrides. Sellers do not need to expose product-local options through `get_signals` unless they also want those signals to be discoverable outside this product. Sellers MUST set `signal_targeting_allowed: true` whenever they return `signal_targeting_options` or `signal_targeting_rules`, and MUST use `included_signals` rather than `signal_targeting_options` for signals that are bundled but not represented as package signal groups.
Signals are named targetable dimensions, similar to feature values. A signal definition declares `value_type` (`binary`, `categorical`, or `numeric`) and may carry richer metadata over time. Product signal listings use `signal_ref` with an explicit resolution scope: `{ "scope": "product", "signal_id": "..." }` refers to a product-local signal defined by the listing, `{ "scope": "data_provider", "data_provider_domain": "...", "signal_id": "..." }` refers to a signal defined in a data provider's published adagents.json `signals[]`, and `{ "scope": "signal_source", "signal_source_url": "...", "signal_id": "..." }` refers to a source-native signal. `signal_ref.scope` is the resolution path, not provenance, and authoritative enrichment lives on the seller, signal source, or data-provider signal definition. For `scope: "product"`, the product listing MUST include `name` and `value_type` because the product is the definition boundary. For `scope: "data_provider"` or `scope: "signal_source"`, `signal_ref` is sufficient and any inline name, description, value type, range, or methodology is contextual, not authoritative. For product-local signals exposed on both `get_signals` and `get_products`, `signal_ref.signal_id` MUST match the seller's `get_signals.signals[].signal_ref.signal_id` for the same signal.
Signal targeting composition is declared on each product, not in seller-wide `get_adcp_capabilities`, because one seller can sell products backed by different ad servers or platforms with different include/exclude and grouping limits. Buyers should read any inline `signal_targeting_options` and `signal_targeting_rules` from the specific product they are composing.
* **`signal_targeting_allowed: false` (default)**: Signals are bundled into the product terms and are not represented as package-level signal groups. The buyer buys the product as offered and does not select or receive echoed signal groups on the package.
* **`signal_targeting_allowed: true`**: The product has a package-level signal targeting surface. In wholesale discovery, if inline `signal_targeting_options` is omitted, buyers use `get_signals` to discover the selectable signal feed. In brief/refine results, sellers may include inline `signal_targeting_options` for the relevant subset or product-specific overrides.
* **`signal_targeting_rules`**: Optional storefront composition rules. Use `resolution_model`, `selection_mode`, `min_selected_signals`, `max_selected_signals`, `max_selected_per_group`, `selection_group_rules`, `max_signal_targeting_groups`, and `max_signals_per_targeting_group` when the seller needs to express optional, required, single-select, mutually exclusive, fixed, seller-planned, or grouped signal choices. `resolution_model: "direct_targeting"` means selected signals are applied as targeting predicates to the package inventory. `resolution_model: "seller_planned"` means selected signals are planning inputs that the seller resolves against product-specific inventory, timing, availability, reach, or pacing constraints; buyers should not attempt to decompose the signal selection into lower-level inventory or schedule decisions. `selection_mode: "required"` means at least `min_selected_signals`, or 1 when `min_selected_signals` is omitted. All explicit package-level signal selection uses the grouped expression shape: top-level `operator: "all"` with child groups using `operator: "any"` for include groups and `operator: "none"` for exclusion groups. If `selection_mode` is `fixed`, buyers render `default_selected` signals as read-only; sellers apply those signals even when the buyer omits `targeting_overlay.signal_targeting_groups`. When `selection_group_rules` are present, each child group MUST contain signals from exactly one `selection_group` and one targeting mode, and buyers MUST send at most one child group for each `(selection_group, targeting_mode)` pair. Sellers MUST reject duplicate, mixed, or collapsed child groups.
* **`activation_status: "requires_activation"`**: `get_products` alone is not sufficient to select the signal unless the buyer already has an activation key the seller accepts. The product option MUST include `signal_agent_segment_id` so the buyer can activate the signal through `activate_signal`, then include the activation key if the seller requires it on the package.
`allowed_targeting_modes` on each signal option controls which buy-time child group operators are valid: `"include"` maps to `operator: "any"`, and `"exclude"` maps to `operator: "none"`. `selection_group` is a product-defined composability bucket for limits like `max_selected_per_group` and `selection_group_rules`; it is not a pointer to a specific child group in the package's `signal_targeting_groups.groups[]`. Use the same `selection_group` when options are freely OR-combinable in one child group for a targeting mode. Use different `selection_group` values when options must be represented as separate ANDed clauses, such as a product backed by one ad server that exposes both audience segments and key-value targeting planes that cannot be collapsed into the same child expression. Different `selection_group` values by themselves are descriptive; sellers should publish `selection_group_rules` when group boundaries affect validation.
```json theme={null}
{
"product_id": "retail_video_premium",
"name": "Retail Video Premium",
"signal_targeting_allowed": true,
"signal_targeting_rules": {
"resolution_model": "direct_targeting",
"selection_mode": "optional",
"max_selected_signals": 2,
"max_selected_per_group": 1,
"selection_group_rules": [
{
"selection_group": "retail_audience",
"targeting_mode": "include",
"selection_mode": "optional",
"max_selected_signals": 1
}
],
"max_signal_targeting_groups": 2,
"max_signals_per_targeting_group": 3
},
"signal_targeting_options": [
{
"signal_ref": {
"scope": "data_provider",
"data_provider_domain": "pinnacle-data.example",
"signal_id": "auto_intenders"
},
"selection_group": "retail_audience",
"allowed_targeting_modes": ["include", "exclude"],
"activation_status": "ready",
"default_selected": false,
"pricing_options": [
{
"pricing_option_id": "signal_cpm_usd_250",
"model": "cpm",
"cpm": 2.50,
"currency": "USD"
}
]
}
]
}
```
A product can also disclose included, non-selectable signals without opening a package-level signal targeting surface:
```json theme={null}
{
"product_id": "broadcast_auto_intenders_weekly_reach",
"name": "Broadcast Auto Intenders Weekly Reach",
"signal_targeting_allowed": false,
"included_signals": [
{
"signal_ref": {
"scope": "data_provider",
"data_provider_domain": "pinnacle-data.example",
"signal_id": "auto_intenders"
}
}
]
}
```
Here the buyer can inspect or verify the Pinnacle Data signal definition through the referenced provider's adagents.json `signals[]`, but cannot add or remove that signal in `create_media_buy`.
A wholesale product with a large or account-specific signal menu can point buyers to `get_signals` instead of inlining every option:
```json theme={null}
{
"product_id": "retail_display_open_exchange",
"name": "Retail Display Open Exchange",
"signal_targeting_allowed": true,
"signal_targeting_rules": {
"resolution_model": "direct_targeting",
"selection_mode": "optional",
"max_signal_targeting_groups": 2
}
}
```
In that shape, because `signal_targeting_allowed` is true and no inline `signal_targeting_options` are returned, the buyer calls `get_signals` to discover candidate signals. Before committing spend, the buyer SHOULD confirm product eligibility by calling `get_products` with the candidate selections in `targeting_overlay.signal_targeting_groups`, or request later-selectable support with `required_overlay_support.signal_targeting_groups`. The legacy `filters.signal_targeting` path is deprecated.
At buy time, package-level `signal_targeting_groups` carries the selected `signal_ref`, value expression, optional seller execution handle (`signal_agent_segment_id`), and signal `pricing_option_id` when the signal has its own price. A simple include-only selection is represented as one child group with `operator: "any"`; grouped inclusion/exclusion uses additional `any` and `none` groups, such as `(A OR B) AND NOT (C)`. This is separate from the package's `pricing_option_id`, which prices the media product itself. Product-scoped signal pricing in `signal_targeting_options[].pricing_options` is authoritative for that product; broader `get_signals` pricing is a default discovery view unless the product omits a price. Sellers MUST echo all applied package signal groups in the resulting package state, including fixed/default selections the seller applied without buyer edits.
For provider-published signals, `signal_ref.data_provider_domain` identifies the upstream data provider and `signal_ref.signal_id` identifies the public signal definition in that provider's adagents.json `signals[]`. Buyers that need provenance verification can fetch that domain's `adagents.json` and confirm the seller appears in `authorized_agents` for that signal or its tags. For product-local signals, use `scope: "product"` and `signal_id`; the ID is meaningful only within the selected product/package context.
Backend execution kind is not part of signal identity. A GAM-backed seller can expose an audience segment, a key-value rule, or another custom-targeting primitive as ordinary `signal_ref` options. If those signals can be combined by the platform in one OR clause, put them in the same `selection_group`; if they require separate clauses, put them in separate `selection_group`s and publish `selection_group_rules` so storefronts compose one child group per `(selection_group, targeting_mode)`.
For seller-planned guaranteed products, such as linear broadcast audio schedules, the selected audience can be portable while the plan is not. In that case, publish the shared audience as a `scope: "data_provider"` signal if it appears across products, set `resolution_model: "seller_planned"` on products where the seller resolves that audience against time-based avails or reach goals, and use `selection_mode: "required"` or `selection_group_rules[].selection_mode: "required"` when an audience choice is mandatory for the package. For non-guaranteed products where selected signals are applied as ordinary targeting predicates, use the default `resolution_model: "direct_targeting"` and point the product to `get_signals` when the wholesale signal menu should not be duplicated inline.
The `seller_planned` model applies to any supply type where inventory is scheduled in advance and constrained by time-bound availability rather than continuously auctioned: live sports, political programming, and tentpole broadcasts follow the same pattern as linear broadcast audio.
### Custom & Account-Specific Products
A server can offer a general catalog, but it can also return:
* **Account-Specific Products**: Products reserved for or negotiated with specific accounts (buyers, agencies, or brands)
* **Custom Products**: Dynamically generated products with `is_custom: true`; targeting-aware discovery products also carry an `expires_at` timestamp, while legacy custom products may omit it
## Product Examples
### Standard CTV Product (Multiple Pricing Options)
```json theme={null}
{
"product_id": "connected_tv_prime",
"name": "Connected TV - Prime Time",
"description": "Premium CTV inventory 8PM-11PM",
"publisher_properties": [
{ "publisher_domain": "streaming.example.com", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } },
{ "format_option_id": "video_30s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 30000 } }
],
"delivery_type": "guaranteed",
"pricing_options": [
{
"pricing_option_id": "cpm_usd_guaranteed",
"pricing_model": "cpm",
"fixed_price": 45.00,
"currency": "USD",
"min_spend_per_package": 10000
},
{
"pricing_option_id": "cpcv_usd_guaranteed",
"pricing_model": "cpcv",
"fixed_price": 0.18,
"currency": "USD",
"min_spend_per_package": 10000
},
{
"pricing_option_id": "cpp_usd_p18-49",
"pricing_model": "cpp",
"fixed_price": 250.00,
"currency": "USD",
"parameters": {
"demographic": "P18-49",
"min_points": 50
},
"min_spend_per_package": 12500
}
],
"delivery_measurement": {
"provider": "Nielsen DAR for P18-49 demographic measurement",
"notes": "Panel-based measurement for GRP delivery. Impressions measured via Comscore vCE."
}
}
```
### Auction-Based Display Product
```json theme={null}
{
"product_id": "custom_abc123",
"name": "Custom - Gaming Enthusiasts",
"description": "Custom audience package for gaming campaign",
"publisher_properties": [
{ "publisher_domain": "gaming.example.com", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "display_300x250", "format_kind": "image", "params": { "width": 300, "height": 250 } },
{ "format_option_id": "display_728x90", "format_kind": "image", "params": { "width": 728, "height": 90 } }
],
"delivery_type": "non_guaranteed",
"pricing_options": [
{
"pricing_option_id": "cpm_usd_auction",
"pricing_model": "cpm",
"currency": "USD",
"floor_price": 5.00,
"price_guidance": {
"p50": 8.00,
"p75": 12.00
}
},
{
"pricing_option_id": "cpc_usd_auction",
"pricing_model": "cpc",
"currency": "USD",
"floor_price": 0.50,
"price_guidance": {
"p50": 1.20,
"p75": 2.00
}
}
],
"delivery_measurement": {
"provider": "Google Ad Manager with IAS viewability",
"notes": "MRC-accredited viewability. 50% in-view for 1s display."
},
"is_custom": true,
"expires_at": "2025-02-15T00:00:00Z"
}
```
### Retail Media Product with Measurement
```json theme={null}
{
"product_id": "albertsons_pet_category_offsite",
"name": "Pet Category Shoppers - Offsite Display & Video",
"description": "Target Albertsons shoppers who have purchased pet products in the last 90 days. Reach them across premium display and video inventory.",
"publisher_properties": [
{ "publisher_domain": "groceryretail.example.com", "selection_type": "all" }
],
"format_options": [
{ "format_option_id": "display_300x250", "format_kind": "image", "params": { "width": 300, "height": 250 } },
{ "format_option_id": "display_728x90", "format_kind": "image", "params": { "width": 728, "height": 90 } },
{ "format_option_id": "video_15s", "format_kind": "video_hosted", "params": { "duration_ms_exact": 15000 } }
],
"delivery_type": "guaranteed",
"pricing_options": [
{
"pricing_option_id": "cpm_usd_guaranteed",
"pricing_model": "cpm",
"fixed_price": 13.50,
"currency": "USD",
"min_spend_per_package": 10000
}
],
"delivery_measurement": {
"provider": "Self-reported impressions from proprietary ad server",
"notes": "Impressions counted per IAB guidelines. Viewability measured via IAS."
},
"outcome_measurement": {
"type": "incremental_sales_lift",
"attribution": "deterministic_purchase",
"window": { "interval": 30, "unit": "days" },
"reporting": "weekly_dashboard"
},
"creative_policy": {
"co_branding": "optional",
"landing_page": "must_include_retailer",
"templates_available": true
}
}
```
## Product Cards
Product cards provide visual representations of products for user interfaces. They are typed inline and do not use creative format references.
### Card Types
Publishers should provide at least the standard card, and optionally a detailed card:
**Standard Card** (`product_card`):
* Compact 300x400px card for product grids and lists
* Supports 2x density images for retina displays
* Quick visual identification of products
**Detailed Card** (`product_card_detailed`, optional):
* Responsive layout with text description alongside hero carousel
* Markdown specifications section below
* Full product documentation similar to media kits
### Structure
```json theme={null}
{
"product_id": "ctv_premium",
"name": "Premium CTV Inventory",
// ... other product fields ...
"product_card": {
"title": "Premium CTV - Living Room Audiences",
"description": "Reach cord-cutters on premium streaming content.",
"image": {
"asset_type": "image",
"url": "https://cdn.example.com/products/ctv_hero.jpg"
},
"price_label": "From $22 CPM",
"cta_label": "View details"
},
"product_card_detailed": {
"title": "Premium CTV - Living Room Audiences",
"description": "Reach high-income households during peak viewing hours.",
"hero_image": { "asset_type": "image", "url": "https://cdn.example.com/products/ctv_hero.jpg" },
"carousel_images": [
{ "asset_type": "image", "url": "https://cdn.example.com/products/ctv_context1.jpg" },
{ "asset_type": "image", "url": "https://cdn.example.com/products/ctv_context2.jpg" }
],
"specifications": [
{ "label": "Resolution", "value": "1920x1080" },
{ "label": "Duration", "value": "30 seconds" }
]
}
}
```
### Rendering Cards
Cards can be rendered in two ways:
1. **Via `preview_creative`**: Pass the card format and manifest to generate a rendered card
2. **Pre-rendered**: Publishers can pre-generate cards and serve them directly
This flexibility allows publishers to choose between dynamic generation or static hosting based on their infrastructure.
### Standard Card Formats
The AdCP reference creative agent defines two standard card formats:
* **`product_card_standard`** (300x400px) - Compact card for product browsing
* **`product_card_detailed`** (responsive) - Rich card with carousel and full specs
Publishers can also define custom card formats to match their branding or highlight unique product attributes.
**Note**: Standard card format definitions are maintained in the [creative-agent repository](https://github.com/adcontextprotocol/creative-agent), not in this protocol specification.
### When to Include Product Cards
Product cards are optional but recommended for:
* Products with strong visual identity (e.g., specific shows, events, publications)
* Premium products where visual presentation enhances perceived value
* Complex products where visual highlights help explain capabilities
* Products targeting specific audiences that benefit from visual representation
Use the detailed card variant when you want to provide comprehensive product documentation similar to media kit pages.
### Client Rendering Guidelines
When displaying products in UIs, clients should follow this fallback order:
1. **If `product_card` exists** → Render card via `preview_creative` or display pre-rendered image
2. **If neither exists** → Render text-only representation (product name + description)
3. **If card rendering fails** → Gracefully fall back to text-only representation
This ensures a consistent user experience regardless of what product metadata is available.
### Reference Assets
Sellers can attach typed collateral to `product_card_detailed` via the `reference_assets` array. Each entry carries a semantic `role` and a canonical asset payload, giving buyer agents a recognized slot to find and present seller-curated visuals — coverage maps, sample renders, environment photos, and media kits.
This is distinct from `hero_image` and `carousel_images`, which are display-oriented. `reference_assets` is for typed collateral that buyers may inspect or use for planning.
**Supported roles:**
| Role | Description |
| - | - |
| `coverage_map` | Geographic or audience reach visualization |
| `sample_render` | Mockup of ad placement in context |
| `environment_photo` | Photo of the physical or digital environment |
| `media_kit` | Downloadable media kit or spec sheet |
| `logo` | Seller or property logo |
| `other` | Seller-defined role (provide `role_label`) |
**Example:**
```json theme={null}
{
"product_card_detailed": {
"title": "Downtown Commuter Screens",
"description": "High-traffic digital screens in metro station concourses...",
"hero_image": {
"asset_type": "image",
"url": "https://cdn.example.com/products/metro_hero.jpg",
"width": 1920,
"height": 1080,
"alt_text": "Metro station digital screen"
},
"reference_assets": [
{
"role": "coverage_map",
"asset": {
"asset_type": "image",
"url": "https://assets.example.com/maps/downtown-coverage.png",
"width": 1600,
"height": 1000,
"alt_text": "Coverage map for downtown commuter screens"
},
"description": "Shows all screen locations across the downtown metro network"
},
{
"role": "sample_render",
"asset": {
"asset_type": "video",
"url": "https://assets.example.com/previews/station-takeover.mp4",
"width": 1080,
"height": 1920
},
"description": "15-second sample of a full station takeover"
},
{
"role": "environment_photo",
"asset": {
"asset_type": "image",
"url": "https://assets.example.com/photos/concourse-evening.jpg",
"width": 2400,
"height": 1600,
"alt_text": "Evening foot traffic at Central Station concourse"
}
}
]
}
}
```
Each asset uses the canonical asset types (`image`, `video`, `markdown`, `url`) — the same primitives used throughout AdCP creative schemas.
## Proposals
Publishers can return **proposals** alongside products - structured media plans with budget allocations that buyers can execute through a defined path. Committed proposals execute directly; draft proposals must be finalized first.
### What Are Proposals?
A proposal is a recommended buying strategy that groups products with suggested budget allocations. Proposals encode publisher expertise - the kind of media planning guidance that traditionally required human sales reps.
Key characteristics:
* **Actionable**: A returned proposal is buyable through its lifecycle. `proposal_status: "draft"` means finalize first; `proposal_status: "committed"` means execute via `create_media_buy` with `proposal_id` before `expires_at`.
* **Budget-agnostic**: Fixed allocations and seller-optimized constraints use percentages, allowing the same proposal to scale to any budget
* **Allocation-aware**: Fixed proposals prescribe the split; seller-optimized proposals delegate continuous cross-package allocation to the seller within explicit goals and constraints
* **Forecast-equipped**: Proposals and allocations can include delivery forecasts to help buyers evaluate expected performance before purchase
### Proposal Structure
```json theme={null}
{
"proposal_id": "swiss_balanced_v1",
"name": "Swiss Multi-Channel Plan",
"description": "Balanced coverage across devices and language regions",
"allocations": [
{
"product_id": "ch_desktop_de",
"allocation_percentage": 20,
"pricing_option_id": "cpm_usd_fixed",
"rationale": "Primary desktop audience in German Switzerland",
"tags": ["desktop", "german"]
},
{
"product_id": "ch_desktop_fr",
"allocation_percentage": 30,
"tags": ["desktop", "french"]
},
{
"product_id": "ch_mobile_de",
"allocation_percentage": 8,
"tags": ["mobile", "german"]
},
{
"product_id": "ch_mobile_fr",
"allocation_percentage": 12,
"tags": ["mobile", "french"]
},
{
"product_id": "ch_inapp_de",
"allocation_percentage": 12,
"tags": ["in-app", "german"]
},
{
"product_id": "ch_inapp_fr",
"allocation_percentage": 18,
"tags": ["in-app", "french"]
}
],
"total_budget_guidance": {
"min": 30000,
"recommended": 50000,
"currency": "USD"
},
"brief_alignment": "Achieves 50/20/30 channel split (desktop/mobile/in-app) and 40/60 language split (German/French)",
"forecast": {
"points": [
{
"budget": 50000,
"metrics": {
"impressions": { "low": 800000, "mid": 1200000, "high": 1500000 },
"reach": { "low": 400000, "mid": 600000, "high": 750000 },
"clicks": { "mid": 4800 }
}
}
],
"method": "modeled",
"currency": "USD",
"valid_until": "2025-04-15T00:00:00Z"
}
}
```
The `tags` field enables grouping allocations by dimension:
* **By channel**: desktop (50%) + mobile (20%) + in-app (30%) = 100%
* **By language**: German (40%) + French (60%) = 100%
#### Seller-optimized proposals
A seller-optimized proposal names the eligible products and cross-package goal without locking an exact split. Optional minimum-spend targets are soft; maximum-spend percentages are hard caps:
```json theme={null}
{
"proposal_id": "performance_shared_v1",
"name": "Seller-optimized performance plan",
"budget_allocation": {
"mode": "seller_optimized",
"optimization_goals": [
{
"kind": "event",
"event_sources": [
{
"event_source_id": "checkout_events",
"event_type": "purchase"
}
]
}
]
},
"pacing": "even",
"allocations": [
{
"product_id": "prospecting",
"min_spend_target_percentage": 20,
"max_spend_percentage": 70
},
{
"product_id": "retargeting",
"max_spend_percentage": 60,
"pacing": "front_loaded"
}
]
}
```
Seller-optimized allocations MUST omit `allocation_percentage`. Minimum targets across allocations must sum to no more than 100, and maximums must collectively permit 100 percent of the budget to be spent. Optional allocation `pacing` becomes subordinate package pacing on execution; aggregate proposal pacing remains the media-buy pacing ceiling. When executed, the seller converts percentage constraints into absolute package constraints and continuously allocates the shared total budget. The seller's internal allocation changes are delivery decisions, not `update_media_buy` mutations.
Each package-level constraint in a seller-optimized proposal maps to a separate seller capability: `max_spend_percentage` to `media_buy.features.seller_optimized_package_budgets`, `min_spend_target_percentage` to `seller_optimized_min_spend_targets`, and allocation `pacing` to `seller_optimized_package_pacing`. A seller emits a constraint only when it advertises the matching capability, so a seller advertising only `seller_optimized_budget` issues proposals with the shared goals and aggregate pacing alone. The example above requires all three.
### Iterating on Proposals
Proposals can be refined using `buying_mode: "refine"` with the `refine` array. Reference proposals by ID — the seller returns an updated proposal with revised allocations, forecasts, and pricing:
```
// Initial discovery
get_products({
idempotency_key: "550e8400-e29b-41d4-a716-446655442039",
buying_mode: "brief",
brief: "Swiss campaign, $50k, 50% desktop/20% mobile/30% in-app, 40% German/60% French"
})
// Response includes proposal "swiss_balanced_v1"
// Refine the proposal
get_products({
idempotency_key: "550e8400-e29b-41d4-a716-446655442040",
buying_mode: "refine",
refine: [
{ scope: "product", product_id: "ch_desktop_de" },
{ scope: "product", product_id: "ch_desktop_fr" },
{ scope: "product", product_id: "ch_mobile_de" },
{ scope: "product", product_id: "ch_mobile_fr" },
{ scope: "product", product_id: "ch_inapp_de" },
{ scope: "product", product_id: "ch_inapp_fr" },
{ scope: "proposal", proposal_id: "swiss_balanced_v1", ask: "focus more on German speakers - try 60/40 instead of 40/60" }
]
})
// Seller returns an updated proposal with revised allocations
```
See [`get_products` refinement](/dist/docs/3.2.8/media-buy/task-reference/get_products#refinement) for the full workflow and examples.
### Executing a Proposal
To execute a committed proposal, provide the `proposal_id` and `total_budget` in `create_media_buy`:
```json theme={null}
{
"proposal_id": "swiss_balanced_v1",
"total_budget": {
"amount": 50000,
"currency": "USD"
},
"brand": { "domain": "acmecorp.com" },
"start_time": "2025-04-01T00:00:00Z",
"end_time": "2025-04-30T23:59:59Z"
}
```
For a fixed proposal, the publisher converts allocation percentages into packages:
* `ch_desktop_de`: 20% × \$50,000 = \$10,000
The split 3.2 [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) task returns immutable drafts. [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) either creates another draft revision or, with `action: "finalize"`, returns a committed snapshot with inventory held until `expires_at`. [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) is the acceptance/execution step. Legacy `get_products` retains its equivalent finalize form throughout 3.x.
* `ch_desktop_fr`: 30% × \$50,000 = \$15,000
* etc.
For a seller-optimized proposal, the publisher instead converts minimum and maximum percentage constraints into absolute package constraints, activates the proposal's cross-package optimization goals and aggregate pacing, and copies allocation pacing onto the corresponding derived package. In either mode, proposal execution simplifies a complex multi-package campaign to one acceptance call.
### When Publishers Return Proposals
Publishers include proposals when:
* The brief requests specific allocation strategies (channel splits, language splits, etc.)
* The publisher can provide strategic guidance based on campaign goals
* Multiple products work better together than individually
Publishers typically omit proposals in `wholesale` mode (the buyer is directing targeting and allocation themselves) or when the brief doesn't suggest a multi-product strategy.
Proposals are optional — publishers may return only products if allocation guidance isn't applicable. In `refine` mode, sellers MAY return proposals alongside refined products even when the buyer did not include proposal entries. Proposals are a seller suggestion — allocation and campaign optimization are primarily orchestrator (buyer-side agent) responsibilities.
### Delivery Forecasts
Publishers can attach delivery forecasts to proposals and individual allocations to help buyers evaluate expected performance before committing budget. For targeting-aware discovery, every forecast and availability statement reflects concrete effective targeting after any disclosed `targeting_resolution` modifications. A dimension requested only through `required_overlay_support` has no concrete values, so the forecast describes the product's discovery/default scope rather than every possible later selection; buyers rediscover with concrete `targeting_overlay` values for a value-specific forecast.
Each forecast contains a `points` array of one or more ForecastPoints. For spend curves, each point pairs a budget level with metric ranges (low/mid/high) — multiple points at ascending budgets show how delivery scales with spend. For availability forecasts, points omit budget and express total available inventory for the requested targeting and dates.
Metric keys come from two vocabularies:
* **Delivery/engagement**: `forecastable-metric` enum values (impressions, reach, clicks, spend, views, completed_views, grps, etc.)
* **Outcomes**: `event-type` enum values (`purchase`, `lead`, `app_install`, `add_to_cart`, `subscribe` for paid subscriptions, `follow` for free durable opt-ins, etc.)
This lets sellers forecast both delivery ("1.2M impressions") and outcomes ("1,800 purchases") in a single forecast. Each forecast declares its method:
* **`estimate`** — rough approximation based on historical averages or heuristics
* **`modeled`** — derived from predictive models or historical data
* **`guaranteed`** — contractually committed delivery levels backed by reserved inventory
Each metric value is a ForecastRange object. Provide `mid` for a point estimate, `low` and `high` for a range, or all three. At minimum, either `mid` or both `low` and `high` must be present.
Forecast points can also carry `dimensions` when a seller needs to expose availability by country, region, placement, device, audience, signal value, or an intersection such as placement x country or product x signal. `dimensions` is an array; each item declares one `kind` (`geo`, `placement`, `device_type`, `device_platform`, `audience`, `signal`, or `time`) and uses the same canonical identifiers as targeting and delivery reporting, such as `geo_level`/`geo_code` for geography, `placement_ref` for placements, and `signal_ref` plus `signal_value`/`presence` for signal buckets. Metro rows use `system` values from `metro-system` (`nielsen_dma`, `uk_itl1`, `uk_itl2`, `eurostat_nuts2`, `custom`); native postal rows use `country` plus country-local `system` values from `postal-system` (for example, `US` / `zip`, `GB` / `outward`, `ZA` / `postal_code`), while deprecated country-fused postal systems such as `us_zip` remain accepted for compatibility; country and region rows omit `system`. When multiple dimension items appear on one point, the point represents the intersection of those constraints. Dimension order has no meaning; buyers normalize row identity from `(forecast_range_unit, budget if present, product_id if present, dimensions sorted by kind)`. Sellers MUST NOT repeat the same `kind` on one point. If a seller needs multiple geo, placement, audience, or signal slices, it should emit multiple points instead. This keeps dimensional availability inside one product or proposal instead of forcing sellers to create separate products for every country, placement, or signal value. Dimension rows are independent of `pricing_options`; the product's pricing options still describe how the product is bought.
Forecast points may include measurement-aware forecasts alongside standard delivery metrics:
* **`viewability`** mirrors the `get_media_buy_delivery` `viewability` block, but numeric values use ForecastRange objects. Sellers SHOULD only emit forecast viewability when the product can report corresponding delivery viewability. Forecast `standard` is required whenever forecast viewability values are present because MRC and GroupM rows are not interchangeable; delivery `viewability.standard` remains optional for 3.x compatibility but SHOULD be populated.
* **`vendor_metric_values`** mirrors delivery reporting for vendor-defined metrics, but `value` and the coverage denominators (`measurable_impressions`, or `measurable_plays` / `measurable_play_seconds` for play-based channels) use ForecastRange objects. Sellers SHOULD only forecast vendor metrics that the product declares in `reporting_capabilities.vendor_metrics`.
#### Forecast Range Units
The `forecast_range_unit` field tells consumers how to interpret the points array — what axis the curve represents:
* **`spend`** (default) — points at ascending budget levels. Standard budget curve.
* **`availability`** — each point represents total available inventory for the requested targeting and dates. Budget is omitted; use `metrics.spend` to express estimated cost. Typical for guaranteed and direct-sold inventory. With `offer_filters.availability_horizon`, points carry a `time` dimension and `availability_status` so one forecast also answers "which dates can I run?" (see [Flexible Availability Windows](#flexible-availability-windows)).
* **`reach_freq`** — points at ascending reach/frequency targets. Used in broadcast planning where the publisher shows how cost scales with frequency goals.
* **`weekly`** / **`daily`** — metrics are per-period values. Budget refers to total campaign spend. A frequency of 3.2 with `weekly` means 3.2 exposures per week.
* **`clicks`** / **`conversions`** — points at ascending outcome targets. Used in goal-based planning (e.g., "tell me your conversion goal, I'll tell you the budget"). Buyers express the goal structurally via [`criteria.outcome_target`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals#reverse-forecasting-with-outcome_target) on sellers that declare `media_buy.outcome_target`, as a volume, a [cost target](/dist/docs/3.2.8/media-buy/task-reference/request_proposals#cost-targets), or both. For a cost target, the points carry the volume planned under the policy the proposal states in `commercial_terms.bidding.cost_per`.
* **`package`** — each point represents a distinct inventory package (e.g., Good/Better/Best tiers). Points are separate products with different inventory compositions, not levels on a spend curve. Used by broadcast TV, audio, and DOOH sellers.
A spend curve and a reach/frequency curve may contain identical data — the difference is the publisher's intent. A spend curve says "here's what different budgets buy." A reach/frequency curve says "here's what it costs to hit different frequency targets." Consumers can read either curve in either direction.
Temporal units (`weekly`, `daily`) change how metrics are interpreted. Without a range unit (or with `spend`), a frequency of 3.2 means 3.2 total campaign exposures. With `weekly`, it means 3.2 exposures per week.
Forecasts can appear at two levels:
* **Proposal-level**: aggregate forecast for the entire media plan
* **Allocation-level**: per-product forecast for individual line items
Allocation-level forecasts may not sum to the proposal-level forecast due to audience overlap and frequency capping. When both are present, the proposal-level forecast is authoritative for total delivery estimation.
For cross-channel planning, forecasts declare a `reach_unit` (individuals, households, devices, accounts, cookies) so buyers can compare reach across publishers. GRP-based forecasts (linear TV, radio) use `demographic_system` and `demographic` to specify the target demo, following the same pattern as CPP pricing.
When a forecast is based on third-party measurement, the `measurement_source` field declares which provider's data was used to produce the numbers. This is distinct from `demographic_system`, which specifies demographic notation — `measurement_source` identifies whose data produced the forecast numbers. A forecast can use Nielsen demographic codes (`demographic_system: "nielsen"`) while the impression numbers come from VideoAmp (`measurement_source: "videoamp"`).
Sellers whose forecasts are based on third-party measurement use `measured_impressions` to express delivery as counted by the `measurement_source` provider. This is distinct from `impressions`, which represents ad-server or first-party estimated delivery. The two metrics are independent of the guarantee — `measured_impressions` can appear on both guaranteed and non-guaranteed forecasts:
* **Guaranteed broadcast**: `method: "guaranteed"` + `measured_impressions` + `measurement_source: "nielsen"` — the seller contractually commits to Nielsen-measured delivery
* **Non-guaranteed CTV**: `method: "modeled"` + `measured_impressions` + `measurement_source: "videoamp"` — VideoAmp-measured estimate, no contractual commitment
* **Programmatic display**: `method: "modeled"` + `impressions` — ad-server counts, no third-party currency needed
Sellers may include both `measured_impressions` and `impressions` in the same point when the buyer needs both the third-party-measured figure and the ad-server estimate.
Podcast sellers use `downloads` as their primary delivery currency per IAB Podcast Measurement guidelines, in place of or alongside `impressions`.
#### Budget Curve
Multiple forecast points at ascending budget levels show how metrics scale with spend, helping buyers find the optimal investment level:
```json theme={null}
{
"points": [
{
"budget": 25000,
"metrics": {
"impressions": { "low": 400000, "mid": 500000, "high": 600000 },
"reach": { "mid": 180000 },
"clicks": { "mid": 2000 }
}
},
{
"budget": 50000,
"metrics": {
"impressions": { "low": 850000, "mid": 1050000, "high": 1200000 },
"reach": { "mid": 320000 },
"clicks": { "mid": 4200 }
}
},
{
"budget": 100000,
"metrics": {
"impressions": { "low": 1500000, "mid": 1900000, "high": 2200000 },
"reach": { "mid": 500000 },
"clicks": { "mid": 7600 }
}
}
],
"method": "modeled",
"currency": "USD",
"reach_unit": "individuals"
}
```
The curve reveals diminishing returns — doubling budget from \$50K to \$100K increases reach by \~56%, not 2x. Buyers can use this to negotiate or reallocate budget across publishers.
#### Availability Forecast
For guaranteed and direct-sold inventory, the forecast is an availability check — how much inventory exists on this placement with this targeting in this flight window. Budget is omitted because available inventory doesn't depend on how much the buyer wants to spend. The seller can include `metrics.spend` to express the estimated cost of the available inventory:
```json theme={null}
{
"points": [
{
"metrics": {
"impressions": { "low": 320000, "mid": 400000, "high": 480000 },
"reach": { "low": 200000, "mid": 260000, "high": 300000 },
"spend": { "low": 6400, "mid": 8000, "high": 9600 }
}
}
],
"forecast_range_unit": "availability",
"method": "guaranteed",
"currency": "USD"
}
```
The buyer agent can compare available impressions against budget requirements to identify underdelivery. If the buyer needs 500,000 impressions at a \$20 CPM to spend their full \$10K budget, and the forecast shows 400,000 mid available, the buyer knows \$2K of budget must be allocated elsewhere.
#### Flexible Availability Windows
Exact-date and flexible-date discovery are two readings of the same question. When the buyer already knows the flight, `offer_filters.start_date`/`end_date` scope discovery to it and the availability forecast answers "can I run these dates?". When the buyer is flexible — common for calendar-shaped inventory like homepage takeovers and sponsorships — `offer_filters.availability_horizon` asks the complementary question, "which dates can I run?":
```json theme={null}
{
"offer_filters": {
"availability_horizon": {
"start_time": "2026-09-01T00:00:00-04:00",
"end_time": "2026-10-01T00:00:00-04:00"
}
}
}
```
The seller answers by partitioning the horizon into `time`-dimensioned forecast points, each carrying an `availability_status`:
```json theme={null}
{
"forecast_range_unit": "availability",
"method": "modeled",
"currency": "USD",
"generated_at": "2026-08-18T12:00:00Z",
"valid_until": "2026-08-18T12:05:00Z",
"points": [
{
"dimensions": [
{ "kind": "time", "start_time": "2026-09-01T00:00:00-04:00", "end_time": "2026-09-20T00:00:00-04:00" }
],
"availability_status": "available",
"metrics": {
"impressions": { "mid": 20000 },
"spend": { "mid": 6400 }
}
},
{
"dimensions": [
{ "kind": "time", "start_time": "2026-09-20T00:00:00-04:00", "end_time": "2026-09-27T00:00:00-04:00" }
],
"availability_status": "unavailable",
"metrics": {}
},
{
"dimensions": [
{ "kind": "time", "start_time": "2026-09-27T00:00:00-04:00", "end_time": "2026-10-01T00:00:00-04:00" }
],
"availability_status": "available",
"metrics": {
"impressions": { "mid": 4200 },
"spend": { "mid": 1350 }
}
}
]
}
```
Window semantics:
* **Windows are half-open** (`[start_time, end_time)`), non-overlapping, and coalesced — adjacent windows with the same status and materially identical metrics are merged.
* **A complete response partitions the requested horizon.** A seller that cannot cover the full horizon signals the gap through the response's `incomplete[]` mechanism rather than silently omitting windows.
* **`availability_status` is a snapshot, never a hold.** `valid_until` bounds its freshness. Commitment happens at proposal finalization or purchase — a buy against a window that has since closed fails with `PRODUCT_UNAVAILABLE`, and the buyer re-reads. Buyers that need a guarantee take an inventory hold by finalizing a proposal rather than polling for fresher snapshots.
* **`unavailable` covers all non-bookable windows, not only held ones.** Sellers MUST apply all product booking eligibility rules — including minimum and maximum bookable duration, day-of-week restrictions, and other scheduling constraints — before reporting status. A gap that is not held by any buyer but is too short to meet the product's minimum duration is `unavailable`, not `available`. Buyers can safely skip `unavailable` rows without attempting a booking; doing so avoids an otherwise-predictable `PRODUCT_UNAVAILABLE` error.
* **No demand disclosure.** Sellers MUST NOT disclose who holds a closed window, and `unavailable` rows may carry empty metrics.
* **`availability_horizon` is not an eligibility filter.** Products remain returnable when only part of the horizon is open — that partial openness is exactly what the buyer asked to see. It is mutually exclusive with `start_date`/`end_date`; buyers that already know their flight use those instead.
* **Derived values stay buyer-side.** "Next available date" and similar conveniences are computed by the buyer from the windows; they are not response fields.
#### Dimensional Availability and Measurement
Sellers can expose availability by country, placement, signal value, placement x country, product x signal, or other dimensional intersections as forecast points on the same product. A point with multiple `dimensions` items represents the intersection of all listed constraints. Rows are comparable when they use the same dimension grain, such as placement x country rows for several countries or signal-value rows for one product baseline. Buyers MUST NOT sum rows unless the seller explicitly documents that the rows form a complete, non-overlapping partition.
Within a single point, dimension items are ANDed, not ORed. Sellers MUST NOT emit more than one item per `kind`; buyers MUST NOT infer OR semantics from order or repetition. Repeated peer values such as two `geo` country rows in one point are a seller conformance issue.
Only count or currency metrics, such as `impressions`, `clicks`, `spend`, `measured_impressions`, and `viewable_impressions`, are candidates for rollup, and only inside a declared complete, non-overlapping partition. Reach, frequency, rates, averages, `viewability.viewable_rate`, `viewability.viewed_seconds`, and `vendor_metric_values[].value` are non-additive unless the seller or measurement vendor publishes an explicit rollup method. Vendor metric coverage counts such as `vendor_metric_values[].measurable_impressions` follow the same partition rule as other counts.
This avoids product-per-country or product-per-placement expansion while still giving buyer agents the planning rows they need:
```json theme={null}
{
"points": [
{
"dimensions": [
{
"kind": "placement",
"placement_ref": {
"publisher_domain": "publisher.example",
"placement_id": "header_bidding"
},
"placement_name": "Header bidding"
},
{
"kind": "geo",
"geo_level": "country",
"geo_code": "US",
"geo_name": "United States"
}
],
"metrics": {
"impressions": { "low": 900000, "mid": 1200000, "high": 1400000 },
"spend": { "mid": 24000 }
},
"viewability": {
"vendor": { "domain": "measurementvendor.example" },
"measurable_impressions": { "mid": 1050000 },
"viewable_rate": { "low": 0.68, "mid": 0.73, "high": 0.78 },
"standard": "mrc"
},
"vendor_metric_values": [
{
"vendor": { "domain": "attentionvendor.example" },
"metric_id": "attention_units",
"value": { "low": 3.9, "mid": 4.4, "high": 4.9 },
"unit": "score",
"measurable_impressions": { "mid": 980000 }
}
]
},
{
"dimensions": [
{
"kind": "placement",
"placement_ref": {
"publisher_domain": "publisher.example",
"placement_id": "header_bidding"
},
"placement_name": "Header bidding"
},
{
"kind": "geo",
"geo_level": "country",
"geo_code": "CA",
"geo_name": "Canada"
}
],
"metrics": {
"impressions": { "low": 250000, "mid": 320000, "high": 380000 },
"spend": { "mid": 9600 }
},
"viewability": {
"vendor": { "domain": "measurementvendor.example" },
"viewable_rate": { "mid": 0.81 },
"standard": "mrc"
}
}
],
"forecast_range_unit": "availability",
"method": "modeled",
"currency": "USD"
}
```
Each point is a row in the forecast, not a separate product. Buyers can compare country-by-placement avails, viewability expectations, and vendor measurement forecasts while still selecting from the product's normal pricing options when they create the buy.
A buyer agent turns a chosen dimensional row into a buy through the existing buy-time surfaces:
* `kind: "geo"` rows map to `packages[].targeting_overlay.geo_countries`, `geo_regions`, `geo_metros`, or `geo_postal_areas`, depending on `geo_level` and seller support. Country rows use ISO 3166-1 alpha-2 `geo_code`; region rows use ISO 3166-2 `geo_code`; metro rows include the corresponding targeting `system` enum; native postal rows include `country` plus the country-local `system`.
* `kind: "device_type"` and `kind: "device_platform"` rows map to the corresponding targeting overlay fields when the seller supports device targeting.
* `kind: "audience"` rows map to `audience_include` or signal targeting only when the audience is selectable for that product; informational audience rows are planning signals, not automatic targeting handles.
* `kind: "placement"` rows map to `targeting_overlay.placement_selection` when the product exposes the placement as `mode: "targetable"`. `dimensions[].placement_ref` describes an inventory slice but does not select it. `creative_assignments[].placement_refs` is only the creative-routing surface after package inventory is selected. Proposal-level forecast points with placement dimensions should include `product_id` when the placement maps to one allocation's product.
`kind: "signal"` rows use canonical `signal_ref` plus optional `signal_value` to describe a signal bucket. Use `presence: "present"` for rows where the signal is available with the supplied value, and `presence: "absent"` with `signal_value: null` for the explicit not-present bucket. `signal_id` is only a shorthand when the enclosing object already identifies the signal unambiguously, such as a coverage forecast nested directly under a single `get_signals` item. Product-level forecasts use `ForecastPoint.product_id` for product context; do not add a separate product dimension item.
After purchase, buyers verify marginals with `get_media_buy_delivery.reporting_dimensions` (`geo`, `device_type`, `device_platform`, `audience`, `placement`, `property`, `collection`, or `installment`) and reconcile measurement expectations through the package's `committed_metrics`, `performance_standards`, and reported `viewability` / `vendor_metric_values`. The standardized `collection_property`, `installment_property`, and `placement_property` dimensions prove which property carried a content program, specific airing or programming block, or aggregate placement. Other arbitrary intersections, such as placement × country or product × signal, are not currently standardized.
#### CTV with GRP Demographics
TV and audio forecasts use `demographic_system` and `demographic` to specify the target demo, and `measurement_source` to declare whose audience data the forecast is modeled against:
```json theme={null}
{
"points": [
{
"budget": 75000,
"metrics": {
"grps": { "low": 45, "mid": 60, "high": 72 },
"impressions": { "mid": 3200000 },
"reach": { "low": 800000, "mid": 1100000, "high": 1300000 },
"frequency": { "mid": 2.9 }
}
}
],
"method": "modeled",
"measurement_source": "nielsen",
"currency": "USD",
"demographic_system": "nielsen",
"demographic": "P18-49",
"reach_unit": "households"
}
```
The `measurement_source: "nielsen"` tells the buyer agent that the GRP and impression numbers are modeled against Nielsen data. The `reach_unit: "households"` tells buyers this CTV publisher counts reach by household, not individual. A display publisher reporting `reach_unit: "devices"` is measuring something different — buyers should not directly compare the two reach numbers.
Note that `measurement_source` and `demographic_system` can differ. A CTV publisher might use Nielsen's demographic notation (`demographic_system: "nielsen"`, `demographic: "P18-49"`) while the underlying audience data comes from VideoAmp (`measurement_source: "videoamp"`). The demographic system specifies the notation; the measurement source specifies whose numbers produced the forecast.
#### Retail Media with Outcome Forecasts
Retail media publishers can forecast both delivery metrics and conversion outcomes. Outcome metric keys use `event-type` values:
```json theme={null}
{
"points": [
{
"budget": 30000,
"metrics": {
"impressions": { "low": 600000, "mid": 750000, "high": 900000 },
"clicks": { "mid": 6000 },
"purchase": { "low": 1200, "mid": 1800, "high": 2400 },
"add_to_cart": { "mid": 4500 }
}
}
],
"method": "modeled",
"currency": "USD"
}
```
Here `impressions` and `clicks` are `forecastable-metric` values while `purchase` and `add_to_cart` are `event-type` values. Both use ForecastRange (low/mid/high) and coexist in the same metrics map.
#### Allocation-Level Forecasts
When a proposal includes per-allocation forecasts, buyers can evaluate each product independently:
```json theme={null}
{
"proposal_id": "retail_holiday_v1",
"name": "Holiday Retail Campaign",
"allocations": [
{
"product_id": "sponsored_search",
"allocation_percentage": 40,
"forecast": {
"points": [
{
"budget": 20000,
"metrics": {
"impressions": { "mid": 500000 },
"clicks": { "mid": 15000 },
"purchase": { "mid": 900 }
}
}
],
"method": "modeled",
"currency": "USD"
}
},
{
"product_id": "offsite_display",
"allocation_percentage": 60,
"forecast": {
"points": [
{
"budget": 30000,
"metrics": {
"impressions": { "low": 1800000, "mid": 2200000, "high": 2600000 },
"reach": { "mid": 450000 },
"purchase": { "low": 400, "mid": 600, "high": 800 }
}
}
],
"method": "modeled",
"currency": "USD",
"reach_unit": "accounts"
}
}
],
"forecast": {
"points": [
{
"budget": 50000,
"metrics": {
"impressions": { "low": 2100000, "mid": 2700000, "high": 3100000 },
"reach": { "mid": 520000 },
"purchase": { "low": 1100, "mid": 1500, "high": 1900 }
}
}
],
"method": "modeled",
"currency": "USD",
"reach_unit": "accounts"
}
}
```
Note that the allocation forecasts (900 + 600 = 1,500 purchases) happen to match the proposal forecast in this example, but they often won't — audience overlap and frequency capping mean the whole is typically less than the sum of its parts. The proposal-level forecast is authoritative for total delivery.
#### Broadcast Audio Spot Plan
Broadcast and audio publishers can return spot-plan proposals with `daypart_targets` on each allocation and weekly frequency projections via `forecast_range_unit: "weekly"`. This pattern lets the publisher solve the optimization problem — the buyer specifies frequency goals, and the publisher returns the plan that achieves them:
```json theme={null}
{
"proposal_id": "iheart_q4_audio",
"name": "Q4 Audio - Adults 25-54",
"allocations": [
{
"product_id": "morning_drive_30s",
"allocation_percentage": 50,
"daypart_targets": [
{
"days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
"start_hour": 6,
"end_hour": 10,
"timezone": "inventory_local",
"label": "Morning Drive"
}
],
"rationale": "Morning drive delivers highest reach against P25-54 with 3x weekly frequency at 2 spots/day",
"forecast": {
"points": [
{
"budget": 37500,
"metrics": {
"grps": { "mid": 42 },
"reach": { "low": 140000, "mid": 180000, "high": 210000 },
"frequency": { "mid": 3.2 },
"impressions": { "mid": 576000 }
}
}
],
"forecast_range_unit": "weekly",
"method": "modeled",
"currency": "USD",
"demographic_system": "nielsen",
"demographic": "P25-54",
"reach_unit": "individuals"
}
},
{
"product_id": "afternoon_drive_30s",
"allocation_percentage": 30,
"daypart_targets": [
{
"days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
"start_hour": 15,
"end_hour": 19,
"timezone": "inventory_local",
"label": "Afternoon Drive"
}
],
"rationale": "Afternoon drive complements morning with incremental reach and frequency overlap",
"forecast": {
"points": [
{
"budget": 22500,
"metrics": {
"grps": { "mid": 28 },
"reach": { "low": 95000, "mid": 120000, "high": 145000 },
"frequency": { "mid": 2.4 },
"impressions": { "mid": 288000 }
}
}
],
"forecast_range_unit": "weekly",
"method": "modeled",
"currency": "USD",
"demographic_system": "nielsen",
"demographic": "P25-54",
"reach_unit": "individuals"
}
},
{
"product_id": "daytime_30s",
"allocation_percentage": 20,
"daypart_targets": [
{
"days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
"start_hour": 10,
"end_hour": 15,
"timezone": "inventory_local",
"label": "Daytime"
}
],
"rationale": "Daytime fill provides frequency reinforcement at lower CPP",
"forecast": {
"points": [
{
"budget": 15000,
"metrics": {
"grps": { "mid": 18 },
"reach": { "low": 60000, "mid": 80000, "high": 95000 },
"frequency": { "mid": 1.8 },
"impressions": { "mid": 144000 }
}
}
],
"forecast_range_unit": "weekly",
"method": "modeled",
"currency": "USD",
"demographic_system": "nielsen",
"demographic": "P25-54",
"reach_unit": "individuals"
}
}
],
"forecast": {
"points": [
{
"budget": 75000,
"metrics": {
"grps": { "mid": 82 },
"reach": { "low": 220000, "mid": 280000, "high": 330000 },
"frequency": { "mid": 4.1 },
"impressions": { "mid": 1008000 }
}
}
],
"forecast_range_unit": "weekly",
"method": "modeled",
"currency": "USD",
"demographic_system": "nielsen",
"demographic": "P25-54",
"reach_unit": "individuals"
}
}
```
The `forecast_range_unit: "weekly"` on each forecast tells the buyer that all metrics are per-week values — frequency of 3.2 means 3.2 exposures per week, not 3.2 over the entire campaign. Budget (\$75K) is total campaign spend.
The `daypart_targets` on each allocation specify the publisher's recommended time windows. These are the same structure used in `targeting` for hard daypart constraints — here the publisher is prescribing the spot plan rather than the buyer constraining it. `inventory_local` evaluates each window in the station's seller-assigned local time; omission has the same default. A synchronized national moment instead uses one concrete IANA zone on the applicable entries.
Note that allocation-level reach doesn't sum to the proposal level (180K + 120K + 80K > 280K) because of audience overlap across dayparts — the same listener may hear morning drive and afternoon drive spots. The proposal-level forecast accounts for this overlap.
#### Broadcast TV Package Forecast
Broadcast TV sellers offer distinct inventory packages rather than impressions at variable spend levels. The `forecast_range_unit: "package"` tells the buyer that each point is a separate package, not a position on a spend curve. Each point includes a `label` so the buyer agent can identify and reference individual packages. A broadcaster might offer a daytime rotator, a prime-access + daytime bundle, and a full prime package:
```json theme={null}
{
"points": [
{
"label": "Daytime Rotator",
"budget": 50000,
"metrics": {
"measured_impressions": { "mid": 800000 },
"grps": { "mid": 35 },
"reach": { "mid": 220000 },
"frequency": { "mid": 2.1 }
}
},
{
"label": "Prime Access + Daytime",
"budget": 85000,
"metrics": {
"measured_impressions": { "mid": 1400000 },
"grps": { "mid": 58 },
"reach": { "low": 290000, "high": 390000 },
"frequency": { "mid": 3.4 }
}
},
{
"label": "Full Prime",
"budget": 150000,
"metrics": {
"measured_impressions": { "mid": 2600000 },
"grps": { "mid": 95 },
"reach": { "low": 420000, "high": 540000 },
"frequency": { "mid": 5.2 }
}
}
],
"forecast_range_unit": "package",
"method": "modeled",
"measurement_source": "nielsen",
"currency": "USD",
"demographic_system": "nielsen",
"demographic": "P18-49",
"reach_unit": "households"
}
```
Each point represents a distinct package — different dayparts, unit types, and flight structures — not the same product at three spend levels. The `label` field lets buyer agents reference packages by name when negotiating or requesting specific options. The `measurement_source: "nielsen"` tells the buyer agent that the impression and GRP numbers are modeled against Nielsen data, not the broadcaster's own measurement. The `measured_impressions` metric expresses delivery as counted by Nielsen — paired with `method: "modeled"`, these are Nielsen-measured estimates. To make them contractual commitments, the seller would use `method: "guaranteed"` instead.
Broadcast buying shape determines product shape:
* **Network or rep-firm package**: model as one seller product when one seller commits the order and fulfills across multiple markets or affiliates. The affiliates are fulfillment surfaces, not independent AdCP hops.
* **Local spot or station-group inventory**: model separate products or packages when inventory is sold by distinct stations, station groups, or market sellers.
* **Market-by-market syndication**: model by the party that sells and commits the inventory. If multiple sellers commit separately, the buyer aggregates their delivery reports across media buys.
Use `delivery_type: "guaranteed"` when spots, units, or inventory are reserved or scheduled. Use `forecast.method: "modeled"` for historical audience ranges and `forecast.method: "guaranteed"` only when the seller is contractually committing to make good delivery outside the stated range. Do not use `non_guaranteed` merely because final measured impressions depend on historical ranges or third-party measurement settlement.
If packages share the same inventory pool and differ only in volume or mix, use `package` forecast points on one product. If they represent fundamentally different inventory (different shows, properties, or dayparts with no overlap), create separate products with their own forecasts.
Sellers expressing the same inventory in multiple measurement currencies (e.g., both Nielsen and VideoAmp) should provide separate DeliveryForecast objects, one per `measurement_source`.
## Integration with Discovery
Products are discovered through the [Product Discovery](/dist/docs/3.2.8/media-buy/product-discovery) process, which uses natural language to match campaign briefs with available inventory. Once products are identified, they can be purchased via `create_media_buy`.
## See Also
* [Product Discovery](/dist/docs/3.2.8/media-buy/product-discovery) - How to discover products using natural language
* [Media Buys](/dist/docs/3.2.8/media-buy/media-buys) - How to purchase products
* [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) - Detailed targeting options
* [Creative Formats](/dist/docs/3.2.8/creative/formats) - Understanding format specifications and discovery
# Proposal negotiation
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation
Implement AdCP 3.2 proposal negotiation from capability discovery through revision, finalization, acceptance, amendment, and cancellation.
AdCP 3.2 proposal negotiation is an immutable-snapshot workflow. Buyers express mechanically verifiable requirements as typed fields and reserve `ask` for commercial nuance. Sellers validate the complete request before mutation, then return one independently classified result for each source proposal.
This guide uses one scenario throughout: Sam, a buyer agent acting for Pinnacle Agency, is negotiating an Acme Outdoor campaign with the StreamHaus sales agent.
## Lifecycle
```mermaid theme={null}
flowchart LR
D0[Initial draft] -->|refine_proposals: revise| D1[Successor draft]
D1 -->|refine_proposals: finalize| H[Committed inventory hold]
H -->|accept_proposal before expires_at| A[Accepted proposal and MediaBuy]
A -->|revise: amendment| AD[Amendment draft]
A -->|revise: cancellation| CD[Cancellation draft]
AD -->|finalize then accept| A2[Updated MediaBuy]
CD -->|finalize then accept| C[Canceled MediaBuy]
```
Every transition creates a new `proposal_id`; the source snapshot remains unchanged. Every successor returned by [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) carries `parent_proposal_id` equal to the source ID. A buyer can therefore reconstruct negotiation and amendment history by walking the parent chain.
`draft` terms are indicative and do not reserve inventory. `finalize` copies an unchanged draft into a `committed` snapshot and creates a hold until `expires_at`. [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) consumes that hold and creates, updates, or cancels the MediaBuy according to `proposal_kind`.
In traditional media terms, this lifecycle is the two-phase avails check. A draft is a **soft avail**: the seller answers from models or cached inventory state, forecasts carry `valid_until` freshness bounds, and nothing is reserved — another buyer can take the inventory before this one commits. `finalize` is where the **firm avail** runs: the seller hits its inventory system, re-prices if needed, and either takes the hold or fails the finalize. Draft numbers are therefore non-binding, and a finalize returning different pricing or forecast values than its source draft showed is correct behavior, not an error. Buyers that need certainty across a slow approval chain hold inventory by finalizing early — not by polling discovery for fresher snapshots.
## Discover what the seller supports
Read `get_adcp_capabilities.media_buy.lifecycle_tools` before selecting the compact lifecycle. A negotiating seller includes `refine_proposals`; it may also publish `media_buy.proposal_refinement`:
For product design and adopter communication, these capability sets are useful shorthand:
| Capability set | Typical advertised tools | What a client can safely claim |
| - | - | - |
| Proposal exploration | `request_proposals`, optionally `refine_proposals` and `decline_proposals` | Request, compare, and negotiate seller-authored proposals; no executable purchase is implied. |
| Executable proposal lifecycle | `request_proposals`, `refine_proposals`, and `accept_proposal` | Negotiate, create a seller-backed hold through finalization, and consume accepted terms into a MediaBuy. |
| Direct purchase | `list_products` and `buy_products` | Read a wholesale offer feed and buy an eligible published offer without proposal negotiation. |
| Campaign operations | `control_media_buy` | Operate an existing MediaBuy within its accepted rights and current state. |
These labels are non-normative adopter shorthand, not new conformance profiles. The advertised `lifecycle_tools` array remains authoritative, and buyers must inspect the individual tools rather than infer support from a label. In particular, a proposal-exploration implementation must not claim executable acceptance unless the seller also exposes the hold and acceptance path.
| Dimension | Request field | Mechanical promise |
| - | - | - |
| `total_budget` | `constraints.total_budget` | Validate a present total, matching currency, and inclusive bounds. |
| `cpm` | `constraints.cpm` | Validate every purchase as fixed CPM/vCPM in the requested currency at or below the ceiling; auction and non-CPM pricing are unsatisfied. |
| `impressions` | `constraints.impressions` | Validate that every purchase has a concrete impression volume and their sum meets the inclusive floor. |
| `flight` | `constraints.flight` | Validate concrete timestamps against `start_no_later_than` and `end_no_earlier_than`; an `asap` start cannot satisfy a start bound. |
| `product_changes` | `product_changes` | Validate keyed `include` and `omit` actions against returned purchases. |
| `alternatives` | `alternatives.count` | Return distinct commercial terms up to the advertised `max_alternatives`. |
| `criteria` | `criteria` | Parse and replace structured discovery criteria. |
An explicit `supported_dimensions: []` means ask-only refinement. An omitted `proposal_refinement` block means typed support is unknown, so the buyer must tolerate per-result `partial` or `unable` outcomes.
When an explicit list omits a dimension, the buyer SHOULD remove or translate that field before sending. If it sends the field anyway, the seller MUST reject the entire task with `UNSUPPORTED_FEATURE` before creating any successor. Free-text interpretation is competence, not a capability dimension; `ask` remains available even when the list is empty.
When the seller interprets hard targeting found only in `ask` and that interpretation materially affects eligibility, pricing, or forecasting, inspect the result's `targeting_resolution.brief_targeting`. Structured `criteria.targeting_overlay` is not echoed when accepted exactly; any product-specific departure remains a sparse `Product.targeting_resolution.modifications` proposal that the buyer must review.
## Two failure planes
Do not flatten task errors and negotiation outcomes into one exception type.
| Plane | Examples | Mutation rule | Buyer action |
| - | - | - | - |
| Task-level error | Malformed payload, more than 25 refinements, duplicate source IDs, count above 10 or `max_alternatives`, explicitly unsupported dimension, unauthorized source | No sibling may mutate | Correct the whole request and retry with a new key. |
| Per-proposal outcome | `revised`, `partial`, `unable`, `finalized` | One ordered result per source; revision outcomes are independent | Verify the typed result, then select, revise, finalize, or decline. |
| Atomic finalize outcome | `finalized`, `hold_unavailable`, `batch_aborted` | Every hold is created or none are | Retry the exact batch only for an exact replay; otherwise form a new request. |
`constraint_unsatisfiable` means the seller accepted the dimension but did not satisfy it. `unsupported_dimension` is used per proposal only when capabilities were unknown; an explicitly omitted dimension is a task-level `UNSUPPORTED_FEATURE`. `commercially_declined` applies only to `ask`, never to a typed constraint.
For example, if StreamHaus explicitly omits `criteria`, the task fails before any proposal is created:
```json theme={null}
{
"$schema": "/schemas/3.2.8/core/protocol-envelope.json",
"status": "failed",
"adcp_error": {
"code": "UNSUPPORTED_FEATURE",
"message": "This seller does not support criteria refinement.",
"field": "refinements[0].criteria",
"recovery": "correctable",
"details": {
"unsupported_dimension": "criteria",
"supported_dimensions": ["total_budget", "cpm", "alternatives"]
}
}
}
```
## Buyer implementation
### 1. Build typed-first requests
Sam requests a USD 50,000 ceiling, a CPM ceiling, US/Canada criteria, a product change, and three distinct alternatives. The prose asks for subjective reach optimization only:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-request.json",
"idempotency_key": "typed-negotiation-sam-0001",
"refinements": [
{
"proposal_id": "proposal_streamhaus_001",
"action": "revise",
"constraints": {
"total_budget": { "max": 50000, "currency": "USD" },
"cpm": { "max": 18, "currency": "USD" },
"flight": { "end_no_earlier_than": "2026-10-31T23:59:59Z" }
},
"product_changes": {
"premium_video_q4": "include",
"display_standard_q4": "omit"
},
"criteria": {
"targeting_overlay": { "geo_countries": ["US", "CA"] }
},
"alternatives": { "count": 3 },
"ask": "Use materially different mixes and prioritize reach."
}
]
}
```
Typed fields are hard proposal requirements. Do not copy legacy `get_products.filters.budget_range` into `constraints.total_budget`: the legacy field is a hard product-discovery filter, while the compact field validates the negotiated proposal's `commercial_terms.total_budget` and forces `partial` or `unable` when missed. Legacy `more_like_this` has no typed compact equivalent and maps only lossily to `ask`.
### Legacy budget compatibility (normative)
Budget compatibility has two distinct rules:
* **Discovery range:** Initial [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) has no `criteria.constraints.total_budget` field. Its budget field is `request_proposals.criteria.offer_filters.budget_range`. A compatibility adapter MAY project that field to `get_products.filters.budget_range` because both are hard product-discovery filters. The adapter MUST copy every supplied numeric bound and the three-letter currency unchanged, MUST preserve inclusive `min` and `max` boundaries, MUST enforce `min <= max`, and MUST NOT perform currency conversion. If the legacy seller cannot apply the exact currency and bounds, the adapter MUST return the pre-dispatch rejection below rather than approximate the filter.
* **Proposal-term constraint:** An adapter MUST NOT project `refine_proposals.refinements[].constraints.total_budget` to `get_products.filters.budget_range`. The compact constraint is evaluated after proposal generation against each successor's `commercial_terms.total_budget`; the legacy field filters product candidates and does not guarantee any returned proposal's aggregate total. Identical `{min,max,currency}` syntax does not make those evaluation targets equivalent. Dropping the constraint, converting currency, changing a boundary, placing it in `ask`, or returning an out-of-range proposal with a warning would all weaken the buyer's hard requirement.
These rules are lifecycle-specific. The discovery projection is valid for an initial `request_proposals` compatibility call. On a revision, a present `criteria.offer_filters` replaces that entire criterion from the source proposal; it is not a subfield delta. The adapter MUST project the complete replacement object to legacy absolute `filters`, or reject before dispatch if any field cannot be represented exactly. When `criteria.offer_filters` is omitted, the adapter MUST also omit legacy `filters`, preserving each referenced proposal's bound discovery constraints. This discovery mapping is not a substitute for `constraints.total_budget` on `action: "revise"`.
Compact `action: "finalize"` accepts no constraints and copies the draft's complete `commercial_terms` unchanged into a committed snapshot. Legacy `finalize` asks for firm pricing and therefore does not, by itself, prove unchanged terms. An adapter MAY project finalize only when it can guarantee that the legacy operation preserves the complete commercial terms, not merely the total budget. Otherwise it MUST reject before dispatch rather than compare or repair terms after mutation.
Every unsupported compact-to-legacy case above returns the same typed local compatibility result:
```typescript theme={null}
type PreMutationUnsupported = {
code: 'PRE_MUTATION_UNSUPPORTED';
unsupported_fields: Array<{
path: string; // RFC 6901 JSON Pointer rooted at the compact request
reason: 'NO_LOSSLESS_LEGACY_MAPPING';
lost_guarantee:
| 'exact_discovery_offer_filter_state'
| 'proposal_total_budget_constraint'
| 'immutable_finalize_terms';
}>;
recovery: 'USE_COMPACT_LIFECYCLE' | 'REFORMULATE_REQUEST';
dispatched: false;
};
```
For example, the first refinement's hard budget constraint uses `/refinements/0/constraints/total_budget`; an unsafe finalize uses `/refinements/0/action`. `unsupported_fields` MUST contain every incompatibility detected during preflight, and any entry rejects the whole operation before a network request or mutation. `PRE_MUTATION_UNSUPPORTED` is not an AdCP wire error code. SDKs MAY express the type idiomatically in each language, but MUST preserve these discriminator values, JSON Pointer paths, lost-guarantee identifiers, recovery choices, and `dispatched: false`. An explicit caller opt-in to lossy projection does not make the mapping conformant.
A fully satisfied revision returns new immutable drafts and no failure prose:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-response.json",
"status": "completed",
"results": [
{
"source_proposal_id": "proposal_streamhaus_001",
"outcome": "revised",
"proposals": [
{
"proposal_id": "proposal_streamhaus_002a",
"parent_proposal_id": "proposal_streamhaus_001",
"proposal_kind": "new_media_buy",
"proposal_status": "draft",
"name": "Acme Outdoor — premium video",
"commercial_terms": {
"brand": { "domain": "acmeoutdoor.example" },
"purchases": [
{
"product_id": "premium_video_q4",
"pricing_option_id": "cpm_guaranteed",
"pricing": {
"pricing_option_id": "cpm_guaranteed",
"pricing_model": "cpm",
"currency": "USD",
"fixed_price": 18
},
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z"
}
],
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z",
"total_budget": { "amount": 50000, "currency": "USD" }
},
"terms_digest": "sha256:Fy6Bo7wUa_FmXGJssc37kGyHNjzBiBZLB9rtVNz8I-E"
}
]
}
],
"products": []
}
```
### 2. Branch on the discriminated result
Handle `outcome` before reading proposal fields:
| Outcome | Read | Required verification |
| - | - | - |
| `revised` | `proposals[]` | Every requested typed constraint and product action is satisfied. The array has one item unless alternatives were requested, in which case it has the exact requested count. |
| `partial` | `proposals[]`, `reason_code`, `unsatisfied_constraints`, `unsatisfied_product_changes` | Every returned draft satisfies every constraint and product action *not* listed as unsatisfied. |
| `unable` | `reason_code`, machine-readable unsatisfied fields | No proposal was produced; never access `proposal` or `proposals`. |
| `finalized` | singular `proposal` | Status is `committed`, parent is the source draft, and `expires_at` leaves enough time to accept. |
A valid counteroffer with only two of the three requested alternatives is `partial`:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-response.json",
"status": "completed",
"results": [
{
"source_proposal_id": "proposal_streamhaus_001",
"outcome": "partial",
"reason_code": "alternatives_unavailable",
"reason": "Two commercially distinct mixes are available at these terms.",
"proposals": [
{
"proposal_id": "proposal_streamhaus_002a",
"parent_proposal_id": "proposal_streamhaus_001",
"proposal_kind": "new_media_buy",
"proposal_status": "draft",
"name": "Acme Outdoor — premium video",
"commercial_terms": {
"brand": { "domain": "acmeoutdoor.example" },
"purchases": [
{
"product_id": "premium_video_q4",
"pricing_option_id": "cpm_guaranteed",
"pricing": {
"pricing_option_id": "cpm_guaranteed",
"pricing_model": "cpm",
"currency": "USD",
"fixed_price": 18
},
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z"
}
],
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z",
"total_budget": { "amount": 50000, "currency": "USD" }
},
"terms_digest": "sha256:Fy6Bo7wUa_FmXGJssc37kGyHNjzBiBZLB9rtVNz8I-E"
},
{
"proposal_id": "proposal_streamhaus_002b",
"parent_proposal_id": "proposal_streamhaus_001",
"proposal_kind": "new_media_buy",
"proposal_status": "draft",
"name": "Acme Outdoor — video and native",
"commercial_terms": {
"brand": { "domain": "acmeoutdoor.example" },
"purchases": [
{
"product_id": "premium_video_q4",
"pricing_option_id": "cpm_guaranteed",
"pricing": {
"pricing_option_id": "cpm_guaranteed",
"pricing_model": "cpm",
"currency": "USD",
"fixed_price": 17.5
},
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z"
},
{
"product_id": "native_feed_q4",
"pricing_option_id": "cpm_native",
"pricing": {
"pricing_option_id": "cpm_native",
"pricing_model": "cpm",
"currency": "USD",
"fixed_price": 16
},
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z"
}
],
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z",
"total_budget": { "amount": 50000, "currency": "USD" }
},
"terms_digest": "sha256:ed58dHH_xw98Gxkt8-dCQi9HZKdkIjuJ4NVLoP3txjs"
}
]
}
],
"products": []
}
```
An honest refusal that produces no draft uses the same response envelope but no proposal field:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-response.json",
"status": "completed",
"results": [
{
"source_proposal_id": "proposal_streamhaus_001",
"outcome": "unable",
"reason_code": "constraint_unsatisfiable",
"reason": "No eligible inventory can meet the requested fixed CPM ceiling.",
"unsatisfied_constraints": ["cpm"]
}
],
"products": []
}
```
### 3. Verify terms independently
For every returned proposal:
1. Recompute `sha256:base64url(SHA-256(JCS(commercial_terms)))` using RFC 8785 JSON Canonicalization Scheme bytes.
2. Compare the recomputed digest byte-for-byte with `terms_digest`.
3. Verify `parent_proposal_id` equals `source_proposal_id`.
4. Re-evaluate budgets, fixed rates, impression totals, flight bounds, product membership, and structured criteria from `commercial_terms`.
5. Verify any `targeting_resolution.brief_targeting` against the hard targeting in `ask`, and review every sparse product `targeting_resolution.modifications` departure before selecting that configured product.
6. On `partial`, enforce the partial invariant: every requirement absent from the unsatisfied sets still passes.
7. Treat `reason`, `description`, `suggestions`, and `ask` as non-contractual prose.
Digest uniqueness alone is not enough for alternatives. Verify that `commercial_terms` are distinct after canonicalization; a seller cannot create fake diversity by changing only IDs, names, descriptions, or digest strings.
### 4. Retry safely
An exact retry uses the same tool name, payload, and `idempotency_key`; the seller returns the original response with `replayed: true`. Any payload change requires a new key. Never use a new key merely to extend a committed hold: finalizing the same draft while its hold is active is `INVALID_STATE`, not a second reservation.
A seller may return `status: "submitted"` with a `task_id` when a complex multi-publisher revision or inventory hold needs upstream pricing or manual re-underwriting. Poll [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) or consume the requested completion notification; do not treat submission as a proposal outcome or retry it under a new key while the task is pending.
### 5. Finalize, then accept before expiry
Finalization changes no terms:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-request.json",
"idempotency_key": "typed-negotiation-sam-finalize-0001",
"refinements": [
{
"proposal_id": "proposal_streamhaus_002a",
"action": "finalize"
}
]
}
```
A finalize batch contains only finalize entries. The seller preflights every source and creates every hold or none. `hold_unavailable` identifies the source that could not be reserved; otherwise eligible siblings use `batch_aborted`.
The successful result is singular and committed; its commercial terms and digest are unchanged:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-response.json",
"status": "completed",
"results": [
{
"source_proposal_id": "proposal_streamhaus_002a",
"outcome": "finalized",
"proposal": {
"proposal_id": "proposal_streamhaus_committed_003",
"parent_proposal_id": "proposal_streamhaus_002a",
"proposal_kind": "new_media_buy",
"proposal_status": "committed",
"expires_at": "2026-09-15T10:15:00Z",
"name": "Acme Outdoor — premium video",
"commercial_terms": {
"brand": { "domain": "acmeoutdoor.example" },
"purchases": [
{
"product_id": "premium_video_q4",
"pricing_option_id": "cpm_guaranteed",
"pricing": {
"pricing_option_id": "cpm_guaranteed",
"pricing_model": "cpm",
"currency": "USD",
"fixed_price": 18
},
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z"
}
],
"start_time": "2026-10-01T00:00:00Z",
"end_time": "2026-11-01T00:00:00Z",
"total_budget": { "amount": 50000, "currency": "USD" }
},
"terms_digest": "sha256:Fy6Bo7wUa_FmXGJssc37kGyHNjzBiBZLB9rtVNz8I-E"
}
}
],
"products": []
}
```
Accept the returned committed proposal and its exact digest before `expires_at`:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/accept-proposal-request.json",
"idempotency_key": "typed-negotiation-sam-accept-0001",
"account": { "account_id": "account_pinnacle_acme" },
"proposal_id": "proposal_streamhaus_committed_003",
"proposal_terms_digest": "sha256:Fy6Bo7wUa_FmXGJssc37kGyHNjzBiBZLB9rtVNz8I-E"
}
```
The seller atomically verifies the proposal ID, digest, hold expiry, authorization, and any base MediaBuy revision. Expired holds return `PROPOSAL_EXPIRED`; the buyer requests and finalizes fresh terms rather than retrying acceptance against a lapsed hold.
### 6. Amend, cancel, or decline
Fork an accepted snapshot with `change_kind: "amendment"`:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-request.json",
"idempotency_key": "typed-negotiation-sam-amend-0001",
"refinements": [
{
"proposal_id": "proposal_streamhaus_accepted_004",
"action": "revise",
"change_kind": "amendment",
"ask": "Extend the flight by two weeks and preserve the total budget."
}
]
}
```
When cancellation requires agreement, fork the accepted snapshot with `change_kind: "cancellation"`:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/refine-proposals-request.json",
"idempotency_key": "typed-negotiation-sam-cancel-0001",
"refinements": [
{
"proposal_id": "proposal_streamhaus_accepted_004",
"action": "revise",
"change_kind": "cancellation",
"ask": "Campaign objectives were met early; request an agreed wind-down."
}
]
}
```
Both successors must be finalized and accepted. Direct [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) cancellation is reserved for rights already granted by the accepted terms. When Sam stops pursuing a draft instead, [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals) records terminal feedback; it does not mutate the proposal into another state.
## Seller implementation
### Compose a proposal specialist behind the sales agent
3.2 does not require a new public "proposal agent" role. A sales agent can
keep one endpoint and execution identity while delegating proposal work to an
internal specialist service. That specialist can own brief interpretation,
constraint evaluation, alternative generation, immutable proposal storage,
lineage, expiry, and terms-digest computation.
The parent sales agent should retain buyer authentication and account binding,
public capability routing, the atomic inventory-hold boundary, proposal
acceptance, and MediaBuy execution. Finalization is the important integration
point: it turns a non-binding snapshot into a seller-backed hold, so it must
coordinate with the inventory and authorization systems that can honor that
commitment.
This split also supports incremental client adoption. A buyer can implement
proposal discovery and refinement before it implements direct purchase or
operational control, and a seller advertises only the lifecycle tools its
public endpoint actually serves. What 3.2 does not define is portable transfer
of a committed hold between unrelated public agents. A terms digest identifies
the snapshot; it does not grant another agent the authority or inventory state
needed to accept it.
### Preflight the whole request
Before loading an LLM, pricing inventory, or writing state:
1. Validate the request schema, the maximum of 25 refinements, unique source IDs, and finalize exclusivity.
2. Authenticate and authorize every source without disclosing cross-account existence.
3. Compare every typed field with the explicit capability declaration.
4. Enforce the protocol alternatives ceiling of 10 and any lower advertised `max_alternatives`.
5. Look up the idempotency key and reject reuse with a changed payload.
6. If any task-level check fails, create no successor and no hold.
Capability support promises parse-and-validate competence, not commercial concession. A supported but unacceptable budget is a per-proposal `constraint_unsatisfiable` result, not `UNSUPPORTED_FEATURE`.
### Keep protocol validation separate from policy
The protocol layer owns schema validation, capability gates, result cardinality, lineage, digest computation, response validation, and transaction boundaries. Application policy owns pricing floors, available product mixes, targeting feasibility, alternative generation, underwriting, and hold duration.
Fence `ask` from pricing and authorization authority. It is attacker-controlled free text and may influence candidate generation only through bounded application policy. Only the typed `commercial_terms` object becomes contractual.
Post-acceptance change rights belong in `commercial_terms.change_terms[]`, not in `ask`, product prose, or an unbound capability. The seller emits at most one term per canonical action. `service_mode` describes the buyer-visible route; `allowed_statuses` defines the non-terminal lifecycle states in which the contractual right applies; and `processing_sla.response_max` and `completion_max` are elapsed-time maxima that already account for weekends and non-working periods. `seller_managed` means the seller controls the internal decision process without exposing whether it used automation or people. The legacy `requires_approval` value remains readable for 3.x compatibility.
The complete array is covered by `terms_digest`. If `change_terms` is present, an unlisted action is not a negotiated right; if the whole field is absent, consumers retain legacy behavior and consult current `available_actions[]`. Runtime `available_actions[]` may narrow a negotiated right because of current state or a stated condition, but MUST NOT silently broaden the accepted terms or replace the negotiated mode, SLA, constraints, conditions, or contract reference. A broader right requires an accepted amendment proposal.
`constraints` makes common bounds preflightable without turning arbitrary seller policy into executable code. The initial portable kinds cover budget deltas and resulting values, flight changes and notice, package-count changes, and effective timing. Product `allowed_actions[].constraints` is advisory; the proposal must restate a bound before it becomes contractual. If only opaque `conditions[]` are present, SDKs report the condition as unevaluated and do not promise that a parameterized request will pass.
Change terms attach to the media buy/account. Exercising one still requires the authenticated caller to pass seller account authorization and, when governance applies, to carry a signed `governance_context` admitted by the plan's `delegations[]`. This permits a properly delegated operator without turning the commercial term into authorization by itself.
At execution, the seller evaluates the currently accepted terms revision, not a caller-supplied or cached earlier proposal. Replayed, superseded, expired, or amended-away rights do not authorize a change. `conditions[]` are opaque identifiers and `description` is display text; neither is interpreted as an instruction or authority grant. Resolving a change term's `terms_ref` uses the normal authenticated contract-document path without forwarding ambient credentials, and the resolved document may explain but never expand the typed action, mode, statuses, constraints, or SLA.
The current MediaBuy action uses `change_term_id` to name the governing `term_id`. The `terms_ref` property on `available_actions[]` shipped in 3.1 with deliberately opaque semantics; it remains readable through 3.x and is removed in 4.0. A 3.2 compatibility projection may echo the change-term ID there for an older consumer, but a buyer must not reinterpret an arbitrary 3.1 value as a proposal-term identity. When both link fields are present as aliases, they must agree.
### Stage immutable successors
For revision batches:
1. Load each immutable source snapshot.
2. Build candidate `commercial_terms` without mutating the source.
3. Evaluate every typed constraint and product action against every candidate.
4. Classify the ordered result as `revised`, `partial`, or `unable`.
5. Generate new proposal IDs, set `parent_proposal_id`, compute JCS digests, and validate the full response.
6. Commit staged successors only after response validation succeeds.
For `partial`, include every failed constraint key and failed product action. Every unlisted requirement must pass for every returned draft. `constraint_unsatisfiable` takes precedence when it coexists with an alternatives shortfall or uninterpreted prose.
For finalize batches, acquire holds inside one transaction or equivalent staged operation. If any hold fails, roll back every sibling. A seller may decline a hold, apply its normal credit and relationship checks, and cap concurrent unexpired holds per buyer to resist inventory squatting. Choose `expires_at` long enough for acceptance but short enough to prevent free inventory options. Return `submitted` when those checks require asynchronous upstream pricing or manual re-underwriting, preserving the original idempotency scope through terminal completion.
### Log for audit without leaking terms
Record the authenticated buyer, source IDs, successor IDs, idempotency fingerprint, capability decision, outcome, unsatisfied keys, hold transaction, and digest. Do not place raw `ask`, full commercial terms, credentials, or cross-buyer pricing in broadly accessible logs. Rate-limit repeated unheld constraint probes: deterministic failures can otherwise become a price oracle.
## Conformance and SDK status
The canonical compliance scenario is `media_buy_seller/typed_proposal_negotiation`. It exercises capability gating, satisfied and unsatisfied constraints, alternatives, immutable lineage, finalize atomicity, exact replay, acceptance, amendment, cancellation, double-finalize rejection, and multi-source ordering.
The deterministic training profiles expose the AdCP 3.2 proposal-negotiation wire contract. The ordinary `/sales/mcp` route remains the backward-compatible ask-only seller. Use the [public test token](/dist/docs/3.2.8/quickstart#setup) with `https://test-agent.adcontextprotocol.org` and one of these capability-distinct routes:
| Profile | Route | Deterministic behavior |
| - | - | - |
| Typed negotiation | `/sales/profiles/typed-negotiation/mcp` | All typed dimensions, up to three alternatives, successful atomic finalize |
| Constrained seller | `/sales/profiles/constrained-seller/mcp` | USD floors, product conflicts, and at most two available alternatives |
| Finalization failure | `/sales/profiles/finalization-failure/mcp` | `hold_unavailable` plus `batch_aborted` siblings with no committed successors |
Pin `adcp_version: "3.2"` on every call. Calls that omit the pin or pin an earlier release get the backward-compatible response. `@adcp/sdk` 14.x accepts `wireAdcpVersion: "3.2"` on its single- and multi-agent client configuration; raw calls remain useful for inspecting the exact envelope as below.
### Try the lifecycle with Addie or Sage
> [card] [Try a live proposal with Addie](https://agenticadvertising.org/chat)
>
> Open the public sandbox chat. No membership is required.
Addie can drive the same sandbox through training-agent-only AdCP tools; Sage
uses those tools inside the member S1 media-buy specialist module. Start a new
conversation and paste:
> Walk me through the AdCP 3.2 proposal lifecycle against
> `https://test-agent.adcontextprotocol.org/sales/profiles/constrained-seller/mcp`.
> Pin `adcp_version` to `3.2` and send `adcp_major_version: 3`. First
> inspect capabilities, then request a draft for `acmeoutdoor.example`, ask for
> three alternatives under a USD 50,000 ceiling, and help me interpret the
> structured counteroffer. Stop before finalizing the hold, and stop again
> before accepting it into a sandbox MediaBuy.
The two pauses make the commercial boundaries visible: revision creates a new
non-binding snapshot, finalization reserves inventory until `expires_at`, and
acceptance creates or changes the MediaBuy. Ask Addie to continue after
inspecting each response. To exercise the teaching and assessment flow, start
S1 with Sage and ask to use the same constrained-seller profile for the
proposal-negotiation lab.
### Run the constrained profile
This live example proves the three-to-two counteroffer and the changed-request retry rule against the public seller. It first requests three alternatives and receives a deterministic `partial` result containing two. It then changes the count to two, uses a new idempotency key, and receives `revised`.
```javascript test=true integration requires-env=ADCP_AUTH_TOKEN theme={null}
const endpoint = 'https://test-agent.adcontextprotocol.org/sales/profiles/constrained-seller/mcp';
const token = process.env.ADCP_AUTH_TOKEN;
if (!token) throw new Error('Set ADCP_AUTH_TOKEN to the public test token');
function parseRpc(raw) {
const dataLine = raw.split(/\r?\n/).find((line) => line.startsWith('data:'));
return JSON.parse(dataLine ? dataLine.replace(/^data:\s*/, '') : raw);
}
async function callTool(id, name, args) {
const response = await fetch(endpoint, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
Accept: 'application/json, text/event-stream',
'Content-Type': 'application/json',
},
body: JSON.stringify({
jsonrpc: '2.0',
id,
method: 'tools/call',
params: { name, arguments: args },
}),
});
const raw = await response.text();
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${raw.slice(0, 200)}`);
}
const payload = parseRpc(raw);
const result = payload.result?.structuredContent;
if (payload.error || !result || result.adcp_error) {
throw new Error(JSON.stringify(payload.error ?? result?.adcp_error ?? 'missing structuredContent'));
}
return result;
}
const version = {
adcp_version: '3.2',
adcp_major_version: 3,
};
const nonce = crypto.randomUUID();
const capabilities = await callTool(1, 'get_adcp_capabilities', version);
if (
capabilities.adcp_version !== '3.2'
|| capabilities.media_buy?.supports_proposals !== true
|| !capabilities.media_buy?.lifecycle_tools?.includes('refine_proposals')
) {
throw new Error('The seller did not negotiate the proposal profile');
}
const requested = await callTool(2, 'request_proposals', {
...version,
idempotency_key: `docs-request-${nonce}`,
brand: { domain: 'acmeoutdoor.example' },
brief: 'social engagement display',
});
const proposalId = requested.proposals?.[0]?.proposal_id;
if (!proposalId) throw new Error('The seller returned no source proposal');
const refinement = {
proposal_id: proposalId,
action: 'revise',
constraints: { total_budget: { currency: 'USD', max: 50000 } },
};
const partial = await callTool(3, 'refine_proposals', {
...version,
idempotency_key: `docs-refine-three-${nonce}`,
refinements: [{ ...refinement, alternatives: { count: 3 } }],
});
const retried = await callTool(4, 'refine_proposals', {
...version,
idempotency_key: `docs-refine-two-${nonce}`,
refinements: [{ ...refinement, alternatives: { count: 2 } }],
});
const first = partial.results?.[0];
const second = retried.results?.[0];
if (
first?.outcome !== 'partial'
|| first.reason_code !== 'alternatives_unavailable'
|| first.proposals?.length !== 2
|| second?.outcome !== 'revised'
|| second.proposals?.length !== 2
) {
throw new Error('The public profile did not return the documented outcomes');
}
console.log({
first: { outcome: first.outcome, alternatives: first.proposals.length },
retry: { outcome: second.outcome, alternatives: second.proposals.length },
});
```
The constrained route is the canonical three-to-two exercise: request a USD 50,000 cap, include and omit products, apply US/Canada criteria, and request three alternatives. Retry the returned `partial` / `alternatives_unavailable` result with two alternatives before selecting and finalizing one. Exact retries reuse the same idempotency key; a changed alternatives count is a new logical request and needs a new key.
For reason-code labs, the semantic ask markers `[commercially-declined]` and `[unsupported-dimension]` select those bounded fixture outcomes. An ordinary untyped ask reaches `uninterpreted`; impossible typed terms reach `constraint_unsatisfiable`; an unknown source reaches `source_unavailable`. The training seller caps each principal at three concurrent unexpired holds.
Keep the following boundaries in your adapter:
* capability preflight is separate from mutation;
* exact replay is separate from changed-request retry;
* task errors are separate from per-proposal outcomes;
* commercial policy is separate from protocol verification;
* finalization is separate from acceptance;
* immutable terms are separate from explanatory prose.
## Implementation checklist
* [ ] Discover `lifecycle_tools`, `supported_dimensions`, and `max_alternatives`.
* [ ] Enforce 25 refinements, 10 alternatives, seller limits, unique sources, and finalize-only batches before mutation.
* [ ] Preserve task errors separately from `revised` / `partial` / `unable` / `finalized`.
* [ ] Verify typed constraints, product actions, partial unsatisfied subsets, parent lineage, and JCS digests.
* [ ] Reuse a key only for the exact same request; use a new key for changed payloads.
* [ ] Stage successors and validate responses before commit.
* [ ] Create finalize holds atomically and enforce expiry during acceptance.
* [ ] Fork accepted snapshots for amendments and negotiated cancellation.
* [ ] Fence `ask`, authorize every source, rate-limit probing, and avoid sensitive logs.
* [ ] Run the typed proposal negotiation storyboard against the implementation.
## Related reference
* [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals)
* [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals)
* [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal)
* [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals)
* [Capability discovery](/dist/docs/3.2.8/protocol/get_adcp_capabilities#proposal_refinement)
* [Legacy refinement compatibility](/dist/docs/3.2.8/media-buy/product-discovery/refinement)
# Refinement
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/product-discovery/refinement
AdCP product refinement — iterate on discovered products and proposals using refine mode in get_products. Adjust selections and request changes before creating a media buy.
Refinement turns product discovery into a conversation. After an initial `brief` or `wholesale` discovery, use `buying_mode: "refine"` to iterate on specific products and proposals — adjusting the selection, requesting changes, and exploring alternatives — before committing to a [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy).
## The refinement lifecycle
A typical media buying workflow follows this pattern:
```
discover → refine → refine → ... → buy
```
1. **Discover** — Call `get_products` with `buying_mode: "brief"` or `"wholesale"` to find matching inventory. The seller returns products (and optionally proposals).
2. **Refine** — Call `get_products` with `buying_mode: "refine"` and a `refine` array of change requests. Each entry declares a scope and what the buyer is asking for. The seller returns updated products with revised pricing and configurations.
3. **Repeat** — Refine as many times as needed. Each call is self-contained and stateless.
4. **Buy** — When satisfied, execute the final selection via `create_media_buy`.
> [!TIP]
>
> Refinement is not required. Simple campaigns can go straight from discovery to purchase. But for campaigns involving multiple products, proposals with budget allocations, or iterative negotiation, refinement is where the value is.
## The refine array
> [!NOTE]
>
> This is the deprecated `get_products` compatibility grammar. New compact-lifecycle integrations use [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals). The surfaces share `ask`, product `include`/`omit` verbs, and the `budget_range` shape. Compact hard constraints are strict while these legacy filters remain extension-tolerant, and their response envelopes are intentionally different.
The `refine` array is a list of change requests. Each entry declares a `scope` and what the buyer is asking for:
| Scope | Purpose | Required fields |
| - | - | - |
| `request` | Direction for the selection as a whole | `ask` |
| `product` | Action on a specific product | `product_id` |
| `proposal` | Action on a specific proposal | `proposal_id` |
The `refine` array requires at least one entry. The seller considers all entries together when composing the response, and replies to each one via `refinement_applied`.
Each scope uses its own id field — `product_id` for product entries, `proposal_id` for proposal entries — matching the id naming convention AdCP uses everywhere else. `action` is optional on product and proposal entries and defaults to `"include"`.
### Product actions
Product-scoped entries may declare an action. When omitted, the seller treats the entry as `"include"`:
| Action | Behavior | `ask` |
| - | - | - |
| `include` (default) | Return this product with updated pricing and data | Optional — specific changes to request (e.g., "add 16:9 format") |
| `omit` | Exclude this product from the response | Ignored |
| `more_like_this` | Find additional products similar to this one. The original product is also returned. | Optional — what "similar" means (e.g., "same audience but video format") |
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442013",
"buying_mode": "refine",
"refine": [
{ "scope": "product", "product_id": "prod_video_premium", "ask": "add 16:9 format option" },
{ "scope": "product", "product_id": "prod_display_ros", "action": "omit" },
{ "scope": "product", "product_id": "prod_native", "action": "more_like_this", "ask": "same audience but video format" }
]
}
```
### Request-level direction
Use `scope: "request"` to describe what you want from the selection as a whole:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442014",
"buying_mode": "refine",
"refine": [
{ "scope": "request", "ask": "good selection but I want more video options and less display" },
{ "scope": "product", "product_id": "prod_video_premium" },
{ "scope": "product", "product_id": "prod_display_ros" },
{ "scope": "product", "product_id": "prod_native" }
]
}
```
The seller may add, remove, or rebalance products based on this direction. Products not referenced in the `refine` array may appear in the response if the seller determines they fit the direction.
**Precedence**: Per-product actions take precedence over request-level direction. If the request-level ask says "less display" but a specific product carries an explicit action to include it, that product is returned regardless.
### Proposal refinement
Reference proposals by `proposal_id` to request adjustments or remove them. Like product entries, `action` defaults to `"include"`:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442015",
"buying_mode": "refine",
"refine": [
{ "scope": "product", "product_id": "prod_video_premium" },
{ "scope": "product", "product_id": "prod_display_ros" },
{ "scope": "proposal", "proposal_id": "prop_balanced_v1", "ask": "shift 20% from display to video" }
]
}
```
### Combining scopes
All scopes work together. A single refinement call can set direction for the selection, act on specific products, and request changes to a proposal:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442016",
"buying_mode": "refine",
"refine": [
{ "scope": "request", "ask": "increase emphasis on video across the plan" },
{ "scope": "product", "product_id": "prod_video_premium" },
{ "scope": "product", "product_id": "prod_display_ros" },
{ "scope": "product", "product_id": "prod_native", "action": "omit" },
{ "scope": "product", "product_id": "prod_audio_spot" },
{ "scope": "proposal", "proposal_id": "prop_awareness_q2", "ask": "reallocate native budget to video products" }
],
"filters": {
"budget_range": { "min": 200000, "max": 200000, "currency": "USD" }
}
}
```
## Seller response
When a buyer sends a `refine` array, the seller responds with `refinement_applied` — an array matched by position to the buyer's change requests. Each entry reports whether the ask was fulfilled:
| Field | Type | Required | Description |
| - | - | - | - |
| `scope` | string | Yes | Echoes the scope (`"request"` / `"product"` / `"proposal"`) from the corresponding `refine` entry. |
| `product_id` | string | Yes when `scope` is `"product"` | Echoes `product_id` from the corresponding refine entry. |
| `proposal_id` | string | Yes when `scope` is `"proposal"` | Echoes `proposal_id` from the corresponding refine entry. |
| `status` | string | Yes | `"applied"`: ask fulfilled. `"partial"`: partially fulfilled. `"unable"`: could not fulfill. |
| `notes` | string | No | Seller explanation. Recommended when status is `"partial"` or `"unable"`. |
```json theme={null}
{
"products": ["..."],
"proposals": ["..."],
"refinement_applied": [
{ "scope": "request", "status": "applied", "notes": "Added 3 video products. No CTV inventory for those dates." },
{ "scope": "product", "product_id": "prod_video_premium", "status": "applied" },
{ "scope": "product", "product_id": "prod_display_ros", "status": "applied" },
{ "scope": "product", "product_id": "prod_native", "status": "applied" },
{ "scope": "product", "product_id": "prod_audio_spot", "status": "partial", "notes": "16:9 not available for this placement — returning 4:3 and 1:1" },
{ "scope": "proposal", "proposal_id": "prop_awareness_q2", "status": "applied", "notes": "Shifted 22% to video (nearest allocation boundary)" }
]
}
```
The `refinement_applied` array MUST contain the same number of entries in the same order as the `refine` array. Each entry MUST echo `scope` and the matching id (`product_id` on product scope, `proposal_id` on proposal scope) so orchestrators can cross-validate alignment. The entire field is optional — sellers that don't track per-ask outcomes can omit it — but sellers that return it MUST return valid, position-matched entries.
Orchestrators SHOULD cross-check entries by the echoed id rather than trusting positional order alone — a seller bug that reorders entries would otherwise silently mis-attribute each outcome.
## Common refinement patterns
### Price and budget asks
Use the free-text `ask` field for commercial requests such as a lower price or a different budget allocation. For example, a buyer can ask for a proposal-scoped CPM reduction:
```json theme={null}
{
"buying_mode": "refine",
"refine": [
{
"scope": "proposal",
"proposal_id": "prop_awareness_q2",
"ask": "reduce the CPM by 10% while keeping the same inventory and dates"
}
]
}
```
Buyers discover this legacy refinement mode when `get_adcp_capabilities.media_buy.buying_modes` includes `"refine"`. That declaration means the seller can receive this free-text ask; it does not guarantee that the seller understands every negotiation strategy or has commercial flexibility on price. There is no finer-grained price-negotiation capability flag. Compact `refine_proposals` integrations separately inspect `media_buy.proposal_refinement.supported_dimensions` for typed parse-and-validate support.
When the seller returns `refinement_applied`, read the matching entry's `status` (`applied`, `partial`, or `unable`) and optional `notes` to learn how it handled this specific request. These fields acknowledge handling; they are not the executable commercial terms. Inspect the returned proposal's pricing and allocations before finalizing or buying.
Because the entire `refinement_applied` field is optional, omission communicates no per-ask outcome: do not infer `applied`, `partial`, or `unable`. A seller may omit it even when the response applies the requested change. Treat the returned proposal and any reported outcome as runtime evidence for this request, not as a general promise that the seller can negotiate price.
### Find similar products
Use `more_like_this` to discover products similar to ones you like. The seller returns the original product plus additional options matching its characteristics:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442017",
"buying_mode": "refine",
"refine": [
{ "scope": "product", "product_id": "prod_video_premium", "action": "more_like_this", "ask": "same premium audience but different formats" }
]
}
```
### Adjust filters
Filters on a refine request represent the complete target state, not a delta. Always send the full filter set you want applied:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442018",
"buying_mode": "refine",
"refine": [
{ "scope": "product", "product_id": "prod_video_premium" },
{ "scope": "product", "product_id": "prod_display_ros" }
],
"filters": {
"start_date": "2026-04-01",
"end_date": "2026-06-30",
"budget_range": { "min": 150000, "max": 150000, "currency": "USD" }
}
}
```
### Narrow or expand a proposal
The product entries define which products the seller should consider for the proposal. Combined with proposal entries, this narrows or expands the proposal's product set:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655442019",
"buying_mode": "refine",
"refine": [
{ "scope": "product", "product_id": "prod_video_premium" },
{ "scope": "product", "product_id": "prod_display_ros" },
{ "scope": "proposal", "proposal_id": "prop_balanced_v1", "ask": "rebalance for just these two products" }
]
}
```
## Finalize is exclusive within `refine[]`
`action: "finalize"` is seller commitment, not buyer acceptance — it transitions a draft proposal to committed with firm pricing and an expires_at hold window. The buyer accepts/executes a committed proposal later via `create_media_buy(proposal_id)`. When a buyer wants to finalize, the spec requires the `refine[]` array contain **only** finalize entries:
* If any entry has `action: "finalize"`, **all** entries in the array MUST be proposal-scoped with `action: "finalize"`. Mixing finalize with `include` / `omit` entries, or with request- or product-scoped entries, MUST be rejected by the seller with `INVALID_REQUEST`.
* Buyers needing to refine *and* commit in close succession **sequence** the calls: first a refine call (no finalize), then a finalize call against the resulting `proposal_id`(s). The two intents are distinct decisions and the spec treats them as distinct calls.
```yaml theme={null}
# ✅ Refine only — no finalize present, mixed scopes allowed
refine:
- { scope: proposal, proposal_id: p1, ask: "shift more to ctv" }
- { scope: request, ask: "frequency cap 3/day across all products" }
# ✅ Finalize only — multiple finalize entries against different proposals
refine:
- { scope: proposal, proposal_id: p1, action: finalize }
- { scope: proposal, proposal_id: p2, action: finalize }
# ❌ Rejected — finalize mixed with non-finalize
refine:
- { scope: proposal, proposal_id: p1, action: finalize }
- { scope: proposal, proposal_id: p2, ask: "shift more to ctv" }
```
For a committed proposal, `expires_at` is the inventory-hold deadline. The
seller MUST persist the committed successor and its inventory reservation as
one atomic state transition: no committed proposal may be observable without
its hold, and a failed finalization may not leave an orphaned reservation. A
seller that needs upstream or manual work uses the async task lifecycle and
publishes the committed result only after the reservation succeeds.
**Multi-finalize is atomic at the observation point.** When multiple finalize entries target different proposals in one call, the contract is: sellers MUST NOT return a success response unless every named proposal has both completed and been persisted as committed. Pre-commit validation runs before any side-effects (inventory pull, terms lock, governance attestation); if any proposal fails validation, the seller MUST reject the entire call without committing any. There is no `unfinalize` operation — atomicity runs on the pre-commit validation gate, not on post-commit reversal. Sellers that cannot guarantee atomic pre-commit validation MUST reject multi-finalize arrays with `MULTI_FINALIZE_UNSUPPORTED` (preferred — explicitly signals seller-side capability gap rather than client-side mistake) or `INVALID_REQUEST` (acceptable fallback for sellers on a pre-3.1 error catalog), and buyers SHOULD then sequence single-finalize calls.
**Mid-commit failure (post-validation, pre-persist).** If a downstream system fails between commit one and commit two — e.g., the second ad server times out after the first has already locked inventory — the seller MUST return `INTERNAL_ERROR` with `refinement_applied[]` carrying per-position outcomes. The spec does NOT define a recovery path: buyers SHOULD treat the resulting state as undefined and re-read via `get_media_buys` / equivalent before retrying. Recovery from this case is operational, not protocol-defined.
**Buyer intent caveat.** Buyers whose intent specifically requires atomic commit (e.g., budget-shared proposals where one finalizing without the other is incoherent) MUST be prepared to abandon the intent if the seller returns `MULTI_FINALIZE_UNSUPPORTED`. The fallback path — sequencing single-finalize calls — is a looser commit guarantee than the original atomic intent; there is no recovery for that loss of intent beyond accepting the looser guarantee or declining to commit at all. There is no capability flag for multi-finalize support — the failure response is the discovery surface, so buyers MUST NOT assume support without a successful first attempt.
The proposal contract does not define pDOOH booking horizons, finite
frame/loop overlap identity, or an implementation-level concurrency-control
algorithm for separate finalize calls. `expires_at` does not answer those
questions; it only bounds an inventory hold once the proposal is committed.
## Proposals in refine mode
Sellers MAY return proposals alongside refined products, even when the buyer did not include proposal entries. For example, a buyer refining three products may receive those products back with updated pricing *and* a proposal suggesting how to combine them.
Key points:
* **Proposals are not guaranteed.** Sellers are not required to generate proposals in refine mode. Allocation and campaign optimization are primarily orchestrator (buyer-side agent) responsibilities.
* **Signal interest via a request-level ask.** Include `{ "scope": "request", "ask": "suggest how to combine these products" }` to indicate you'd welcome a proposal.
* **Unsolicited proposals can be refined or ignored.** If a seller returns a proposal you didn't request, you can refine it in a follow-up call, or simply ignore it and build packages manually via `create_media_buy`.
Publishers typically omit proposals in `wholesale` mode, where the buyer is directing targeting and allocation themselves.
## Statelessness
Each `get_products` request with `buying_mode: "refine"` is self-contained. The
opaque product and proposal IDs carry the configurations being refined; they do
not identify a transport session. Top-level `filters`, `targeting_overlay`, and
`required_overlay_support`, when present, are complete replacement state for
the refined results rather than deltas. When omitted, the configuration already
bound to each referenced product ID remains in force. Sales agents MUST NOT
depend on unreferenced transport-level or conversational state.
Sellers still maintain their own product and proposal registries — "stateless" means the *protocol exchange* carries no implicit state between calls.
This design enables:
* **Stateless implementations** — sellers don't need to track refinement sessions
* **Safe retries** — a failed refinement call can be retried with the same parameters
* **Parallel exploration** — an orchestrator can explore multiple refinement paths simultaneously
## Client validation
Orchestrators should validate refinement requests before sending:
* **Non-empty refine** — The `refine` array requires at least one entry. An empty `[]` is rejected by schema validation.
* **Valid entries** — Each product entry requires `scope` and `product_id`. Each proposal entry requires `scope` and `proposal_id`. Request-level entries require `scope` and `ask`. `action` is optional on product and proposal entries (defaults to `"include"`); valid values are `include` / `omit` / `more_like_this` for products and `include` / `omit` / `finalize` for proposals.
* **Filters are absolute** — Send the full filter set you want applied, not a delta from the previous request.
* **Targeting and future support are absolute when present** — Send the complete
desired `targeting_overlay` and `required_overlay_support`. Changed effective
targeting, forecast assumptions, non-pricing terms, resolution, or overlay
support produces a new configured `product_id`; otherwise the seller keeps
the prior ID stable until expiration. Changed commercial terms receive a new
immutable `pricing_option_id`, so the selected pair remains unambiguous.
Client implementations should validate refinement requests against the [request schema](/dist/docs/3.2.8/building/schemas-and-sdks) before sending.
## Error handling
| Error Code | When | Resolution |
| - | - | - |
| `PRODUCT_NOT_FOUND` | One or more referenced product IDs are unknown, tombstones were evicted, or IDs belong to another account/lineage | Remove invalid IDs and retry, or re-discover with a `brief` request |
| `PRODUCT_EXPIRED` | One or more caller-authorized configured product IDs are still recognized and passed `expires_at` | Re-discover with a new `brief` or `wholesale` request; inaccessible IDs and IDs whose tombstones are no longer retained return `PRODUCT_NOT_FOUND` |
| `PROPOSAL_EXPIRED` | A referenced proposal ID has passed its `expires_at` | Re-discover with a new `brief` or `wholesale` request |
| `PROPOSAL_NOT_FOUND` | The referenced `proposal_id` is unknown to the seller (never issued, wrong tenant, or evicted from cache) | Re-issue `get_products` in `brief` or `wholesale` mode to obtain a fresh draft; finalize that recognized proposal before creating the media buy |
| `MULTI_FINALIZE_UNSUPPORTED` | `refine[]` carried multiple `action: 'finalize'` entries but the seller cannot guarantee atomic multi-proposal commit | Sequence single-proposal finalize calls (one finalize per `get_products` call) |
| `INVALID_REQUEST` | `refine` provided in `brief` or `wholesale` mode, empty `refine` array, or missing required fields | Check `buying_mode` and required fields |
### Troubleshooting: "must NOT have additional properties" on `refine[].id`
Each scope branch in `refine[]` is `additionalProperties: false`, which means a stray `id` field from the pre-3.0-rc refine shape is rejected — not silently ignored — with an error along the lines of:
```
/refine/0: must NOT have additional properties { additionalProperty: "id" }
/refine/0: must match oneOf schema { required: ["product_id"] }
```
If you see this, an orchestrator is still constructing product or proposal refine entries with the generic `id` field. Rename to `product_id` under `scope: "product"` and `proposal_id` under `scope: "proposal"`. See the [task reference](/dist/docs/3.2.8/media-buy/task-reference/get_products#refine-array) for the current shape. The same rename applies to `refinement_applied[]` if you're echoing on the seller side.
### Seller migration
Sellers returning `refinement_applied` have breaking work alongside buyers:
* Each response entry MUST now carry `scope`, and for product/proposal scopes MUST echo `product_id` / `proposal_id`. Flat `{status, notes}` entries are rejected by the response schema.
* Missing `action` on an incoming `refine[]` entry MUST be treated as `action: "include"`, not parsed as an error.
* Seller conformance tests against the 3.0 request schema will reject any lingering orchestrator payloads that still use the generic `id` field — refresh your fixture corpus after upgrading.
## Normative requirements
The [Media Buy Specification](/dist/docs/3.2.8/media-buy/specification#get_products) defines the following normative requirements for refinement:
**Orchestrators:**
* MUST include `refine` when `buying_mode` is `"refine"`
* MUST NOT include `refine` when `buying_mode` is `"brief"` or `"wholesale"`
* MUST provide `scope` and `product_id` for each product entry, and `scope` and `proposal_id` for each proposal entry
* MAY omit `action` on product and proposal entries — sellers treat missing `action` as `"include"`
* MUST NOT include multiple entries for the same product ID or proposal ID in a single `refine` array
**Sales agents:**
* MUST omit products with `action: "omit"` from the response
* MUST omit proposals with `action: "omit"` from the response
* MUST return products with `action: "include"`, with updated pricing
* SHOULD fulfill the `ask` on product entries with `action: "include"`
* SHOULD return additional products similar to those with `action: "more_like_this"`, plus the original product
* SHOULD consider request-level asks when composing the response — this MAY result in additional products beyond those explicitly referenced. Per-product actions take precedence over request-level direction.
* SHOULD fulfill the `ask` on proposal entries with `action: "include"`
* SHOULD include `refinement_applied` in the response when the buyer provides `refine`, with one entry per change request matched by position
* MAY return proposals even when the buyer did not include proposal entries
## See also
* [`get_products` task reference](/dist/docs/3.2.8/media-buy/task-reference/get_products#refinement) — API reference with request/response schemas
* [Media Products](/dist/docs/3.2.8/media-buy/product-discovery/media-products) — product model and proposal structure
* [Media Buy Specification](/dist/docs/3.2.8/media-buy/specification#get_products) — normative requirements
* [Orchestrator Design](/dist/docs/3.2.8/building/operating/orchestrator-design) — building buyer-side agents
# Reliable Reporting: implementing reporting.core
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/reporting-core-implementation-guide
The required Reliable Reporting tier: obligations, immutable closes, seller status, and an optional buyer-to-seller status loop — over the transports you already have.
> [!WARNING]
>
> Reliable Reporting is experimental in 3.2. `reporting.core` is its required
> tier; `managed_delivery` and `reconciled_billing` are separately advertised
> optional tiers.
>
> The consumer-status loop is additive and opt-in in 3.2, and it stays opt-in
> until the notice window closes on October 24, 2026. Sellers advertise
> `consumer_status_task` only when implemented. The active notice makes it
> required Core no earlier than the first minor after that date. Check the public
> training seller's advertised capabilities before testing this extension.
Every buyer eventually asks one question: **"do I have definitive reporting
for this period — and if not, whose problem is it?"** `reporting.core` makes
that question machine-answerable. Core is the required operational reporting
baseline: a seller must retain immutable revision evidence and expose its exact
binding over existing reporting transports. A seller that advertises the
consumer-status extension additionally records what the authenticated buyer
could actually consume. Core requires no destination, manifest, external
materialization, billing receipt, bespoke webhook, or outbound push code. It does require the
fixed revision-binding digest over canonical rows; this is distinct from the
Managed Delivery external-materialization canonicalization contract. Core carries
the operational cost of durable obligations, revision retention, and repair.
For an exact Core revision read, call `get_media_buy_delivery` with
`reporting_revision_id` and, optionally, an account selector. The returned `reporting_revision_binding`
must echo that ID and bind `{ reporting_revision_id, row_count, control_totals,
reporting_rows }` with RFC 8785 JCS and SHA-256. Exact reads are cursor-paginated:
every page repeats identical revision metadata and binding, and a consumer hashes
the concatenated rows in cursor order only after exhausting the frozen walk. Do
not substitute a fresh date-range pull for this read: it may have changed since
the immutable revision was published.
## What Core is
Four Core ideas, plus one opt-in status loop:
1. **Obligations exist before reports.** For every active delivery
configuration and period, the seller records what *should* exist — so a
missing first report is detectable, not silent.
2. **A zero-row report differs from no report.** An empty period commits a
revision like any other; absence means something is wrong.
3. **Revisions are immutable logical content.** A provisional restatement is a
new snapshot revision superseding the old snapshot, never an edit. An
`official` revision is immutable billing-purpose evidence and cannot be
superseded; later corrections are explicit accounting adjustments.
4. **[`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status)
exposes seller state** — one authoritative read over the obligation ledger,
summarized by five health states.
5. **When `consumer_status_task` is advertised,
[`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status)
closes the loop** — the buyer tells the seller whether an expected period
was received, omitted, missing, unreadable, or contradictory. Both
attributed histories stay visible; neither overwrites the other.
| Health | Meaning |
| - | - |
| `healthy` | Everything due has been produced. |
| `waiting` | Nothing is due yet. |
| `delayed` | Something due is late, automated recovery is still running. |
| `action_required` | A human on the named `responsible_party` must act. |
| `complete` | The queried scope is closed and every final obligation is satisfied. |
## Lifecycle at a glance
The reporting configuration creates the clock. Accepting a media buy does not
start a separate reporting SLA. Before a period closes, both sides can derive
its boundary and `next_expected_at`, but the seller cannot freeze an
`all_media_buys` denominator yet. At the period boundary, the obligation
becomes part of the authoritative ledger whether or not source data exists.
A closed, complete summary can still have an active configuration schedule.
The seller MUST populate `next_expected_at` with the nearest future period
start across its active in-scope `delivery_config_generations` when such a
period exists outside the evaluated scope, and omit it when none exists.
This summary projection preserves both complete-health scope guards and MUST
NOT create, expose, lease, count, or alter an open-period obligation or change
the scope's coverage. See
[future expectations on complete summaries](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status#future-expectation-on-a-complete-summary)
for the selection rule and its distinction from obligation and webhook deadlines.
```mermaid theme={null}
%%{init: {"sequence": {"showSequenceNumbers": true}}}%%
sequenceDiagram
accTitle: Reporting Core obligation and revision lifecycle
accDescr: A buyer installs a reporting configuration. At period end the seller commits an obligation before acquiring source data, then commits an immutable revision. Managed delivery can optionally materialize and notify; status reads remain authoritative.
participant Buyer as Buyer agent
participant Seller as Seller agent
participant Ledger as Reporting ledger
participant Source as Reporting source
participant Destination as Managed destination
Buyer->>Seller: sync_accounts(reporting_delivery_configs)
Seller-->>Buyer: Ready configuration + resolved schedule
Note over Buyer,Seller: Both derive the next full period and expected_at
Note over Seller,Ledger: period.end — freeze scope_resolved_at and media_buy_ids
Seller->>Ledger: Commit obligation independently of source availability
Buyer->>Seller: get_reporting_status
Seller-->>Buyer: Obligation is visible (usually waiting)
Seller->>Source: Acquire and normalize period data
Source-->>Seller: Rows, including a valid zero-row result
Seller->>Ledger: Commit immutable revision
opt Source corrects an official revision later
Seller->>Ledger: Commit immutable adjustment into an open accounting period
Seller-->>Buyer: reporting.ledger_changed (optional)
end
alt Core
Seller-->>Buyer: Revision readable through reporting API
else Managed delivery
Seller->>Destination: Materialize and verify revision
Seller->>Ledger: Commit verified materialization
Seller-->>Buyer: reporting.delivery_ready (optional)
end
opt Nothing satisfies the obligation by expected_at
Seller->>Ledger: waiting → delayed
Seller-->>Buyer: reporting.status_changed (optional)
end
Buyer->>Seller: get_reporting_status (authoritative repair)
opt Seller advertises consumer_status_task
Buyer->>Seller: sync_reporting_status (consumer status)
Seller->>Ledger: Record buyer statement; compare current states
opt Seller healthy but buyer cannot consume
Seller->>Ledger: Open caller-scoped CONSUMER_STATUS_MISMATCH
end
end
```
This gives each side a distinct responsibility:
* **Seller:** commit every elapsed eligible period before taking a ledger
snapshot after `period.end`, independently of source availability and before
committing a revision. A matching `periods` view includes it in the
paginated record set.
* **Buyer:** retain the accepted configuration generation, derive the same
expected periods, and treat a missing obligation as a protocol failure rather
than evidence that no activity occurred. When the seller advertises
`consumer_status_task`, sync the resulting consumer status back and update it
whenever consumption state changes.
* **Both:** calculate `expected_at` as `period.end + delivery_sla`. The
obligation is committed at period close and appears in the first ledger
snapshot strictly after it; the report becomes late only at
`expected_at`.
For example, a configuration activated at `00:20Z` with hourly aligned periods
starts at the next full boundary. Its first period is `[01:00Z, 02:00Z)`. The
obligation appears in the first ledger snapshot strictly after `02:00Z`; with
`delivery_sla: PT1H`, it stays `waiting` through `03:00Z` and becomes
`delayed` after that if no revision has been produced. A snapshot exactly at
`02:00Z` does not expose it.
## What Core is not
* **No push requirement.** Polling `get_reporting_status` is the
authoritative recovery path; a seller with no outbound push is fully
conformant. When advertised, `sync_reporting_status` is an ordinary inbound
task call, not a seller push or a buyer-hosted callback.
If you do offer push, Core's doorbell is `reporting.status_changed` — an
invalidation for health transitions in either direction, with stable
`issue_ids`. `reporting.ledger_changed` is the separate optional invalidation
for every new revision or adjustment, including changes that leave health
untouched. `reporting.delivery_ready` belongs to the managed-delivery tier
and never fires for Core configurations.
* **No delivery machinery.** Core offerings omit `method`: the status ledger
and its immutable revision metadata are required, while any existing
`get_media_buy_delivery` read or legacy reporting webhook remains an
optional data transport. Core never requires push. Destinations, manifests,
and provisioning belong to the `managed_delivery` tier.
* **No Managed canonicalization or billing receipts.** `reconciliation_mode` is
`delivery_only`, offering profiles omit the external-materialization
`canonicalization_*` contract, and `sync_reporting_receipts` does not exist
for you. The opt-in `sync_reporting_status` extension instead echoes only the
fixed revision-binding SHA-256 when reporting was received; it carries no row
totals, Managed evidence, or billing acceptance. Receipts and Managed
external materialization machinery belong to the `reconciled_billing` tier.
The boundary is executable: the `reporting-core` fixture test in the
protocol repository implements a complete polling-only seller and asserts
its source contains none of
`destination | manifest | billing receipt | readiness | webhook` (the Core binding
digest is intentionally retained).
## Build order for a seller
1. **Advertise the tier.** In `get_adcp_capabilities`, add
`media_buy.reporting_delivery` with `supported: true`, `configuration_task`,
`status_task`, at least one offering, `automated_recovery_window_seconds`,
and `status_retention_days` — and add `media_buy.reporting_delivery` to
`experimental_features`. Do not set `managed_delivery` or
`reconciled_billing` until you implement them.
2. **Define one Core offering.** Feed purpose, an immutable
`report_definition_id`, a content-addressed reporting profile (schema URI
* SHA-256, grain, primary keys), a schedule (`period_duration`,
`alignment`, `delivery_sla`), supported finality, and
`reconciliation_mode: "delivery_only"`. No `method`.
3. **Generate obligations.** When an account installs a delivery
configuration through [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts),
derive its future period boundaries and `next_expected_at`. At each eligible
`period.end`, freeze the media-buy scope and commit that obligation
independently of source availability and before committing its first
revision. Every later ledger snapshot must record it, and a
matching `get_reporting_status` `periods` view must return it, even when the
first report never arrives. Campaign starts, stops, and configuration
generations change *future* obligations, never past ones.
4. **Commit revisions.** When a period's data is final enough for its
declared finality, record an immutable revision — including zero-row
periods. Snapshot restatements create superseding revisions. Official
revisions are terminal; publish any later source correction as a signed
delta in a `reporting-adjustment` record applied to an open accounting
period.
5. **Opt in to consumer status.** When implemented, advertise
`consumer_status_task: "sync_reporting_status"` and accept it idempotently.
Validate the expected period from the authenticated caller's immutable
configuration generation even when no seller obligation exists. Retain
superseded history and expose only that caller's statements back through the
periods ledger.
6. **Project status.** Serve `get_reporting_status`: summary and periods
views over a consistent ledger snapshot, health computed from obligations
versus revisions versus the clock and current consumer status, `issues[]` carrying the typed code,
`responsible_party`, and `recommended_action` whenever health is
`delayed` or `action_required`.
7. **Escalate honestly.** A due obligation stays `delayed` while automated
recovery runs, for at most `automated_recovery_window_seconds`; after
that it is `action_required`. Never park a dead feed in `delayed`. A
`CONSUMER_STATUS_MISMATCH` follows the same discipline: every conflict is
`action_required` immediately *except* a `received` status made stale only by
your own restatement, which is `delayed` until the first superseding
revision's `created_at + delivery_sla` (or
`automated_recovery_window_seconds` when that SLA resolves to zero) and
`action_required` after. Later restatements do not restart that window. Carry
one `issue_id` and one `opened_at` across the transition. If you advertise
`consumer_mismatch_escalation_seconds`, also advertise `operations_contact`
and switch `recommended_action` to a `contact_*` value once the window
elapses; that boundary wins when it overlaps the grace window. Resolve a
mismatch only when the underlying conflict ends. Waive one only after an
explicit bilateral agreement covering that exact caller/account issue and
causing status. A valid waiver retires the issue, restores the underlying
seller health while retaining the immutable consumer statement, and triggers
an offered `reporting.status_changed` recovery fire when health changes.
8. **Count silence; do not act on it.** A buyer that misses its
`expected_at + automated_recovery_window_seconds` status deadline is counted
in `obligation_counts.consumer_status_pending` and nothing else. Missing
buyer status never changes your health, your reliability statistics, or
another caller's view.
## Build order for a buyer
1. **Save the contract.** Persist every accepted reporting configuration
generation, including its schedule, activation boundary, scope, report
definition, coverage requirement, and required finality. Do not reconstruct
historical expectations from a seller's current configuration.
2. **Derive expected periods.** Calculate the same half-open intervals and
`expected_at` timestamps. A mid-period configuration activation begins at
the next full boundary; deactivation still owes a period that already
started.
3. **Use your own denominator.** For each elapsed expected period, require a
matching obligation in the complete paginated `periods` view. The seller's
returned obligation list cannot prove that the first one was not omitted.
4. **Close the history.** Keep one `ledger_snapshot_id` across every page,
deduplicate immutable IDs, match the returned record counts, and distinguish
a zero-row revision from no revision. An external billing system MAY retain
an exact official `reporting_revision_id` as supporting evidence and apply
later adjustments under its own controls. Apply managed-resource and receipt checks only when the selected
tier requires them.
5. **Checkpoint repair.** After consuming every page, persist
`changes_checkpoint`; send it as `changes_after` on the next periods read.
Deduplicate safely replayed records by immutable ID.
6. **Sync consumer status when advertised.** If the seller declares
`consumer_status_task`, call `sync_reporting_status` after bounded repair
with the exact configuration generation, report definition, and period.
Failures are sent promptly; later state changes use a new immutable status ID
that supersedes the current leaf. Post a current status for every elapsed
expected period by `expected_at + automated_recovery_window_seconds` — not
only before closing the scope — and still have one for every elapsed period at
scope close. If reporting arrives but contradicts the accepted generation
(a frozen media buy with no rows, a promised metric missing, the wrong
currency), that is `content_mismatch` with a closed `mismatch_code`, not a
measurement argument. When a seller restatement makes your `received` stale,
re-read and supersede within the grace window rather than waiting for the
escalation.
7. **Treat push as a wake-up.** `reporting.ledger_changed` starts a
`changes_after` repair. Because a clock-only health transition may commit no
ledger record, `reporting.status_changed` starts a non-incremental current
summary or periods read. Poll periodically even when notifications are enabled.
## How to verify
* The **`reporting-core-declaration` universal storyboard** grades the
proper-name Reliable Reporting 1.0 declaration and Core boundary. The
capability-gated **`reliable-reporting-managed-delivery`** and
**`reliable-reporting-reconciled-billing`** storyboards grade the optional
tiers. The lifecycle-focused
**`reporting-core` storyboard** uses `reporting_core_lifecycle_probe` to
verify an obligation-before-report, clock-derived delayed health, and
explicit zero-row publication. Sellers advertising `consumer_status_task`
additionally run the capability-gated **`reporting-consumer-status`**
storyboard for missing-obligation identity, mismatch, and supersession.
* The **reporting-core fixture test** is the tier boundary stated as code —
copy its Core capability block and offering as your starting fixtures.
* Buyers verify the contract the same way with or without webhooks: they poll
`get_reporting_status` and reconcile obligations against what they
received.
Reliable Reporting 1.0 and the opt-in consumer-status loop are part of the
AdCP 3.2 wire bundle. The public training sales agent serves `"3.2"`. Read the
advertised version from `get_adcp_capabilities` and put that exact negotiated
value on every `sync_accounts`, controller, and `get_reporting_status` request.
First read the version the public sales sandbox advertises, then call
`comply_test_controller` with
`scenario: "reporting_core_lifecycle_probe"` and `operation: "prepare"`. Use
the returned account and stable identifiers in a `get_reporting_status`
`periods` read. Then run `advance_time` with `target_health: "delayed"`, read
the summary, run `publish_zero_row`, and read the periods view again. The
[controller reference](/dist/docs/3.2.8/building/by-layer/L3/comply-test-controller#reporting_core_lifecycle_probe)
contains the exact request shapes.
## The ladder above Core
Nothing in Core obligates you to climb, and each rung is separately
advertised:
* **`managed_delivery: true`** adds offerings with a `method` —
file transfer, dataset shares, warehouse materialization — plus
exact-resource retention and authorization-revocation bounds, bound to
principal-layer destinations ([`sync_principal`](/dist/docs/3.2.8/protocol/sync_principal)).
* **`reconciled_billing: true`** adds `receipt_task`
([`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts)),
`consumer_receipt` reconciliation, and the canonical-digest contract —
bilateral agreement on exact logical content, for billing.
Start with Core. It solves the problem everyone actually has.
## Reporting reliability and billing authority
Reliable Reporting answers *"did the report I was promised arrive, intact, on
time?"* It does not answer *"whose number governs the invoice?"* That second
question is answered by `measurement_terms.billing_measurement` on the media
buy — see [Billing Authority](/dist/docs/3.2.8/media-buy/advanced-topics/billing-authority)
for how a deal names the seller's ad server, the buyer's third-party ad server,
or a measurement vendor as the authoritative counter.
The two models are deliberately separate today, and a buyer can be green on
both surfaces while the invoice is still disputed: Reliable Reporting proves
the seller's feed was delivered and read, not that its counts match the
authoritative party's. Until they are unified, keep the distinction explicit:
* **Reliable Reporting** is the operational contract for the seller-produced
feed: obligations, immutable revisions, health, and — when advertised —
consumer status.
* **`report_usage`** is the predecessor path for media-buy billing when the
authoritative counter is the buyer or a vendor. It has no obligations, no
immutable revisions, no binding digest, and no status surface. Treat it as
the pre-Reliable-Reporting path for that case, not as a second reporting
ledger.
* **`content_mismatch`** on `sync_reporting_status` covers contract facts the
accepted configuration generation already fixed. It is not the channel for
"your count and mine differ by 12%"; that is `max_variance_percent` and
`makegood_policy`.
`reporting-delivery-config.json` reserves an `authoritative_party` field for
the eventual unification. In 3.2 the only accepted value is `seller` (the
default); a seller MUST reject `consumer` with `UNSUPPORTED_FEATURE` because no
released minor defines the buyer-deposited revision task. Reserving the field
now keeps that work additive instead of breaking the billing-feed constraints.
Tracked in [#7440](https://github.com/adcontextprotocol/adcp/issues/7440).
## File-transfer object and version references
For Managed Delivery file transfers, every manifest `files[]` entry carries a
credential-free, destination-relative `object_ref`. For an S3 destination,
that means the decoded object key relative to the configured destination — not
an `s3://` URI and not a key with `?versionId=` appended. The object key has a
1,024-character schema bound, which accommodates S3's 1,024-UTF-8-byte key
limit; JSON Schema measures characters, not bytes.
When a provider has an immutable object version, place its decoded native
value in the entry's optional `native_version_ref`, separately from the key.
This covers S3 VersionIds as well as GCS generations and provider-native
snapshots. A VersionId can include characters such as `+`, `/`, and `=` that
expand when URI encoded. Keep the decoded value in the manifest and encode it
only while constructing the provider request. The same destination-relative
`object_ref` is used by `physical_checksums[]`, so it identifies the same
object without carrying credentials, signed URLs, or query parameters.
`reporting-file-manifest.json` contains the `files[]` entries:
```json theme={null}
{
"files": [
{
"object_ref": "reports/2026-08-26/part-000.parquet",
"native_version_ref": "3/L4kqtJlcpXroDTDmJ+rmSpXd3aIbrHY+",
"size_bytes": 128,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"row_count": 0
}
]
}
```
`reporting-verification.json` contains the `physical_checksums[]` entries:
```json theme={null}
{
"physical_checksums": [
{
"object_ref": "reports/2026-08-26/part-000.parquet",
"algorithm": "sha256",
"value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}
```
# Media Buy Specification
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/specification
AdCP media buy specification — transport layer, task definitions, JSON schemas, authentication, and compliance requirements for agent-to-agent advertising.
> [!NOTE]
>
> **AdCP 3.0 Proposal** - This specification is under development for AdCP 3.0. Feedback welcome via [GitHub Discussions](https://github.com/adcontextprotocol/adcp/discussions).
**Status**: Request for Comments
**Last Updated**: February 2026
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
## Abstract
The Media Buy Protocol defines a standard interface for AI-powered advertising automation. This protocol enables AI agents to discover advertising inventory, create and manage campaigns, synchronize creative assets, and track performance through natural language interactions.
## Protocol Overview
The Media Buy Protocol provides:
* Natural language inventory discovery based on campaign briefs
* Campaign creation with package-level budget and targeting
* Creative asset management and synchronization
* Performance tracking and optimization feedback
* Human-in-the-loop approval workflows
## Transport Requirements
Sales agents MUST support at least one of the following transports:
| Transport | Protocol | Description |
| - | - | - |
| MCP | Model Context Protocol | Tool-based interaction via JSON-RPC |
| A2A | Agent-to-Agent | Message-based interaction |
Sales agents SHOULD support MCP as the preferred transport.
Sales agents MUST declare Media Buy Protocol support via `get_adcp_capabilities`:
```json theme={null}
{
"$schema": "https://adcontextprotocol.org/schemas/3.2.8/protocol/get-adcp-capabilities-response.json",
"status": "completed",
"adcp": {
"major_versions": [2],
"idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
},
"supported_protocols": ["media_buy"],
"account": {
"supported_billing": ["operator", "agent"],
"supported_account_currency_modes": ["fixed", "per_media_buy"]
}
}
```
## Core Concepts
### Request Roles
Every media buy request involves three entities:
* **Orchestrator**: The platform making the API request (e.g., DSP, trading desk)
* **Account**: The billing relationship—who gets billed and what rates apply (identified by `account_id`)
* **Agent**: The entity placing the buy (identified by authentication token)
### Sales Agent Types
**Publisher Sales Agents** — represent a single publisher's inventory:
* Sales agents MUST only return products for inventory they are authorized to sell
* Sales agents MUST validate authorization via `adagents.json` when applicable
**Aggregator Sales Agents** — represent multiple publishers:
* Sales agents MUST clearly identify the source publisher for each product
* Sales agents MUST NOT misrepresent inventory provenance
### Identifiers
* **`product_id`**: Opaque identifier for a product returned by `get_products`. A non-custom wholesale ID remains stable for the same logical offer within the seller and declared `cache_scope`, including across reads and wholesale-feed webhooks; feed and pricing versions communicate temporal catalog mutation, while retirement or replacement may end the identity. Binding commercial terms are immutable under `pricing_option_id`, so changed price, floor, currency, model, or priced applicability receives a new option ID. An `is_custom: true` ID remains stable only in its issuing discovery/refinement lineage through its promised lifetime. Creating a package with the product and pricing-option IDs accepts the disclosed configuration and commercial option. A caller-authorized custom ID past `expires_at` returns `PRODUCT_EXPIRED`; after its tombstone is no longer retained or outside its account/lineage, `PRODUCT_NOT_FOUND` applies without disclosing cross-tenant existence.
### Structured requirements and briefs
Buyers SHOULD use a structured request field whenever one represents their
requirement. Structured input is compact, machine-validatable, and avoids lossy
natural-language inference. Briefs carry goals, context, semantic intent,
preferences, and requirements without a structured representation.
An explicit hard requirement in a brief remains binding. Sellers MUST apply it
even when the buyer did not duplicate it in a structured field. When structured
hard targeting inferred from prose materially affects product eligibility,
pricing, or forecasting, sellers MUST confirm the resulting predicate once in
`request_proposals` or `get_products` response-root
`targeting_resolution.brief_targeting`, or in the corresponding
`refine_proposals.results[]` entry when the interpretation came from that
refinement's `ask`. Otherwise confirmation remains a best practice. Absence of
Product targeting resolution confirms exact acceptance of a structured overlay
for that product only; it does not confirm how the seller interpreted prose.
`required_overlay_support` requests later-selectable capability, not concrete
values, value-specific availability, or a forecast for every possible value. A
requirement `true` matches support `true` or any valid support object; an object
requirement matches `true` or a support object containing every requested
boolean and array subset. Unrequested fields and numeric seller limits do not
participate. Forecasts without concrete values describe the product's
discovery/default scope; buyers rediscover with concrete `targeting_overlay`
values for value-specific forecasts. Fixed prices and floors remain binding
uniformly for supported selections, while price guidance remains non-binding.
Sellers with value-dependent rates return a concretely targeted configured
product, split rate tiers into products, or withhold binding prices until
concrete rediscovery; they never reuse a selected `pricing_option_id` at new
terms.
Placement selection follows the same exact-outcome rule across discovery,
create, and update. A selected set exactly equal to the product's complete
`mode: "included"` set is an inherent restatement and does not require
`overlay_support.placement_selection`; partial selection does.
### Frequency-cap scope and product support
Pick the field by what you are doing:
| Role | You want to | Use |
| - | - | - |
| Buyer | Cap one package with its own counter | `packages[].targeting_overlay.frequency_cap` (or `purchases[]` on `buy_products`); require any package-cap support with `required_overlay_support.frequency_cap: true` |
| Buyer | Cap the whole buy with one shared counter | root `frequency_cap` on the create, update, or buy request; require support with `required_media_buy_support` |
| Buyer | Keep a cap editable after creation | `required_overlay_support.frequency_cap_support.mutable_fields` for package caps and `required_media_buy_support.frequency_cap_constraints.mutable_fields` for the root cap at discovery; whether a live buy can change now is `MediaBuy.available_actions` |
| Buyer | Change the root cap on a live buy | `control_media_buy` with `frequency_cap` (`null` clears it); requires `update_media_buy_frequency_cap` in `available_actions` |
| Buyer | Add a product to a buy that has a root cap | `update_media_buy.new_packages`; every added product must participate in the shared counter or the whole update is rejected |
| Seller | Say a product accepts package caps as it always has | `Product.overlay_support.frequency_cap: true` |
| Seller | Say a product accepts package caps only within limits, or create-only | `Product.overlay_support.frequency_cap_support` |
| Seller | Say a product can join one counter shared across the buy | `Product.media_buy_support.frequency_cap: true`, plus seller-wide `media_buy.aggregate_frequency_capping` |
Scope is determined by field location. A cap nested in a package
`targeting_overlay` owns an independent counter for that package. A root
`frequency_cap` on a MediaBuy request, accepted commercial terms, or MediaBuy
state owns one counter shared across every package. `FrequencyCap` therefore
defines no `scope` discriminator; unknown extension fields remain accepted but
cannot change the scope established by location. When both levels are present,
an impression is eligible only when both caps permit it. Repeating the same
package cap on every package does not create a shared counter.
#### Package caps
The legacy package capability remains
`Product.overlay_support.frequency_cap: true`, with its existing broad meaning
within seller-wide limits. A product that is constrained or create-only uses
the separate `frequency_cap_support` field instead:
```json theme={null}
{
"overlay_support": {
"frequency_cap_support": {
"mutable_fields": ["max_impressions"],
"supported_control_modes": ["max_impressions"],
"supported_per_units": ["individuals"],
"max_impressions_constraints": {
"minimum": 1,
"maximum": 10
},
"window_constraints": [{
"unit": "days",
"allowed_intervals": [1, 7, 30]
}]
}
}
}
```
Older buyers ignore the new field and see no legacy frequency-cap promise,
which is safe. A product declares one form or the other; the schema rejects
both together, so a structured declaration is always binding. A structured
buyer requirement matches either a containing `frequency_cap_support` object
or the broad legacy declaration, so buyers send `frequency_cap_support` alone;
a requirement carrying both is likewise rejected, because `frequency_cap: true`
alone would exclude every constrained product. Legacy `frequency_cap: true`
promises the broad contract, including changes through `update_frequency_caps`;
a seller that cannot change a product's cap after creation switches that
product to `frequency_cap_support` with `mutable_fields: []`.
Each count or duration constraint is either an exhaustive preset list or an
inclusive range, never both, so a unit-only declaration never implies support
for every interval or count. A field omitted from `frequency_cap_support`
inherits the seller-wide `media_buy.frequency_capping` declaration and never
broadens it: an omitted `supported_per_units` inherits the seller-wide per
units, and omitted `window_constraints` or `suppression_constraints` inherit
the seller-wide `supported_window_units` with no interval restriction, so a
product that needs interval limits must declare them. A product value absent
from the seller-wide declaration is invalid. A weekly window is
`{ "interval": 7, "unit": "days" }`; there is no `weeks` unit. `mutable_fields` lists the cap fields that can change after
creation: `[]` means create-only, `["max_impressions"]` permits a count change
while keeping `per` and `window` fixed, and omission leaves update support
undeclared. A product that omits `mutable_fields`, like one declaring legacy
`frequency_cap: true`, matches any `mutable_fields` requirement because the
broad legacy meaning applies; `[]` never matches a non-empty requirement.
Product capability describes implementation support, and a product with a
non-empty `mutable_fields` SHOULD also list `update_frequency_caps` in its
`allowed_actions` template; `MediaBuy.available_actions` remains authoritative
for whether a particular buy can change now.
Discovery matching uses subset containment after inheritance. A requested
window or suppression unit matches when the product's resolved unit list
contains it: the product's own `window_constraints` or
`suppression_constraints` when present, otherwise the seller-wide
`supported_window_units` (omitted means every unit).
`update_frequency_caps` authorizes package-cap changes. For heterogeneous
packages, the action carries `applicable_package_ids`; omission means every
package. A missing action or a package outside that list returns
`ACTION_NOT_ALLOWED`; a cap shape outside product capability, including a
change to a field not listed in `mutable_fields`, returns
`UNSUPPORTED_FEATURE`; a change outside accepted commercial terms returns
`REQUOTE_REQUIRED`. These checks run in that order: `available_actions`
authorization first, then product capability, then accepted commercial terms,
so a request that fails more than one returns the earliest code. Failure
preserves state.
#### Shared MediaBuy caps
Aggregate support is advertised separately as
`media_buy.aggregate_frequency_capping`; the legacy `media_buy.frequency_capping`
object continues to mean package support. Participation is product-scoped as
`Product.media_buy_support.frequency_cap: true`, optionally narrowed by
`frequency_cap_constraints`. Every selected product must advertise
participation and must support the root cap's `per` value; a product mix that
does not is rejected atomically. Discovery uses `required_media_buy_support`
when the value is not yet known, and `media_buy_frequency_cap` when the exact
aggregate value must be executable; the exact value alone suffices because it
implies participation. In 3.2, root caps are max-impression caps only: duration
windows are rolling, `campaign` spans the MediaBuy flight, and the units are
the same as package caps (a weekly window is seven `days`). Suppression remains
package-only because its legacy value does not identify a counter entity.
A root cap outside the seller-wide capability or any selected product's
resolved constraints, or a product mix that cannot share it, is rejected with
`UNSUPPORTED_FEATURE` before any mutation; sellers MUST NOT silently drop,
soften, or clamp it. A create, update, or buy response that does not echo the
root cap means the seller did not apply it; buyers MUST treat the buy as
uncapped and MUST NOT assume the cap is enforced. `media_buy_support.frequency_cap_constraints.mutable_fields`
declares whether a product's implementation can change the root cap after
creation, and a product declaring a non-empty list SHOULD also list
`update_media_buy_frequency_cap` in its `allowed_actions` template;
`MediaBuy.available_actions` decides whether a live buy can change now. A
root-cap change inside accepted commercial terms uses `control_media_buy` and
applies immediately; a change the accepted terms do not permit returns
`REQUOTE_REQUIRED` and goes through proposal refinement. The same order
applies to the root cap: a change on a buy whose `available_actions` omits
`update_media_buy_frequency_cap` returns `ACTION_NOT_ALLOWED` before any
capability check, a cap the seller-wide domain or a selected product cannot
execute returns `UNSUPPORTED_FEATURE` before any commercial-terms check, and
only then does a change outside accepted terms return `REQUOTE_REQUIRED`.
`frequency_cap_constraints.mutable_fields` governs which fields of an existing
root cap may change; clearing the cap, or setting one on an uncapped buy, is
governed by the action alone.
Cross-MediaBuy or cross-order counters require a separately identified grouping
resource; they are not another value of `FrequencyCap.scope`.
Changing a cap never resets its counter. Prior qualifying exposures in the
resulting active window continue to count. Adding or removing a package also
does not reset or subtract aggregate history. A package addition or proposal
revision whose resulting product mix cannot enforce the root cap is rejected
atomically; the check applies to the state the request would produce, so an
update that clears the root cap and adds packages in one request adds them
uncapped. Proposal refinement uses `remove_media_buy_frequency_cap: true` to
clear a cap because omission inherits it. Successful creates, updates, and reads
echo root and package caps at their separate locations.
### Product execution requirements (experimental)
Many products need account resources that live outside the media buy: a
conversion product needs a pixel or dataset, an app-promotion product needs a
registered app, a catalog-sales product needs a product catalog, and a product
that runs as a page or profile needs that identity connected.
`Product.execution_requirements` lists these needs so a buyer knows, before
`create_media_buy`, what it must supply and where it goes on the request. A
seller using this experimental surface lists `media_buy.execution_requirements`
in `experimental_features` on `get_adcp_capabilities`.
Each entry's `kind` determines where the resource is bound:
| `kind` | Satisfied by | Established through |
| - | - | - |
| `event_source` | A package `optimization_goals[]` entry of `kind: "event"` that the seller will use (within `max_optimization_goals`, by priority) with a used `event_sources[]` entry (only the first one when the seller does not support `multi_source_event_dedup`) whose `event_source_id` names an event source available to the account and whose `event_type` is in `event_types` when that list is present | [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources). When `conversion_tracking.platform_managed` is `true`, the seller-managed source's ID is the `sync_event_sources` response entry with `managed_by: "seller"` |
| `catalog` | A `packages[].catalogs[]` entry whose `type` is in `catalog_types` | [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs), an inline catalog, or a selector (`ids`, `gtins`) over the seller's own catalog |
| `downstream_connection` | A completed seller-side connection or grant of the declared `connection.connection_type` — not a request field | The seller's connection flow, as described for `AUTHORIZATION_REQUIRED` |
```json theme={null}
{
"product_id": "social_app_installs",
"catalog_types": ["app"],
"conversion_tracking": { "action_sources": ["app"] },
"execution_requirements": [
{ "kind": "event_source", "event_types": ["app_install"] },
{ "kind": "catalog", "catalog_types": ["app"] },
{
"kind": "downstream_connection",
"connection": { "connection_type": "publisher_identity", "scope": "identity", "required_for": ["create_media_buy"] }
}
]
}
```
The excerpt shows only the fields relevant here.
Rules:
* **All entries are required.** Alternatives inside one entry (`event_types`,
`catalog_types`) are any-of.
* **Account-independent.** The declaration says what the product needs, not
whether the caller's account has it. It does not change `cache_scope`, so a
public wholesale catalog stays cacheable, and it MUST NOT carry
account-specific resource IDs or names. Connection entries carry no
`resource_ref`, `connection_id`, or `expires_at`, no `status` other than
`unknown`, and a `required_for` that includes `create_media_buy` when present.
* **Complete when present.** Together with the `required_connections` of the
format declarations a package selects, the list is complete for this
vocabulary: a seller MUST NOT reject a package that satisfies all of them for
lacking a resource of an undeclared kind. A connection every package needs,
including the advertiser account itself, belongs in
`execution_requirements`; a connection only some formats need (such as a
post authorization for published-post formats) stays on the format
declaration. Absence of the field means undeclared, not "needs nothing".
* **Declare only what execution needs.** Declare `event_source` only when the
product requires event optimization. A pixel wanted only for attribution or
reporting is not an execution requirement in 3.2: declaring it would push
buyers into an event goal that changes the bidding objective. Closed-loop
retail sellers with `platform_managed` measurement likewise declare
`event_source` only when the package must bind the seller-managed source.
* **Coherent with product capabilities.** On the full `Product`, an
`event_source` requirement requires `conversion_tracking`. On both the full
and the canonical product, a `catalog` requirement requires `catalog_types`,
and every type it lists MUST appear there.
* **App promotion.** Use `catalog_types: ["app"]`; app items carry `app_id`,
`bundle_id`, `apple_id`, and `store_url`. Platforms typically promote one app
on one store per package, so a seller MAY require the app catalog to resolve
to a single item (select it with `ids`) and treat a multi-item catalog as
`ineligible`. An `app_install` or other app event source that is not
associated with the bound app is also `ineligible`.
* **Rejection.** When an `event_source` or `catalog` entry is unmet on a
buyer-supplied `create_media_buy` `packages[]` entry or `update_media_buy`
`new_packages[]` entry, or when an update removes or replaces a package's
satisfying binding, a seller that declares the requirement MUST return
`VALIDATION_ERROR` with `error.field` naming the first unmet binding (for
example `packages[0].optimization_goals` on create, or
`new_packages[0].catalogs` on update) and `error.details` conforming to
[`execution-requirement-unmet.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/execution-requirement-unmet.json).
`reason` distinguishes `not_bound` (nothing referenced), `not_found` (the
referenced resource is not available to the account), and `ineligible` (the
resource exists but does not satisfy the requirement). For `not_found` and
`ineligible`, sellers SHOULD point `field` at the offending entry, such as
`packages[0].optimization_goals[1].event_sources[0]`. A seller that also
emits `issues[]` SHOULD emit one entry per unmet requirement in the same
order. Unrelated updates to an existing package are not re-checked. An unmet
`downstream_connection` returns `AUTHORIZATION_REQUIRED` with
`error.details.missing_connections[]`.
* **Satisfy everything before calling.** A package can miss several
requirements across both error codes, and a seller may report either first.
Buyers SHOULD check every declared entry, and every selected format's
`required_connections`, before calling rather than fixing one error per
retry.
* **Proposal execution.** Packages a seller derives from
`create_media_buy.proposal_id` are not buyer-supplied, so the rejection rule
above does not apply to them in 3.2. How a proposal carries these bindings is
tracked with per-account readiness for 3.3.
This surface does not report the caller's account state. When an account has
several eligible event sources or catalogs, the buyer chooses one by binding it
on the request. When it has several eligible connections, such as several
connected pages, the seller applies its documented default. Per-account
readiness — which resources the account already has, which one to pick, the
binding for lead forms and messaging destinations, and proposal bindings — is
tracked for AdCP 3.3 in
[adcp#7763](https://github.com/adcontextprotocol/adcp/issues/7763).
### Product identity absence and reach reporting (experimental)
`Product.identity` is an optional, product-scoped declaration for inventory
whose delivery does not have a persistent per-entity identifier. It is not a
seller-wide capability: mixed inventory may legitimately return one product
with `persistent_identifier: false` and another without that constraint. A
seller using this experimental surface lists `media_buy.product_identity` in
`experimental_features` on `get_adcp_capabilities`; its absence is
undeclared, not proof of identifier availability.
When `persistent_identifier` is `false`, the product MUST NOT declare
`overlay_support.frequency_cap`, `overlay_support.frequency_cap_support`, or
`media_buy_support.frequency_cap`. A seller that cannot enforce a requested cap
rejects it under the exact-apply-or-reject rule; it never accepts and ignores it.
Delivery for such a product MUST NOT report `reach_unit` as `devices`,
`accounts`, or `cookies`. `individuals` and `households` remain valid for
panel-based or place-based modeled measurement. For an identity-absence
product, a delivery row that reports `frequency` MUST also report
`reach_unit`, even when that row omits `reach`. If either `reach` or
`frequency` is reported with `reach_unit: "custom"`, the discovered product
MUST include a non-empty `identity.reach_methodology` describing that unit.
This product-to-delivery conformance invariant applies only when the product
has made the experimental identity-absence declaration; it does not tighten
the stable shared delivery-metrics payload for legacy products.
A package row, and a breakdown row attributed to that package, is bound to its
selected product for this invariant. A media-buy totals row is bound only when
every contributing package selected a product with
`persistent_identifier: false`; mixed-product totals do not make a
product-specific identity claim. Sellers use package or product-bound
breakdowns to report and verify reach or frequency for mixed buys.
* **`media_buy_id`**: Unique identifier for a media buy. Sales agents MUST return this on successful creation. Orchestrators MUST use this for all subsequent operations on the media buy. A `media_buy_id` is a stable handle to any order in the seller's ad server that the authenticated account owns — not only orders originally booked via AdCP.
* **`package_id`**: Unique identifier for a package within a media buy. Sales agents MUST return this for each package created.
* **`idempotency_key`**: Client-generated unique key for safe retries. Sales agents that receive a duplicate key for the same account MUST return the original response rather than re-executing.
### Account Ownership vs. Creation Surface
AdCP is a protocol onto the seller's ad operations, not a shadow ledger beside them. Account-scoped tasks (`get_media_buys`, `get_media_buy_delivery`, `update_media_buy`, creative sync where applicable) are scoped by **account ownership**, not by the surface through which a resource was created. A sales agent MUST NOT partition its own inventory into "AdCP-managed" and "non-AdCP" subsets for the purpose of these tasks.
Concretely:
* `get_media_buys` MUST return every media buy owned by the authenticated account — whether created via `create_media_buy`, via the seller's native APIs or UI, via manual trafficking, or via legacy/third-party systems — subject only to the declared `status_filter` and pagination.
* Any `media_buy_id` returned by `get_media_buys` MUST be a valid argument to `get_media_buy_delivery` and to `update_media_buy` for every action listed in its `valid_actions`.
* A sales agent MUST NOT mark a buy read-only, hide it, or return `MEDIA_BUY_NOT_FOUND` on the basis that it was not originally booked through AdCP.
* When a specific action is unavailable for business reasons (contractual obligations, platform constraints, policy), the sales agent expresses that by omitting the action from `valid_actions`, not by refusing the buy from account-scoped listings.
* **Creation surface is never a business reason.** Sales agents MUST NOT omit an action from `valid_actions` — or return `INVALID_STATE` on an otherwise-valid update — solely because the buy was created outside AdCP. `valid_actions` omissions are legitimate only when grounded in actual contractual, platform, or policy constraints that would apply equally to an AdCP-created buy in the same state. A seller that returns non-AdCP buys with a systematically empty `valid_actions` is non-conformant, because that behavior is indistinguishable from hiding the buy and defeats the normative intent of the rules above.
#### Partitioning belongs at the account boundary
When a seller has a legitimate reason to keep a set of buys outside a caller's operational reach — child-seller models, NDA-scoped PMP deals, sandbox-vs-production separation, tenant-level privacy partitions — the correct mechanism is **account partitioning**, not within-account filtering:
* Expose the hidden subset as a separate account (or sub-account) the caller is not authorized to reference.
* Within any account the caller *is* authorized on, return the full set of buys that account owns per the rules above.
The account boundary is the AdCP primitive for access partitioning; `get_agent_capabilities` is the introspection surface for the scope granted on a given account. Callers can see what they can see; what they cannot see lives behind an account reference they do not hold. Within-account filtering — returning only a subset of an account's buys to a caller who is authorized on that account — reintroduces the shadow-ledger problem this rule forbids.
### Asynchronous Operations
The Media Buy Protocol is asynchronous by design. Operations MAY return immediately or MAY require extended processing:
* **Synchronous responses**: Sales agents MAY return completed results immediately
* **Asynchronous responses**: Sales agents MAY return `status: "submitted"` or `status: "working"` with a task reference
* **Human-in-the-loop**: Sales agents MAY require internal human review (e.g. IO signing) by keeping the task in `status: "submitted"` until the reviewer acts. Sales agents MAY also use `status: "input-required"` when the buyer must respond (e.g. confirm a budget). Human approval is modelled at the task layer — there is no `pending_approval` MediaBuy status (that value exists only on Account.status for account onboarding review)
* **Rejection**: Sales agents MAY reject a media buy in `pending_creatives` or `pending_start` status when platform setup reveals the order cannot be fulfilled (e.g., inventory sold out, policy issue discovered during ad server setup). Orchestrators MUST treat `rejected` as a terminal state. If the seller does not want to accept the order at create time, it SHOULD fail `create_media_buy` with an error rather than creating a media buy in `rejected` status.
Orchestrators MUST handle all response types and MUST NOT assume synchronous completion.
### Transaction boundaries across lifecycle surfaces
`create_media_buy` and `update_media_buy` are compound 3.x compatibility
facades. Each request is one atomic mutation. Sellers MUST validate every
requested package, inline creative, creative assignment, catalog selection, and
cross-field relationship before committing any part of the request. If one
inline creative or assignment is invalid, the complete create or update fails;
the seller MUST NOT leave behind a MediaBuy, package, library write, assignment,
or partial update from that request.
Request validation is not creative review. After valid creative input has been
committed, a later content-policy, brand-safety, or accessibility rejection
updates creative and assignment approval state but does not roll back the
MediaBuy or a successful update. Before activation, a buy without sufficient
approved coverage remains `pending_creatives` until the buyer supplies a
correction or replacement. Rejection affecting an active buy follows the
creative-impairment and serving rules instead of reversing commitment.
The compact lifecycle separates commitment, operational control, and creative
traffic. `buy_products` or `accept_proposal` commits before `sync_creatives` can
assign against the returned package IDs. Each call is atomic, but the sequence
is a saga: failure of a later sync leaves the purchase committed. Likewise, a
legacy update split into proposal acceptance, `control_media_buy`, and
`sync_creatives` has multiple independent failure boundaries and is not an
atomic compatibility translation. Compensating cancellation, when allowed by
the accepted terms, is a new state transition rather than rollback.
Callers use the compatibility facade whenever one transaction must combine
targeting with assignment replacement, or when an inline-only seller has no
creative library. A targeting change that would orphan an assignment MUST be
validated with its complete assignment replacement in the same facade update;
`control_media_buy` followed by `sync_creatives` cannot provide that guarantee.
### Media Buy State Transitions
Media buys progress through a defined set of states. Terminal states (`completed`, `rejected`, `canceled`) allow no further transitions.
```
create_media_buy ──┬──▶ pending_creatives ──▶ pending_start ──▶ active
├──▶ active ──(pause)──▶ paused
└──▶ paused (when created with paused: true)
paused ──(resume)──▶ active
active ─────────────▶ completed (terminal)
paused ─────────────▶ completed (terminal)
pending_creatives ──▶ rejected (terminal) — seller rejects during setup
pending_start ──────▶ rejected (terminal) — seller rejects during setup
Any non-terminal ──── update(canceled: true) ──▶ canceled (terminal)
```
**Rules:**
* Sales agents MAY return `active`, `paused`, `pending_creatives`, or `pending_start` from `create_media_buy` (seller's choice based on platform setup time and the buyer's create-time `paused` request)
* Sales agents MUST transition media buys from `pending_start` to `active` when the flight date arrives. Sales agents SHOULD notify orchestrators via webhook when this transition occurs.
* A successful committed `create_media_buy` response constitutes **order confirmation**. Sales agents MUST include `confirmed_at` in create/get responses; the value is the seller commitment timestamp, or `null` for a provisional buy that exists but is still waiting for seller commitment.
* Sales agents MUST include `revision` in create, get, and update responses. The revision number MUST increment on every mutating state change or update.
* `active` ↔ `paused` transitions use `update_media_buy` with `paused: true` or `paused: false`
* `create_media_buy` with top-level `paused: true` creates a held media buy when it would otherwise be `active`. Setup blockers still take precedence: no creatives yields `pending_creatives`, and a future flight yields `pending_start` until the start condition is satisfied. The hold is latent while those blockers are visible; once creatives are present and the flight can start, the buy enters `paused` instead of `active`.
* `update_media_buy` with `paused: false` resumes a buy that is currently `paused` or clears a latent create-time hold while the visible state is still `pending_creatives` or `pending_start`. Clearing a latent hold does not bypass setup blockers; the visible status remains pending until creatives are supplied and the flight can start.
* `active` or `paused` → `completed` when the flight ends, goal is met, or budget is exhausted (seller-initiated)
* Buyer-initiated cancellation uses `update_media_buy` with `canceled: true` and optional `cancellation_reason`
* On the `update_media_buy` compatibility facade, root `canceled: true` takes precedence over package cancellation and every other requested mutation. The seller cancels the whole MediaBuy, releases all of its package assignments, ignores every other field except `cancellation_reason`, and SHOULD return a structured warning identifying the ignored fields. A package-only cancellation is evaluated only when root `canceled` is absent. Compact `control_media_buy` instead makes root cancellation mutually exclusive with package and other controls, so a mixed compact request is invalid rather than precedence-resolved.
* Seller-initiated cancellation (e.g., policy violation, inventory withdrawal) transitions the media buy to `canceled` with `cancellation.canceled_by: "seller"`; buyers recover the state through `get_media_buys`. A durable resource-scoped status webhook remains reserved for the 4.0 notification model—operation-scoped `push_notification_config` is not a future lifecycle subscription. A 3.2 seller advertising `account.change_feed` with `media_buy` coverage instead emits the generic account-anchored `account.change_recorded` invalidation, which the buyer repairs through `get_media_buys`; it is not a resource-status payload.
* Seller-initiated rejection (from `pending_creatives` or `pending_start`) is likewise observable through `get_media_buys`; implementations MUST NOT synthesize an operation-completion webhook after the originating operation has already completed.
* Sales agents MUST include a `cancellation` object with `canceled_at` and `canceled_by` when transitioning a media buy or package to `canceled`
* Sales agents MAY reject buyer cancellation of a non-terminal media buy with error code `NOT_CANCELLABLE` (e.g., when the seller contractually refuses mid-flight cancellation)
* When a buyer attempts to cancel a media buy already in `canceled` (`canceled: true` on a `canceled` buy), sales agents MUST reject with `NOT_CANCELLABLE`
* All other updates to media buys in terminal states (`completed`, `rejected`, `canceled`) — including `canceled: true` attempts against `completed` or `rejected` buys — MUST be rejected with `INVALID_STATE`
* Rejection (`rejected` status) is only valid from `pending_creatives` or `pending_start`. Sales agents MUST NOT reject media buys that have already transitioned to `active`.
* The base 3.x media-buy wire does not define a durable seller-initiated resource-status subscription. Sellers MUST preserve the transition in MediaBuy readback and history. In 3.2, a seller MAY provide immediate generic invalidation by advertising the [experimental](/dist/docs/3.2.8/reference/experimental-status) `account.change_feed` capability (and feature id) with `media_buy` coverage and accepting an `account.change_recorded` account subscriber; otherwise buyers needing immediate push delivery require an implementation extension until the 4.0 resource-scoped notification contract lands.
* The `canceled` field on update requests uses `"const": true` — only `true` is valid. Sending `canceled: false` fails schema validation. Cancellation is irreversible; there is no "uncancel" operation.
* **Creative assignments are released on buy rejection or cancellation.** When a media buy transitions to `rejected` or `canceled`, all package-creative assignments on that media buy are released. For sellers that advertise `creative.has_creative_library: true`, the creatives persist in the creative library per [assignment state and creative state](/dist/docs/3.2.8/creative/creative-libraries#creative-state-and-assignment-state-are-separate) and MAY be referenced by `creative_id` in a subsequent `create_media_buy` or `sync_creatives` call. Inline-only sellers that advertise `inline_creative_management` without a creative library MAY keep submitted creatives package-scoped; they do not advertise cross-buy reuse or `list_creatives` readback.
* **Creative review is independent of buy outcome.** Sales agents MUST NOT implicitly reject a creative because its containing buy was rejected; a creative rejection MUST be a deliberate review decision with its own `rejection_reason`. If the buy was rejected because a creative violated content policy, the sales agent MAY reject that creative — but only via the normal review path with its own `rejection_reason`; the buy's `rejected` status is not itself sufficient.
* **Observability of released assignments.** The media-buy-level `canceled` or `rejected` transition, preserved in `get_media_buys` status and history, IS the audit record for all its released assignments; buyers MUST NOT rely on per-assignment diff observability. A negotiated implementation webhook extension may accelerate discovery but is not required by 3.x. Released assignments no longer appear in `get_media_buys` responses for that buy. Buyers confirming library reusability SHOULD call `list_creatives` to verify the creative is still in the library and observe its current status. Inline-only buyers should retain their submitted creative bodies because `get_media_buys` surfaces package-level approval state, not full creative-body retrieval. Package-scoped deadlines (`creative_deadline`) on the prior package have no bearing on a library creative's eligibility for a new buy.
* **Retention.** Sales agents with creative libraries SHOULD retain released creatives in the library for at least 90 days after the last assignment is released. A normative retention floor is specified in the creative retention contract tracked under [#2260](https://github.com/adcontextprotocol/adcp/issues/2260); until that contract lands, buyers relying on long-horizon reuse SHOULD verify persistence via `list_creatives` before referencing a released creative on a new buy.
#### Revision and confirmation semantics
`revision` is the optimistic concurrency token for a media buy. The wire field on `update_media_buy` is named `revision`; implementations may call it `expected_revision` internally, but the semantics are the same: the caller is saying "apply this update only if the current stored media-buy revision still equals this value."
Sellers MUST enforce the revision check atomically at the persistence boundary for every mutating update. A read-compare-write sequence in application memory can race with another writer and allow lost updates. The update and compare belong in one database transaction, conditional update, or equivalent atomic primitive. On mismatch, return `CONFLICT` and leave the media buy unchanged.
Mutating updates increment `revision` and return the new value. This includes budget, flight date, targeting, status, package, creative-assignment, inline-creative, reporting-webhook, invoice-recipient, and committed-metric changes made through `update_media_buy`. Validation-only requests, exact idempotency replay of an already-applied operation, and reads via `get_media_buys` do not bump revision.
`sync_creatives` has its own idempotency and atomicity boundary. Library uploads
and assignment operations performed there do not increment the MediaBuy
`revision`; there is no shared revision fence between creative sync and MediaBuy
control. Consequently, the same logical assignment change increments revision
when it is part of the `update_media_buy` compatibility mutation but does not
when it is performed through `sync_creatives`. Buyers MUST NOT use an unchanged
MediaBuy revision as proof that package-assignment state is unchanged.
Buyers SHOULD pass the latest observed `revision` on every `update_media_buy` call intended to change state. The request field remains optional for backward compatibility. When `revision` is present, sellers MUST compare it atomically with the write and reject stale values with `CONFLICT`. On `CONFLICT`, reload the media buy with `get_media_buys`, reconcile against the current state, then retry with the new `revision` and a fresh `idempotency_key`.
When a MediaBuy has `accepted_proposal` state and a successful
`update_media_buy` compatibility request changes the commercial envelope, the
seller MUST atomically materialize an accepted successor proposal snapshot and
advance `accepted_proposal_id`, `accepted_proposal_terms_digest`, and
`accepted_proposal` with the MediaBuy update. The successor records the prior
accepted proposal as its parent and the pre-update MediaBuy revision as its
base. This keeps a later compact amendment anchored to the terms that are
actually in force. An in-envelope operational change or creative-only change
does not create a commercial successor. A seller that cannot update the
MediaBuy and accepted snapshot together MUST reject the compound facade update;
it MUST NOT leave a stale accepted-proposal pointer.
`confirmed_at` is the seller's commitment timestamp, not a delivery-status timestamp. Once populated, it remains stable through later pause, resume, cancellation, completion, and reporting transitions. Use the `submitted` response branch when no `media_buy_id` is being returned to the buyer. Sellers MAY instead return synchronous success with `media_buy_id`, `packages`, and `confirmed_at: null` for a provisional buy; such buys MUST be retrievable via `get_media_buys` and MUST transition by setting `confirmed_at` exactly once on commitment. A provisional buy with `confirmed_at: null` MUST NOT be `active` and MUST NOT include `packages[].committed_metrics`.
**Package-level lifecycle:**
Packages follow the same pause/cancel pattern as media buys. Additionally:
* Packages MAY have a `creative_deadline` — after this deadline, creative changes to the package are rejected with `CREATIVE_DEADLINE_EXCEEDED`. When absent, the media buy's `creative_deadline` applies. `CREATIVE_REJECTED` covers content-policy, brand-safety, and accessibility-review failures.
* Package cancellation (`canceled: true` in a package update) is irreversible and independent of the media buy's status — a single package can be canceled while the media buy remains active. Creative assignments on the canceled package are released per the media-buy-level rule above; creatives assigned to other active packages on the same media buy are unaffected.
* Sales agents MUST retain delivery data for canceled packages. When `include_snapshot` is true, sales agents SHOULD return a final snapshot reflecting delivery state at the time of cancellation.
* When all packages in a media buy are canceled, the media buy itself remains in its current status (`active` or `paused`). Sellers that support mid-flight package additions advertise `add_packages` in `valid_actions` — the buyer can add new packages via `new_packages` in `update_media_buy`. Otherwise, the buyer SHOULD explicitly cancel the media buy. Sales agents SHOULD notify orchestrators (via `context.notes` in the update response) when the last active package is canceled. Sales agents MAY auto-transition the media buy to `canceled` after a seller-defined grace period if no new activity occurs.
### Creative Approval on Packages
**Schema**: [`enums/creative-approval-status.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/creative-approval-status.json)
Each package tracks per-creative approval status separately from the creative's library-level status. A creative may be `approved` in the library but `rejected` on a specific package (e.g., wrong format for the placement).
| Status | Description |
| - | - |
| `pending_review` | Creative submitted and awaiting platform review |
| `approved` | Creative approved for delivery on this package |
| `rejected` | Creative rejected for this package; see `rejection_reason` |
Rejection is not terminal — the buyer fixes the creative and resubmits through the seller's advertised creative path, which resets the approval to `pending_review`. The resubmission path:
1. Check `rejection_reason` on `get_media_buys` response
2. Fix the creative (update assets, adjust manifest)
3. Resubmit via `sync_creatives` for library-backed sellers, or via `packages[].creatives` on `update_media_buy` for inline-only sellers
4. Approval resets to `pending_review`
**Interaction with `creative_deadline`:** If a creative is rejected after the package's `creative_deadline`, the buyer MAY still resubmit — sellers SHOULD accept resubmissions for rejected creatives even past the deadline, since the buyer is correcting a seller-identified issue. Sellers that cannot accept late resubmissions MUST return `CREATIVE_DEADLINE_EXCEEDED`.
### Verification Tag Enforcement
When a confirmed package's `performance_standards` includes any entry with a `vendor`, creatives assigned to that package MUST include at least one URL asset with `url_type: "tracker_script"` or `url_type: "tracker_pixel"` corresponding to each specified vendor. Sales agents SHOULD reject creative assignments that lack required verification tags with `CREATIVE_REJECTED` and a `details` message identifying the missing vendor tag. Buyer agents SHOULD proactively include vendor tags based on the agreed `measurement_terms` before submitting creatives.
## Tasks
The Media Buy Protocol defines the following tasks. See task reference pages for complete request/response schemas and examples.
### get_products
**Schema**: [`media-buy/get-products-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-request.json) / [`media-buy/get-products-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-response.json)
**Reference**: [`get_products` task](/dist/docs/3.2.8/media-buy/task-reference/get_products)
Discover advertising inventory using natural language briefs or explicit wholesale intent.
**Requirements:**
* Orchestrators MUST set `buying_mode` to `"brief"`, `"wholesale"`, or `"refine"`
* Orchestrators MUST include `brief` when `buying_mode` is `"brief"`
* Orchestrators MUST NOT include `brief` when `buying_mode` is `"wholesale"` or `"refine"`
* Orchestrators MUST include `refine` when `buying_mode` is `"refine"`
* Orchestrators MUST NOT include `refine` when `buying_mode` is `"brief"` or `"wholesale"`
* Orchestrators MUST provide `scope` and `product_id` for each product entry in `refine`, and `scope` and `proposal_id` for each proposal entry
* Orchestrators MAY omit `action` on product and proposal entries (defaults to `"include"`)
* Orchestrators MUST NOT include multiple entries for the same product ID or proposal ID in a single `refine` array
* Sales agents MUST return products matching the brief criteria when a brief is provided
* Sales agents MUST include `product_id` and `pricing_options` for each product
* Sales agents SHOULD include relevance scoring when multiple products match
* Sales agents that understand a well-formed `brief` or `refine` request but deliberately decline to offer products for commercial, availability, or seller-policy reasons MUST return the `GetProductsRejected` arm with `status: "rejected"` and a buyer-facing `reason`
* Sales agents MUST NOT use `GetProductsRejected` for a completed search with no matching inventory, incomplete work, or a technical failure: use `status: "completed"` with `products: []`, a usable partial response with `incomplete[]` / an async task arm, or the error channel respectively
* `incomplete[]` describes missing scopes in an otherwise usable response; it does not classify the condition as retryable. A timeout or unavailable upstream that prevents a usable response MUST use the error channel, normally `SERVICE_UNAVAILABLE` with `error.recovery: "transient"` and optional `retry_after`
* Sales agents using `GetProductsRejected` MUST NOT also return `products`, `proposals`, `incomplete`, `filter_diagnostics`, `refinement_applied`, `cache_scope`, `errors`, or envelope-level `adcp_error`; the task completed successfully with a structured business outcome rather than a full or partial search result
* Orchestrators receiving `GetProductsRejected` MUST treat the transport call as successful, dispatch on `status: "rejected"`, and use `suggestions[]` when present to decide whether to revise and resubmit the brief
**Refinement requirements:**
Each `get_products` request with `buying_mode: "refine"` is self-contained — sales agents MUST NOT depend on transport-level session state. The `refine` array and `filters` on each request fully specify the refinement intent. Sellers maintain their own product and proposal registries; "stateless" means the protocol exchange carries no implicit state between calls. This enables stateless implementations and safe retries.
* Sales agents MUST treat a missing `action` on product and proposal refine entries as `action: "include"`
* Sales agents MUST omit products with `action: "omit"` from the response
* Sales agents MUST omit proposals with `action: "omit"` from the response
* Sales agents MUST return products with `action: "include"`, with updated pricing
* Sales agents SHOULD fulfill the `ask` on product entries with `action: "include"`
* Sales agents SHOULD return additional products similar to those with `action: "more_like_this"`, plus the original product
* Sales agents SHOULD consider request-level asks (`scope: "request"`) when composing the response — this MAY result in additional products beyond those explicitly referenced. Per-product actions take precedence over request-level direction.
* Sales agents SHOULD fulfill the `ask` on proposal entries with `action: "include"`
* Sales agents SHOULD include `refinement_applied` in the response, with one entry per change request matched by position
* Sales agents that return `refinement_applied` MUST echo `scope` on each entry and MUST echo `product_id` / `proposal_id` for product and proposal scopes, so orchestrators can cross-validate alignment
* Sales agents MAY return proposals alongside products in refine mode, even when the orchestrator did not include proposal entries
### Canonical creative-format discovery
Sales-agent `list_creative_formats` is deprecated in AdCP 3.2. An agent-global list cannot represent product-, placement-, account-, or inventory-specific deliverability.
For older 3.x callers, the deprecated media-buy request still accepts `account`.
Sellers with account-specific catalogs use it to scope the returned formats;
sellers with one shared catalog MAY ignore it. New integrations use
`get_products` with `account` and read each product's `format_options[]`.
Use these canonical sources instead:
* Publisher acceptance: publisher `adagents.json.formats[]`
* Sales-agent deliverability: `get_products` `Product.format_options[]`
* Creative production/validation/preview: creative agent `get_adcp_capabilities.creative.supported_formats[]`
**Requirements:**
* Sales agents MUST publish the closed sellable format set on every product's canonical `format_options[]`
* Placement-level declarations MAY narrow, but MUST NOT broaden, the product set
* Sales agents MUST NOT present publisher-catalog formats as if every declared format were deliverable by that agent
* Compatibility `list_creative_formats` responses MAY be projected from canonical declarations for older 3.x peers, but MUST NOT be independently authored
### create_media_buy
**Schema**: [`media-buy/create-media-buy-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-request.json) / [`media-buy/create-media-buy-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-response.json)
**Reference**: [`create_media_buy` task](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy)
Create a media buy from selected packages or execute a proposal.
**Requirements:**
* Orchestrators MUST include either `packages` array or `proposal_id`
* Orchestrators MUST include `start_time` and `end_time` for the campaign
* Sales agents MUST return `media_buy_id` on successful creation
* Sales agents MUST return `confirmed_at` on successful creation. The value is the seller commitment timestamp, or `null` when the response creates a provisional buy that is not yet committed.
* Sales agents MUST return `revision` on successful creation
* Sales agents MUST return `creative_deadline` indicating when creatives must be uploaded
* Sales agents MUST validate budget against pricing options
* On validation failure, sales agents MUST return an `errors` array
### update_media_buy
**Schema**: [`media-buy/update-media-buy-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/update-media-buy-request.json) / [`media-buy/update-media-buy-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/update-media-buy-response.json)
**Reference**: [`update_media_buy` task](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy)
Modify an existing media buy's budget, targeting, or settings.
**Package operations** are structurally explicit — the operation type is determined by where the package appears in the request:
| Operation | Request location | Description |
| - | - | - |
| **New** | `new_packages[]` | Add a package to the media buy |
| **Changed** | `packages[]` | Modify an existing package (budget, targeting, dates, creatives) |
| **Canceled** | `packages[]` with `canceled: true` | Cancel an existing package (irreversible) |
**Requirements:**
* Orchestrators MUST include `media_buy_id`
* Sales agents MUST accept any `media_buy_id` returned by `get_media_buys` for the authenticated account and MUST NOT refuse updates on the basis that the buy was originally created outside AdCP. Business constraints on specific operations are expressed by omitting them from `valid_actions`. See [Account Ownership vs. Creation Surface](#account-ownership-vs-creation-surface).
* Sales agents MUST apply PATCH semantics: only specified fields are updated;
omitted fields remain unchanged. Within a request-side package
`targeting_overlay`, this rule applies per dimension: omission preserves the
dimension, a non-null value replaces it, and `null` clears it. Successful
response and readback schemas contain only the resulting non-null targeting
state.
* When a buyer attempts to cancel a media buy already in `canceled` (`canceled: true` on a `canceled` buy), sales agents MUST reject with `NOT_CANCELLABLE`
* All other updates to media buys in terminal states (`completed`, `rejected`, `canceled`) — including `canceled: true` attempts against `completed` or `rejected` buys — MUST be rejected with `INVALID_STATE`
* Orchestrators MAY cancel a media buy by setting `canceled: true` with optional `cancellation_reason`
* Sales agents MUST transition the media buy to `canceled` status upon accepting cancellation
* Sales agents MAY reject cancellation of a non-terminal media buy with error code `NOT_CANCELLABLE`
* Orchestrators MAY cancel individual packages by setting `canceled: true` on a package update
* Sales agents MUST reject creative changes to packages past their `creative_deadline` with error code `CREATIVE_DEADLINE_EXCEEDED`
* Orchestrators MAY add new packages to an existing media buy via `new_packages`. Sales agents that support this MUST advertise `add_packages` in `valid_actions`. Sales agents that do not support adding packages MUST reject with `UNSUPPORTED_FEATURE`.
* When root `canceled: true` is present alongside other fields in an update request, including `packages[].canceled`, sales agents MUST cancel the whole MediaBuy and MUST ignore all other fields except `cancellation_reason`. Root cancellation takes precedence over package cancellation and other concurrent mutations. Sales agents SHOULD include a structured success `warnings[]` entry naming ignored fields; warnings no longer belong in opaque `context`. Package cancellation is evaluated independently only when root `canceled` is absent. Within a package update, `canceled: true` likewise takes precedence over that package's sibling fields: apply only its cancellation and reason and warn about ignored siblings. Root fields and other package entries still apply atomically unless root cancellation is present.
* Sales agents MUST return `affected_packages` containing the state of each directly modified package after the update is applied (or the proposed state if pending approval); an empty array is valid when only campaign-level fields (e.g., `paused`, `start_time`) are updated
* When manual approval is required, sales agents MUST persist the pending update request, MUST return `implementation_date: null`, and MUST NOT return empty `affected_packages`
* Sales agents SHOULD return the updated media buy state
### sync_catalogs
**Schema**: [`media-buy/sync-catalogs-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-catalogs-request.json) / [`media-buy/sync-catalogs-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-catalogs-response.json)
**Reference**: [`sync_catalogs` task](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs)
Synchronize catalogs (products, inventory, stores, and vertical feeds) on a seller account.
**Requirements:**
* Orchestrators MUST include `account_id`
* When `catalogs` is provided, it MUST contain at least one catalog
* When `catalogs` is omitted, the call is discovery-only and returns existing catalogs without modification
* Sales agents MUST return per-catalog outcomes, including what action was taken and any item-level issues
* Sales agents SHOULD support `dry_run` for validation without applying changes
### list_creatives
> [!NOTE]
>
> `list_creatives` is defined in the [Creative Protocol](/dist/docs/3.2.8/creative/specification#list_creatives). Sales agents that host creative libraries MAY implement `list_creatives` as part of the Creative Protocol. See the [`list_creatives` task reference](/dist/docs/3.2.8/creative/task-reference/list_creatives).
### sync_creatives
> [!NOTE]
>
> `sync_creatives` is defined in the [Creative Protocol](/dist/docs/3.2.8/creative/specification#sync_creatives). Any agent that advertises `creative.has_creative_library: true` implements `sync_creatives` as part of the Creative Protocol. See the [`sync_creatives` task reference](/dist/docs/3.2.8/creative/task-reference/sync_creatives).
### get_media_buys
**Schema**: [`media-buy/get-media-buys-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buys-request.json) / [`media-buy/get-media-buys-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buys-response.json)
**Reference**: [`get_media_buys` task](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys)
Retrieve operational media buy state, including package status, creative approvals, missing formats, and optional delivery snapshots.
**Requirements:**
* Orchestrators MAY filter by `account_id`, `media_buy_ids`, and `status_filter`
* Orchestrators SHOULD use cursor pagination (`pagination.max_results` / `pagination.cursor`) for broad scope queries
* Sales agents MUST return every media buy owned by the authenticated account that matches the declared filter set, regardless of how the buy was created (AdCP, seller's native APIs/UI, manual trafficking, legacy systems). See [Account Ownership vs. Creation Surface](#account-ownership-vs-creation-surface).
* Sales agents MUST return current media buy status and package-level operational state for each matched media buy
* Sales agents SHOULD include `status_as_of` when the returned media-buy-level `status` is served from a cache or computed as a rolled-up status from upstream legs. For rolled-up statuses, `status_as_of` MUST NOT be later than the oldest upstream status observation that could affect the returned roll-up, so it never overstates freshness. Omit it or return `null` to make no freshness assertion; buyers MUST NOT infer that an omitted or null value means the status is live. Buyers use `status_as_of` to interpret list-status freshness; `updated_at` remains the media buy's last modification time.
* Sales agents SHOULD include `valid_actions` for each media buy, listing the actions the buyer can perform in the current state. This eliminates the need for agents to internalize the state machine. Expected mapping:
| Status | Expected `valid_actions` |
| - | - |
| `pending_creatives` | `pause`, `cancel`, `sync_creatives` |
| `pending_start` | `pause`, `cancel`, `sync_creatives` |
| `active` | `pause`, `cancel`, `update_budget`, `update_dates`, `update_packages`, `add_packages`, `sync_creatives` |
| `paused` | `resume`, `cancel`, `update_budget`, `update_dates`, `update_packages`, `add_packages`, `sync_creatives` |
| `completed` / `rejected` / `canceled` | *(empty array)* |
Sellers MAY omit actions based on business rules (e.g., omit `cancel` when contractual obligations prevent it, omit `add_packages` when the platform does not support mid-flight additions).
When `pending_creatives` or `pending_start` is masking a create-time hold from `paused: true`, sellers SHOULD also include `resume` so buyers can clear the hold before the setup blocker clears.
`valid_actions` contains only mutation operations — read-only operations (`get_media_buys`, `get_media_buy_delivery`) are always permitted regardless of state. Agents SHOULD use `valid_actions` as an optimization hint but MUST handle `INVALID_STATE` errors gracefully, since `valid_actions` may not reflect real-time state changes from concurrent operations. Absence of an action means "not declared by this seller," not necessarily "forbidden."
For creative changes, `sync_creatives` in `valid_actions` is a legacy creative-change action label, not proof that the `sync_creatives` task exists. Buyers use the creative path the seller advertises: `sync_creatives` and `creative_assignments` for sellers with `creative.has_creative_library: true`, or `packages[].creatives` on `update_media_buy` for inline-only sellers that advertise `media_buy.features.inline_creative_management: true`.
* Orchestrators MAY request revision history by setting `include_history` to the number of most-recent entries desired. Sales agents SHOULD return a `history` array per media buy when `include_history > 0`, containing revision number, timestamp, server-derived actor identity, action type, and optional summary. History entries MUST be ordered most-recent-first.
* Sales agents MUST include one media-buy currency for every AdCP-authored buy. `total_budget`, package budget/minimum constraints, and canonical BiddingPolicy monetary fields use that denomination, and every selected pricing option MUST declare it. Packages requiring another currency belong in a separate media buy. `package.currency` remains a legacy/external-buy readback field; `snapshot.currency` may identify an upstream reporting denomination but MUST NOT reinterpret authored budget or bidding values.
* Sales agents SHOULD include creative approval outcomes and pending format requirements when available
* If `include_snapshot` is true and snapshot data is omitted for a package, sales agents MUST return `snapshot_unavailable_reason`
* When `include_snapshot` is true and snapshots are returned, each snapshot MUST include `as_of` and `staleness_seconds`
* Default `status_filter: ["active"]` applies only when `media_buy_ids` is omitted
### get_media_buy_delivery
**Schema**: [`media-buy/get-media-buy-delivery-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buy-delivery-request.json) / [`media-buy/get-media-buy-delivery-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buy-delivery-response.json)
**Reference**: [`get_media_buy_delivery` task](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)
Track performance metrics and campaign delivery.
**Requirements:**
* Orchestrators MUST include `media_buy_id`
* Sales agents MUST accept any `media_buy_id` returned by `get_media_buys` for the authenticated account, regardless of creation surface. See [Account Ownership vs. Creation Surface](#account-ownership-vs-creation-surface).
* Sales agents MUST return delivery metrics at the package level
* Sales agents SHOULD include dimensional breakdowns when requested
* Sales agents MUST include `as_of` timestamp indicating data freshness
### provide_performance_feedback
**Schema**: [`media-buy/provide-performance-feedback-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/provide-performance-feedback-request.json) / [`media-buy/provide-performance-feedback-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/provide-performance-feedback-response.json)
**Reference**: [`provide_performance_feedback` task](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback)
Submit performance signals to enable publisher optimization.
**Requirements:**
* Orchestrators MUST include `media_buy_id` and performance metrics
* Sales agents MUST acknowledge receipt of feedback
* Sales agents SHOULD use feedback to optimize delivery within campaign constraints
### sync_event_sources
**Schema**: [`media-buy/sync-event-sources-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-event-sources-request.json) / [`media-buy/sync-event-sources-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-event-sources-response.json)
**Reference**: [`sync_event_sources` task](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources)
Configure event sources on a seller account for conversion tracking with upsert semantics.
**Requirements:**
* Orchestrators MUST include `account_id`
* When `event_sources` is provided, it MUST contain at least one event source
* When `event_sources` is omitted, the call is discovery-only and returns all event sources on the account without modification
* Sales agents MUST return per-source results with `action` indicating what happened
* Sales agents MUST include seller-managed event sources in the response when present
* Sales agents SHOULD return `setup` instructions for newly created event sources
* Sales agents MAY include `seller_id` for cross-referencing in the seller's platform
### log_event
**Schema**: [`media-buy/log-event-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/log-event-request.json) / [`media-buy/log-event-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/log-event-response.json)
**Reference**: [`log_event` task](/dist/docs/3.2.8/media-buy/task-reference/log_event)
Send conversion or marketing events for attribution and optimization.
**Requirements:**
* Orchestrators MUST include `event_source_id` referencing a configured event source
* Orchestrators MUST include at least one event with `event_id`, `event_type`, and `event_time`
* Sales agents MUST return `events_received` and `events_processed` counts
* Sales agents MUST deduplicate events by `event_id` + `event_type` + `event_source_id`
* Sales agents SHOULD report `partial_failures` for individually failed events
* Sales agents SHOULD return `match_quality` score when user matching is attempted
### sync_audiences
**Schema**: [`media-buy/sync-audiences-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-audiences-request.json) / [`media-buy/sync-audiences-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-audiences-response.json)
**Reference**: [`sync_audiences` task](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences)
Manage first-party CRM audiences on a seller account. Upload hashed customer lists, check matching status, and reference the resulting audiences in targeting overlays.
**Requirements:**
* Orchestrators MUST include `account_id`
* Orchestrators MUST include at least one audience with hashed member data
* Sales agents MUST return per-audience outcomes with matching status
* Sales agents SHOULD support `push_notification_config` for async matching completion
* Sales agents MUST accept SHA-256 hashed identifiers and MUST reject cleartext email/phone in `hashed_email`/`hashed_phone` fields (PII minimization at the transport boundary; see [Privacy Considerations](/dist/docs/3.2.8/reference/privacy-considerations#unsalted-hashed-identifiers-are-pseudonymous-not-anonymous) for the retention/consent obligations that hashing does not satisfy)
## Error Handling
Sales agents MUST return errors using the [standard AdCP error schema](/dist/docs/3.2.8/building/by-layer/L3/error-handling).
Common error codes:
* `MEDIA_BUY_NOT_FOUND`: Referenced media buy does not exist
* `PACKAGE_NOT_FOUND`: Referenced package does not exist
* `PRODUCT_NOT_FOUND`: Referenced product does not exist
* `PRODUCT_EXPIRED`: Referenced configured product passed `expires_at`; re-run `get_products`
* `BUDGET_EXCEEDED`: Operation would exceed allocated budget
* `CREATIVE_REJECTED`: Creative failed content-policy, brand-safety, or accessibility review
* `CREATIVE_DEADLINE_EXCEEDED`: Creative change submitted after the package's `creative_deadline`
* `INVALID_STATE`: Operation is not permitted for the resource's current status (e.g., updating a completed or canceled media buy)
* `NOT_CANCELLABLE`: Media buy or package cannot be canceled in its current state
* `GOVERNANCE_DENIED`: A registered governance agent denied the transaction. Buyer may restructure the buy, escalate to human spending authority, or contact the governance agent.
* `TERMS_REJECTED`: Buyer-proposed `measurement_terms` were rejected by the seller. Error details SHOULD identify which term failed and the seller's acceptable range or supported vendors. Recovery: adjust the proposed terms and retry, or omit `measurement_terms` to accept the product's defaults.
* `BIDDING_PLACEMENT_CONFLICT`: Media-buy/package bidding scopes cannot be represented by the provider's native campaign, package, or shared-strategy placement. Sellers MUST reject before mutation and identify conflicting scopes where safe.
* `AMBIGUOUS_BIDDING_POLICY`: Canonical `bidding` and legacy bidding fields are both present on the same effective package. Sellers reject rather than choosing precedence.
* `REQUOTE_REQUIRED`: An `update_media_buy` request changes the parameter envelope (budget, flight dates, volume, targeting) the original quote was priced against. The `pricing_option` remains locked; the seller is declining the requested shape at that price. Distinct from `TERMS_REJECTED` (measurement) and `POLICY_VIOLATION` (content). Details SHOULD follow [`error-details/requote-required.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/requote-required.json): `envelope_field` names the breached paths, `change_term_id` identifies the governing accepted right when present, and `decline_reason` SHOULD classify a structured seller-policy reason when the coarse dimension is safe to disclose. AdCP 3.2 buyers use the reason to inform refinement of `accepted_proposal_id`; some policies still require the buyer-safe message, a free-text `ask`, or human negotiation. Legacy 3.1 callers adjust the update, rediscover products or terms, add packages when available, or create a separate media buy.
* `VALIDATION_ERROR`: Request format or parameter errors
* `AUTH_MISSING`: No credentials were presented. Recovery: correctable.
* `AUTH_INVALID`: Credentials were presented but rejected (expired / revoked / malformed). Recovery: terminal.
## Security Considerations
### Transport Security
All Media Buy Protocol communications MUST use HTTPS with TLS 1.2 or higher.
### Authentication
* Orchestrators MUST authenticate with sales agents using valid credentials
* Sales agents MUST validate credentials before processing requests
* Sales agents MUST use account context to determine inventory access
### Budget Authorization
* Sales agents MUST validate that accounts are authorized for requested budget levels
* Sales agents MUST NOT exceed authorized budget limits without explicit approval
### Creative Security
* Sales agents MUST validate creative content for policy compliance
* Sales agents SHOULD scan creatives for malware and malicious content
* Sales agents MUST NOT serve creatives that fail security validation
## Conformance
### Sales Agent Conformance
A conformant Media Buy Protocol sales agent MUST:
1. Support at least one specified transport (MCP or A2A)
2. Implement all tasks per their schemas
3. Return required fields as defined in response schemas
4. Use specified error codes
5. Handle asynchronous operations appropriately
6. Enforce authentication and authorization
7. Apply `get_products.targeting_overlay` to product availability, pricing, and forecasts
8. Omit `targeting_resolution` for exact matches and disclose only modifications for configured alternatives
9. Treat placement, property, and collection selection as targeting and return complete effective package targeting on readback
10. Return dimension-specific execution details, including demographics, inside the generic package `targeting_resolution` envelope
See [Required tasks by protocol](/dist/docs/3.2.8/protocol/required-tasks) for a consolidated view of required and optional tasks across all AdCP protocols.
### Orchestrator Conformance
A conformant Media Buy Protocol orchestrator MUST:
1. Authenticate with sales agents
2. Include required fields as defined in request schemas
3. Handle asynchronous task-level responses (`submitted`, `working`, `input-required`) including webhook delivery of completion artifacts
4. Use `media_buy_id` to reference media buys in subsequent operations
5. Respect `creative_deadline` for creative uploads
6. Treat a selected context-scoped `product_id` as acceptance of its disclosed `targeting_resolution`
## Implementation Notes
### Response Time Expectations
Sales agents SHOULD target the following response times:
| Operation Type | Target Latency |
| - | - |
| Capability/catalog lookups | \< 1 second |
| Discovery with AI/LLM (get_products) | \< 60 seconds |
| Reporting queries (get_media_buy_delivery) | \< 60 seconds |
| Campaign operations (create, update, sync) | Async acceptable |
### Idempotency
Every state-mutating AdCP task request MUST carry an `idempotency_key`, except the published 3.x `get_products` compatibility facade, whose request shape keeps the field optional. In AdCP 3.2, product discovery uses explicit contracts: `request_proposals`, `refine_proposals`, and `decline_proposals` require a key; `list_products` and the legacy facade leave it optional. Pure reads MUST tolerate the field but MAY ignore it, so buyers MUST NOT rely on keyed reads returning a cached response. A seller that elects or is required to provide replay applies this contract:
* The same key and equivalent canonical payload within the replay window MUST return the original response without re-executing the request.
* The same key with a different canonical payload MUST return `IDEMPOTENCY_CONFLICT`.
* Keys are scoped to the authenticated caller and account so retries cannot cross tenant boundaries.
The compact tasks use the same product-discovery authorization policy as the legacy facade, but each stateful task has a distinct idempotency identity. A retry MUST use the same tool name and payload; changing names is a different logical request. Sellers retain `get_products` through 3.x for compatibility. Its key remains optional on every arm. A seller may ignore a supplied key on a guaranteed side-effect-free synchronous read. Buyers SHOULD supply one whenever the request may allocate a task or change observable state. When supplied and the seller declares `adcp.idempotency.supported: true`, the seller MUST apply replay protection before that effect. If the key is omitted or the seller declares `adcp.idempotency.supported: false`, an ambiguous result cannot be retried with a portable at-most-once guarantee. See [Request safety — idempotency](/dist/docs/3.2.8/building/by-layer/L1/security#idempotency) for the normative cache, replay, and concurrency rules.
### Human-in-the-Loop
Sales agents MAY require human approval for any operation. Approval is modelled at the **task layer**:
* When the seller is waiting on an **internal** human (e.g. IO signing, traffic-manager review), sales agents MUST keep the task in `status: "submitted"` until the reviewer acts. On completion, the task transitions to `completed` with the final artifact carrying `media_buy_id` and the full success payload.
* When the seller needs the **buyer** to respond (e.g. confirm a budget that exceeds a pre-approved limit), sales agents MUST return `status: "input-required"` with a message describing what is needed. The buyer responds within the same A2A context.
* Sales agents SHOULD provide an estimated approval timeline in the task message.
* Orchestrators SHOULD implement webhook handlers (via `push_notification_config`) for completion notifications rather than polling.
`pending_approval` is not a valid MediaBuy or Task status — that value exists only on `Account.status` (for account onboarding review). Do not repurpose it for media-buy or task-level approval.
## Schema Reference
| Schema | Description |
| - | - |
| [`media-buy/get-products-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-request.json) | get_products request |
| [`media-buy/get-products-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-response.json) | get_products response |
| [`media-buy/create-media-buy-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-request.json) | create_media_buy request |
| [`media-buy/create-media-buy-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-response.json) | create_media_buy response |
| [`media-buy/update-media-buy-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/update-media-buy-request.json) | update_media_buy request |
| [`media-buy/update-media-buy-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/update-media-buy-response.json) | update_media_buy response |
| [`media-buy/list-creative-formats-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/list-creative-formats-request.json) | Deprecated named-format compatibility request |
| [`media-buy/list-creative-formats-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/list-creative-formats-response.json) | Deprecated named-format compatibility response |
| [`creative/list-creatives-request.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/list-creatives-request.json) | list_creatives request (Creative Protocol) |
| [`creative/list-creatives-response.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/list-creatives-response.json) | list_creatives response (Creative Protocol) |
| [`creative/sync-creatives-request.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/sync-creatives-request.json) | sync_creatives request (Creative Protocol) |
| [`creative/sync-creatives-response.json`](https://adcontextprotocol.org/schemas/3.2.8/creative/sync-creatives-response.json) | sync_creatives response (Creative Protocol) |
| [`media-buy/get-media-buy-delivery-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buy-delivery-request.json) | get_media_buy_delivery request |
| [`media-buy/get-media-buy-delivery-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buy-delivery-response.json) | get_media_buy_delivery response |
| [`media-buy/provide-performance-feedback-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/provide-performance-feedback-request.json) | provide_performance_feedback request |
| [`media-buy/provide-performance-feedback-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/provide-performance-feedback-response.json) | provide_performance_feedback response |
# accept_proposal
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/accept_proposal
Accept a committed proposal to create, amend, or cancel a MediaBuy.
`accept_proposal` is the single terminal action for the compact proposal lifecycle. It accepts exactly one committed immutable proposal snapshot.
`committed` retains the AdCP 3.1 reservation guarantee: the seller has locked the proposal's commercial terms and reserved its inventory until `expires_at`. Finalization creates that hold; acceptance consumes it and creates, amends, or cancels the MediaBuy.
Depending on `proposal_kind`, acceptance:
* creates a new MediaBuy;
* applies an amendment to an existing MediaBuy; or
* applies a negotiated cancellation.
The proposal already carries the commercial terms, so the request does not repeat packages, dates, targeting, or creatives.
**Request schema:** [`/schemas/3.2.8/media-buy/accept-proposal-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/accept-proposal-request.json)
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441011",
"account": { "account_id": "account_123" },
"proposal_id": "proposal_committed_456",
"proposal_terms_digest": "sha256:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"name": "Acme summer launch"
}
```
For scalable proposals, include `total_budget`. Acceptance may also set a hard aggregate `daily_budget_cap` and optional shared `budget_cap_timezone`; these constrain execution without changing negotiated pricing. If the proposal carries a signature-required insertion order, include `io_acceptance`.
If the proposal belongs to an `opportunity`, acceptance closes that planning cycle with `accepted_with_seller`; callers may repeat the matching opportunity ID explicitly, while the accepted proposal retains the association.
Success returns the resulting MediaBuy identity, the proposal with `proposal_status: "accepted"`, and `purchase_bindings[]` mapping proposal purchase positions to package IDs for later creative assignment. Acceptance is idempotent. The seller atomically verifies `proposal_id`, `proposal_terms_digest`, expiry, and any `base_media_buy_revision`; stale or mismatched acceptance never applies different terms.
The optional `name` is buyer-authored MediaBuy display metadata, not a
commercial proposal term. A supplied request value wins over `proposal.name`,
is persisted unchanged, and is echoed outside `accepted_proposal`; it is not
covered by `proposal_terms_digest` or the accepted snapshot's `terms_digest`.
When an acceptance creates a MediaBuy and the request omits `name`, the seller
may seed it from `proposal.name` only when that value already satisfies the
MediaBuy constraints: non-whitespace and no longer than 255 characters. The
seller must not silently truncate or rewrite a proposal name to make it fit. A
seeded name is then persisted and reported like any other name.
A completed acceptance MAY include `warnings[]` for non-blocking observations at the commitment boundary. Each warning identifies its package through the returned `media_buy_id` and `purchase_bindings[].package_id`; a continuing condition is also readable as an indicator through [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys). The seller may instead return `input-required` before consuming the proposal. Warnings never appear on failed or submitted arms.
An unexpired committed proposal cannot be rejected merely because its reserved inventory was sold elsewhere. Once `expires_at` passes, the hold lapses and the seller returns [`PROPOSAL_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-expired); the buyer must request and finalize a fresh proposal.
# buy_products
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/buy_products
Buy published product offers directly without proposals or inline creatives.
`buy_products` is the buyer-composed purchase path. It creates a MediaBuy from canonical product selections returned by [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products), accepting the published commercial terms as-is.
Creative objects and assignments are deliberately absent. Use the creative lifecycle after the MediaBuy has been created. If the buyer needs different commercial terms, request or refine a proposal instead.
Per-purchase flight dates, `measurement_terms`, and `performance_standards` may be omitted to inherit the published offer. The accepted snapshot resolves and preserves those terms. If this purchase ends a tracked planning cycle, `opportunity` closes it with `accepted_with_seller`.
**Request schema:** [`/schemas/3.2.8/media-buy/buy-products-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/buy-products-request.json)
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441010",
"account": { "account_id": "account_123" },
"brand": { "domain": "acmeoutdoor.example" },
"name": "Acme summer display launch",
"feed_version": "products-2027-06-01T12:00:00Z",
"pricing_version": "pricing-42",
"daily_budget_cap": 5000,
"budget_cap_timezone": "America/New_York",
"frequency_cap": {
"max_impressions": 5,
"per": "individuals",
"window": { "interval": 7, "unit": "days" }
},
"purchases": [
{
"product_id": "product_display_standard",
"pricing_option_id": "cpm_usd",
"budget": 50000,
"daily_budget_cap": 3000
}
],
"start_time": "asap",
"end_time": "2027-07-01T00:00:00Z"
}
```
The root `frequency_cap` uses one counter across all purchases. A
`targeting_overlay.frequency_cap` inside a purchase instead owns an independent
package counter; when both exist, both must permit delivery. Every selected
product must advertise aggregate participation through
`media_buy_support.frequency_cap`. Sellers reject an unadvertised aggregate cap
or an incompatible product mix atomically with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature)
before any mutation, and never clamp it. Buyers send the root field only when the seller advertises
`aggregate_frequency_capping`; root caps are max-impression-only in 3.2.
The media-buy `daily_budget_cap` is a hard aggregate ceiling and does not allocate its value among purchases. A purchase-level budget cap is an optional subordinate ceiling, not a reservation. Every budget cap shares the accepted media-buy `budget_cap_timezone`; sellers reject undeclared budget-cap scopes with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature).
Success returns the MediaBuy identity and an `accepted_proposal` snapshot. Its typed `commercial_terms` preserve the exact feed and pricing versions, product and format selections, catalogs, budgets, targeting, flight, billing, and reporting commitments; `terms_digest` binds that envelope for governance and audit. The separate `purchase_bindings[]` maps each zero-based purchase position to its seller-assigned `package_id`, which SDKs use for later creative assignment without placing execution IDs inside the immutable digest. The seller creates this snapshot even though the buyer did not negotiate first, giving every MediaBuy the same commercial history for later [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals).
An optional buyer-supplied `name` is persisted and echoed on the completed
commitment and subsequent [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys)
reads. It is operational display metadata outside `accepted_proposal` and is
not covered by `terms_digest`.
Each purchase uses request-only `ProductPurchaseInput`. Its
`targeting_overlay` has three states per dimension: omission inherits the
selected product's configured/default value, a non-null value replaces it, and
`null` explicitly suppresses it. A clear cannot remove inherent product scope.
The accepted proposal uses strict `ProductPurchase`; it records the resolved
effective targeting with cleared dimensions omitted and never carries `null`.
A completed purchase MAY include `warnings[]` for non-blocking observations at commitment, such as a material inventory shortfall forecast. Each warning identifies its package through the returned `media_buy_id` and `purchase_bindings[].package_id`; a continuing condition is also readable as an indicator through [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys). The seller may instead return `input-required` before commitment. Warnings never appear on failed or submitted arms.
The accepted snapshot records the published terms the buyer purchased. It does not imply that every direct product is non-guaranteed: discovery mode, buyer composition, and delivery guarantee are independent dimensions.
# control_media_buy
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/control_media_buy
Apply operational delivery controls within accepted MediaBuy terms.
`control_media_buy` applies operational changes authorized by the terms currently accepted for the MediaBuy. It requires the current `revision` for optimistic concurrency. The accepted envelope includes proposal-bound `commercial_terms.change_terms[]`: when the current `available_actions[]` projection links a `self_serve` or `conditional_self_serve` action through `change_term_id`, a request inside that term's typed constraints is already authorized even if it changes the original numeric value. The accepted term is the authority; product `allowed_actions[]` is only advisory.
Supported controls include:
* pause, resume, and an already-permitted unilateral cancellation;
* total, aggregate-daily, and package budget controls;
* budget allocation, pacing, bidding, and shared frequency capping;
* package targeting, catalog references, keyword, impression, and optimization controls;
* MediaBuy display-name metadata; and
* reporting-webhook configuration.
It does not accept creatives, creative assignments, new products/packages, flight-date changes, pricing changes, or billing-term changes. Those concerns use their dedicated lifecycle or a proposal refinement.
## Transaction boundary
One `control_media_buy` request is atomic under the supplied MediaBuy
`revision`. That fence covers only the operational fields in this request.
[`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) has a separate idempotency and atomicity boundary, does not
increment MediaBuy revision for assignment changes, and cannot join this
transaction. There is no shared fence between control and assignment state.
`name` is revision-checked non-commercial metadata. Changing it updates the
shared trafficking display label and increments MediaBuy revision, but does not
change the accepted commercial terms or create an accepted-proposal successor.
Consequently, a targeting patch that removes a placement used by an
existing creative assignment cannot be performed as control followed by sync
without a race window. Use the [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) compatibility facade to send
the targeting patch and complete assignment replacement in one transaction. The
same facade is required for inline-only sellers, because they do not advertise
`sync_creatives` as a later creative path.
Within each package `targeting_overlay` is a request-only per-dimension patch.
Omitting a dimension preserves its effective value, a non-null value replaces
it, and `null` clears it. Sellers return the resulting targeting through strict
readback schemas: cleared dimensions are absent and `null` never appears in
package state or capability/discovery output.
Commercial amendment followed by operational control is also a saga, not one
transaction. If [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) applies the amendment and a subsequent
control fails, the amended commercial snapshot remains accepted. Re-read the
MediaBuy and its new revision before retrying control. A compatibility request
that requires commercial and operational fields to succeed together must be
handled atomically through `update_media_buy`, not silently decomposed.
Root `canceled: true` is mutually exclusive with every package and other
control; a mixed compact request is invalid before mutation. Within a package,
`canceled: true` is likewise mutually exclusive with that package's other
fields. This differs from the compatibility facade, where root cancellation
takes precedence and other fields are ignored with a warning.
Catalog controls accept only IDs previously managed through [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs).
They cannot atomically ingest an inline catalog body, and a catalog synchronized
before a later failed control remains on the account. This task also cannot add
the compatibility facade's `artifact_webhook`, recreate a per-package initial
pause atomically with purchase, or author an exact initial
`committed_metrics` set.
**Request schema:** [`/schemas/3.2.8/media-buy/control-media-buy-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/control-media-buy-request.json)
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441012",
"account": { "account_id": "account_123" },
"media_buy_id": "media_buy_789",
"revision": 4,
"daily_budget_cap": 5000,
"frequency_cap": {
"max_impressions": 3,
"per": "individuals",
"window": { "interval": 7, "unit": "days" }
},
"pacing": "even",
"packages": [
{
"package_id": "package_video",
"daily_budget_cap": 3000,
"paused": true
}
]
}
```
Daily-cap changes apply immediately and atomically with spend already incurred in the current cap day counted. Lowering a cap below current-day spend pauses further applicable delivery without reversing prior spend. `null` removes an aggregate or package cap. A media-buy `budget_cap_timezone` change starts at the next boundary under the previously effective timezone; package controls never carry their own timezone.
Root frequency-cap changes also apply immediately without resetting the shared
counter. Prior qualifying exposures in the resulting window continue to count;
adding or removing packages does not subtract aggregate history. Set
`frequency_cap: null` to remove the root cap. Package targeting caps remain
separate and independently binding. Root changes require
`update_media_buy_frequency_cap`; package changes require
`update_frequency_caps`.
When an otherwise valid control has no negotiated change right, the seller returns [`ACTION_NOT_ALLOWED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-action-not-allowed) with `reason: "not_supported_on_buy"`. When a structured seller policy caused that buy-specific denial, the seller SHOULD also populate `details.decline_reason` unless disclosure would expose private thresholds or enforcement controls. A negotiated right whose opaque condition cannot yet be evaluated returns `reason: "condition_unresolved"` on the current protocol surface and remains absent from `available_actions[]`; released 3.1 callers receive the compatible `not_supported_on_buy` reason. Structural denials such as `wrong_status`, `not_supported_on_product`, `mode_mismatch`, and `condition_unresolved` SHOULD omit `decline_reason`.
When the buy has the right but the request exceeds its typed constraints, the seller returns [`REQUOTE_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-requote-required). Its details SHOULD follow [`error-details/requote-required.json`](https://adcontextprotocol.org/schemas/3.2.8/error-details/requote-required.json): `envelope_field` identifies the breached paths, `change_term_id` identifies the accepted right when one governed the request, and optional `decline_reason` classifies a safely disclosable seller-policy dimension. The buyer uses that reason to inform recovery: it may select a corresponding typed refinement when one exists, or rely on the buyer-safe message, a free-text `ask`, or human negotiation. The buyer then reads `accepted_proposal_id` from [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys), passes it to [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) to create a draft amendment, finalizes that draft into a committed hold, and applies it through [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal). This pointer survives SDK restart and moves atomically after each accepted amendment.
A completed in-envelope control MAY include `warnings[]` for non-blocking observations, such as a material inventory shortfall forecast observed after the applied control. A continuing condition is also readable as an indicator through `get_media_buys`. Failed and submitted controls never carry this warning surface. Flight-date changes are not controls; a `flight_change_creates_pacing_risk` warning belongs on the completed `accept_proposal` response that applies the amendment.
`canceled: true` is direct only when the accepted cancellation policy already grants the caller that right. A cancellation requiring counterparty agreement uses `refine_proposals` with `change_kind: "cancellation"`.
Seller-initiated cancellation does not call a buyer tool. The seller advances the MediaBuy revision and records `cancellation.canceled_by: "seller"`; `get_media_buys` is the normative recovery surface. A durable compact-lifecycle resource-status webhook is intentionally not inferred from the per-operation async callback and remains 4.0 work. Separately, a 3.2 seller advertising the [experimental](/dist/docs/3.2.8/reference/experimental-status) `account.change_feed` capability with `media_buy` coverage emits generic account-anchored `account.change_recorded`, which tells the buyer to drain the feed and repair through `get_media_buys` rather than carrying status itself.
# create_media_buy
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/create_media_buy
create_media_buy task — create advertising campaigns in AdCP from discovered products. Handles packages, budgets, flight dates, governance rules, and approval workflows.
Create a media buy from selected packages or execute a proposal. Handles validation, approval if needed, and campaign creation.
> [!WARNING]
>
> `create_media_buy` is the AdCP 3.x compatibility facade as of 3.2. New integrations use [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) for direct purchases or [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) for proposal execution. Existing payloads remain supported throughout 3.x.
Supports three execution shapes:
* **Fixed packages**: Provide `packages` with independent package budgets (legacy default)
* **Seller-optimized packages**: Provide `packages`, `total_budget`, and `budget_allocation.mode: "seller_optimized"` so the seller allocates a shared budget across packages
* **Proposal execution**: Provide `proposal_id` and `total_budget`; the committed proposal determines whether allocation is fixed or seller-optimized
## Compatibility transaction boundary
The compatibility facade is one atomic mutation, including package trafficking
that appears inline. Before creating a MediaBuy, package, library creative, or
assignment, the seller MUST validate the complete request. An invalid inline
creative or `creative_assignments` entry—including an invalid creative ID,
format, locale, placement route, or package relationship—fails the entire
`create_media_buy` request. The seller returns the terminal error shape and
MUST NOT leave a MediaBuy or any other mutation from that request behind.
This pre-commit validation boundary is separate from creative review. A
structurally and operationally valid creative may enter `processing` or
`pending_review` after the buy is created. A later content-policy, brand-safety,
or accessibility rejection changes the creative or package-approval state; it
does not roll back the confirmed MediaBuy. Before activation, a buy with no
approved creative coverage remains `pending_creatives` until the buyer corrects
or replaces the asset. A rejection affecting an active buy follows the normal
creative-impairment and serving rules rather than reversing creation.
The compact lifecycle deliberately has a different boundary. [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) or
[`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) commits first and returns the seller-assigned package IDs;
[`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) then uploads and assigns library creatives. That sequence is a
saga, not one atomic transaction. A later sync or assignment failure leaves the
MediaBuy committed. `dry_run` can validate a library upload, but it cannot fully
validate package-specific assignment against package IDs that do not exist yet.
Setting `paused: true` where supported reduces activation risk, and a later
cancellation may compensate for a trafficking failure, but neither action is a
rollback.
Use this facade when all-or-none purchase and trafficking is required, or when
the seller supports only inline creative management. Compact purchase has no
inline-only creative continuation. It also has no lossless direct-purchase
equivalent for `artifact_webhook`, per-package initial `paused`, inline catalog
bodies or filters, or a buyer-authored exact `committed_metrics` set. Catalogs
must be synchronized before compact purchase and can remain on the account when
the purchase fails; direct compact purchase lets the seller derive reporting
commitments, while an exact negotiated set must already be present in an
accepted proposal. Callers MUST treat these as explicit compatibility risks,
not silently drop or approximate them.
**Response Time**: Instant to days (returns `completed`, `working` \< 120s, or `submitted` for hours/days)
**Request Schema**: [`/schemas/3.2.8/media-buy/create-media-buy-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-request.json)
**Response Schema**: [`/schemas/3.2.8/media-buy/create-media-buy-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/create-media-buy-response.json)
## Quick Start
Create a simple media buy with two packages:
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/sdk';
// Calculate dates dynamically - start tomorrow, end in 90 days
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(0, 0, 0, 0);
const endDate = new Date(tomorrow);
endDate.setDate(endDate.getDate() + 90);
const result = await testAgent.createMediaBuy({
brand: {
domain: 'acmecorp.com'
},
packages: [
{
product_id: 'prod_d979b543',
pricing_option_id: 'cpm_usd_auction',
format_option_refs: [{ scope: 'product', format_option_id: 'display_300x250_image' }],
budget: 2500,
bidding: { bid_amount: 5.00 }
},
{
product_id: 'prod_e8fd6012',
pricing_option_id: 'cpm_usd_auction',
format_option_refs: [{ scope: 'product', format_option_id: 'display_300x250_html' }],
budget: 2500,
bidding: { bid_amount: 4.50 }
}
],
start_time: tomorrow.toISOString(),
end_time: endDate.toISOString()
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
// Validate response against schema
const validated = CreateMediaBuyResponseSchema.parse(result.data);
// Check for errors (discriminated union response)
if ('errors' in validated && validated.errors) {
throw new Error(`Failed to create media buy: ${JSON.stringify(validated.errors)}`);
}
if ('media_buy_id' in validated) {
console.log(`Created media buy ${validated.media_buy_id}`);
console.log(`Upload creatives by: ${validated.creative_deadline}`);
console.log(`Packages created: ${validated.packages.length}`);
}
```
```python Python test=false theme={null}
import asyncio
import time
from datetime import datetime, timedelta, timezone
from adcp.testing import test_agent
async def create_campaign():
# Calculate dates dynamically - start tomorrow, end in 90 days
tomorrow = datetime.now(timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0) + timedelta(days=1)
end_date = tomorrow + timedelta(days=90)
result = await test_agent.simple.create_media_buy(
brand={
'domain': 'acmecorp.com'
},
packages=[
{
'product_id': 'prod_d979b543',
'pricing_option_id': 'cpm_usd_auction',
'format_kind': 'image',
'params': {'width': 300, 'height': 250},
'budget': 2500,
'bidding': {'bid_amount': 5.00}
},
{
'product_id': 'prod_e8fd6012',
'pricing_option_id': 'cpm_usd_auction',
'format_kind': 'html5',
'params': {'width': 300, 'height': 250},
'budget': 2500,
'bidding': {'bid_amount': 4.50}
}
],
start_time=tomorrow.isoformat().replace('+00:00', 'Z'),
end_time=end_date.isoformat().replace('+00:00', 'Z')
)
# Check for errors (discriminated union response)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Failed to create media buy: {result.errors}")
print(f"Created media buy {result.media_buy_id}")
print(f"Upload creatives by: {result.creative_deadline}")
print(f"Packages created: {len(result.packages)}")
asyncio.run(create_campaign())
```
```bash CLI test=false theme={null}
npx @adcp/sdk@latest \
https://test-agent.adcontextprotocol.org/sales/mcp \
create_media_buy \
'{"brand":{"domain":"acmecorp.com"},"packages":[{"product_id":"prod_d979b543","pricing_option_id":"cpm_usd_auction","format_option_refs":[{"scope":"product","format_option_id":"display_300x250_image"}],"budget":30000,"bidding":{"bid_amount":5.00}},{"product_id":"prod_e8fd6012","pricing_option_id":"cpm_usd_auction","format_option_refs":[{"scope":"product","format_option_id":"display_300x250_html"}],"budget":20000,"bidding":{"bid_amount":4.50}}],"start_time":"2025-06-01T00:00:00Z","end_time":"2025-08-31T23:59:59Z"}' \
--auth $ADCP_AUTH_TOKEN
```
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | [account-ref](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) | Yes | Account reference. Pass `{ "account_id": "..." }` or `{ "brand": {...}, "operator": "..." }` if the seller supports implicit resolution. Required for billing and policy evaluation. |
| `proposal_id` | string | No\* | ID of the exact committed proposal snapshot produced by [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) with `action: "finalize"`, or by the legacy [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) finalize action. Drafts fail with [`PROPOSAL_NOT_COMMITTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-not-committed); declined or already executed proposals fail with [`INVALID_STATE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-state). Exact retries reuse the original idempotency key and replay success. |
| `opportunity` | OpportunityContext | No | Proposal-mode planning-cycle closure shared with [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) and [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals); requires `proposal_id`. Omitting status is the create-specific signal to infer closed with `accepted_with_seller`; if status is sent, it must explicitly carry that closure. |
| `total_budget` | TotalBudget | No\* | Hard aggregate lifetime budget. Its currency is the single media-buy denomination for package constraints and canonical bidding. Required for proposals and seller-optimized explicit packages. Optional in fixed explicit-package mode; when supplied there, it must equal the sum of package budgets. |
| `daily_budget_cap` | number | No | Hard aggregate ceiling per calendar day in the media-buy currency. It limits total buy spend without allocating or reserving amounts for packages. Requires `media_buy` in `budget_capping.supported_scopes`. |
| `frequency_cap` | MediaBuyFrequencyCap | No | Aggregate max-impression cap using one counter across packages. Requires seller `aggregate_frequency_capping` and compatible `media_buy_support` on every product; sellers reject an unsupported cap or product mix with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) before any mutation. Omit when executing a proposal because accepted terms are authoritative. |
| `budget_cap_timezone` | string | No | Shared IANA calendar-day boundary override for aggregate and package daily caps. Accepted only when `budget_capping.buyer_timezone_override` is true; otherwise `timezone_basis` selects `Account.timezone` or the advertised `fixed_timezone`. |
| `budget_allocation` | BudgetAllocation | No | Cross-package allocation mode. Omit for fixed allocation. Use `seller_optimized` with media-buy optimization goals to delegate allocation to the seller. Must be omitted when executing a proposal because the committed proposal supplies it. |
| `packages` | Package\[] | No\* | Array of package configurations (see below). Required when not using proposal_id. |
| `brand` | BrandRef | Yes | Brand reference — resolved to full identity at execution time. See [brand.json](/dist/docs/3.2.8/brand-protocol/brand-json) |
| `start_time` | string | Yes | `"asap"` or ISO 8601 date-time. For new media buys, concrete date-times must not be in the past. |
| `end_time` | string | Yes | ISO 8601 date-time (UTC unless timezone specified) |
| `pacing` | string | No | Aggregate pacing for the media-buy budget: `even`, `asap`, or `front_loaded`. Defaults to `even` when `total_budget` is present. For proposal execution, omit it or match the committed proposal's pacing; conflicting overrides are rejected. |
| `bidding` | BiddingPolicy | No | Complete media-buy bidding default inherited by packages that omit `packages[].bidding`. In shared-budget mode its goal-bound controls bind to the allocation primary goal; in fixed mode inherited cost controls require compatible package result units. |
| `paused` | boolean | No | Create the media buy with delivery held. When true and the buy would otherwise be active, `media_buy_status` is `paused`. Setup blockers still take precedence: missing creatives yield `pending_creatives`, and future flights yield `pending_start`; the hold becomes visible as `paused` after those blockers clear. |
| `invoice_recipient` | [BusinessEntity](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#billing-entity-and-invoice-recipient) | No | Override the account's default billing entity for this buy. The seller MUST validate the recipient is authorized and include it in [`check_governance`](/dist/docs/3.2.8/governance/campaign/tasks/check_governance) when governance agents are configured. |
| `po_number` | string | No | Purchase order number |
| `name` | string | No | Human-readable shared label for trafficking UI display and buyer-seller communication (maximum 255 characters). Sellers persist and echo it unchanged; it is not a purchase-order, reconciliation, or identity key. |
| `idempotency_key` | string | No | Unique key for safe retries. If a request with the same key and account has already been processed, the seller returns the existing media buy. MUST be unique per (seller, request) pair. Min 16 chars. |
| `context` | object | No | Opaque correlation data echoed unchanged in the response. Use for internal tracking, trace IDs, or other caller-specific identifiers. |
| `reporting_webhook` | ReportingWebhook | No | Automated reporting delivery configuration |
| `artifact_webhook` | object | No | Content-artifact delivery configuration established with the buy. This compatibility field has no compact purchase or later control equivalent; adapters MUST NOT silently discard it. |
\* Either `packages` OR (`proposal_id` + `total_budget`) must be provided.
When executing a proposal through this 3.x compatibility facade, `proposal_status` determines whether `create_media_buy` is valid. The split 3.2 request and revise operations return drafts; `refine_proposals` with `action: "finalize"` returns the `committed` snapshot that can be accepted before `expires_at`. New callers use [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal). Legacy [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) drafts require its finalize form, which remains supported throughout 3.x.
An unexpired `committed` proposal carries an inventory hold and cannot be rejected merely because the seller sold that reserved inventory elsewhere. After `expires_at`, the hold lapses and the seller returns [`PROPOSAL_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-expired).
### TotalBudget Object
| Parameter | Type | Required | Description |
| - | - | - | - |
| `amount` | number | Yes | Total budget amount |
| `currency` | string | Yes | ISO 4217 currency code |
### Package Object
| Parameter | Type | Required | Description |
| - | - | - | - |
| `product_id` | string | Yes | Opaque product ID from `get_products`. Non-custom wholesale IDs are stable for the same logical offer within seller and declared cache scope; custom IDs are stable only in their issuing discovery/refinement lineage. Selecting it accepts any `targeting_resolution` disclosed on that product. Sellers MUST echo it on every response package object representing the request. |
| `pricing_option_id` | string | Yes | Pricing option ID from product's `pricing_options` array |
| `format_option_refs` | FormatOptionRef\[] | No | Canonical 3.2 selector into the product's `format_options[]`: publisher-scoped or product-scoped. New buyers use it as their only selector route. |
| `format_kind` | CanonicalFormatKind | No | Direct canonical selector. Pair with enough `params` to satisfy the product declaration and omit `format_option_refs`. |
| `format_ids` | FormatID\[] | Deprecated | Named-format compatibility selector accepted from older 3.x peers. New buyers MUST NOT emit it. Receivers normalize it and equivalence-check it against every co-present canonical route. |
| `params` | object | No | Parameters for the direct canonical selector in `format_kind`. Follows the selected canonical's parameter vocabulary. Requires `format_kind`; `params` alone is schema-invalid. For fixed-size image selectors, `width` and `height` must co-occur. A broad selector such as `{format_kind: "image"}` does not satisfy a product whose `format_options[]` fixes both dimensions; sellers reject under-specified direct selectors with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature). |
| `budget` | number | Conditional | Hard lifetime package spend cap in the media-buy currency. Required in fixed mode. Optional in seller-optimized mode; it remains a ceiling, not a current or reserved allocation, and requires `media_buy.features.seller_optimized_package_budgets`. |
| `min_spend_target` | number | No | Soft lifetime package spend target in the media-buy currency for seller-optimized allocation. Requires `media_buy.features.seller_optimized_min_spend_targets`. The seller should attempt to reach it, but it is not a billing or delivery guarantee. |
| `impressions` | number | No | Impression goal for this package |
| `paused` | boolean | No | Create package in paused state (default: `false`) |
| `pacing` | string | No | `"even"` (default), `"asap"`, or `"front_loaded"`. In seller-optimized mode, package pacing that differs from the media-buy `pacing` requires `media_buy.features.seller_optimized_package_pacing`; omit it unless that capability is advertised. |
| `daily_budget_cap` | number | No | Optional hard package-level spend ceiling per calendar day, subordinate to any aggregate media-buy `daily_budget_cap`. It is a package constraint, not a reserved daily allocation; seller-optimized packages may omit it. All daily caps on the buy use the media-buy cap timezone. |
| `bidding` | BiddingPolicy | No | Complete package-authored bidding override. Use `{automatic: true}` to explicitly override a media-buy policy with provider automatic bidding. Omit to inherit. This is replacement inheritance, not a field-by-field merge. |
| `bid_price` | number | No | **Deprecated in 3.2.** Use `bidding.bid_amount` or `bidding.max_bid`. A package cannot supply both representations. |
| `optimization_goals` | [OptimizationGoal\[\]](/dist/docs/3.2.8/media-buy/conversion-tracking/#optimization-goals) | No | Objective functions for this package: what to optimize and in what priority. Currency controls belong in `bidding`; legacy `target.cost_per` and `target.per_ad_spend` remain accepted only for migration. |
| `targeting_overlay` | TargetingInput | No | Request-only per-dimension targeting applied to the configured targeting represented by `product_id` (see [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting#request-mutation-semantics)). A nested `frequency_cap` owns an independent package counter; it does not share state with other packages or with a root `frequency_cap`. Omission inherits the configured/product default for a dimension, a non-null value replaces it, and `null` explicitly suppresses it. A clear cannot remove inherent product scope; the seller rejects a clear it cannot execute. The resulting package echoes the complete effective overlay with cleared dimensions omitted and no `null` values. Non-null additions must compile exactly or be rejected and require product `overlay_support` unless already accepted during discovery. The narrow exception is a placement set equal to the product's complete, explicitly enumerated `mode: "included"` set, or a `collection_selection` exactly restating the product's complete `collections` bundle (gated by `collection_targeting_allowed`, which has no `overlay_support` key); either needs no selectable support, while a partial set does. Opaque property and collection list refs have no equivalent fixed-restatement exception. For `demographics`, inspect the selected product's `demographic_targeting` declaration first. Creative assignment placement refs only route creatives. A supported selection with no current inventory returns [`PRODUCT_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-unavailable), never silent substitution or repricing. |
| `audience_evidence_requirements` | AudienceEvidenceRequirements | No | Package-level suitability policy. Sellers reject an unsatisfied required policy rather than dropping it, and return every snapshot used to satisfy it in the confirmed package's `audience_evidence_selections` with `decision_use: "package_construction"`. This is not a targeting instruction. |
| `audience_evidence_pins` | AudienceEvidencePin\[] | No | Exact discovery snapshots the buyer requires, each pinned by `evidence_id`, `snapshot_id`, `version`, and `content_digest`. Sellers reject missing, substituted, or mutated snapshots. Every accepted pin is returned in the confirmed package's `audience_evidence_selections` and retained on package readback. |
| `start_time` | string | No | ISO 8601 date-time for this package's flight start. When omitted, inherits the media buy's `start_time`. Must fall within the media buy's date range. Does not support `"asap"`. |
| `end_time` | string | No | ISO 8601 date-time for this package's flight end. When omitted, inherits the media buy's `end_time`. Must fall within the media buy's date range. |
| `creative_assignments` | CreativeAssignment\[] | No | Assign existing library creatives with optional weights and placement targeting. Every reference and route is validated as part of the atomic create; one invalid entry fails the whole request. |
| `creatives` | CreativeAsset\[] | No | Upload new creative assets inline and assign. Requires `media_buy.features.inline_creative_management: true`; when the seller also advertises `creative.has_creative_library: true`, `creative_id` must not already exist in the library. Pre-commit validation failure blocks the entire create; later review rejection does not roll it back. |
| `catalogs` | Catalog\[] | No | Catalog bodies, references, or filtered selections promoted by this package. Compact purchase accepts previously synchronized catalog IDs only, so translating an inline body requires a separate, non-atomic [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs) mutation. |
| `context` | object | No | Opaque correlation data echoed unchanged in the package response, webhooks, and read surfaces. Use to map seller-assigned `package_id` back to your internal line items, campaign structure, or tracking state. Buyers targeting mixed seller populations SHOULD include a per-package correlation value here, commonly `context.buyer_ref`, for legacy sellers that do not echo `product_id`. |
| `measurement_terms` | [MeasurementTerms](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#measurement-terms-and-performance-standards) | No | Buyer's proposed billing measurement and makegood terms. Overrides product defaults. Seller accepts (echoed on confirmed package), rejects with [`TERMS_REJECTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-terms-rejected), or adjusts. When omitted, product's `measurement_terms` apply. |
| `performance_standards` | [PerformanceStandard\[\]](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#measurement-terms-and-performance-standards) | No | Buyer's proposed performance standards (viewability, IVT, completion rate, brand safety, attention score). Overrides product defaults. Seller accepts, rejects with `TERMS_REJECTED`, or adjusts. When omitted, product's `performance_standards` apply. |
| `committed_metrics` | object\[] | No | Buyer's proposed reporting contract — metrics the buyer wants the seller to commit to populating in delivery reports. Same negotiation pattern as `measurement_terms`/`performance_standards`: each entry tags `scope: "standard"` (with `metric_id` from the closed enum) or `scope: "vendor"` (with `vendor` BrandRef + vendor's `metric_id`, and optionally `methodology_version` to pin the vendor catalog's methodology version). Request-side entries do NOT carry `committed_at` — that timestamp is stamped by the seller on accept. Seller accepts (echoes on response with `committed_at`), rejects with `TERMS_REJECTED`, or normalizes (echoes a different but compatible list). When omitted, the seller decides what to commit based on the product's `available_metrics` plus any `required_metrics` filter the buyer passed at discovery. |
For `targeting_overlay.geo_places` and `geo_places_exclude`, create-time values
must be within the selected Product's corresponding `overlay_support` tuple.
Unsupported dimensions, systems, countries, place types, or combinations return
`UNSUPPORTED_FEATURE`. A supported tuple with an invalid, unknown, or deprecated
ID—or an unsupported explicit catalog version—returns [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) with
`error.field` on the offending field. A supported selection with no current
inventory returns `PRODUCT_UNAVAILABLE`, without silent substitution or
repricing. An accepted create confirms the selected terms for the complete
effective targeting.
### BiddingPolicy Object
`optimization_goals` select the objective; `bidding` constrains how the seller executes against it. Every monetary amount is in the media-buy currency, which is not repeated in the block. The pricing option contributes only the auction unit, never a second currency. Every package's selected pricing option must declare the media-buy currency; split packages requiring another currency into a separate media buy.
| Field | Meaning |
| - | - |
| `automatic: true` | Explicit provider automatic bidding. At package scope this overrides, rather than inherits, media-buy bidding. |
| `bid_amount` | Manual auction bid in media-buy currency per the selected pricing option's auction unit. It is not a promise that the clearing price equals the bid. |
| `max_bid` | Hard per-auction ceiling in media-buy currency per the selected pricing option's auction unit. It is the only canonical hard auction ceiling. |
| `cost_per: { amount, strength }` | Average cost in media-buy currency per scope-bound primary-goal result. `strength` is `cap` or `target`; neither is a per-result guarantee. |
| `roas: { value, strength }` | Dimensionless return per unit of ad spend. `strength` is `floor` or `target`; value-bearing event sources must declare `value_currencies` containing the media-buy currency. Each buy consumes only exact-currency value records; no conversion is permitted. |
`automatic`, `bid_amount`, `cost_per`, and `roas` are mutually exclusive primary modes. `max_bid` can stand alone or supplement `cost_per`/`roas` only where the relevant scope capability advertises the combination; `bid_amount` and `max_bid` cannot coexist.
Goal binding is determined by authored scope:
1. A seller-optimized media-buy `cost_per` or `roas` binds to the primary goal in `budget_allocation.optimization_goals`.
2. A package-authored override binds to that package's primary `optimization_goals` goal.
3. A fixed-allocation media-buy `cost_per` binds separately to every inheriting package and is valid only when their primary-goal result units are compatible. Metric goals must identify the same metric and result-defining qualifier; vendor metrics must identify the same vendor and metric; event goals must identify the same event-type/custom-name set and resolved attribution window. A fixed media-buy `roas` may span different event identities, but every inheriting primary goal must be value-bearing.
The primary goal is the earliest array entry among goals tied for the lowest explicit numeric priority. Unprioritized goals follow explicitly prioritized goals; when every priority is omitted, the first entry is primary. `bid_amount` and `max_bid` use the selected pricing option's auction unit, which permits a package conversion-cost target plus a max-CPC ceiling while keeping both monetary amounts in one currency. Auction-unit identity is the pricing model plus all billing-event qualifiers after defaults: for example CPV view threshold, CPP demographic, time unit, or flat-rate/DOOH parameters. A media-buy `bid_amount` or `max_bid` may be inherited only by packages with the same auction-unit identity; other packages need package overrides.
Precedence is complete-block inheritance:
1. Package `bidding` replaces media-buy `bidding` for that package.
2. An omitted package block inherits the complete media-buy block.
3. `{automatic: true}` is an explicit package override that disables inherited buyer controls for that package.
4. If both scopes are absent, provider automatic delivery applies.
5. Sellers preserve authored scope on readback and never copy an inherited media-buy policy into every package.
In seller-optimized/shared-budget mode, media-buy bidding is authoritative for any strategy the provider requires at campaign level. Package overrides are permitted only for controls that provider supports under the shared strategy. Sellers validate all effective policies before mutation and reject incompatible placement with [`BIDDING_PLACEMENT_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-bidding-placement-conflict); they never choose one conflicting package policy based on package order.
In independent-package budget mode, sellers normally write each effective policy to the package-native object. When a provider requires one campaign strategy and all effective package policies are identical, a seller may lift that policy to the native campaign, but readback still preserves whether the buyer authored it at media-buy or package scope.
Capability discovery is structured. Sellers advertise only the scopes, modes, strengths, and supplements they preserve, for example a package-only cost-cap implementation:
```json theme={null}
{
"media_buy": {
"features": {
"bidding_policy": {
"package": {
"fixed": {
"modes": ["cost_per", "automatic"],
"cost_per_strengths": ["cap"]
}
}
}
}
}
}
```
Each scope is partitioned into `fixed` and `seller_optimized` profiles so support in one allocation context makes no claim about the other. `supported_combinations` entries use `kind: "max_bid_with_cost_per"` or `kind: "max_bid_with_roas"` and list the exact cost/ROAS strengths supported in that combination. Presence of `bidding_policy` alone is not a blanket claim, and the former boolean form is invalid in 3.2.
During 3.2, sellers accept either canonical `bidding` or one legacy representation on an effective package, never both. Mixed input is rejected with [`AMBIGUOUS_BIDDING_POLICY`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-ambiguous-bidding-policy). Legacy normalization is deterministic: `bid_price` plus pricing-option `max_bid: true` becomes `bidding.max_bid`; other `bid_price` becomes `bidding.bid_amount`; goal `target.cost_per` becomes `bidding.cost_per` with `strength: "target"`; and goal `target.per_ad_spend` becomes `bidding.roas` with `strength: "target"`.
A provider portfolio bidding strategy illustrates the current abstraction boundary. This contract represents the numeric policy but does not model a provider portfolio resource or shared identity above a media buy. A seller may create and own a single-buy provider strategy to honor a portfolio-only ceiling. Selecting an existing strategy, sharing learning across media buys, or updating several buys atomically requires a future provider-neutral bidding-policy resource/reference; provider identity may be returned under `ext` until then.
## Response
### Success Response
| Field | Description |
| - | - |
| `media_buy_id` | Seller's unique identifier |
| `name` | Persisted human-readable media-buy label. When supplied in the request, the seller MUST echo it unchanged. |
| `account` | Resolved account billed for this media buy, echoed as a full [Account](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) object (includes `account_id`, `name`, `status`, and the resolved `brand`/`operator`). When the request used implicit resolution (`brand` + `operator`), this confirms the account the seller resolved. Optional. |
| `confirmed_at` | ISO 8601 timestamp when the seller committed to the media buy. Stable after it is set. May be `null` in deferred/manual approval flows until seller commitment occurs. |
| `creative_deadline` | ISO 8601 timestamp for creative upload deadline |
| `revision` | Initial media-buy revision. Use this value as the `revision` token on the next [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) call intended to change state. |
| `packages` | Array of created packages with complete state. Packages MAY include a per-package `creative_deadline` and SHOULD echo canonical selectors supplied on create so read surfaces are lossless. When additional creative coverage is required, each package carries `formats_to_provide[]`. A package whose selected option has `tracker_execution_contract` MUST carry it even when coverage is already complete. Entries are immutable `PackageFormatSnapshot` values that bind the effective Product declaration, `product_id`, stable option identity, applicable placements, exact VAST/DAAST execution version, and RFC 8785 digests. When the request included audience-evidence pins or requirements, each package MUST return matching `audience_evidence_selections` with `decision_use: "package_construction"`. |
| `warnings` | Structured non-blocking observations. The buy was still created. A continuing condition also appears on [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys); see [Indicators and Warnings](/dist/docs/3.2.8/media-buy/media-buys/indicators). |
Treat `packages[].formats_to_provide[]` as the immutable checklist and production-contract snapshot established at booking time. An ordinary checklist entry can be ID-less, but a contract-bearing snapshot always has `format_option_id`, `product_id`, `tracker_execution_contract_digest`, and `product_snapshot_digest`. It remains present after upload or assignment because validation and serving use the package-time contract, never mutable Product discovery. After uploads or assignments, call [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys): `packages[].formats_pending[]` is the canonically equal subset that still lacks creative coverage and may be empty. The deprecated `format_ids_to_provide` / `format_ids_pending` projections exist only for older 3.x peers.
`confirmed_at` is seller commitment time, not a delivery-status timestamp. Do not update it when a buy later pauses, resumes, starts delivery, completes, or reports performance. A committed synchronous create stamps it immediately. Use the `submitted` response branch when no `media_buy_id` is being returned to the buyer. Sellers MAY instead return synchronous success with `media_buy_id`, `packages`, and `confirmed_at: null` for a provisional buy; such buys MUST be retrievable via `get_media_buys` and MUST transition by setting `confirmed_at` exactly once on commitment. A provisional buy with `confirmed_at: null` MUST NOT be `active` and MUST NOT include `packages[].committed_metrics`.
#### Reporting contract on confirmed packages
Each package in the response MAY carry `committed_metrics` — the binding reporting contract the seller has agreed to populate in delivery reports for this package. The field is a unified array carrying both standard metrics (from the closed `available-metric.json` enum) and vendor-defined metrics (anchored on a BrandRef), with each entry tagged by an explicit `scope` discriminator and timestamped via `committed_at`:
When `confirmed_at` is `null`, sellers MUST omit `packages[].committed_metrics`. The first response that sets `confirmed_at` MAY include the initial committed-metrics set, and each such entry's `committed_at` MUST equal `confirmed_at`.
```json theme={null}
{
"package_id": "pkg_001",
"committed_metrics": [
{ "scope": "standard", "metric_id": "impressions", "committed_at": "2026-04-29T10:53:00Z" },
{ "scope": "standard", "metric_id": "completed_views", "committed_at": "2026-04-29T10:53:00Z" },
{ "scope": "vendor", "vendor": { "domain": "attentionvendor.example" },
"metric_id": "attention_units", "committed_at": "2026-04-29T10:53:00Z" },
{ "scope": "standard", "metric_id": "viewable_rate",
"qualifier": { "viewability_standard": "mrc" },
"committed_at": "2026-05-30T14:22:00Z" }
]
}
```
**How the contract works:**
* **Day-1 entries** share `committed_at = confirmed_at`. The seller stamps the day-1 set on the `create_media_buy` response based on what they're prepared to deliver from the product's `reporting_capabilities`.
* **Mid-flight additions** are appended via `update_media_buy` — append-only with their own `committed_at` timestamps. This lets a seller honestly say "Adelaide attention is now part of the contract from day 30 onward" without having to cancel and reissue the buy.
* **Existing entries are immutable.** Sellers MUST reject `update_media_buy` requests that attempt to modify or remove existing entries with a `validation_error` (suggested code: `IMMUTABLE_FIELD`). New entries can be appended.
* **Methodology pin on vendor metrics.** A vendor-scope entry MAY carry `methodology_version`, pinning the vendor catalog's `measurement.metrics[].methodology_version` the commitment is contracted against. A buyer proposes it on the request; the seller echoes it on accept or normalizes to the version it can deliver. A vendor methodology change that alters the value definition is a contract change — append a new entry with its own `committed_at`, never silently substitute. Absence means untracked. The observable signal for "the vendor changed methodology" is the `methodology_version` string in the vendor's own `get_adcp_capabilities.measurement.metrics[]` catalog: sellers that pin a version SHOULD re-read the catalog on a schedule and SHOULD subscribe to the vendor agent's `capabilities.changed` notification where the vendor supports agent-level webhooks. The measurement catalog is an experimental surface, so vendors are not yet obliged to publish a version or to notify — where a vendor does neither, a pin cannot be honoured and sellers SHOULD decline to commit one.
* **Qualifiers on standard metrics.** Some metrics have multiple incompatible measurement paths and need disambiguation:
* **`viewability_standard`** — when `metric_id` is one of `viewable_impressions`, `viewable_rate`, `measurable_impressions`, `viewed_seconds`, `viewed_seconds_percentiles`, or `viewed_seconds_histogram` and the seller commits to a specific viewability standard (MRC and GroupM are materially different thresholds — see the `viewability-standard` enum), the entry MUST carry `qualifier.viewability_standard`. Symmetric on `missing_metrics`: a buyer expecting MRC viewability flags a GroupM-only delivery report as missing the MRC commitment. Without the qualifier, the standard is unspecified; buyers MUST NOT combine an unqualified distribution with any other row, including another row whose standard is unspecified.
* **`completion_source`** — when `metric_id` is `completion_rate` and the seller commits to a specific source (the player/ad server's own completion event vs. a third-party measurement vendor anchored on `performance_standard.vendor`), the entry MUST carry `qualifier.completion_source` (`seller_attested` or `vendor_attested`). The two paths can yield materially different rates, particularly in SSAI environments. Symmetric on `missing_metrics`.
* **`attribution_methodology`** — when `metric_id` is an outcome metric (`conversions`, `conversion_value`, `roas`, `cost_per_acquisition`, `incremental_sales_lift`, `brand_lift`, `foot_traffic`, `conversion_lift`, `brand_search_lift`, `units_sold`, `new_to_brand_rate`, `new_to_brand_units`, `leads`) and the seller commits to a specific attribution methodology, the entry SHOULD carry `qualifier.attribution_methodology` (`deterministic_purchase` for retail-media closed-loop; `probabilistic`, `panel_based`, or `modeled` for other paths). Two outcome rows under different methodologies are not interchangeable; symmetric on `missing_metrics`.
* **`attribution_window`** — when `metric_id` is an outcome metric and the seller commits to a specific lookback window, the entry SHOULD carry `qualifier.attribution_window` as a structured duration (`{ interval: 14, unit: "days" }`). Two outcome rows over different windows are reported as separate rows so buyers don't accidentally aggregate across periods.
Without the qualifier, the contract is ambiguous and reconciliation falls back to whatever the delivery report happens to carry. The qualifier vocabulary is closed (`additionalProperties: false`); new keys ship explicitly in subsequent minors.
Vendor-scope entries MAY carry the same qualifier keys when the same vendor metric is committed under more than one methodology or window — e.g., `attribution_window` on a vendor outcome metric distinguishes a 14-day vendor attribution commitment from a 30-day one for the same `(vendor, metric_id)`. `missing_metrics` mirrors the qualifier for vendor entries exactly as it does for standard entries.
* **Reconciliation:** `missing_metrics` on [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) filters `committed_metrics` to entries where `committed_at < reporting_period.end`, then flags any that aren't populated in the report. A metric committed mid-flight is only audited from its commitment timestamp forward. Qualifiers are matched verbatim — a committed `{viewable_rate, mrc}` is not satisfied by a delivered `viewable_rate` carrying `viewability.standard: groupm`.
* **Optional in v1.** Sellers without per-package snapshot infrastructure can adopt incrementally. Absence is conformant but carries a known audit gap: without the snapshot, `missing_metrics` reconciles against the product's live `available_metrics` at report time, which may not reflect what was committed at create time. Sellers that omit `committed_metrics` accept this risk; buyers SHOULD treat absence as "no audit-grade contract" rather than "clean delivery." Expected to become required at the next major.
### Error Response
| Field | Description |
| - | - |
| `errors` | Array of error objects explaining failure |
Terminal and submitted responses never include `warnings`. Each success warning carries typed `affected_resource` identity; codes follow the negotiated AdCP release.
### Submitted Response
Returned when the buy cannot be confirmed synchronously — e.g., guaranteed buys awaiting IO signing, governance review queued, or batched processing. The completion artifact (delivered through AdCP polling or a push-notification webhook) carries `media_buy_id` and `packages`. A2A profile callers poll with [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json); MCP sellers may also expose the legacy AdCP `tasks/get` name.
There is no proposal-specific acceptance webhook. Proposal execution that needs human approval, IO signing, or asynchronous processing uses this same submitted task envelope and the standard task/webhook completion path.
| Field | Description |
| - | - |
| `status` | Literal `"submitted"` — discriminates this shape from the sync success branch, which uses `media_buy_status` for lifecycle state. |
| `task_id` | Handle the buyer polls with `get_task_status` on the A2A profile (or the advertised AdCP polling task on MCP), or receives on webhook callbacks. |
| `message` | Optional human-readable explanation (e.g., "Awaiting IO signature from sales team"). |
| `errors` | Optional advisory warnings (non-blocking). Terminal failures belong in the Error Response. |
**Note**: Responses are mutually exclusive across these three shapes. Dispatch on `status` first: `"submitted"` → async envelope, otherwise check `errors` before accessing success fields.
### When to return Submitted vs synchronous Success (normative)
The choice between `submitted` and synchronous success is **per-call**, driven by per-product attributes and the seller's policy on each specific create — not a uniform per-seller rule. A sales-guaranteed seller may legitimately return synchronous success on some `create_media_buy` calls and `submitted` on others within the same session; conformant SDK skills MUST NOT instruct agents to return `submitted` for every `create_media_buy` regardless of input. Sellers that uniformly return `submitted` fail the non-IO-approval paths in the `sales-guaranteed` compliance storyboard.
Sellers MUST return `submitted` when:
* The request references one or more products with `delivery_type: "guaranteed"` **and** the seller declares the `requires_io_approval` capability — the human-approval handshake cannot complete inside the response. The completion artifact is delivered through AdCP polling (`get_task_status` on the A2A profile) or webhook once IO signing finishes.
* The request triggers a seller-side governance review that cannot complete synchronously (e.g., manual brand-safety review for a regulated vertical).
* The request enters a batched-processing queue the seller cannot drain inside the response timeout.
Sellers MUST return synchronous success when:
* All referenced products have `delivery_type: "non_guaranteed"`. The buy is created and acknowledged in-line; `media_buy_id` and `packages` are issued immediately. This applies regardless of the seller's specialism — a sales-guaranteed seller serving a non-guaranteed product returns synchronous success.
* The request references guaranteed products and the seller does NOT declare `requires_io_approval` (rare; typically retail-SKU or quoted-rate guaranteed flows where the seller has pre-cleared approval).
* The buy enters a known non-terminal state immediately observable to the buyer (`pending_creatives` / `pending_start` / `active` / `paused`).
The compliance grader observes both paths against the same seller via separate storyboard scenarios: the `create_buy_submitted` scenario seeds a guaranteed product with `requires_io_approval`; four shared scenarios (`measurement_terms_rejected`, `pending_creatives_to_start`, `inventory_list_targeting`, `invalid_transitions`) seed non-guaranteed products and expect synchronous `media_buy_id` returns. Sellers that return `submitted` on the synchronous-expected scenarios fail compliance — see [`sales-guaranteed` specialism](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/specialisms/sales-guaranteed) for the fixture pattern (non-guaranteed products listed first so open-brief [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) calls resolve to a synchronous-create path).
This rule resolves the skill ↔ storyboard contradiction tracked at [#3822](https://github.com/adcontextprotocol/adcp/issues/3822): an SDK skill that instructs agents to "return a task envelope for every `create_media_buy`" is non-conformant; the correct skill instructs agents to dispatch on per-product `delivery_type` and the seller's `requires_io_approval` capability.
## Common Scenarios
### Campaign with Targeting
Add geographic restrictions and frequency capping:
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/sdk';
// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);
const result = await testAgent.createMediaBuy({
brand: {
domain: 'acmecorp.com'
},
packages: [{
product_id: 'prod_d979b543',
pricing_option_id: 'cpm_usd_auction',
format_option_refs: [{
scope: 'product',
format_option_id: 'display_300x250_image'
}],
budget: 2500,
bidding: { bid_amount: 5.00 },
targeting_overlay: {
geo_countries: ['US'],
geo_regions: ['US-CA', 'US-NY'],
frequency_cap: {
suppress: { interval: 60, unit: 'minutes' }
}
}
}],
start_time: 'asap',
end_time: endDate.toISOString()
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}
if ('media_buy_id' in validated) {
console.log(`Campaign ${validated.media_buy_id} created with targeting`);
}
```
```python Python test=false theme={null}
import asyncio
import time
from datetime import datetime, timedelta, timezone
from adcp.testing import test_agent
async def create_targeted_campaign():
# Calculate end date dynamically - 90 days from now
end_date = datetime.now(timezone.utc) + timedelta(days=90)
result = await test_agent.simple.create_media_buy(
brand={
'domain': 'acmecorp.com'
},
packages=[{
'product_id': 'prod_d979b543',
'pricing_option_id': 'cpm_usd_auction',
'format_kind': 'image',
'params': {'width': 300, 'height': 250},
'budget': 2500,
'bidding': {'bid_amount': 5.00},
'targeting_overlay': {
'geo_countries': ['US'],
'geo_regions': ['US-CA', 'US-NY'],
'frequency_cap': {
'suppress': {'interval': 60, 'unit': 'minutes'}
}
}
}],
start_time='asap',
end_time=end_date.isoformat().replace('+00:00', 'Z')
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Creation failed: {result.errors}")
print(f"Campaign {result.media_buy_id} created with targeting")
asyncio.run(create_targeted_campaign())
```
### Campaign with Conversion Optimization
Keep the purchase event as the objective, then express target ROAS and the max-CPC auction ceiling separately in `bidding`. You must have an event source configured via [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources):
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/sdk';
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);
const result = await testAgent.createMediaBuy({
brand: {
domain: 'acmecorp.com'
},
packages: [{
product_id: 'prod_retail_sp',
pricing_option_id: 'cpc_usd_auction',
budget: 10000,
bidding: {
roas: { value: 4.0, strength: 'target' },
max_bid: 1.20
},
optimization_goals: [{
kind: 'event',
event_sources: [
{ event_source_id: 'retailer_sales', event_type: 'purchase', value_field: 'value' }
],
priority: 1
}]
}],
start_time: 'asap',
end_time: endDate.toISOString()
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}
if ('media_buy_id' in validated) {
console.log(`Campaign ${validated.media_buy_id} created with target ROAS`);
}
```
```python Python test=false theme={null}
import asyncio
import time
from datetime import datetime, timedelta, timezone
from adcp.testing import test_agent
async def create_optimized_campaign():
end_date = datetime.now(timezone.utc) + timedelta(days=90)
result = await test_agent.simple.create_media_buy(
brand={
'domain': 'acmecorp.com'
},
packages=[{
'product_id': 'prod_retail_sp',
'pricing_option_id': 'cpc_usd_auction',
'budget': 10000,
'bidding': {
'roas': {'value': 4.0, 'strength': 'target'},
'max_bid': 1.20
},
'optimization_goals': [{
'kind': 'event',
'event_sources': [
{ 'event_source_id': 'retailer_sales', 'event_type': 'purchase', 'value_field': 'value' }
],
'priority': 1
}]
}],
start_time='asap',
end_time=end_date.isoformat().replace('+00:00', 'Z')
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Creation failed: {result.errors}")
print(f"Campaign {result.media_buy_id} created with target ROAS")
asyncio.run(create_optimized_campaign())
```
### Catalog-driven packages
A catalog-driven package allocates a single budget envelope to an entire catalog of items. Instead of creating separate packages per item, the platform optimizes delivery across all catalog items based on performance. This is the AdCP equivalent of catalog-based campaign types such as Google Performance Max or Meta Dynamic Product Ads.
Include the `catalogs` field in a package to make it catalog-driven. Each catalog should have a distinct type (e.g., one product catalog, one store catalog). The referenced catalogs must already be synced via [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs).
**Job campaign with synced job catalog:**
```json test=false theme={null}
{
"brand": { "domain": "acme-restaurants.com" },
"packages": [{
"product_id": "prod_job_board",
"pricing_option_id": "cpc_eur_auction",
"budget": 5000,
"bidding": { "bid_amount": 2.50 },
"catalogs": [{
"catalog_id": "chef-vacancies",
"type": "job"
}]
}],
"start_time": "asap",
"end_time": "2026-06-30T23:59:59Z"
}
```
**Retail media with product catalog and store catchment targeting:**
```json test=false theme={null}
{
"brand": { "domain": "acmecorp.com" },
"packages": [{
"product_id": "prod_retail_sp",
"pricing_option_id": "cpc_usd_auction",
"budget": 10000,
"bidding": { "bid_amount": 1.20 },
"catalogs": [{
"catalog_id": "gmc-primary",
"type": "product",
"tags": ["summer"]
}],
"targeting_overlay": {
"store_catchments": [{
"catalog_id": "retail-locations",
"catchment_ids": ["drive"]
}]
}
}],
"start_time": "asap",
"end_time": "2026-09-30T23:59:59Z"
}
```
The platform distributes budget across catalog items based on performance. For per-item reporting, use [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) which returns `by_catalog_item` breakdowns. Creative variants for catalog-driven packages represent individual catalog items rendered as ads.
**Package with explicit signal targeting:**
Use `targeting_overlay.signal_targeting_groups` when the buyer wants seller-offered signals applied to a specific package. The selected product must set `signal_targeting_allowed: true` and make the signal eligible through inline `signal_targeting_options` when present, through [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals) for wholesale products that omit inline options, and through `signal_targeting_rules`. The grouped expression shape is always used: top-level `operator: "all"` with child groups using `operator: "any"` for include groups and `operator: "none"` for exclusion groups. For simple include-only targeting, send one `any` group. For binary signals, send `value: true` in both include and exclusion groups; exclusion is expressed by the parent `none` group, not by `value: false`. Signals are referenced with `signal_ref`: use `scope: "product"` for a product-local signal option, `scope: "data_provider"` with `data_provider_domain` for a signal defined in a data provider's published adagents.json `signals[]`, or `scope: "signal_source"` with `signal_source_url` for a source-native signal. This is distinct from `audience_include` / `audience_exclude`, which only reference first-party audiences registered through [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences). Send `signal_agent_segment_id` only when the selected product option or `get_signals` result exposed it as a separate execution handle required by the seller.
When a creative carries a build-time `signal_condition` (from [`build_creative`](/dist/docs/3.2.8/creative/task-reference/build_creative)'s `signal_conditions` fan-out, [#5240](https://github.com/adcontextprotocol/adcp/issues/5240)), assigning it to a package whose signal targeting is incompatible — e.g. a sun creative to a rain-targeted package — is rejected with [`SIGNAL_TARGETING_INCOMPATIBLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-signal-targeting-incompatible). Compatibility is matched on the same shared `signal_ref` identity used here. See the [signals specification](/dist/docs/3.2.8/signals/specification#creative-signal-fan-out-and-trafficking-compatibility) for the normative trafficking-compatibility contract.
```json test=false theme={null}
{
"brand": { "domain": "acmecorp.com" },
"packages": [{
"product_id": "retail_video_premium",
"pricing_option_id": "media_cpm_usd",
"budget": 25000,
"targeting_overlay": {
"signal_targeting_groups": {
"operator": "all",
"groups": [{
"operator": "any",
"signals": [{
"signal_ref": {
"scope": "data_provider",
"data_provider_domain": "pinnacle-data.example",
"signal_id": "auto_intenders"
},
"value_type": "binary",
"value": true,
"pricing_option_id": "signal_cpm_usd_250",
"signal_agent_segment_id": "seller_sig_auto_intenders"
}]
}]
}
}
}],
"start_time": "asap",
"end_time": "2026-09-30T23:59:59Z"
}
```
Include plus exclusion example:
```json test=false theme={null}
{
"brand": { "domain": "acmecorp.com" },
"packages": [{
"product_id": "retail_video_premium",
"pricing_option_id": "media_cpm_usd",
"budget": 25000,
"targeting_overlay": {
"signal_targeting_groups": {
"operator": "all",
"groups": [
{
"operator": "any",
"signals": [
{
"signal_ref": { "scope": "product", "signal_id": "high_intent_shoppers" },
"value_type": "binary",
"value": true
},
{
"signal_ref": { "scope": "product", "signal_id": "loyalty_members" },
"value_type": "binary",
"value": true
}
]
},
{
"operator": "none",
"signals": [
{
"signal_ref": { "scope": "product", "signal_id": "recent_purchasers" },
"value_type": "binary",
"value": true
}
]
}
]
}
}
}],
"start_time": "asap",
"end_time": "2026-09-30T23:59:59Z"
}
```
### Campaign with Inline Creatives
Upload creatives at the same time as creating the campaign:
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/sdk';
// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);
const result = await testAgent.createMediaBuy({
brand: {
domain: 'acmecorp.com'
},
packages: [{
product_id: 'prod_d979b543',
pricing_option_id: 'cpm_usd_auction',
format_option_refs: [{ scope: 'product', format_option_id: 'display_300x250_image' }],
budget: 2500,
bidding: { bid_amount: 5.00 },
creatives: [{
creative_id: 'hero_video_30s',
name: 'Hero Video',
format_kind: 'image',
format_option_ref: { scope: 'product', format_option_id: 'display_300x250_image' },
assets: {
image: {
asset_type: 'image',
url: 'https://cdn.example.com/hero-banner.jpg',
width: 300,
height: 250
}
}
}]
}],
start_time: 'asap',
end_time: endDate.toISOString()
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}
if ('packages' in validated) {
console.log(`Campaign created with ${validated.packages[0].creative_assignments.length} creatives`);
}
```
```python Python test=false theme={null}
import asyncio
import time
from datetime import datetime, timedelta, timezone
from adcp.testing import test_agent
async def create_with_creatives():
# Calculate end date dynamically - 90 days from now
end_date = datetime.now(timezone.utc) + timedelta(days=90)
result = await test_agent.simple.create_media_buy(
brand={
'domain': 'acmecorp.com'
},
packages=[{
'product_id': 'prod_d979b543',
'pricing_option_id': 'cpm_usd_auction',
'format_kind': 'image',
'params': {'width': 300, 'height': 250},
'budget': 2500,
'bidding': {'bid_amount': 5.00},
'creatives': [{
'creative_id': 'hero_video_30s',
'name': 'Hero Video',
'format_kind': 'image',
'assets': {
'image_main': {
'asset_type': 'image',
'url': 'https://cdn.example.com/hero-banner.jpg',
'width': 300,
'height': 250
}
}
}]
}],
start_time='asap',
end_time=end_date.isoformat().replace('+00:00', 'Z')
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Creation failed: {result.errors}")
print(f"Campaign created with {len(result.packages[0].creative_assignments)} creatives")
asyncio.run(create_with_creatives())
```
### Campaign with Reporting Webhook
Receive automated reporting notifications:
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/sdk';
// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);
const result = await testAgent.createMediaBuy({
brand: {
domain: 'acmecorp.com'
},
packages: [{
product_id: 'prod_d979b543',
pricing_option_id: 'cpm_usd_auction',
format_option_refs: [{ scope: 'product', format_option_id: 'display_300x250_image' }],
budget: 2500,
bidding: { bid_amount: 5.00 }
}],
start_time: 'asap',
end_time: endDate.toISOString(),
reporting_webhook: {
url: 'https://buyer.example.com/webhooks/reporting',
authentication: {
schemes: ['Bearer'],
credentials: 'secret_token_xyz_minimum_32_chars'
},
reporting_frequency: 'daily',
requested_metrics: ['impressions', 'spend', 'completed_views']
}
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}
if ('media_buy_id' in validated) {
console.log(`Campaign created - daily reports will be sent to webhook`);
}
```
```python Python test=false theme={null}
import asyncio
import time
from datetime import datetime, timedelta, timezone
from adcp.testing import test_agent
async def create_with_reporting():
# Calculate end date dynamically - 90 days from now
end_date = datetime.now(timezone.utc) + timedelta(days=90)
result = await test_agent.simple.create_media_buy(
brand={
'domain': 'acmecorp.com'
},
packages=[{
'product_id': 'prod_d979b543',
'pricing_option_id': 'cpm_usd_auction',
'format_kind': 'image',
'params': {'width': 300, 'height': 250},
'budget': 2500,
'bidding': {'bid_amount': 5.00}
}],
start_time='asap',
end_time=end_date.isoformat().replace('+00:00', 'Z'),
reporting_webhook={
'url': 'https://buyer.example.com/webhooks/reporting',
'authentication': {
'schemes': ['Bearer'],
'credentials': 'secret_token_xyz_minimum_32_chars'
},
'reporting_frequency': 'daily',
'requested_metrics': ['impressions', 'spend', 'completed_views']
}
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Creation failed: {result.errors}")
print('Campaign created - daily reports will be sent to webhook')
asyncio.run(create_with_reporting())
```
### Executing a Proposal
Execute a committed proposal finalized through [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) without manually constructing packages:
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { CreateMediaBuyResponseSchema } from '@adcp/sdk';
// Calculate end date dynamically - 90 days from now
const endDate = new Date();
endDate.setDate(endDate.getDate() + 90);
const result = await testAgent.createMediaBuy({
proposal_id: 'swiss_balanced_v1', // From refine_proposals action: "finalize"
total_budget: {
amount: 50000,
currency: 'USD'
},
brand: {
domain: 'acmecorp.com'
},
start_time: 'asap',
end_time: endDate.toISOString()
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = CreateMediaBuyResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Creation failed: ${JSON.stringify(validated.errors)}`);
}
if ('media_buy_id' in validated) {
// Publisher converted proposal allocations to packages
console.log(`Created media buy ${validated.media_buy_id}`);
console.log(`Packages created: ${validated.packages.length}`);
}
```
```python Python test=false theme={null}
import asyncio
import time
from datetime import datetime, timedelta, timezone
from adcp.testing import test_agent
async def execute_proposal():
# Calculate end date dynamically - 90 days from now
end_date = datetime.now(timezone.utc) + timedelta(days=90)
result = await test_agent.simple.create_media_buy(
proposal_id='swiss_balanced_v1', # From refine_proposals action: "finalize"
total_budget={
'amount': 50000,
'currency': 'USD'
},
brand={
'domain': 'acmecorp.com'
},
start_time='asap',
end_time=end_date.isoformat().replace('+00:00', 'Z')
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Creation failed: {result.errors}")
# Publisher converted proposal allocations to packages
print(f"Created media buy {result.media_buy_id}")
print(f"Packages created: {len(result.packages)}")
asyncio.run(execute_proposal())
```
When executing a proposal:
* For fixed allocation, the publisher converts exact allocation percentages to package budgets using `total_budget`
* For seller-optimized allocation, the publisher preserves the shared allocation goals and converts minimum/maximum percentage constraints to package targets/caps (a seller only issues those constraints, and allocation pacing, when it advertises the matching package-control capability)
* Allocation-level pacing becomes subordinate package pacing; aggregate proposal pacing becomes media-buy pacing
* Packages are created automatically based on the proposal's allocations
* All other fields (brand, start_time, end_time, etc.) work the same as manual mode
See [Proposals](/dist/docs/3.2.8/media-buy/product-discovery/media-products#proposals) for the complete workflow.
### Context for Correlation
The `context` field is an opaque object that sellers echo unchanged in responses and webhooks. Use it to map seller-assigned IDs back to your internal systems without needing to maintain a separate lookup table.
Context works at two levels:
* **Media buy level** — echoed in the `create_media_buy` response
* **Package level** — echoed in each package's response, webhooks, and read surfaces, useful for mapping `package_id` back to your internal line items. For explicit package requests, sellers MUST also echo `product_id`.
When targeting mixed seller populations, include package context such as `context.buyer_ref` as a legacy-safe fallback for older sellers that may not echo `product_id`.
**Mapping to internal campaign and line item IDs:**
```json test=false theme={null}
{
"brand": { "domain": "acmecorp.com" },
"context": {
"campaign_id": "camp-2026-q3-awareness",
"planner": "media-team-west",
"trace_id": "req-8f3a-4b2c"
},
"packages": [
{
"product_id": "prod_d979b543",
"pricing_option_id": "cpm_usd_auction",
"budget": 15000,
"bidding": { "bid_amount": 5.00 },
"context": {
"line_item_id": "li-001",
"flight": "june-awareness"
}
},
{
"product_id": "prod_e8fd6012",
"pricing_option_id": "cpm_usd_auction",
"budget": 10000,
"bidding": { "bid_amount": 4.50 },
"context": {
"line_item_id": "li-002",
"flight": "june-retargeting"
}
}
],
"start_time": "2026-06-01T00:00:00Z",
"end_time": "2026-08-31T23:59:59Z"
}
```
The seller's response echoes your context back alongside the seller-assigned IDs:
```json test=false theme={null}
{
"media_buy_id": "mb_12345",
"context": {
"campaign_id": "camp-2026-q3-awareness",
"planner": "media-team-west",
"trace_id": "req-8f3a-4b2c"
},
"packages": [
{
"package_id": "pkg_001",
"product_id": "prod_d979b543",
"context": {
"line_item_id": "li-001",
"flight": "june-awareness"
}
},
{
"package_id": "pkg_002",
"product_id": "prod_e8fd6012",
"context": {
"line_item_id": "li-002",
"flight": "june-retargeting"
}
}
]
}
```
Sellers must never parse or act on context data — it exists purely for the buyer's internal use.
## Error Handling
Common errors and resolutions:
| Error Code | Description | Resolution |
| - | - | - |
| [`PRODUCT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-not-found) | Invalid product_id | Verify product exists via [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) |
| [`PRODUCT_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-expired) | Configured product passed `expires_at` and remains recognizable to the seller | Re-run [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) and select a current configuration |
| [`PRODUCT_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-unavailable) | The product or a supported targeting selection has no current inventory | Re-run [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) with the concrete targeting values or choose another product; the seller does not silently substitute values or reprice |
| [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) | Canonical or legacy compatibility selector does not resolve or satisfy the product's closed accepted set | Re-author against the product's `format_options[]`, include required canonical parameters, or select a published `format_option_id`. |
| [`CONFLICTING_SELECTORS`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflicting-selectors) | Co-present, resolvable package format selector routes select different product format contracts | Emit one canonical selector route, or correct the required legacy projection so it selects the same contract under the canonical v2-narrows-v1 comparison. |
| [`BUDGET_TOO_LOW`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-budget-too-low) | Budget below product minimum | Increase budget or choose different product |
| [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) | Targeting constraints or a submitted `creative_id` violate seller/product business rules | Follow `error.field` and `error.message`; broaden targeting criteria or use a different package-scoped `creative_id` as indicated |
| [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) with `details.unmet_requirements[]` | A package does not bind an event source or catalog its product declares in the experimental `execution_requirements` | Bind the resource at `error.field` (`optimization_goals[].event_sources[]` or `catalogs[]`); for `reason: "not_found"`, register it through [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) or [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs) first. See [Product execution requirements](/dist/docs/3.2.8/media-buy/specification#product-execution-requirements-experimental) |
| [`POLICY_VIOLATION`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-policy-violation) | Brand/product violates policy | Review publisher's content policies |
| [`INVALID_PRICING_OPTION`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-pricing-option) | pricing_option_id not found | Use ID from product's `pricing_options` |
| [`CREATIVE_LOCALE_NOT_ACCEPTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-creative-locale-not-accepted) | An assigned library creative has no materialized locale variant accepted by an in-scope format option, or its `serve_default` points outside that option's eligible set | Read `format_options[].locale_policy`, supply a matching source/target variant, narrow placement scope, choose another option, or change the default policy |
Example error response:
```json theme={null}
{
"errors": [{
"code": "UNSUPPORTED_FEATURE",
"message": "Product 'prod_d979b543' does not accept image creatives at 728×90",
"field": "packages[0].params",
"details": { "supported_sizes": [{ "width": 300, "height": 250 }] }
}]
}
```
## Key Concepts
### Format Specification
Each package SHOULD specify the formats it will use via `format_option_refs[]` or a direct canonical selector (`format_kind` plus optional `params`). Omitting selectors defaults to all product options.
* Publish placeholder creatives in ad servers
* Pin exactly what creative assets are needed
* Validate that the product supports the requested formats
* Track which assets are missing
New 3.2 buyers author one canonical route: `format_option_refs[]`, or direct
`format_kind` with optional `params`. They MUST NOT combine those routes and
MUST NOT newly emit deprecated `format_ids[]`. Omitting all selectors defaults
to all product options; legacy-only `format_ids[]` remains valid throughout the
3.x compatibility window.
Receivers also accept multi-route requests from older 3.x peers, but precedence
is applied only after resolution and equivalence checking. The seller first
resolves every present route independently through the canonical mapping path.
An unresolved option reference or unprojectable legacy ID returns
[`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature)
before equivalence is evaluated. Once all routes resolve, the seller derives
the product `format_options[]` entries selected by each route using directional
product satisfaction and requires those sets to match. Legacy parameter
compatibility follows the asymmetric [v2 narrows v1](/dist/docs/3.2.8/creative/canonical-formats#narrows-formal-definition-normative)
relation rather than raw object equality. Equivalent routes use
`format_option_refs[]` as authoritative, then direct `format_kind`/`params`,
then `format_ids[]`. Any disagreement is rejected with
[`CONFLICTING_SELECTORS`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-conflicting-selectors);
a canonical selector never silently hides a conflicting legacy projection. For
fixed-size images, width and height travel together and both dimensions must
match in any permitted dual projection.
Before purchase, buyers SHOULD also inspect the selected declaration's optional
`locale_policy.accepted_language_ranges`. These seller ranges use RFC 4647
Basic Filtering and let the buyer determine whether a planned or existing
creative has at least one eligible materialized locale variant. A constrained
option is canonical-only and must use a format-options-aware canonical path:
`format_option_refs` when published or needed for disambiguation, otherwise
direct `format_kind` with satisfying `params`. Legacy `format_ids` cannot
preserve the policy. Media buys may be created
before creatives exist, so discovery prevents incompatible planning while hard
enforcement occurs when a creative is assigned. When one assignment can serve
across several placements, the creative must satisfy each effective placement
locale policy independently or the buyer must narrow its placement scope.
3.1+ format-option example (buyer authoring against a publisher-scoped `Product.format_options[]` entry):
```json test=false theme={null}
{
"packages": [
{
"product_id": "prod_d979b543",
"pricing_option_id": "cpm_usd_auction",
"format_option_refs": [
{
"scope": "publisher",
"publisher_domain": "daily-pulse.example",
"format_option_id": "daily_pulse_homepage_image"
}
],
"budget": 2500,
"bidding": { "bid_amount": 5.00 }
}
]
}
```
See [Format Workflow](#format-workflow) below for complete details.
### Brand reference
The `brand` field identifies the advertiser for policy compliance and business purposes.
```json theme={null}
{
"brand": {
"domain": "acmecorp.com"
}
}
```
Full brand identity data (colors, fonts, product catalog) is resolved from brand.json at execution time. See [brand.json](/dist/docs/3.2.8/brand-protocol/brand-json).
### Pricing & Currency
Each package specifies its `pricing_option_id`, which determines:
* Pricing model (CPM, CPCV, CPP, etc.)
* Rate and whether it's fixed or auction-based
The media buy has one currency. Every selected pricing option MUST declare that currency; the option does not introduce a package-specific denomination. Split products requiring another currency into a separate media buy. See [Pricing Models](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models).
### Budget & Pacing Controls
AdCP supports fixed package budgets and media-buy-level shared budgets. `budget_allocation.mode` makes the interpretation explicit; omission preserves the legacy fixed behavior.
> [!NOTE]
>
> **Choosing an allocation mode.** Omitting `budget_allocation` still means fixed allocation, but buyer agents SHOULD send it explicitly: `{"mode": "fixed"}` or a `seller_optimized` block. If the principal's instruction does not settle whether the budget is one shared pool across packages or split per package (for example, "spend \$100k across these two products"), the buyer agent SHOULD ask the principal rather than guess.
| Field | Level | Type | Controls |
| - | - | - | - |
| `total_budget.amount` + `total_budget.currency` | Media buy | TotalBudget | Hard aggregate lifetime spend cap. Required for proposals and seller-optimized allocation. |
| `budget_allocation` | Media buy | BudgetAllocation | `fixed` keeps package budgets independent; `seller_optimized` delegates cross-package allocation against shared goals. |
| `budget` | Package | number | Hard package spend cap. Required in fixed mode; optional ceiling in seller-optimized mode. |
| `min_spend_target` | Package | number | Soft minimum-spend target in seller-optimized mode. Not a guarantee. |
| `impressions` | Package | number | Impression goal for the package. An alternative volume target to `budget`; a seller may pace to whichever binds first. |
| `pacing` | Media buy | enum | How the seller spreads aggregate spend across the media-buy flight. |
| `packages[].pacing` | Package | enum | Subordinate temporal preference affecting which package receives the aggregate spend. |
| `daily_budget_cap` | Media buy | number | Optional hard aggregate ceiling per calendar day. It limits total buy spend without allocating that amount among packages. |
| `frequency_cap` | Media buy | MediaBuyFrequencyCap | Optional hard cap with one counter shared across participating packages. |
| `packages[].targeting_overlay.frequency_cap` | Package | FrequencyCap | Optional hard cap with an independent counter for that package. |
| `packages[].daily_budget_cap` | Package | number | Optional subordinate package ceiling per calendar day. It is not a reservation or current allocation. |
| `bidding` | Media buy or package | BiddingPolicy | Buyer execution policy. Media-buy is the inherited default; package is a complete override. |
| `bid_price` | Package | number | Deprecated legacy representation normalized to `bidding.bid_amount` or `bidding.max_bid`. |
| `start_time` / `end_time` | Package | string | The flight window the budget is spread across. When omitted, the package inherits the media buy's flight dates. |
**Pacing modes** (from [`/schemas/3.2.8/enums/pacing.json`](https://adcontextprotocol.org/schemas/3.2.8/enums/pacing.json)):
| Mode | Behavior |
| - | - |
| `even` | Allocate remaining budget evenly over the remaining flight (default). |
| `asap` | Spend remaining budget as quickly as possible. |
| `front_loaded` | Allocate more of the remaining budget earlier in the remaining flight. |
Example package with an even-paced budget over a fixed flight:
```json theme={null}
{
"product_id": "prod_ctv_sports",
"pricing_option_id": "po_cpm_fixed",
"budget": 50000,
"pacing": "even",
"start_time": "2099-08-01T00:00:00Z",
"end_time": "2099-08-31T23:59:59Z"
}
```
With `even` pacing over the 31-day flight above, the seller spreads the $50,000 budget across the month — roughly $1,613/day — subject to the seller's own pacing engine and available inventory.
#### Seller-optimized allocation
Seller-optimized allocation is a nested optimization:
1. Hard aggregate and package caps, flight windows, pauses, and policy restrictions always apply.
2. Media-buy pacing controls how much the buy spends over time.
3. Package pacing influences which eligible package receives that spend and MUST NOT cause aggregate delivery to exceed the media-buy pacing plan.
4. `budget_allocation.optimization_goals` choose allocation across packages; `packages[].optimization_goals` optimize delivery within one package.
5. Media-buy `bidding.cost_per`/`roas` bind to the primary cross-package allocation goal; package overrides bind to package goals and are allowed only when the provider can preserve their authored semantics under the shared strategy.
All package constraints and canonical bidding amounts in a seller-optimized buy use `total_budget.currency`, and every selected pricing option MUST declare that currency. This one-currency rule also applies to fixed AdCP-authored buys; packages requiring another denomination belong in a separate media buy. Every participating product MUST support the primary cross-package optimization goal. Sellers reject incompatible product combinations, currencies, pricing terms, or delivery constraints with [`TERMS_REJECTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-terms-rejected) or [`BIDDING_PLACEMENT_CONFLICT`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-bidding-placement-conflict) and identify the incompatible package.
Package caps may sum above the media-buy total; that headroom is what permits dynamic allocation. Minimum-spend targets must sum to no more than the total; sellers advertising `seller_optimized_min_spend_targets` MUST reject over-subscribed aggregate minimums with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) before any provider mutation, and sellers also advertising `seller_optimized_package_budgets` reject a `min_spend_target` above its own package `budget` the same way. If package caps cannot collectively spend the total, the seller rejects the request as infeasible.
Capability declarations in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) are layered. `media_buy.features.seller_optimized_budget: true` covers the core contract: the shared `total_budget`, seller allocation across packages, media-buy-level `pacing`, and allocation echo on read surfaces. Each package control in a seller-optimized buy has its own sub-capability, meaningful only alongside the parent:
| Package control | Sub-capability |
| - | - |
| `packages[].budget` (hard cap) | `seller_optimized_package_budgets` |
| `packages[].min_spend_target` | `seller_optimized_min_spend_targets` |
| `packages[].pacing` (when it differs from media-buy `pacing`) | `seller_optimized_package_pacing` |
Media-buy `pacing` is part of the core contract only for `even`. A seller declaring `seller_optimized_budget` MUST accept omitted `pacing` (which defaults to `even` when `total_budget` is present) and `pacing: "even"`. It MAY reject `asap` or `front_loaded` with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) (`error.field` set to `pacing`) before any provider mutation, and MUST NOT silently coerce them to `even`. Fixed-allocation pacing is unchanged.
A seller that declares the parent but not a given sub-capability MUST reject a seller-optimized request carrying that package control with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) before any over-subscription validation or provider mutation, and MUST NOT silently drop or coerce it. Over-subscription `INVALID_REQUEST` checks apply only to declared controls, so a core-only seller that receives an over-subscribed `min_spend_target` returns `UNSUPPORTED_FEATURE`.
Continuous allocation decisions inside an accepted seller-optimized buy are delivery behavior. They do not mutate package caps, increment the media-buy revision, create history entries, or constitute separate `reallocate_budget` actions.
```json theme={null}
{
"idempotency_key": "0c491eb7-fdf7-47de-b3c3-7284f2c56a41",
"account": { "account_id": "acc_performance_001" },
"brand": { "domain": "acmecorp.com" },
"total_budget": { "amount": 100000, "currency": "USD" },
"budget_allocation": {
"mode": "seller_optimized",
"optimization_goals": [
{
"kind": "event",
"event_sources": [
{ "event_source_id": "checkout_events", "event_type": "purchase" }
]
}
]
},
"pacing": "even",
"bidding": {
"cost_per": { "amount": 25, "strength": "cap" },
"max_bid": 8
},
"packages": [
{
"product_id": "prospecting",
"pricing_option_id": "cpm_auction",
"budget": 70000,
"min_spend_target": 20000
},
{
"product_id": "retargeting",
"pricing_option_id": "cpm_auction",
"budget": 60000,
"pacing": "front_loaded"
}
],
"start_time": "2099-08-01T00:00:00Z",
"end_time": "2099-08-31T23:59:59Z"
}
```
The package caps total $130,000, creating room for the seller to allocate the $100,000 shared total toward the better-performing package. The first package has a soft \$20,000 minimum-spend target; neither package has a reserved allocation. Because this request uses package caps, a minimum-spend target, and package pacing, the seller must advertise all three sub-capabilities. A seller that advertises only `seller_optimized_budget` accepts the same allocation with the package `budget`, `min_spend_target`, and `pacing` fields omitted.
#### Daily budget cap
An optional media-buy `daily_budget_cap` sets a hard ceiling on aggregate spend per calendar day without creating package allocations. Optional package `daily_budget_cap` values add subordinate per-package ceilings. In seller-optimized mode, package caps may be omitted so the seller can allocate the aggregate daily allowance dynamically; a package cap is always a ceiling, never a reservation.
Daily caps are **orthogonal to `pacing`**. The media-buy cap bounds aggregate daily spend, package caps bound individual package spend, and pacing governs distribution within those limits. `pacing: "asap"` plus a cap is valid. Every cap on one media buy uses its accepted `budget_cap_timezone`. Without a buyer override, `budget_capping.timezone_basis` selects either the account's operational timezone or the advertised feature-specific `fixed_timezone`; aggregate and package accounting then share that one boundary.
`daily_budget_cap` requires seller support: sellers advertise `media_buy.budget_capping` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities), including supported scopes and the default timezone basis. A cap is always hard. Sellers MUST reject an undeclared scope with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) rather than silently dropping or softening it, and echo accepted caps plus the resolved shared timezone on read surfaces.
When a seller does not support `daily_budget_cap`, approximate a daily rate with `pacing: "even"` and a `budget ÷ flight_days` calculation, or split a long flight into shorter packages each with its own `budget` — both are best-effort, not a guaranteed ceiling.
### Targeting Overlays
**Use sparingly** - most targeting should be in your brief and handled through product selection.
Use overlays only for:
* Geographic restrictions (RCT testing, regulatory compliance)
* Frequency capping
* AXE segment inclusion/exclusion (legacy — new integrations use [TMP](/dist/docs/3.2.8/trusted-match))
See [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) for details.
## Format Workflow
### Why Format Specification Matters
When creating a media buy, format specification enables:
1. **Placeholder Creation** - Publisher creates placeholders in ad server with correct specs
2. **Validation** - System validates products support requested formats
3. **Clear Expectations** - Both parties know exactly what's needed
4. **Progress Tracking** - Track which assets are missing vs. required
5. **Technical Setup** - Ad server configured before creatives arrive
### Complete Workflow
```
1. get_products → Find products and read canonical format_options[]
2. Validate compatibility → Ensure products support desired formats
3. create_media_buy → Specify formats via format_option_refs[] or
format_kind/params (direct canonical);
omit for all-formats default
└── Publisher creates placeholders
└── Response snapshots canonical requirements in packages[].formats_to_provide[]
4. Creative supply → Upload matching files via `sync_creatives` for library-backed sellers, or inline `packages[].creatives` for inline-only sellers
└── Poll get_media_buys; remaining coverage appears in packages[].formats_pending[]
5. Campaign activation → Replace placeholders with real creatives
```
### Format Validation
Publishers MUST validate:
* All formats are supported by the product
* Package selections match the product's canonical `format_options[]`
* Creative requirements can be fulfilled within timeline
Invalid canonical format-option example:
```json theme={null}
{
"errors": [{
"code": "UNSUPPORTED_FEATURE",
"message": "Product 'ctv_sports_premium' has no format_options[] entry for format option 'audio_standard'",
"field": "packages[0].format_option_refs[0]",
"supported_format_option_refs": [
{ "scope": "publisher", "publisher_domain": "streamhaus.example", "format_option_id": "ctv_video_30s_premium" },
{ "scope": "publisher", "publisher_domain": "streamhaus.example", "format_option_id": "ctv_video_15s_premium" }
]
}]
}
```
### Flight date validation
For new media buys, the top-level `start_time` MUST be either `"asap"` or a
date-time that is not in the past. A past concrete `start_time` MUST return an
[`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) error.
When a package specifies `start_time` or `end_time`, sellers SHOULD validate that:
* Both dates fall within the media buy's date range
* `start_time` is before `end_time`
Out-of-range or inverted dates SHOULD return an `INVALID_REQUEST` error:
```json theme={null}
{
"errors": [{
"code": "INVALID_REQUEST",
"message": "Package 'week_5' end_time 2026-04-05T23:59:59Z is after media buy end_time 2026-03-31T23:59:59Z",
"field": "packages[3].end_time"
}]
}
```
## Asynchronous Operations
This task can complete instantly or take days depending on complexity and approval requirements. The response includes a `status` field that tells you what happened and what to do next.
| Status | Meaning | Your Action |
| - | - | - |
| `completed` | Done immediately | Process the result |
| `working` | Processing (\~2 min) | Poll frequently or wait for webhook |
| `submitted` | Long-running (hours/days) | Use webhooks or poll infrequently |
| `input-required` | Needs your input | Read message, respond with info |
| `failed` | Error occurred | Handle the error |
**Note:** For the complete status list see [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle).
> [tab] MCP
>
> ### Immediate Success (`completed`)
>
> The task completed synchronously. No async handling needed.
>
> **Request:**
>
> ```javascript test=false theme={null}
> const response = await session.call('create_media_buy', {
> brand: { domain: 'acmecorp.com' },
> packages: [
> {
> product_id: 'prod_ctv_sports',
> pricing_option_id: 'cpm_fixed',
> budget: 50000
> }
> ]
> });
> ```
>
> **Response:**
>
> ```json theme={null}
> {
> "status": "completed",
> "media_buy_id": "mb_12345",
> "account": {
> "account_id": "acc_acme_direct",
> "name": "Acme",
> "status": "active",
> "brand": { "domain": "acmecorp.com" },
> "operator": "acmecorp.com"
> },
> "media_buy_status": "active",
> "confirmed_at": "2025-06-01T10:00:00Z",
> "creative_deadline": "2025-06-15T23:59:59Z",
> "revision": 1,
> "packages": [
> {
> "package_id": "pkg_001",
> "product_id": "prod_ctv_sports"
> }
> ]
> }
> ```
>
> The top-level `status` is the envelope task-status (TaskStatus) — `completed` on synchronous success. The body-level `media_buy_status` carries the buy's lifecycle state (`pending_creatives`, `pending_start`, `active`, or `paused`). The AdCP 3.2 source schema no longer permits the legacy top-level `status: MediaBuyStatus` form; see [Media-buy status field migration](#media-buy-status-field-migration) below.
>
> ### Long-Running (`submitted`)
>
> The task is queued for manual approval. Configure a webhook to receive updates.
>
> **Request with webhook:**
>
> ```javascript test=false theme={null}
> const response = await session.call('create_media_buy',
> {
> brand: { domain: 'acmecorp.com' },
> packages: [
> {
> product_id: 'prod_premium_ctv',
> pricing_option_id: 'cpm_fixed',
> budget: 500000 // Large budget triggers approval
> }
> ]
> },
> {
> pushNotificationConfig: {
> url: 'https://your-app.com/webhooks/adcp',
> authentication: {
> schemes: ['bearer'],
> credentials: 'your_webhook_secret'
> }
> }
> }
> );
> ```
>
> **Initial response:**
>
> ```json theme={null}
> {
> "status": "submitted",
> "task_id": "task_abc123",
> "message": "Budget exceeds auto-approval limit. Sales review required (2-4 hours)."
> }
> ```
>
> **Webhook POST when approved:**
>
> ```json theme={null}
> {
> "task_id": "task_abc123",
> "task_type": "create_media_buy",
> "status": "completed",
> "timestamp": "2025-01-22T14:30:00Z",
> "message": "Media buy approved and created",
> "result": {
> "media_buy_id": "mb_67890",
> "account": {
> "account_id": "acc_acme_direct",
> "name": "Acme",
> "status": "active",
> "brand": { "domain": "acmecorp.com" },
> "operator": "acmecorp.com"
> },
> "confirmed_at": "2025-01-22T14:30:00Z",
> "creative_deadline": "2025-06-20T23:59:59Z",
> "revision": 1,
> "packages": [
> {
> "package_id": "pkg_002",
> }
> ]
> }
> }
> ```
>
> ### Error (`failed`)
>
> **Response:**
>
> ```json theme={null}
> {
> "status": "failed",
> "errors": [
> {
> "code": "INSUFFICIENT_INVENTORY",
> "message": "Requested targeting yields no available impressions",
> "field": "packages[0].targeting",
> "suggestion": "Expand geographic targeting or increase CPM bid"
> }
> ]
> }
> ```
> [tab] A2A
>
> ### Immediate Success (`completed`)
>
> **Request:**
>
> ```javascript test=false theme={null}
> const response = await a2a.send({
> message: {
> messageId: crypto.randomUUID(),
> role: 'ROLE_USER',
> parts: [{
> data: {
> skill: 'create_media_buy',
> input: {
> idempotency_key: '550e8400-e29b-41d4-a716-446655440010',
> account: { account_id: 'acc_demo_001' },
> brand: { domain: 'brand.example' },
> proposal_id: 'proposal_001',
> total_budget: { amount: 100000, currency: 'USD' },
> start_time: 'asap',
> end_time: '2027-06-30T23:59:59Z'
> }
> }
> }]
> }
> });
> ```
>
> **Response:**
>
> ```json theme={null}
> {
> "task": {
> "id": "task_123",
> "contextId": "ctx_456",
> "status": { "state": "TASK_STATE_COMPLETED" },
> "artifacts": [{
> "artifactId": "media-buy-result",
> "parts": [
> { "text": "Media buy created successfully" },
> {
> "data": {
> "status": "completed",
> "media_buy_id": "mb_12345",
> "confirmed_at": "2025-06-01T10:00:00Z",
> "creative_deadline": "2025-06-15T23:59:59Z",
> "revision": 1,
> "packages": [{ "package_id": "pkg_001" }]
> }
> }
> ]
> }]
> }
> }
> ```
>
> ### Processing (`working`)
>
> To receive transport progress while the AdCP handler is running, use A2A 1.0
> `SendStreamingMessage` or `SubscribeToTask` and consume `StreamResponse` SSE
> frames. The non-streaming helper shown here uses ordinary `SendMessage`, which
> waits for a terminal or interrupted A2A state unless
> `configuration.returnImmediately` is explicitly enabled.
>
> ### Long-Running AdCP Operation (`submitted`)
>
> **Profile request:**
>
> ```javascript test=false theme={null}
> const response = await a2a.send({
> message: {
> messageId: crypto.randomUUID(),
> role: 'ROLE_USER',
> parts: [{
> data: {
> skill: 'create_media_buy',
> input: {
> idempotency_key: '550e8400-e29b-41d4-a716-446655440011',
> account: { account_id: 'acc_demo_001' },
> brand: { domain: 'brand.example' },
> proposal_id: 'proposal_requires_approval_001',
> total_budget: { amount: 500000, currency: 'USD' },
> start_time: 'asap',
> end_time: '2027-06-30T23:59:59Z'
> }
> }
> }]
> }
> });
> ```
>
> **Completed A2A invocation containing the AdCP Submitted response:**
>
> ```json theme={null}
> {
> "task": {
> "id": "a2a-task-abc",
> "contextId": "ctx_456",
> "status": { "state": "TASK_STATE_COMPLETED" },
> "artifacts": [{
> "artifactId": "adcp-result",
> "parts": [{
> "data": {
> "status": "submitted",
> "task_id": "adcp-task-abc",
> "message": "Awaiting budget approval"
> }
> }]
> }]
> }
> }
> ```
>
> Poll the durable operation with a new activated invocation of [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) using `adcp-task-abc`. Do not poll `a2a-task-abc`; that A2A transport invocation is already complete. The AdCP handle is not duplicated in artifact metadata.
>
> ### Input Required (`input-required`)
>
> Task is paused waiting for clarification or approval.
>
> **Response:**
>
> ```json theme={null}
> {
> "task": {
> "id": "task_def",
> "contextId": "ctx_456",
> "status": {
> "state": "TASK_STATE_INPUT_REQUIRED",
> "message": {
> "messageId": "msg-approval-001",
> "taskId": "task_def",
> "contextId": "ctx_456",
> "role": "ROLE_AGENT",
> "parts": [
> { "text": "The requested budget exceeds your pre-approved limit. Please confirm you want to proceed with $500K spend." },
> { "data": { "reason": "APPROVAL_REQUIRED" } }
> ]
> }
> }
> }
> }
> ```
>
> **Follow-up to approve:**
>
> ```javascript test=false theme={null}
> await a2a.send({
> message: {
> messageId: crypto.randomUUID(),
> taskId: 'task_def',
> contextId: 'ctx_456',
> role: 'ROLE_USER',
> parts: [{
> data: {
> skill: 'create_media_buy',
> input: {
> idempotency_key: '550e8400-e29b-41d4-a716-446655440011',
> account: { account_id: 'acc_demo_001' },
> brand: { domain: 'brand.example' },
> proposal_id: 'proposal_requires_approval_001',
> total_budget: { amount: 500000, currency: 'USD' },
> start_time: 'asap',
> end_time: '2027-06-30T23:59:59Z',
> ext: { 'buyer.example': { approval_confirmed: true } }
> }
> }
> }]
> }
> });
> ```
>
> ### Error (`failed`)
>
> **Response:**
>
> ```json theme={null}
> {
> "task": {
> "id": "task_xyz",
> "contextId": "ctx_456",
> "status": { "state": "TASK_STATE_FAILED" },
> "artifacts": [{
> "artifactId": "adcp-error",
> "parts": [
> { "text": "Failed to create media buy" },
> {
> "data": {
> "adcp_error": {
> "code": "INSUFFICIENT_INVENTORY",
> "message": "Requested targeting yields no available impressions",
> "suggestion": "Expand geographic targeting"
> }
> }
> }
> ]
> }]
> }
> }
> ```
For complete async handling patterns, see [Async Operations](/dist/docs/3.2.8/building/by-layer/L3/async-operations).
## Usage Notes
* Total budget is distributed across packages based on individual `budget` values
* Creative assets must be uploaded before deadline for campaign activation
* Impression-time targeting (audience, frequency, suitability) is handled by [TMP](/dist/docs/3.2.8/trusted-match)
* Pending states (`working`, `submitted`) are normal, not errors
* Orchestrators MUST handle pending states as part of normal workflow
* **Inline creatives**: The `creatives` array creates or supplies package creatives inline. If the seller advertises `creative.has_creative_library: true`, inline creatives enter the library; use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) to update existing library creatives and `creative_assignments` to assign existing library creatives. If the seller advertises `inline_creative_management: true` without a creative library, use `packages[].creatives` on `create_media_buy` and [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy); do not call `sync_creatives`.
* **Inline validation and review**: Library-backed inline creatives enter the library with the same review lifecycle as `sync_creatives` uploads, while inline-only sellers may keep them package-scoped. Invalid request-time creative or assignment input fails the whole atomic create. Once valid input is committed, later policy review is independent: rejection does not undo the buy, and sellers MUST NOT skip review solely because the buy did not activate. Retention of unassigned library creatives is seller-defined in 3.0. See [Inline creatives on the package](/dist/docs/3.2.8/creative/creative-libraries#path-2-inline-creatives-on-the-package).
## Content Standards
When a media buy includes content standards (via the `governance.content_standards` field on [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) responses or the media buy request), the buyer is requesting brand suitability enforcement during delivery.
> [!NOTE]
>
> Content standards are created by calling [`create_content_standards`](/dist/docs/3.2.8/governance/content-standards/tasks/create_content_standards) on a verification agent (e.g., IAS, DoubleVerify). Standards MUST be [calibrated](/dist/docs/3.2.8/governance/content-standards/tasks/calibrate_content) with each seller before use in production to ensure the seller's local evaluation model aligns with the verification agent's interpretation. See the [Content Standards overview](/dist/docs/3.2.8/governance/content-standards/index) for the full setup workflow: create → calibrate → activate → validate.
## Policy Compliance
Brand and products are validated during creation. Policy violations return errors:
```json theme={null}
{
"errors": [{
"code": "POLICY_VIOLATION",
"message": "Brand or product category not permitted on this publisher",
"field": "brand",
"suggestion": "Contact publisher for category approval process"
}]
}
```
Publishers should ensure:
* Brand/products align with selected packages
* Creatives match declared brand/products
* Campaign complies with all advertising policies
## Next Steps
After creating a media buy:
1. **Supply creatives**: Use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) for library-backed sellers, or `packages[].creatives` on [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) for inline-only sellers
2. **Monitor Status**: Use [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)
3. **Optimize**: Use [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback)
4. **Update**: Use [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) to modify campaign
## Media-buy status field migration
3.1 split two enums that 3.0 collided at the same root key — envelope `status` (TaskStatus) at the top of every response, and body `media_buy_status` (MediaBuyStatus, **new in 3.1**) carrying the buy's lifecycle state alongside. The legacy top-level `status: MediaBuyStatus` form was `deprecated: true` only in the 3.1 schema and is removed from the 3.2 source schema ([#4906](https://github.com/adcontextprotocol/adcp/issues/4906)); nested `status` on [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys), [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery), and `core/media-buy.json` follow in 4.0 ([#4905](https://github.com/adcontextprotocol/adcp/issues/4905)).
During the 3.1 migration window, buyers MUST prefer `media_buy_status` when present. The 3.1 compliance storyboards assert `path: "media_buy_status"` — a 3.1 seller emitting only the legacy `status` is schema-valid but fails certification. In 3.2, sellers MUST stop emitting the legacy lifecycle value; root `status` is reserved for TaskStatus.
Full migration: [Migration › `media_buy_status`](/dist/docs/3.2.8/reference/migration/media-buy-status).
## Learn More
* [Media Buy Lifecycle](/dist/docs/3.2.8/media-buy/media-buys/) - Complete campaign workflow
* [get_products](/dist/docs/3.2.8/media-buy/task-reference/get_products) - Discover inventory
* [Targeting](/dist/docs/3.2.8/media-buy/advanced-topics/targeting) - Targeting strategies
* [Pricing Models](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models) - Currency and pricing
# decline_proposals
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/decline_proposals
Terminally decline one or more immutable proposals.
`decline_proposals` records that the buyer evaluated one or more proposals and will not pursue them. The operation is terminal: a seller must reject later [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals), canonical [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal), or new logical calls through the deprecated 3.x [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) compatibility facade for a declined proposal with [`INVALID_STATE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-state). Exact retries of an earlier successful call still follow the shared idempotency replay contract. A proposal that was already executed cannot subsequently be declined and returns `unable`.
**Request schema:** [`/schemas/3.2.1/media-buy/decline-proposals-request.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/decline-proposals-request.json)
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441004",
"declines": [
{
"proposal_id": "proposal_123",
"reason": "inventory_fit",
"detail": "The available placement mix does not fit this campaign."
}
],
"opportunity": {
"opportunity_id": "opp_spring_launch_2027",
"status": "closed",
"close_reason": "not_pursued"
}
}
```
Each result has an explicit `declined` or `unable` outcome and preserves request order. Retrying with the same idempotency key replays the original response. Declining the same proposal again under a new key also returns `declined` while preserving the first recorded reason and detail, making the terminal state semantically idempotent.
When `opportunity` is present, every proposal must belong to its `opportunity_id`. Proposal outcomes are independent, but the opportunity update is applied only if every result is `declined`; any `unable` result leaves the opportunity unchanged.
The request does not carry `proposal_version`. Each `proposal_id` identifies one immutable commercial snapshot; [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) mints a new ID whenever terms change.
# get_media_buy_delivery
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery
get_media_buy_delivery task — retrieve impressions, spend, pacing, and dimensional breakdowns for active AdCP campaigns. Supports custom date ranges and metric filtering.
Retrieve comprehensive delivery metrics and performance data for media buy reporting.
**Request schema:** [`get-media-buy-delivery-request.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/get-media-buy-delivery-request.json)
**Response schema:** [`get-media-buy-delivery-response.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/get-media-buy-delivery-response.json)
**Response Time**: \~60 seconds (reporting query)
## Scope
`get_media_buy_delivery` works on any `media_buy_id` returned by [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys), regardless of how the underlying campaign was created. Sales agents MUST NOT refuse delivery reporting — or narrow its coverage — on the basis that the buy originated outside AdCP. If delivery data for a buy is genuinely unavailable (e.g., the ad server has not yet reported a flight), the seller returns the buy in `media_buy_deliveries` with zero or partial metrics; the seller does not omit it and does not return [`MEDIA_BUY_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-media-buy-not-found) for an account-owned buy.
## Exact Reliable Reporting revision read
Reliable Reporting (AdCP 3.2) adds the mutually exclusive `reporting_revision_id`
selector. It returns the immutable content for exactly that revision,
not a newly calculated date-range result. The response carries the full
`reporting_revision` metadata, authoritative `reporting_rows`, and
`reporting_revision_binding` with the same revision ID, row count, control totals,
and the committed `revision_content_sha256` over the JCS binding object. Consumers verify those fields before
using the content as reporting evidence. Existing `media_buy_ids` and date-range
calls remain unchanged. A zero-row revision returns an empty `media_buy_deliveries`
array with `row_count: 0`, proving that no rows is a published result rather than a
missing report.
Exact reads are cursor-paginated: every page repeats identical `reporting_revision`,
`reporting_revision_binding`, and `pagination.total_count`, which equals the
revision row count. Consumers MUST exhaust the cursor, concatenate `reporting_rows`
in returned order, then compute SHA-256 of RFC 8785/JCS
`{ reporting_revision_id, row_count, control_totals, reporting_rows }`. Hashing one
page is not verification. `pagination` is available only with
`reporting_revision_id`; exact mode rejects every other delivery/filter selector.
When `account` is omitted, the seller searches all accounts accessible to the
authenticated caller. Unknown and unauthorized revision/account combinations return
the same nondisclosing [`REFERENCE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-reference-not-found) result.
A revision the seller still owes within `status_retention_days` but cannot currently
serve or verify — for example, its stored rows are missing or fail the binding —
returns [`SERVICE_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-service-unavailable)
to an authorized caller, never `REFERENCE_NOT_FOUND`, and
[`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status) reports
a `REVISION_UNREADABLE` issue for each affected obligation.
**Request Schema**: [`/schemas/3.2.8/media-buy/get-media-buy-delivery-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buy-delivery-request.json)
**Response Schema**: [`/schemas/3.2.8/media-buy/get-media-buy-delivery-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buy-delivery-response.json)
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | [account-ref](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) | No | Account reference. Pass `{ "account_id": "..." }` or `{ "brand": {...}, "operator": "..." }` if the seller supports implicit resolution. Only returns media buys belonging to this account. When omitted, returns data across all accessible accounts. |
| `media_buy_ids` | string\[] | No\* | Array of media buy IDs to retrieve |
| `status_filter` | string \| string\[] | No | Status filter: `"pending_creatives"`, `"pending_start"`, `"active"`, `"paused"`, `"completed"`. Defaults to `["active"]` when omitted. |
| `start_date` | string | No | Report start date (YYYY-MM-DD), inclusive, as a calendar date in the product's reporting timezone (`reporting_capabilities.timezone`). Omit for campaign lifetime data. Only accepted when product supports `date_range`. |
| `end_date` | string | No | Report end date (YYYY-MM-DD), **exclusive**, in the same reporting timezone as `start_date`. Omit for campaign lifetime data. Only accepted when product supports `date_range`. |
| `reporting_dimensions` | object | No | Request dimensional breakdowns within `by_package`. Include a key as an empty object (e.g., `"device_type": {}`) to activate with defaults. Keys: `geo`, `device_type`, `device_platform`, `format`, `audience`, `demographic`, `placement`, `property`, `collection`, `installment`, `collection_property`, `installment_property`, `placement_property`, `spot`, `creative`, `keyword`, `catalog_item`. Most accept optional `limit`, `sort_by`, and `sort_direction`. `format` groups rows by canonical `format_kind`, not duration or other format-option parameters. Demographic also accepts canonical `age_ranges`, each of which must match the product's independent demographic reporting capability exactly. `spot` accepts only `limit`, returns rows by `aired_at` ascending, and defaults to the complete log for the reporting period. Geo requires `geo_level`; include `system` for metro/postal levels. `creative`, `keyword`, and `catalog_item` are returned automatically when the seller supports them, even when omitted from this object — including one of their keys is optional and upgrades that breakdown to a negotiated contract (`limit`, `sort_by`, `sort_direction`, and a binding truncation/sort-echo disclosure) without changing the automatic default. Unsupported dimensions are silently omitted. When a requested dimension is supported, the seller returns its array (possibly empty) and truncation flag. Metric-sorted dimensions also return applied-sort echoes; demographic and property-grain arrays also return suppression flags. Spot has no sort echoes. Unsupported requested demographic ranges return [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature); malformed requests return a validation error. |
| `time_granularity` | string | No | Per-window slice granularity for pull recovery, matching `reporting_webhook.reporting_frequency` vocabulary (`hourly`, `daily`, `weekly`, `monthly`, `quarterly`, `post_campaign`). When set, the response includes `windows[]` slices shape-aligned with webhook fires at the same granularity. Capability-scoped — value MUST be in the product's `reporting_capabilities.windowed_pull_granularities`. See [Windowed pull recovery](#windowed-pull-recovery). |
| `include_window_breakdown` | boolean | No | When `true` (and `time_granularity` is set), include the `windows[]` array on each media buy. Defaults to `false`. Ignored when `time_granularity` is omitted. |
| `requested_metrics` | string\[] | No | Narrow the response to a subset of metrics — same semantics as `reporting_webhook.requested_metrics`. Applies to `totals`, `by_package`, daily/window slices, and breakdown rows. When omitted, all available metrics are included (unchanged behavior). See [Requesting a metric subset](#requesting-a-metric-subset). |
> **Date Range Behavior**: The date range is **start-inclusive, end-exclusive**, in the reporting timezone. For example, `start_date: "2026-01-01"` and `end_date: "2026-01-02"` returns delivery data for January 1st only (from `2026-01-01 00:00:00` up to, but not including, `2026-01-02 00:00:00` reporting-timezone time). To get a full week of data (Jan 1-7), use `end_date: "2026-01-08"`.
### Deterministic filter contract
`media_buy_ids` and accepted date bounds MUST observably scope the response.
Every `media_buy_deliveries[]` row MUST have a `media_buy_id` in
`media_buy_ids` when that filter is present. A seller MUST NOT accept the filter
and return delivery rows for other buys.
Dates are calendar dates in the **reporting timezone**: the
`reporting_capabilities.timezone` of the products behind the in-scope packages.
It may equal `Account.timezone`, but buyers do not infer that. When the
reporting timezone is `UTC`, the dates are UTC days.
For an accepted `start_date` and `end_date`, `reporting_period.start` and
`reporting_period.end` MUST be the instants at which those dates begin in the
reporting timezone. All aggregates, per-buy totals, daily rows, and requested
window slices MUST be computed only from delivery in that start-inclusive,
end-exclusive interval. Delivery outside that interval MUST NOT contribute to
the response. The boundaries stay RFC 3339 instants. For a product reporting in
`America/New_York`, `start_date: "2026-04-15"` begins at
`2026-04-15T00:00:00-04:00`, which can also be written as
`2026-04-15T04:00:00Z`. Sellers SHOULD echo the reporting timezone in
`reporting_period.timezone`. `daily_breakdown[].date` labels and daily, weekly,
monthly, and quarterly `windows[]` use the same timezone. A reporting-timezone day can be 23
or 25 hours long across a DST change.
A date-bounded request covers one reporting timezone. When its in-scope packages
span products with different reporting timezones, the seller MUST reject it with
[`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error)
rather than pick a timezone. The buyer narrows `media_buy_ids` to buys that
share one reporting timezone, or omits both dates. There is no package filter,
so a single buy whose own packages span reporting timezones can only be read
without dates. Two additional constraints apply to lifetime reads when packages
span multiple reporting timezones:
* **Buy-level `daily_breakdown`**: Sellers MUST omit this aggregate breakdown when the media buy's packages span more than one reporting timezone. Package-level `daily_breakdown` remains, each in its own product's reporting timezone.
* **`time_granularity` of `daily`, `weekly`, `monthly` or `quarterly`**: Sellers MUST reject with [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) when the in-scope packages span more than one reporting timezone. The buyer narrows `media_buy_ids` to buys sharing one reporting timezone.
Exact
`reporting_revision_id` reads return the revision's own period, whose
`source_timezone` names its calendar.
A filtered request can legitimately return the same rows and values as a less
restrictive request when all underlying delivery already matches. Conformance is
therefore established from returned membership, status, and date boundaries—not
by requiring two response payloads to differ.
**Date Range Examples**:
| start_date | end_date | Data Returned |
| - | - | - |
| `2026-01-01` | `2026-01-02` | January 1st only (1 day) |
| `2026-01-01` | `2026-01-08` | January 1st through 7th (7 days) |
| `2026-01-01` | `2026-02-01` | Full month of January (31 days) |
| `2026-01-15` | `2026-01-16` | January 15th only (1 day) |
\*`media_buy_ids` filters results to specific media buys. If neither provided, returns all media buys in current session context.
## Response
Returns delivery data as per-media-buy rows:
| Field | Description |
| - | - |
| `reporting_period` | Half-open report period: `start`/`end` instants on reporting-timezone day boundaries, plus `timezone`, the reporting timezone applied (sellers SHOULD return it; exact-revision reads carry the revision's `source_timezone` instead) |
| `currency` | **Deprecated in 3.2; removed in 4.0.** Optional legacy response-wide currency for reports whose monetary values all share one denomination. Do not treat it as an aggregation currency. Prefer row or package currency. |
| `attribution_window` | Attribution methodology: `post_click` and `post_view` (duration objects), and `model` (last_touch, first_touch, linear, time_decay, data_driven) |
| `aggregated_totals` | **Deprecated in 3.2; removed in 4.0.** Legacy cross-buy aggregate. When present, the deprecated response-wide `currency` is required and denominates its spend. Optional `reach_aggregation` distinguishes cross-buy deduplicated reach from a sum of constituent reach values. Sellers should omit this aggregate and buyers should calculate only aggregates whose row currencies and metric semantics are compatible. |
| `media_buy_deliveries` | Array of delivery data per media buy |
### Media Buy Delivery Object
> [!NOTE]
>
> **3.1 vocabulary note.** `get_media_buy_delivery` returns the lifecycle state on a nested `media_buy_deliveries[].status` field (no envelope collision — nested at depth 1). [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) success responses return the same lifecycle state on a top-level **`media_buy_status`** field (added in 3.1 to avoid colliding with the envelope task-status `status`). Same enum, two field names in 3.1 — the cascade unifies in 4.0 ([#4905](https://github.com/adcontextprotocol/adcp/issues/4905)). See [Migration › `media_buy_status`](/dist/docs/3.2.8/reference/migration/media-buy-status) for the full picture.
| Field | Description |
| - | - |
| `media_buy_id` | Media buy identifier |
| `currency` | ISO 4217 denomination for monetary values in this row. Sellers SHOULD populate it when the row has one currency. Every package currency in an AdCP-authored buy MUST match it. Legacy or external mixed-currency buys omit it and report monetary values only at package level. |
| `status` | Current status (`pending_creatives`, `pending_start`, `active`, `paused`, `completed`). In webhook context, may also be `reporting_delayed` or `failed`. Maps to `media_buy_status` on `create_media_buy` / `update_media_buy` success responses (3.1 vocabulary note above). |
| `totals` | Metrics aggregated within this media buy. Legacy or external mixed-currency buys omit monetary totals such as `spend`. |
| `by_package` | Package-level breakdowns with delivery_status, paused state, and pacing_index |
| `daily_breakdown` | Day-by-day delivery for single-currency rows, one row per calendar date in the reporting timezone. Omitted for legacy/external mixed-currency buys because daily rows have no package currency grain. |
See the pinned [3.2.1 schema](https://adcontextprotocol.org/schemas/3.2.1/media-buy/get-media-buy-delivery-response.json) for the released field list, including exact-revision reads.
### Final vs provisional numbers
A delivery row is either **final for its measurement window** or it isn't. Final means the seller considers these numbers closed for the period — no further revision — and is willing to invoice on them, subject to whatever `measurement_terms.billing_measurement` the buy was created with. Anything else is provisional: still settling as measurement matures (broadcast C3 → C7 DVR accumulation, post-IVT scrubbing, conversion dedup) and **not** an invoicing source of truth.
Per-row signals:
* `media_buy_deliveries[*].is_final` and `media_buy_deliveries[*].finalized_at` — row-level finality, true iff every package in the row is final for the same measurement window.
* `media_buy_deliveries[*].by_package[*].is_final` and `.finalized_at` — package-level finality with the exact timestamp.
* `media_buy_deliveries[*].by_package[*].measurement_window` — which maturation stage the numbers represent (`c3`, `c7`, `post_sivt`, `downloads_30d`, …).
Callers using rows where `is_final` is false (or absent) for pacing and reporting are safe; callers using them for reconciliation, accruals, or finance close are not.
### Who is authoritative for billing
Whose number invoices the buy is a **contract term**, declared in the buy's [`measurement_terms.billing_measurement`](/dist/docs/3.2.8/media-buy/advanced-topics/billing-authority):
* **Seller-attested** (the default when `billing_measurement` is absent or names the seller's own ad server): invoice off final rows on `get_media_buy_delivery`.
* **Vendor-attested** (third-party measurement vendor named in the buy — e.g., Nielsen, IAS, DV, MOAT): invoice off the named vendor's authoritative numbers. Operationally this is most often the seller pulling from the vendor and publishing on `get_media_buy_delivery` with `is_final: true`; when the buyer holds the vendor relationship instead, the buyer pushes via [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage) with `final: true` and `finalized_at` set.
* **Buyer-attested** (buyer's 3PAS or MMP named in the buy — e.g., CM360, Flashtalking): invoice off the buyer's final records pushed via `report_usage`.
When the authoritative party doesn't publish final numbers within `measurement_terms.billing_measurement.finalization_deadline_hours`, the counterparty MAY fall back to its own attestation; the breach is handled under `makegood_policy`. The deadline applies symmetrically to whichever party is named in `vendor`. When variance between parties exceeds `max_variance_percent`, parties resolve via the buy's [`makegood_policy.available_remedies`](/dist/docs/3.2.8/media-buy/advanced-topics/accountability) and out-of-band negotiation.
See [Billing authority](/dist/docs/3.2.8/media-buy/advanced-topics/billing-authority) for the end-to-end flow. A structured dispute task — opening, transitioning, and resolving a delivery dispute on the wire — is targeted for AdCP 3.2.
### Currency and cross-buy aggregation
The response-wide `currency` and `aggregated_totals` fields are deprecated in AdCP 3.2 and removed in 4.0. When legacy `aggregated_totals` is present, the response-wide currency is required solely to denominate its spend. One response can contain media buys in different currencies, and AdCP does not define exchange rates, conversion timestamps, or an FX authority. The response-wide currency therefore MUST NOT otherwise be interpreted as an aggregation currency or as evidence that the seller converted package spend.
Sellers SHOULD populate `media_buy_deliveries[].currency` whenever a row has one denomination. It denominates that row's monetary `totals` and every package monetary value. For an AdCP-authored buy, every `by_package[].currency` MUST equal the row currency and the media-buy currency. For a legacy or externally created mixed-currency buy, sellers omit row currency, `daily_breakdown`, and all monetary or money-derived values from row and window totals. They report those values only on package rows (including window package rows) with each package's own currency.
Consumers that encounter a row without currency must process each package amount with that package's currency; they must not silently drop those amounts or synthesize a row total:
```javascript test=false theme={null}
if (!delivery.currency) {
for (const pkg of delivery.by_package) {
console.log(`${pkg.package_id}: ${pkg.spend.toFixed(2)} ${pkg.currency}`);
}
}
```
Buyers that need cross-buy totals calculate them from `media_buy_deliveries[]`. They MUST first verify that currencies, metric qualifiers, measurement windows, finality, and deduplication semantics are compatible. Counts such as impressions are not automatically safe to add merely because they are non-monetary; reach may be deduplicated differently, and rates require their component-weighted calculation rather than summing or averaging row values.
For the deprecated `aggregated_totals.reach` field, sellers producing AdCP 3.2 payloads SHOULD include `reach_aggregation` whenever aggregate reach is present. `reach_aggregation: "deduplicated"` means the seller deduplicated uniques across every included media buy. `reach_aggregation: "sum_of_constituent_reach"` means the seller added the independently unique reach values from each buy, so the same reach unit may be counted more than once. Sellers MUST omit aggregate `frequency` for `sum_of_constituent_reach`. Legacy payloads without `reach_aggregation` remain valid, but their aggregation semantics are unknown; consumers MUST NOT use that reach as a frequency denominator.
## Common Scenarios
### Single Media Buy
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuyDeliveryResponseSchema } from '@adcp/sdk';
// Get single media buy delivery report
const result = await testAgent.getMediaBuyDelivery({
media_buy_ids: ['mb_12345'],
start_date: '2024-02-01',
end_date: '2024-02-07'
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);
// Check for errors (discriminated union response)
if ('errors' in validated && validated.errors) {
throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}
if (validated.media_buy_deliveries.length > 0) {
const delivery = validated.media_buy_deliveries[0];
console.log(`Delivered ${delivery.totals.impressions.toLocaleString()} impressions`);
if (delivery.currency && delivery.totals.spend !== undefined) {
console.log(`Spend: ${delivery.totals.spend.toFixed(2)} ${delivery.currency}`);
}
console.log(`CTR: ${(delivery.totals.ctr * 100).toFixed(2)}%`);
}
```
```python Python integration=true theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# Get single media buy delivery report
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
media_buy_ids=['mb_12345'],
start_date='2024-02-01',
end_date='2024-02-07'
)
)
# Check for errors (discriminated union response)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
if result.media_buy_deliveries:
delivery = result.media_buy_deliveries[0]
print(f"Delivered {delivery.totals.impressions:,} impressions")
if getattr(delivery, 'currency', None) and getattr(delivery.totals, 'spend', None) is not None:
print(f"Spend: {delivery.totals.spend:.2f} {delivery.currency}")
print(f"CTR: {delivery.totals.ctr * 100:.2f}%")
asyncio.run(main())
```
### Multiple Media Buys
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuyDeliveryResponseSchema } from '@adcp/sdk';
// Get all active media buys from context
const result = await testAgent.getMediaBuyDelivery({
status_filter: 'active',
start_date: '2024-02-01',
end_date: '2024-02-07'
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}
console.log(`${validated.media_buy_deliveries.length} active campaigns`);
// Review each campaign
validated.media_buy_deliveries.forEach(delivery => {
const spend = delivery.currency && delivery.totals.spend !== undefined
? `, ${delivery.totals.spend.toFixed(2)} ${delivery.currency}`
: '';
console.log(`${delivery.media_buy_id}: ${delivery.totals.impressions.toLocaleString()} impressions${spend}, CTR ${(delivery.totals.ctr * 100).toFixed(2)}%`);
});
```
```python Python test=false theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# Get all active media buys from context
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
status_filter='active',
start_date='2024-02-01',
end_date='2024-02-07'
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
print(f"{len(result.media_buy_deliveries)} active campaigns")
# Review each campaign
for delivery in result.media_buy_deliveries:
spend = (f", {delivery.totals.spend:.2f} {delivery.currency}"
if getattr(delivery, 'currency', None) and getattr(delivery.totals, 'spend', None) is not None else "")
print(f"{delivery.media_buy_id}: {delivery.totals.impressions:,} impressions{spend}, CTR {delivery.totals.ctr * 100:.2f}%")
asyncio.run(main())
```
### Date Range Reporting
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuyDeliveryResponseSchema } from '@adcp/sdk';
// Get month-to-date performance
const now = new Date();
const monthStart = new Date(now.getFullYear(), now.getMonth(), 1);
const dateFormat = date => date.toISOString().split('T')[0];
const result = await testAgent.getMediaBuyDelivery({
media_buy_ids: ['mb_12345'],
start_date: dateFormat(monthStart),
end_date: dateFormat(now)
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}
if (validated.media_buy_deliveries.length > 0) {
// Analyze daily breakdown
const dailyBreakdown = validated.media_buy_deliveries[0].daily_breakdown;
if (dailyBreakdown && dailyBreakdown.length > 0) {
console.log(`Daily average: ${Math.round(validated.media_buy_deliveries[0].totals.impressions / dailyBreakdown.length).toLocaleString()} impressions`);
// Find peak day
const peakDay = dailyBreakdown.reduce((max, day) =>
day.impressions > max.impressions ? day : max
);
console.log(`Peak day: ${peakDay.date} with ${peakDay.impressions.toLocaleString()} impressions`);
}
}
```
```python Python test=false theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
from datetime import date
async def main():
# Get month-to-date performance
today = date.today()
month_start = date(today.year, today.month, 1)
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
media_buy_ids=['mb_12345'],
start_date=str(month_start),
end_date=str(today)
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
if result.media_buy_deliveries:
# Analyze daily breakdown
daily_breakdown = result.media_buy_deliveries[0].daily_breakdown
if daily_breakdown:
daily_avg = result.media_buy_deliveries[0].totals.impressions // len(daily_breakdown)
print(f"Daily average: {daily_avg:,} impressions")
# Find peak day
peak_day = max(daily_breakdown, key=lambda d: d.impressions)
print(f"Peak day: {peak_day.date} with {peak_day.impressions:,} impressions")
asyncio.run(main())
```
### Multi-Status Query
```javascript JavaScript integration=true theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuyDeliveryResponseSchema } from '@adcp/sdk';
// Get both active and paused campaigns
const result = await testAgent.getMediaBuyDelivery({
status_filter: ['active', 'paused'],
start_date: '2024-02-01',
end_date: '2024-02-07'
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}
// Group by status
const byStatus = validated.media_buy_deliveries.reduce((acc, delivery) => {
if (!acc[delivery.status]) acc[delivery.status] = [];
acc[delivery.status].push(delivery);
return acc;
}, {});
console.log(`Active campaigns: ${byStatus.active?.length || 0}`);
console.log(`Paused campaigns: ${byStatus.paused?.length || 0}`);
// Identify underperforming campaigns
byStatus.paused?.forEach(delivery => {
if (delivery.by_package && delivery.by_package.length > 0) {
const avgPacing = delivery.by_package.reduce((sum, pkg) => sum + pkg.pacing_index, 0) / delivery.by_package.length;
console.log(`${delivery.media_buy_id}: paused with ${(avgPacing * 100).toFixed(0)}% pacing`);
}
});
```
```python Python integration=true theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
from collections import defaultdict
async def main():
# Get both active and paused campaigns
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
status_filter=['active', 'paused'],
start_date='2024-02-01',
end_date='2024-02-07'
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
# Group by status
by_status = defaultdict(list)
for delivery in result.media_buy_deliveries:
by_status[delivery.status].append(delivery)
print(f"Active campaigns: {len(by_status['active'])}")
print(f"Paused campaigns: {len(by_status['paused'])}")
# Identify underperforming campaigns
for delivery in by_status['paused']:
if delivery.by_package:
avg_pacing = sum(pkg.pacing_index for pkg in delivery.by_package) / len(delivery.by_package)
print(f"{delivery.media_buy_id}: paused with {avg_pacing * 100:.0f}% pacing")
asyncio.run(main())
```
### Correlating Your Own Reference
> [!NOTE]
>
> **`media_buy_ids` are seller-assigned.** They are the `media_buy_id` values returned by [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) and [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) — not buyer-side identifiers. AdCP has no buyer-reference lookup key: the top-level `buyer_ref` field was removed in 3.0.0, making seller-assigned `media_buy_id`/`package_id` canonical. If you hold only your own identifier, include it in the opaque `context` object (commonly `context.buyer_ref`) when you call `create_media_buy`; the seller echoes `context` back on `create_media_buy` and [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys), so you can reconcile your reference to the seller's `media_buy_id` before requesting delivery.
```javascript JavaScript integration=true theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuyDeliveryResponseSchema } from '@adcp/sdk';
// Compare several media buys by their seller-assigned IDs (from create_media_buy / get_media_buys)
const result = await testAgent.getMediaBuyDelivery({
media_buy_ids: ['mb_q1_campaign_2024', 'mb_q1_retargeting_2024']
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}
// Compare campaigns
validated.media_buy_deliveries.forEach(delivery => {
if (delivery.totals.impressions > 0 && delivery.currency && delivery.totals.spend !== undefined) {
const cpm = (delivery.totals.spend / delivery.totals.impressions) * 1000;
console.log(`${delivery.media_buy_id}: CPM ${cpm.toFixed(2)} ${delivery.currency}, CTR ${(delivery.totals.ctr * 100).toFixed(2)}%`);
}
});
```
```python Python integration=true theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# Compare several media buys by their seller-assigned IDs (from create_media_buy / get_media_buys)
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
media_buy_ids=['mb_q1_campaign_2024', 'mb_q1_retargeting_2024']
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
# Compare campaigns
for delivery in result.media_buy_deliveries:
if (delivery.totals.impressions > 0 and getattr(delivery, 'currency', None)
and getattr(delivery.totals, 'spend', None) is not None):
cpm = (delivery.totals.spend / delivery.totals.impressions) * 1000
print(f"{delivery.media_buy_id}: CPM {cpm:.2f} {delivery.currency}, CTR {delivery.totals.ctr * 100:.2f}%")
asyncio.run(main())
```
### Account-Scoped Query
```javascript JavaScript test=false theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuyDeliveryResponseSchema } from '@adcp/sdk';
// Get delivery for a specific advertiser account
const result = await testAgent.getMediaBuyDelivery({
account: { account_id: 'acc_acme_pinnacle' },
status_filter: 'active',
start_date: '2024-02-01',
end_date: '2024-02-07'
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuyDeliveryResponseSchema.parse(result.data);
if ('errors' in validated && validated.errors) {
throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}
for (const delivery of validated.media_buy_deliveries) {
if (delivery.currency && delivery.totals.spend !== undefined) {
console.log(`${delivery.media_buy_id}: ${delivery.totals.spend.toFixed(2)} ${delivery.currency}`);
}
}
```
```python Python test=false theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuyDeliveryRequest
async def main():
# Get delivery for a specific advertiser account
result = await test_agent.get_media_buy_delivery(
GetMediaBuyDeliveryRequest(
account={'account_id': 'acc_acme_pinnacle'},
status_filter='active',
start_date='2024-02-01',
end_date='2024-02-07'
)
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Query failed: {result.errors}")
for delivery in result.media_buy_deliveries:
if getattr(delivery, 'currency', None) and getattr(delivery.totals, 'spend', None) is not None:
print(f"{delivery.media_buy_id}: {delivery.totals.spend:.2f} {delivery.currency}")
asyncio.run(main())
```
## Metrics Definitions
| Metric | Definition |
| - | - |
| **Impressions** | Number of times ads were displayed |
| **Spend** | Amount spent in specified currency |
| **Clicks** | Number of ad clicks (if available) |
| **CTR** | Click-through rate (clicks/impressions) |
| **Views** | Content engagements at the billable view threshold — video views, audio/podcast stream starts, or format-specific view events |
| **Completed Views** | Audio/video completions (at threshold or 100%) |
| **Completion Rate** | Completion rate (completed_views/impressions) |
| **Conversions** | Attributed conversions (purchases, new listeners, app installs, etc.) |
| **Conversion Value** | Total monetary value of attributed conversions |
| **ROAS** | Return on ad spend (conversion_value / spend) |
| **New-to-Brand Rate** | Fraction of conversions from first-time brand buyers (0-1) |
| **Cost per Acquisition** | Cost per conversion (spend / conversions) |
| **Reach** | Unique users reached (see `reach_unit` for measurement unit: individuals, households, devices, accounts, cookies). Measurement window declared via `reach_window`; without it, buyers must not sum reach across rows. |
| **Reach Unit** | Unit of measurement for reach — required when reach is present |
| **Reach Window** | Window semantics for reported reach/frequency: `cumulative` (uniques since campaign start), `period` (uniques within a single non-overlapping reporting period — e.g., daily snapshot), or `rolling` (uniques within a trailing window — e.g., trailing-7-day). Never sum across rows. Optional but strongly recommended when reach is present. |
| **Frequency** | Average ad exposures per reach unit, measured over `reach_window` |
| **Viewability** | Object with `vendor`, `measurable_impressions` (denominator), `viewable_impressions`, `viewable_rate`, `viewed_seconds` (average in-view duration per measurable impression — pairs with the `viewed_seconds` optimization goal), and `standard` |
| **Follows** | New followers, page likes, or free channel/feed subscribes attributed to delivery |
| **Pacing Index** | Actual vs. expected delivery rate (1.0 = on track, \<1.0 = behind, >1.0 = ahead) |
| **CPM** | Cost per thousand impressions (spend/impressions \* 1000) |
## Query Behavior
### Context-Based Queries
* If no `media_buy_ids` provided, returns all media buys from current session context
* Context established by previous operations (e.g., [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy))
### Status Filtering
* Defaults to `["active"]` if not specified
* Can be single string (`"active"`) or array (`["active", "paused"]`)
* Valid filter values are media-buy lifecycle statuses: `pending_creatives`, `pending_start`, `active`, `paused`, `completed`
* `reporting_delayed` and `failed` are delivery/reporting statuses returned in webhook contexts, not request filter values
* Some legacy integrations may emit `pending`; treat it as equivalent to `pending_start`
### Date Ranges
* If dates not specified, returns campaign lifetime delivery data
* Both `start_date` and `end_date` must be provided together — partial date ranges are invalid
* Date format: `YYYY-MM-DD`, a calendar date in the product's reporting timezone (`reporting_capabilities.timezone`)
* **Start-inclusive, end-exclusive**: `start_date` is included, `end_date` is excluded. For example, `start_date: "2026-01-01"` and `end_date: "2026-01-02"` returns data for January 1st only.
* Products declare date range support in `reporting_capabilities.date_range_support`
* Products with `date_range_support: "lifetime_only"` reject requests that include `start_date`/`end_date` with an [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) error
* Products with `date_range_support: "date_range"` accept date parameters and filter delivery data accordingly
* Daily breakdown may be truncated for long date ranges to reduce response size
### Metric Availability
* **Universal**: Impressions, spend (available on all platforms)
* **Format-dependent**: Clicks, completed_views, completion_rate (depends on inventory type and platform capabilities)
* **Audience**: Reach, frequency (available on platforms with deduplicated measurement)
* **Commerce attribution**: Conversions, conversion_value, roas, new_to_brand_rate (available on commerce media and streaming platforms)
* **Engagement**: Follows, saves, engagements, profile_visits (available on social and streaming platforms)
* **Attribution window**: `attribution_window` describes the lookback windows and model used for conversion attribution (e.g., 14-day click, 1-day view, last_touch)
* **Package-level**: All metrics broken down by package with pacing_index
### Requesting a metric subset
`requested_metrics` narrows the response to a specific list of metrics — the same field and semantics as `reporting_webhook.requested_metrics`, now also available on the GET path. It applies to every metrics-bearing object in the response: `totals`, `by_package`, daily and window slices, and breakdown rows. `impressions` and `spend` are always included regardless of what the list contains, except that a legacy or externally created mixed-currency buy omits monetary values from media-buy and window totals, omits `daily_breakdown`, and reports monetary values only on currency-qualified package rows. Requesting a leaf metric identity (e.g. `viewable_rate`, `quartile_75`) returns its canonical nested carrier (`viewability`, `quartile_data`) rather than a flat duplicate field. A metric requested but not available for the buy is simply omitted — no error — and `missing_metrics` is unaffected by that omission: it still reconciles solely against `committed_metrics`, and sellers MUST NOT list a metric there just because the buyer excluded it via `requested_metrics`. Values outside the product's `reporting_capabilities.available_metrics` are ignored. Omitting the field preserves current behavior — all available metrics are returned.
## Data Freshness
* Reporting data typically has 2-4 hour delay
* Real-time impression counts not available
* Use for periodic reporting and optimization decisions, not live monitoring
**Phased-maturation channels**: Data freshness differs for channels where billing-grade data is produced in phases rather than arriving final on day one — broadcast TV (Live → C3 → C7 DVR accumulation, final C7 \~15–22 days after broadcast), DOOH (tentative plays → post-IVT/fraud-check final), digital with IVT filtering (raw → post-GIVT → post-SIVT), and podcast (7-day → 30-day downloads). Products with `reporting_capabilities.measurement_windows` declare these timelines. Buyers reconcile against the `measurement_window` specified in `billing_measurement` on the agreed terms. See [Accountability](/dist/docs/3.2.8/media-buy/advanced-topics/accountability) for measurement terms and [Optimization and reporting](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting) for the full lifecycle.
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing) | No credentials presented | Provide credentials via auth header |
| [`AUTH_INVALID`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-invalid) | Credentials rejected (expired / revoked) | Human credential rotation required; do not auto-retry |
| [`MEDIA_BUY_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-media-buy-not-found) | Media buy doesn't exist | Verify `media_buy_id`; for legacy correlation use [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) + `context.internal_campaign_id` |
| [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) | A date string or filter violates its schema constraints | Use YYYY-MM-DD dates and a documented status value |
| [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) | Only one date is present, `end_date` is not after `start_date`, or a dated request spans products with different reporting timezones | Supply both dates with `start_date < end_date`. Narrow `media_buy_ids` to buys sharing one reporting timezone, or omit both dates for lifetime delivery |
| [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) | Product only supports lifetime reporting | Omit `start_date` and `end_date`. Check `reporting_capabilities.date_range_support` on the product. |
| [`UNSUPPORTED_GRANULARITY`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-granularity) | Requested `time_granularity` is not in the product's `windowed_pull_granularities` | Re-issue with a granularity from `error.details.supported_granularities`, or omit `time_granularity` to fall back to cumulative date-range pulls. See [Windowed pull recovery](#windowed-pull-recovery). |
| [`REFERENCE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-reference-not-found) | Unknown or unauthorized `reporting_revision_id` + account combination (nondisclosing — expired, inaccessible, and absent revisions return the same response) | Verify the revision ID exists and is accessible to the authenticated account |
| [`SERVICE_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-service-unavailable) | A retained `reporting_revision_id` whose content cannot currently be served or verified | Retry within the standard retry budget; if the open revision issue in [`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status) says `contact_seller`, stop retrying and escalate |
A valid query with no matching media buys succeeds with an empty `media_buy_deliveries` array.
## Package-Level Metrics
The `by_package` array provides per-package delivery details with these key fields:
**Buyer Control**:
* **`paused`**: Whether the package is currently paused by the buyer (true/false)
**System State**:
* **`delivery_status`**: System-reported operational state:
* `delivering` - Package is actively delivering impressions
* `not_delivering` - Package recorded zero impressions for the entire reporting window while it was in-flight. Sellers should only report this for a final window; a provisional zero may reflect measurement lag.
* `completed` - Package finished successfully
* `budget_exhausted` - Package ran out of budget
* `flight_ended` - Package reached its end date
* `goal_met` - Package achieved its impression/conversion goal
**Performance**:
* **`pacing_index`**: Delivery pace (1.0 = on track, below 1.0 = behind, above 1.0 = ahead)
* **`rate`**: Effective pricing rate (e.g., CPM)
* **`pricing_model`**: How the package is billed (cpm, cpcv, cpp, revenue_share, etc.)
* **`commissionable_value`**: For `revenue_share`, the settled attributed value to which the selected `commission_rate` applies. Verify `spend = round_currency(commissionable_value × commission_rate)`.
**Accountability**:
* **`metric_values`**: Qualified standard values actually delivered for this package. Each row uses `{ scope: "standard", metric_id, qualifier, value, ...components }`, matching standard-scope `package.committed_metrics` and `missing_metrics` on `(scope, metric_id, qualifier)`. Sellers report the finest available qualifier set at package grain. When a metric appears here, its flat package scalar MUST be omitted to prevent two sources of truth. Vendor-scope values remain in `vendor_metric_values`, and buyers perform only semantically compatible cross-package aggregation.
* **`missing_metrics`**: Metrics the binding reporting contract advertised but that are not populated in this report. Each entry uses an explicit `scope` discriminator: `{ "scope": "standard", "metric_id": "completed_views" }` for entries from the closed `available-metric.json` enum, `{ "scope": "vendor", "vendor": { "domain": "..." }, "metric_id": "attention_units" }` for vendor-defined metrics. Standard entries MAY carry a `qualifier` mirroring the `committed_metrics` qualifier (e.g., `{ "scope": "standard", "metric_id": "viewable_rate", "qualifier": { "viewability_standard": "mrc" } }` flags a missing MRC commitment even when GroupM viewability was reported, or `{ "scope": "standard", "metric_id": "completion_rate", "qualifier": { "completion_source": "vendor_attested" } }` flags a missing vendor-attested commitment even when seller-attested completion was reported — the paths are not interchangeable). Reconciled against `package.committed_metrics` (filtered to entries where `committed_at < reporting_period.end`) when present; falls back to the product's current `reporting_capabilities.available_metrics` and `vendor_metrics` when absent. Empty array (or absent) indicates clean delivery against the contract; non-empty signals an accountability breach. Sellers MUST exclude metrics that are not yet measurable for the current `measurement_window` (e.g., post-IVT counts during the live window) — those will appear (or not) when a wider window supersedes this report via `supersedes_window`.
* **`vendor_metric_values`**: Reported values for vendor-defined metrics that the product's `reporting_capabilities.vendor_metrics` declared (proprietary attention, emissions, panel demographics, brand-lift surveys, etc.). Each entry carries `{ vendor, metric_id, value, unit?, measurable_impressions?, measurable_plays?, measurable_play_seconds?, vendor_relationship?, qualifier?, breakdown? }`. The `measurable_impressions` field is the coverage denominator — vendor measurement is rarely 100% of delivery, since vendors only score impressions where their SDK fires or their panel matches. Buyers compute coverage as `measurable_impressions / impressions`. When `measurable_impressions` is absent, coverage is unspecified — buyers MUST NOT compute a coverage rate or assume full coverage. For play-based channels (DOOH, cinema, place-based) where `impressions` is itself modelled from `plays`, the row carries `measurable_plays` (coverage = `measurable_plays / plays`) or `measurable_play_seconds` (coverage = `measurable_play_seconds / dooh_metrics.screen_time_seconds` on screen networks, or against the seller's reported playout seconds on place-based audio) instead; a row SHOULD carry exactly one denominator. `vendor_relationship` (`first_party` / `affiliated` / `third_party`) MAY echo the product's `reporting_capabilities.vendor_metrics[].vendor_relationship` so the row states the seller–vendor relationship without a join back to the product; when present it MUST equal the declared value, and absence is undeclared, never `third_party`. Distinct from the row-level `measurement_source` provider slug used by measured channels (radio, broadcast, OOH). When a declared vendor metric is omitted entirely from this array, infer no measurement happened (no integration). JIC or panel-based co-viewing adjustments, claim reconciliation, confidence intervals, and panel sizes belong here, usually in `breakdown`, rather than in buy-time signal targeting definitions.
**Key Distinction**: `paused` reflects buyer control, while `delivery_status` reflects system reality. A package can be not paused but have `delivery_status: "budget_exhausted"`.
## Creative-Level Metrics
When the seller supports creative-level reporting (`supports_creative_breakdown` in reporting capabilities), each package includes a `by_creative` array with per-creative delivery metrics.
Each creative entry includes:
* **`creative_id`**: Creative identifier matching the creative assignment
* **`creative_name`**: Optional human-readable name current when the report is generated. This is convenience metadata; use `creative_id` as the stable identity.
* **`weight`**: Delivery weight for this creative during the reporting period (0-100)
* All standard delivery metrics (impressions, spend, clicks, ctr, etc.)
```json theme={null}
{
"by_package": [
{
"package_id": "pkg_001",
"spend": 5000,
"impressions": 100000,
"pricing_model": "cpm",
"rate": 50,
"currency": "USD",
"delivery_status": "delivering",
"by_creative": [
{
"creative_id": "hero_video_30s",
"creative_name": "Brand hero video — 30 seconds",
"weight": 60,
"impressions": 60000,
"spend": 3000,
"clicks": 3000,
"ctr": 0.05,
"completion_rate": 0.72
},
{
"creative_id": "hero_video_15s",
"creative_name": "Brand hero video — 15 seconds",
"weight": 40,
"impressions": 40000,
"spend": 2000,
"clicks": 1200,
"ctr": 0.03,
"completion_rate": 0.85
}
]
}
]
}
```
For deeper creative analytics including variant-level delivery data (asset combination optimization, generative creative), use [`get_creative_delivery`](/dist/docs/3.2.8/creative/task-reference/get_creative_delivery). This is a Creative Protocol task — call it on any agent that implements the Creative Protocol, which may be the same sales agent if it declares `"creative"` in `supported_protocols`. See [Creative capabilities on sales agents](/dist/docs/3.2.8/creative/sales-agent-creative-capabilities).
By default `by_creative` is returned automatically at the seller's discretion, with no limit, sort, or truncation contract. To answer questions like "top creatives by completion rate," include `reporting_dimensions: { "creative": { "limit": 10, "sort_by": "quartile_100" } }` in the request — this negotiates the breakdown, making `by_creative_truncated`, `by_creative_sorted_by`, and `by_creative_sort_direction` binding. See [Dimension Breakdowns](#dimension-breakdowns).
## Catalog-item reporting
For catalog-driven packages (packages with a `catalog` field), the seller can return per-catalog-item delivery in the `by_catalog_item` array within each package.
Each entry identifies the catalog item and includes standard delivery metrics:
| Field | Description |
| - | - |
| `content_id` | The item identifier (SKU, GTIN, job ID, etc.) |
| `content_id_type` | Identifier type (`sku`, `gtin`, `job_id`, etc.) matching the catalog's `content_id_type` |
| Standard metrics | `impressions`, `spend`, `clicks`, `ctr`, `conversions`, `roas`, and other delivery metrics |
This is optional. Sellers that support item-level reporting populate `by_catalog_item`; sellers that do not simply omit it.
By default `by_catalog_item` is returned automatically at the seller's discretion, with no limit, sort, or truncation contract. Including `reporting_dimensions.catalog_item` (e.g., `{ "limit": 25, "sort_by": "roas" }`) negotiates the breakdown, making `by_catalog_item_truncated`, `by_catalog_item_sorted_by`, and `by_catalog_item_sort_direction` binding. See [Dimension Breakdowns](#dimension-breakdowns).
```json theme={null}
{
"by_package": [
{
"package_id": "pkg_001",
"spend": 5000,
"impressions": 100000,
"pricing_model": "cpc",
"rate": 1.20,
"currency": "USD",
"delivery_status": "delivering",
"by_catalog_item": [
{
"content_id": "SKU-12345",
"content_id_type": "sku",
"impressions": 45000,
"spend": 2250,
"clicks": 1800,
"ctr": 0.04,
"conversions": 90,
"roas": 4.2
},
{
"content_id": "SKU-67890",
"content_id_type": "sku",
"impressions": 55000,
"spend": 2750,
"clicks": 2200,
"ctr": 0.04,
"conversions": 110,
"roas": 3.8
}
]
}
]
}
```
## Windowed pull recovery
`reporting_webhook` fires at the buyer's chosen `reporting_frequency` (hourly through post_campaign). When a receiver is offline long enough for transport retries to expire, the buyer loses per-window detail unless GET can reproduce the same slices. `time_granularity` + `include_window_breakdown` close that gap.
### Capability check
Sellers declare which granularities they honor for pull recovery via `reporting_capabilities.windowed_pull_granularities`. Buyers MUST check the capability before requesting `time_granularity`:
```json test=false theme={null}
{
"reporting_capabilities": {
"available_reporting_frequencies": ["hourly", "daily"],
"windowed_pull_granularities": ["daily"]
}
}
```
The seller in this example emits hourly webhooks but only honors daily pulls — common in stream-tap architectures where the webhook is a Kafka tap and historical pulls go through a warehouse. Two-paths-parity holds at the **declared** set; for hourly recovery, the webhook is primary. Sellers that want full parity declare every frequency they fire.
### Requesting windowed slices
```json test=false theme={null}
{
"media_buy_ids": ["mb_12345"],
"start_date": "2026-06-01",
"end_date": "2026-06-02",
"time_granularity": "hourly",
"include_window_breakdown": true
}
```
### Response shape
Each media buy gains a `windows[]` array on the response:
```json test=false theme={null}
{
"media_buy_deliveries": [
{
"media_buy_id": "mb_12345",
"currency": "USD",
"status": "active",
"totals": { "impressions": 12345678, "spend": 5432.10 },
"by_package": [ /* cumulative per-package — unchanged */ ],
"windows": [
{
"window_start": "2026-06-01T00:00:00Z",
"window_end": "2026-06-01T01:00:00Z",
"totals": { "impressions": 510234, "spend": 226.05 },
"by_package": [
{ "package_id": "pkg_001", "impressions": 510234, "spend": 226.05 }
],
"is_final": true
},
{
"window_start": "2026-06-01T01:00:00Z",
"window_end": "2026-06-01T02:00:00Z",
"totals": { "impressions": 488112, "spend": 215.83 },
"is_final": true
}
]
}
]
}
```
Slices are ordered by `window_start` ascending; consecutive rows are contiguous (each row's `window_end` equals the next row's `window_start`). Each slice payload is shape-aligned with what `reporting_webhook` would have delivered for the same window — a buyer reconciling a missed webhook joins on `(media_buy_id, window_start)`.
### Spec contract
* **Capability-scoped MUST** — sellers MUST honor `time_granularity` requests for any value in `windowed_pull_granularities`. Pulls outside the declared set return [`UNSUPPORTED_GRANULARITY`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-granularity).
* **Asymmetric is honest** — sellers MAY emit higher-frequency webhooks than they expose for pull. Declaring `available_reporting_frequencies: ["hourly", "daily"]` with `windowed_pull_granularities: ["daily"]` is valid; the buyer treats the hourly webhook as primary at that frequency.
* **Same-shape recovery** — slice payloads mirror webhook fire payloads at the same granularity so a buyer's reconciliation pipeline does not branch on transport path.
This surface anchors [snapshot-and-log](/dist/docs/3.2.8/protocol/snapshot-and-log) Rule 4 (either path is complete) for data-bearing events. See that page for the broader contract.
## Dimension Breakdowns
When you include `reporting_dimensions` in the request, the response includes dimensional breakdown arrays within each `by_package` entry. Each breakdown entry inherits all fields from `delivery-metrics` plus dimension-specific identifiers.
### Requesting breakdowns
```json test=false theme={null}
{
"media_buy_ids": ["mb_123"],
"reporting_dimensions": {
"geo": { "geo_level": "metro", "system": "nielsen_dma", "limit": 10 },
"device_type": {},
"format": { "sort_by": "spend" },
"demographic": {
"age_ranges": [{ "min": 26, "max": 30, "include_unknown": false }]
},
"placement": { "limit": 5, "sort_by": "roas" },
"property": {},
"collection": {},
"installment": {},
"collection_property": { "sort_by": "impressions" },
"installment_property": {},
"placement_property": {},
"spot": {}
}
}
```
Geo, device, format, audience, demographic, placement, property, collection, installment, collection_property, installment_property, placement_property, creative, keyword, and catalog_item dimensions accept optional `limit`, `sort_by` (any value from the `sort-metric` enum; defaults to `spend`), and `sort_direction` (`asc` or `desc`; defaults to `desc`, largest first). The seller echoes the sort it actually applied in the corresponding `by_*_sorted_by` and `by_*_sort_direction` fields. For every requested dimension that the product declares supported, sellers MUST return the breakdown array (possibly empty) and `by_*_truncated`. Metric-sorted dimensions also return both sort echoes; demographic and property-grain arrays also return `by_*_suppressed`. Geo requires `geo_level`; demographic accepts optional canonical `age_ranges`; spot accepts only `limit`, is ordered by `aired_at`, and has no sort echoes. Most arrays are independent one-dimensional marginals. `collection_property`, `installment_property`, and `placement_property` are deliberate intersections that prove which property carried the collection, specific installment, or placement.
`creative`, `keyword`, and `catalog_item` are different from the other dimensions in one respect: sellers return them automatically whenever they support the underlying capability, whether or not the buyer's `reporting_dimensions` mentions them. Omitting the key preserves that automatic default — rows show up with no completeness contract, and `by_creative_truncated`/`by_keyword_truncated`/`by_catalog_item_truncated` and their sort echoes are only RECOMMENDED. Including the key (even as `{}`) negotiates the breakdown: `limit` and `sort_by`/`sort_direction` are honored, and the truncation flag and applied-sort echo become MUST-return fields, the same as any other requested dimension.
### Available dimensions
| Dimension | Breakdown field | Required fields | Additional fields | Capability declaration |
| - | - | - | - | - |
| Geography | `by_geo` | `geo_level`, `geo_code`, `impressions`, `spend` | `system`, `country`, `geo_name` | `supports_geo_breakdown` |
| Device type | `by_device_type` | `device_type`, `impressions`, `spend` | — | `supports_device_type_breakdown` |
| Device platform | `by_device_platform` | `device_platform`, `impressions`, `spend` | — | `supports_device_platform_breakdown` |
| Creative format | `by_format` | `format_kind`, `impressions`, `spend` | Other delivery metrics | `supports_format_breakdown` |
| Audience | `by_audience` | `audience_id`, `audience_source`, `impressions`, `spend` | `audience_name` | `supports_audience_breakdown` |
| Demographic | `by_demographic` | `demographic`, `demographic_system`, `impressions`, `spend` | `age`, other delivery metrics | `supports_demographic_breakdown` |
| Placement | `by_placement` | `placement_id`, `impressions`, `spend` | `placement_identity`, `placement_name`, `publisher_domain` | `supports_placement_breakdown` |
| Property | `by_property` | `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, `property_name` | `supports_property_breakdown` |
| Collection | `by_collection` | `collection_ref`, `impressions`, `spend` | `collection_name` | `supports_collection_breakdown` |
| Installment | `by_installment` | `installment_ref`, `impressions`, `spend` | `installment_name`, `scheduled_at` | `supports_installment_breakdown` |
| Collection × property | `by_collection_property` | `collection_ref`, `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, `collection_name`, `property_name` | `supports_collection_property_breakdown` |
| Installment × property | `by_installment_property` | `installment_ref`, `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, `installment_name`, `scheduled_at`, `property_name` | `supports_installment_property_breakdown` |
| Placement × property | `by_placement_property` | `placement_id`, `placement_identity`, `publisher_domain`, `identifier`, `impressions`, `spend` | `property_ref`, convenience names | `supports_placement_property_breakdown` |
| Spot/as-run | `by_spot` | `spot_id`, `aired_at` | `creative_id`, `impressions`, `network`, `station`, `daypart`, other delivery metrics | `supports_spot_breakdown` |
| Creative | `by_creative` | `creative_id`, `impressions`, `spend` | `creative_name`, `weight`, other delivery metrics | `supports_creative_breakdown` (automatic; `reporting_dimensions.creative` optionally negotiates limit/sort) |
| Keyword | `by_keyword` | `keyword`, `match_type`, `impressions`, `spend` | other delivery metrics | Search/retail media capability (automatic; `reporting_dimensions.keyword` optionally negotiates limit/sort) |
| Catalog item | `by_catalog_item` | `content_id`, `content_id_type`, `impressions`, `spend` | other delivery metrics | Catalog-driven packages only (automatic; `reporting_dimensions.catalog_item` optionally negotiates limit/sort) |
Check `reporting_capabilities` on the product to discover which dimensions are available. Product-level capabilities are authoritative since different products from the same seller may support different breakdowns.
`by_format` uses the AdCP 3.1 canonical `format_kind` vocabulary. It answers cross-kind questions such as how `video_hosted`, `native_in_feed`, and `image` delivery compare; it does not distinguish two creatives that share a format kind but differ by duration, dimensions, or another format-option parameter. Sellers MUST combine adopter-defined shapes into one `custom` row. When `by_format_truncated` is false, additive metrics such as impressions and spend SHOULD reconcile to package totals, subject to each metric's measurement and attribution semantics. `by_format_sorted_by` and `by_format_sort_direction` echo the sort actually applied, so a fallback to `spend` is visible rather than silent. Buyers MUST NOT expect row-level correspondence between `by_format` and `by_creative` because they are independently produced at different grains. Requested dimensional breakdowns, including `by_format`, are negotiated on the GET path. Reporting webhook configuration does not negotiate or guarantee them, although webhook payloads MAY carry the same fields as extensions. Requested dimensions do not apply to `windows[].by_package`; those rows remain shape-aligned with webhook fires for pull recovery.
`demographic_targeting` declares what the product can execute; `supports_demographic_breakdown` separately declares what it can measure and report. A product can therefore target 26–30 but disclose fixed 25–34 reporting. Buyers MUST NOT infer exact reporting from targeting capability or parse equivalence from a native label. `demographic` uses the notation of its accompanying `demographic_system`; canonical `age`, when present, is the authoritative machine-comparable interval.
`supports_geo_breakdown`, `supports_demographic_breakdown`, and `supports_spot_breakdown` are structured capability objects; the other declarations in this table are boolean flags. Demographic capability declares exact predicates versus fixed intervals, available measurement systems, and whether small cells may be suppressed. `supports_spot_breakdown.available_metrics` lists metrics available at spot grain; an empty array means the product supplies as-run airing evidence but no per-spot delivery metrics.
Placement identity names its authority. `placement_identity.kind: "publisher_ref"` carries the publisher `adagents.json` domain; `kind: "seller_inline"` carries the defining `seller_agent`. The flat `placement_id` remains required for 3.1 consumers. New 3.2 sellers SHOULD add `placement_identity` to `by_placement`; legacy rows without it remain valid but are only package-scoped. The new `by_placement_property` row always requires `placement_identity`. `placement_name` is convenience metadata.
Every property row includes `publisher_domain` and an operational `identifier` such as a domain, app bundle or store ID, station ID, or facility ID. Their tuple is the stable operational key even for unregistered surfaces. When the surface resolves to the publisher catalog, optional `property_ref` adds `{publisher_domain, property_id}` and MUST use the same domain. Collection identity is canonical through `collection_ref`; `installment_ref` nests it. Independent marginals do not establish correlation. `by_collection_property`, `by_installment_property`, and `by_placement_property` are affirmative delivery evidence for returned intersections; catalog declarations establish only eligibility or carriage. For programmed channels, the installment intersection is what proves that a specific content airing or programming block ran on each reported host property. It is distinct from `by_spot`, which identifies an individual ad as-run occurrence. When an intersection array is truncated or suppressed, the absence of a row does not prove non-delivery.
Each property-grain array has a `by_*_suppressed` flag, separate from `by_*_truncated`. `true` means privacy, policy, or measurement thresholds omitted otherwise reportable rows from that array; `false` means no rows were threshold-suppressed. Suppression policies may use different bases or thresholds at different grains, so AdCP 3.2 does not attempt to encode a shared numeric floor. Suppression and truncation may both be true.
For social inventory, the platform or serving app maps to the property axis and the feed, story, short-video, search, or other render position maps to the placement axis. A fictional network could therefore report property `social.example/photo_app` intersecting publisher placement `social.example/feed`. For a conversational publisher, web, mobile app, and assistant surfaces are properties while sponsored-answer, recommendation-card, or sidebar locations are placements. Adapters omit dimensions the upstream platform does not expose; they never infer placement delivery from campaign eligibility.
Spot rows are channel-neutral as-run records. Linear TV commonly supplies `network`, radio commonly supplies `station`, and sellers MAY populate both; neither is required. `spot_id` identifies the scheduled occurrence and remains stable when the same airing is re-reported across Live, C3, C7, or another measurement-window progression. `aired_at` proves that it aired. Sellers MUST order rows by `aired_at` ascending. When `reporting_dimensions.spot.limit` is omitted, sellers SHOULD return the complete log for the requested reporting period. `by_spot_truncated` tells the buyer whether the returned log is complete.
The optional `creative_id` identifies the creative that aired, matching the package's creative asset or assignment. For library-backed sellers this is the [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) identifier; inline-only sellers use the `creative_id` supplied through `packages[].creatives`. Sellers SHOULD populate it whenever they can associate a specific airing with a creative, particularly when the package could serve more than one creative during any part of the reporting period, including a mid-period replacement. Sellers that cannot make that association MUST omit the field rather than emit a default or placeholder. Buyers MUST NOT aggregate `by_spot` rows by `creative_id` and expect the result to equal `by_creative[]` impressions for the same creative: the two dimensions are independently produced at different granularities and are subject to different metric-maturation and attribution semantics within the package `measurement_window`. `by_creative` is the authoritative creative-performance aggregate; `creative_id` on a spot row identifies which creative aired, not an independent metric roll-up source.
Delivery metrics on a spot row are optional. Omission means the metric is not yet available in the package's current `measurement_window`, or the product did not declare it in `supports_spot_breakdown.available_metrics`. A later window may return the same `spot_id` with impressions populated. An explicit `impressions: 0` is a measured zero; it does not mean pending or unavailable, and `null` is invalid.
### Truncation
Each breakdown array has a sibling boolean flag (e.g., `by_geo_truncated`). When `true`, additional non-suppressed rows exist beyond the returned top-N set. When `false`, every non-suppressed row is present. For every dimension requested via `reporting_dimensions`, sellers MUST return the truncated flag whenever the corresponding breakdown array is present.
For the bounded-enum dimensions — `device_type`, `device_platform`, `audience`, and `placement` — a truncated breakdown is retrievable rather than a dead end: sellers MUST also return `by__pagination` (the same cursor-pagination shape used by [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products)) whenever `by__truncated` is true. Pass the returned `cursor` back as `reporting_dimensions..cursor` on the next request, repeating `limit`, `sort_by`, and `sort_direction` unchanged, to fetch the next page. Every other dimension's truncation — including `by_geo`, which can reach tens of thousands of rows at `postal_area` granularity — remains an analytical ranking rather than a complete export; AdCP 3.2 does not define a complete property-export operation for these, and buyers that need exhaustive brand-safety or allowlist reconciliation must use the seller's native reporting or export interface. Metric dimensions are sorted by the requested `sort_by` value in the requested `sort_direction` (descending by default); rows without the applied metric sort last regardless of direction. The seller echoes the metric and direction it actually applied in `by_*_sorted_by`/`by_*_sort_direction`, which sellers MUST return whenever a requested dimension's breakdown array is present. For `by_creative`, `by_keyword`, and `by_catalog_item` rows returned automatically without a request key, the truncated and echo fields are RECOMMENDED rather than required — automatic rows carry no completeness contract. Spot rows always use `aired_at` ascending and carry neither field.
Demographic and property-grain reporting also return `by_*_suppressed`. `true` means privacy, policy, or measurement thresholds omitted otherwise reportable rows, so the visible rows may not reconcile to package totals. This is distinct from truncation caused by a row limit, and both flags may be true.
### Audience sources
The `audience_source` field indicates where the audience segment originated:
| Source | Description | Targetable? |
| - | - | - |
| `synced` | Buyer's first-party data via [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) | Yes — use `audience_include`/`audience_exclude` |
| `platform` | Seller's native segments (interest, behavioral) | No — informational |
| `third_party` | External data provider segments | No — informational |
| `lookalike` | Platform-generated expansion from a seed | No — informational |
| `retargeting` | Prior engagement via seller's pixel/tag | No — informational |
| `unknown` | Unclassified or unrecognized audience source | No — informational |
## Best Practices
**1. Check Date Range Support**
Before requesting date-filtered delivery, check `reporting_capabilities.date_range_support` on the product. Products with `lifetime_only` support reject date range requests — omit `start_date` and `end_date` to get campaign lifetime data instead.
**2. Use Date Ranges for Analysis**
For products that support date ranges, specify dates for period-over-period comparisons and trend analysis.
**3. Monitor Pacing Index**
Aim for 0.95-1.05 pacing index. Values outside this range indicate delivery issues.
**4. Check Daily Breakdown**
Identify delivery patterns and weekend/weekday performance differences.
**5. Compare Package Performance**
Use `by_package` breakdowns to identify best-performing inventory. Check both `paused` state and `delivery_status` to understand why packages aren't delivering.
**6. Track Status Changes**
Use multi-status queries to understand why campaigns were paused or completed.
## Post-Delivery Governance Validation
Delivery reporting is not the final step. When campaign governance is active, delivery data feeds into governance validation to detect unauthorized supply paths, geo drift, and pacing violations.
The governance feedback loop:
1. Pull delivery data via `get_media_buy_delivery`
2. Report outcomes to the governance agent via [`report_plan_outcome`](/dist/docs/3.2.8/governance/campaign/tasks/report_plan_outcome)
3. The governance agent compares actual delivery against planned parameters (drift detection)
4. Validate property delivery via [`validate_property_delivery`](/dist/docs/3.2.8/governance/property/tasks/validate_property_delivery) to catch unauthorized supply paths
| Governance task | Purpose |
| - | - |
| [`report_plan_outcome`](/dist/docs/3.2.8/governance/campaign/tasks/report_plan_outcome) | Feed delivery data to the governance agent for budget tracking and drift detection |
| [`validate_property_delivery`](/dist/docs/3.2.8/governance/property/tasks/validate_property_delivery) | Validate delivery records against property lists — catches ads running on unauthorized properties |
| [`validate_content_delivery`](/dist/docs/3.2.8/governance/content-standards/tasks/validate_content_delivery) | Validate content artifacts against brand suitability standards |
| [`get_plan_audit_logs`](/dist/docs/3.2.8/governance/campaign/tasks/get_plan_audit_logs) | View the full plan state and audit trail |
Without this feedback loop, delivery data is reported but never validated. Budget overruns, pacing divergence, geo drift, and unauthorized supply paths go undetected.
## Next Steps
After retrieving delivery data:
1. **Optimize Campaigns**: Use [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) to adjust budgets, pacing, or targeting
2. **Provide Feedback**: Use [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) to share results with seller
3. **Update Creatives**: Use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) for library-backed sellers, or inline `packages[].creatives` on [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) for inline-only sellers
4. **Create Follow-Up Campaigns**: Use [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) based on insights
## Learn More
* [Media Buy Lifecycle](/dist/docs/3.2.8/media-buy/media-buys/) - Complete campaign workflow
* [Async Operations](/dist/docs/3.2.8/building/by-layer/L3/async-operations) - Async patterns and status handling
* [Performance Optimization](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting) - Using delivery data for optimization
# get_media_buys
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/get_media_buys
get_media_buys task — retrieve media buy status in AdCP including creative approvals, missing assets, configuration, and optional near-real-time delivery snapshots.
Retrieve the current operational state of media buys: configuration, creative approval status, missing assets, and optional near-real-time delivery snapshots.
**Response Time**: \~1 second
## Scope of Results
Sales agents MUST return every media buy owned by the authenticated account, regardless of how the buy was created — via AdCP [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy), via the seller's own APIs, via manual trafficking, via legacy or third-party systems. Scope is **account ownership**, not creation surface. A `media_buy_id` returned here identifies any order in the seller's ad server accessible to the authenticated caller.
Any media buy returned by `get_media_buys` MUST be reachable by every task in its `valid_actions`. Sales agents MUST NOT mark a buy read-only, hide it, or refuse updates on the basis that it was not originally created via AdCP. When an action is unavailable for business reasons (contractual obligations, platform constraints, policy), the seller MUST omit only that action from `valid_actions` — never the whole set, and never merely because the buy was created outside AdCP. A seller that returns non-AdCP buys with a systematically empty `valid_actions` is non-conformant; that pattern is indistinguishable from hiding the buy.
Sellers that need to partition inventory away from a caller MUST do so at the **account boundary**, not within-account. See [Account Ownership vs. Creation Surface](/dist/docs/3.2.8/media-buy/specification#account-ownership-vs-creation-surface).
**Request Schema**: [`/schemas/3.2.8/media-buy/get-media-buys-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buys-request.json)
**Response Schema**: [`/schemas/3.2.8/media-buy/get-media-buys-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-media-buys-response.json)
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | [account-ref](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) | No | Account reference. Pass `{ "account_id": "..." }` or `{ "brand": {...}, "operator": "..." }` if the seller supports implicit resolution. When omitted, returns data across all accessible accounts. |
| `media_buy_ids` | string\[] | No\* | Array of media buy IDs to retrieve |
| `status_filter` | string \| string\[] | No | Status filter: `"pending_creatives"`, `"pending_start"`, `"active"`, `"paused"`, `"completed"`, `"rejected"`, `"canceled"`. Defaults to `["active"]` only when `media_buy_ids` is omitted. |
| `indicator_types` | string\[] | No | Return buys with at least one requested current indicator on the buy, a package, or a package–creative assignment. Buyers MUST request only advertised types; sellers MAY reject unsupported filtering with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature). |
| `include_snapshot` | boolean | No | When true, include near-real-time delivery snapshots for each package. Defaults to `false`. |
| `include_history` | integer | No | Include the last N revision history entries per media buy (returns min(N, available)). 0 or omit to exclude. Max 1000. |
| `include_webhook_activity` | boolean | No | When true, each media buy includes a `webhook_activity` array with recent delivery-report webhook fires for the calling principal. Defaults to `false`. See [Webhook activity](#webhook-activity). |
| `webhook_activity_limit` | integer | No | Per-buy cap on returned webhook records (most-recent first). Range 1–200, default 50. Ignored when `include_webhook_activity` is false. |
| `pagination` | object | No | Cursor-based pagination controls (`max_results`, `cursor`) for broad queries. |
\*`media_buy_ids` filters results to specific media buys. If neither is provided, the query is scope-based and uses `status_filter` + `pagination`.
When `media_buy_ids` are provided, no implicit status filtering is applied. Pass `status_filter` explicitly if you want to filter identified buys by status.
### Deterministic filter contract
Every returned `media_buys[]` row MUST have a `media_buy_id` in
`media_buy_ids` when that filter is present and a `status` in `status_filter`
when that filter is present. When both are supplied, both predicates apply to
every row, across every page. A seller MUST NOT accept a schema-valid filter and
return unfiltered account results.
A filter can validly leave the result unchanged when every accessible buy
already matches. Conformance is established from the returned rows' ID and
status membership—not by requiring filtered and unfiltered response payloads to
differ.
## Response
Returns an array of media buys with current status, creative approval state, and optionally delivery snapshots:
| Field | Description |
| - | - |
| `media_buys` | Array of media buy objects |
| `pagination` | Cursor pagination metadata (`has_more`, `cursor`, optional `total_count`) |
| `errors` | Task-specific errors (e.g., media buy not found) |
### Media Buy Object
> [!NOTE]
>
> **3.1 vocabulary note.** `get_media_buys` returns the lifecycle state on a nested `media_buys[].status` field (no envelope collision — nested at depth 1). [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) success responses return the same state on a top-level **`media_buy_status`** field (added in 3.1 to avoid colliding with the envelope task-status `status`). Same enum, two field names in 3.1 — the cascade unifies in 4.0 ([#4905](https://github.com/adcontextprotocol/adcp/issues/4905)). Buyers maintaining cross-call state should treat the two as the same logical value. See [Migration › `media_buy_status`](/dist/docs/3.2.8/reference/migration/media-buy-status) for the full picture.
| Field | Description |
| - | - |
| `media_buy_id` | Seller's media buy identifier |
| `name` | Persisted human-readable label for trafficking UI display and buyer-seller communication. Sellers MUST return it for AdCP-created buys that supplied `name`; it may be absent for external buys or buys created without one. It is not an identifier or financial reference. |
| `accepted_proposal_id` | Current immutable commercial snapshot used to begin [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals); present for compact-lifecycle buys. |
| `accepted_proposal_terms_digest` | Digest binding the current accepted proposal terms for recovery and governance verification. |
| `accepted_proposal` | Complete accepted canonical proposal for compact-lifecycle buys. Together with the ID and digest, this lets a restarted client refine the current commercial envelope without reconstructing historical offers. |
| `invoice_recipient` | Per-buy invoice recipient when provided at creation. Confirms the seller accepted the billing override. Bank details are omitted (write-only). |
| `status` | Current status (`pending_creatives`, `pending_start`, `active`, `paused`, `completed`, `rejected`, `canceled`). Maps to `media_buy_status` on `create_media_buy` / `update_media_buy` success responses (3.1 vocabulary note above). |
| `status_as_of` | ISO 8601 timestamp when the seller last refreshed the returned media-buy-level `status` from its source of truth. For rolled-up statuses, this MUST NOT be later than the oldest upstream status observation that could affect the returned roll-up. Optional; omitted or `null` makes no freshness assertion, and buyers MUST NOT infer live status from absence. Use this to interpret cached or rolled-up statuses separately from `updated_at`, which means the media buy's last modification time. |
| `currency` | ISO 4217 currency for media-buy-level monetary values |
| `total_budget` | Hard aggregate lifetime budget (in `currency`) |
| `daily_budget_cap` | Current hard aggregate spend ceiling per calendar day. It limits total buy spend without allocating package amounts. |
| `frequency_cap` | Current shared MediaBuy-level frequency cap, echoed whenever set. Its counter aggregates exposures across every participating package; each `packages[].targeting_overlay.frequency_cap` remains an independent counter. |
| `budget_cap_timezone` | Shared IANA calendar-day boundary for every aggregate and package daily cap. Present whenever any daily cap is set. |
| `budget_allocation` | Fixed or seller-optimized cross-package allocation configuration. Omission means fixed for legacy buys. |
| `pacing` | Aggregate media-buy pacing strategy |
| `bidding` | Media-buy-authored bidding policy. Packages that inherit it omit their own `bidding` block. |
| `creative_deadline` | Creative upload deadline (ISO 8601) |
| `confirmed_at` | ISO 8601 timestamp when the seller committed to this media buy. May be `null` until seller commitment occurs in deferred/manual approval flows; stable after it is set. |
| `cancellation` | Cancellation metadata (present only when `status` is `canceled`). Object with `canceled_at` (ISO 8601), `canceled_by` (`"buyer"` or `"seller"`), and optional `reason`. |
| `revision` | Current revision number. Pass in [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) or the 3.x `update_media_buy` facade for optimistic concurrency. |
| `valid_actions` | Actions the buyer can perform in the current state (e.g., `["pause", "cancel", "update_budget"]`). See [valid actions mapping](#valid-actions-mapping). |
| `available_actions` | Canonical routed actions for compact-lifecycle buys. Package-scoped actions may carry `applicable_package_ids`; omission means all relevant packages. Required whenever `accepted_proposal` is present. |
| `indicators` | Current buy-level seller indicators. In 3.2, `budget_constrained` is valid here. Sibling evaluation fields define exact type coverage and freshness. |
| `history` | Revision history entries, most recent first. Only present when `include_history > 0`. Append-only — entries are never modified or deleted. |
| `webhook_activity` | Recent delivery, health, `indicators.changed`, and `creative.assignment_changed` attempts relevant to this buy. Only present when requested and supported. |
| `context` | Opaque media-buy-level correlation data echoed unchanged from `create_media_buy`. Sellers MUST include persisted context when the media buy was created through AdCP with context, and MAY omit it for media buys created outside AdCP or without context. Use it to reconcile `media_buy_id` with buyer tracking state. |
| `packages` | Array of packages with creative status and optional snapshots |
### Package Object
| Field | Description |
| - | - |
| `package_id` | Seller's package identifier |
| `product_id` | Product identifier this package is purchased from. For packages created from an explicit `create_media_buy` package request, sellers MUST echo the request package's `product_id` on every response package object that represents that requested package. |
| `budget` | Hard lifetime package spend cap in `media_buy.currency`. In seller-optimized mode this is not a current allocation and may be absent. |
| `daily_budget_cap` | Optional subordinate hard package ceiling per shared media-buy cap day. It is not a reserved allocation. |
| `min_spend_target` | Soft lifetime package spend target in `media_buy.currency` accepted for seller-optimized allocation. |
| `pacing` | Package pacing preference. It is subordinate to media-buy aggregate `pacing` and cannot cause aggregate delivery to exceed that strategy. |
| `currency` | Legacy/external-buy package denomination. For AdCP-authored buys this equals `media_buy.currency`; it does not reinterpret canonical budget or bidding amounts. |
| `bidding` | Package-authored bidding override. `{automatic: true}` explicitly overrides media-buy controls; omission inherits media-buy `bidding`. |
| `bid_price` | Deprecated legacy bid representation; 3.2 sellers should normalize and echo `bidding`. |
| `optimization_goals` | Current package objective functions, separate from currency-bearing `bidding` policy. |
| `format_ids` | Legacy named-format IDs supplied on `create_media_buy`, echoed whenever the original request included them, including dual-emission cases where another selector won precedence. |
| `format_option_refs` | Structured 3.1+ format option references supplied on `create_media_buy`, echoed whenever the original request included them. |
| `format_kind` | Direct canonical selector supplied on `create_media_buy`, echoed whenever the original request included it, including informational-echo cases where another selector won precedence. |
| `params` | Parameters for the direct canonical selector in `format_kind`, echoed whenever the original request included them; requires `format_kind`. |
| `targeting_overlay` | Complete effective targeting currently applied to the package, including configured-product constraints and later buyer additions. Property, collection, and placement selection are represented here alongside audience and geography. |
| `targeting_resolution` | Generic targeting execution readback. When demographics were requested or applied, `targeting_resolution.demographics` contains the exact-only `equivalent: true` predicate, execution mechanism, and effective determination bases. Other targeting dimensions can evolve inside the same envelope. |
| `start_time` | Flight start time (ISO 8601). Check this before interpreting delivery status. |
| `end_time` | Flight end time (ISO 8601) |
| `paused` | Whether buyer has paused this package |
| `canceled` | Whether this package has been canceled (irreversible) |
| `cancellation` | Cancellation metadata (present only when `canceled` is true). Object with `canceled_at` (ISO 8601), `canceled_by` (`"buyer"` or `"seller"`), and optional `reason`. |
| `creative_deadline` | Per-package creative deadline (ISO 8601). When absent, the media buy's `creative_deadline` applies. |
| `context` | Opaque package-level correlation data echoed unchanged from the `create_media_buy` package request. Sellers MUST include persisted context when the package was created through AdCP with context, and MAY omit it for packages created outside AdCP or without context. Buyers targeting mixed seller populations can use the per-package correlation value they included on create, commonly `context.buyer_ref`, to map `package_id` back to their line items when a legacy create response did not echo `product_id`. |
| `creative_approvals` | Array of creative approval states (see below) |
| `indicators` | Current package-level seller indicators such as diversity, audience saturation, inventory forecast, pacing, or budget constraint |
| `formats_to_provide` | Immutable package-time `PackageFormatSnapshot` checklist. A contract-bearing snapshot remains present after creative coverage is complete and binds the effective Product declaration, product/option/placement identity, exact VAST/DAAST execution version, and contract/product digests used for assignment and serving. |
| `formats_pending` | Canonically equal subset of `formats_to_provide` that still lacks creative coverage. It may be empty even while the retained contract-bearing snapshot remains in `formats_to_provide`; omission means readiness was not reported. |
| `format_ids_pending` | **Deprecated in 3.2.** Legacy named-format projection of `formats_pending` for older 3.x peers. |
| `snapshot_unavailable_reason` | Reason code when `include_snapshot: true` but no snapshot is returned for this package |
| `snapshot` | Near-real-time delivery snapshot (when `include_snapshot: true`) |
### Creative Approval Object
| Field | Description |
| - | - |
| `creative_id` | Creative identifier |
| `approval_status` | `pending_review`, `approved`, `partially_approved`, or `rejected` |
| `rejection_reason` | Explanation of rejection (when `approval_status` is `rejected`) |
| `approval_scopes` | Complete publisher/placement outcomes when `approval_status` is `partially_approved` |
| `indicators` | Current seller indicators scoped to this package–creative relationship |
| `indicator_types_evaluated` | Exact indicator types covered by this snapshot; omitted types remain unknown |
| `indicators_as_of` | When the seller completed the evaluation represented by `indicators` |
| `indicators_evaluated_scope` | Optional publisher or placement coverage; omission means the whole assignment was evaluated |
Indicators are deliberately attached here rather than to the creative globally. A creative may be fatigued in one package or publisher context while remaining effective elsewhere.
```json theme={null}
{
"creative_id": "acme_summer_video",
"approval_status": "approved",
"indicator_types_evaluated": ["creative_fatigue"],
"indicators_as_of": "2026-08-04T12:00:00Z",
"indicators": [
{
"type": "creative_fatigue",
"detected_at": "2026-08-03T09:00:00Z"
}
]
}
```
The media buy itself may also carry `budget_constrained`; packages may carry `creative_diversity_low`, `audience_saturation`, `inventory_shortfall_forecast`, `pacing_risk`, or `budget_constrained`. Assignment types remain nested under `creative_approvals[]`. Omitted `indicators` is unknown; empty is evaluated-clear only for `indicator_types_evaluated` and declared coverage. See [Indicators and Warnings](/dist/docs/3.2.8/media-buy/media-buys/indicators).
For sellers that advertise `inline_creative_management` without a creative library, `creative_approvals` is the only standardized approval-state readback surface for the package's currently assigned inline creatives. It reports `creative_id`, aggregate `approval_status`, optional `rejection_reason`, and `approval_scopes` for mixed publisher outcomes, but it does not include the full `CreativeAsset` payload, placement routing, weights, or prior revisions submitted on `create_media_buy` or `update_media_buy`. Buyers should retain their own submitted creative bodies when integrating with inline-only sellers.
Creative revisions are represented as `approval_status: "rejected"` with a specific `rejection_reason`. There is no package-level `input-required` status for creative edits; upload corrected library assets via [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives), or corrected inline-only package assets via `packages[].creatives` on [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy).
### History Entry Object
| Field | Required | Description |
| - | - | - |
| `revision` | Yes | Revision number after this change was applied |
| `timestamp` | Yes | ISO 8601 timestamp when this change occurred |
| `action` | Yes | What happened: `created`, `activated`, `paused`, `resumed`, `canceled`, `rejected`, `completed`, `updated_budget`, `updated_dates`, `updated_packages`, `package_canceled`, `package_paused`, `package_resumed` |
| `actor` | No | Identity of who made the change (server-derived from auth context, not caller-provided) |
| `summary` | No | Human-readable description (e.g., "Budget changed from $5,000 to $7,500 on pkg_abc") |
| `package_id` | No | Package affected, when the change targeted a specific package |
History entries are **append-only** — sellers MUST NOT modify or delete previously emitted entries. Callers MAY cache entries by revision number.
`revision` increments only when the seller applies a mutating state change or update. Reads, validation-only calls, and exact idempotency replays do not create history entries or bump revision. Buyers should treat the returned revision as the token for their next `update_media_buy` call intended to change state.
`confirmed_at` is not a delivery status timestamp. It records seller commitment and remains stable through later pause/resume, activation, completion, cancellation, and reporting changes.
### Snapshot Object
| Field | Description |
| - | - |
| `as_of` | ISO 8601 timestamp when the platform captured this snapshot |
| `staleness_seconds` | Maximum data age in seconds. Use this to interpret zero delivery: 900 (15 min) means zero is likely real; 14400 (4 hr) means reporting may still be catching up. |
| `impressions` | Total impressions delivered since package start |
| `spend` | Total spend since package start |
| `currency` | Optional snapshot currency override for `spend` |
| `clicks` | Total clicks since package start (when available) |
| `pacing_index` | Delivery pace (1.0 = on track, \<1.0 = behind, >1.0 = ahead) |
| `delivery_status` | `delivering`, `not_delivering`, `completed`, `budget_exhausted`, `flight_ended`, `goal_met` |
| `ext` | Optional extension object for seller-specific operational fields |
**`not_delivering`** means the package is within its scheduled flight but has delivered zero impressions for at least one full staleness cycle. Implementers must not return `not_delivering` until `staleness_seconds` have elapsed since package activation — a new package with no impressions in its first minutes is expected, not a problem. Check `start_time` to confirm the package is within its flight before acting on this status.
For AdCP-authored buys, budget constraints and canonical bidding always use `media_buy.currency`. `snapshot.currency` identifies the reporting denomination for snapshot spend, and legacy/external buys may still carry `package.currency`; neither changes the denomination of buyer-authored 3.2 controls.
### Webhook Activity
When `include_webhook_activity: true`, each returned media buy MAY carry a `webhook_activity` array describing recent webhook fires relevant to that buy. It covers both per-buy reporting/health events and account-level `indicators.changed` or `creative.assignment_changed` invalidations whose payload names the buy. This is the buyer-side debug surface for the [persistent-channel webhook contract](/dist/docs/3.2.8/building/by-layer/L3/webhooks#persistent-channel-contract).
The record shape, request-field names, scoping, retention floor, three-state presence, and cardinality rules are uniform across AdCP resources that adopt this surface. See [Webhook activity log pattern](/dist/docs/3.2.8/protocol/snapshot-and-log#webhook-activity-log-pattern) on the snapshot/log contract page for the cross-resource normative section — the rules below restate it for the media-buy call site and add the media-buy-specific capability gate.
Per-buy delivery events (`scheduled`, `final`, `delayed`, `adjusted`, `window_update`) and health events (`impairment`) use the buy's `push_notification_config`; their `subscriber_id` may be absent in a single-subscriber setup. Indicator and assignment invalidations use account `notification_configs[]`; their `subscriber_id` is required. Support for the latter is declared by `media_buy.relationship_notifications`, including whether this activity log is available. All share the same webhook delivery contract and buyer-side debug need.
| Field | Description |
| - | - |
| `idempotency_key` | Equals the `idempotency_key` carried in the webhook payload itself ([§ Dedup by `idempotency_key`](/dist/docs/3.2.8/building/by-layer/L3/webhooks#dedup-by-idempotency_key)). Stable across retries of the same logical fire — buyers correlate this surface with their own endpoint logs via this exact field. Reference it when filing support tickets. |
| `notification_id` | Optional event-layer id copied from the webhook payload when the notification type defines one. Sellers SHOULD populate it on newly recorded attempts and MUST preserve the payload value when they do. It may be absent on retained records created before 3.2; point-in-time delivery-report fires do not define it. |
| `subscriber_id` | Identifies which registered webhook subscriber received this fire. Required for account-level indicator/assignment invalidations; may be absent for a single per-buy subscriber. Per-buy channels populate it once they support multiple subscribers (4.0+, see [#3009](https://github.com/adcontextprotocol/adcp/issues/3009)). |
| `fired_at` | ISO 8601 timestamp when the seller initiated this attempt. |
| `completed_at` | ISO 8601 timestamp when the response was observed (or terminal failure). Null while `status` is `pending`. |
| `notification_type` | Verbatim from the webhook payload: `scheduled`, `final`, `delayed`, `adjusted`, `window_update`, `impairment`, `indicators.changed`, or `creative.assignment_changed`. |
| `sequence_number` | Sequence number from the webhook payload — useful for spotting stale-sequence drops or gaps. Absent when the notification type does not carry one. |
| `attempt` | 1-indexed retry counter for this logical fire. Initial fire is `attempt: 1`. |
| `status` | `success`, `failed`, `timeout`, `connection_error`, or `pending`. See semantics below. |
| `url` | Target URL with **query string and fragment stripped**, and high-entropy / token-shaped path segments redacted. Match this against your registered URL by origin + path, not full URL. |
| `http_status_code` | HTTP status from the buyer's endpoint. Null when no HTTP response was received (`timeout`, `connection_error`, `pending`). |
| `response_time_ms` | Wall-clock latency between request send and response receipt. Null for non-completed attempts. |
| `payload_size_bytes` | Size of the request body the seller sent — useful for diagnosing oversized-payload rejections. |
| `error_message` | Short human-readable server-side classification of failure. Null for `success`. Sellers MUST NOT include request / response bodies or headers here. |
**Status semantics:**
* `success` — response received with a 2xx status. `http_status_code` populated.
* `failed` — response received with a non-2xx status. `http_status_code` populated; `error_message` describes the response.
* `timeout` — no response within the seller's configured timeout. `http_status_code` null. Operationally: the buyer's endpoint is reachable but slow / overloaded.
* `connection_error` — DNS, TLS, or socket failure before any HTTP response. `http_status_code` null. Operationally: the buyer's endpoint is unreachable or misconfigured.
* `pending` — attempt is in flight or queued for retry. `completed_at` is null; subsequent attempts appear with the same `idempotency_key` and incremented `attempt`.
**Record cardinality:** one record per attempt. A successful first-attempt fire appears as a single record with `attempt: 1`. A 3-attempt retry trail (e.g., two failures then a success) appears as three records sharing `idempotency_key`.
**Scoping (normative):**
* `webhook_activity` MUST be scoped to the **calling principal**. When multiple buyer principals share visibility into the same media buy via account-level access, each principal sees only fires targeting its own endpoint.
* Sellers that surface this field **MUST** retain records for at least 30 days from each record's `completed_at` — uniformly across `success`, `failed`, `timeout`, and `connection_error` outcomes (all of which populate `completed_at`). For records still in `pending` status, the clock runs from `fired_at` until the attempt terminates and then transitions to 30 days from `completed_at` — retry trails do not age out mid-flight. Sellers that cannot honor this floor MUST omit the field entirely rather than return a shorter window; the three-state presence semantics give them a clean opt-out and buyers a single guarantee they can build against.
* This surface is a debug aid, not a full audit log. There is no cursor for older fires beyond `webhook_activity_limit` — buyers needing full history must persist webhook records on their own side.
**Three-state presence semantics:**
| State | Meaning |
| - | - |
| Field **omitted** | Seller does not surface an applicable activity log for this buy. Neither a declared per-buy webhook surface nor `media_buy.relationship_notifications.supports_webhook_activity` provides one, no relevant subscriber is registered, or the seller does not persist fire history. |
| Empty array `[]` | Seller persists fire history but has fired nothing recent for this principal. |
| Non-empty array | Actual fire records, most-recent first. |
For per-buy events, sellers whose declared `propagation_surfaces` excludes `webhook` omit those records. That does not suppress account-level indicator/assignment records when `media_buy.relationship_notifications.supports_webhook_activity` is true.
**Diagnosing an unexpected omission.** For a per-buy event, check the buy's `push_notification_config` and the seller's `capabilities.media_buy.propagation_surfaces` via [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). For an indicator or assignment event, check the account's `notification_configs[]` and `media_buy.relationship_notifications.supports_webhook_activity`. If the relevant registration and capability both check out, omission is a seller-side persistence gap and warrants an operator ticket.
**Privacy:**
* The `url` field has its query string and fragment **stripped**, and sellers SHOULD redact path segments resembling shared secrets (high-entropy random material, UUID / token shapes).
* Request and response bodies are **not surfaced** by this field. A future `include_webhook_payloads` extension may add them under stricter authorization controls — out of scope here.
* `error_message` is a server-side classification string only — never request headers, never response bodies, never buyer-endpoint stack traces.
#### Diagnose a webhook delivery problem
```typescript TypeScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuysResponseSchema, type WebhookActivityRecord } from '@adcp/sdk';
// The WebhookActivityRecord type is regenerated by the SDK from
// /schemas/core/webhook-activity-record.json — once the SDK rebuilds against this
// branch's schemas the import resolves. The same type appears on every AdCP resource
// that surfaces webhook_activity[], so debug helpers can be written once and reused.
function latestAttempt(trail: WebhookActivityRecord[]): WebhookActivityRecord {
return trail.reduce((a, b) => (a.attempt >= b.attempt ? a : b));
}
const result = await testAgent.getMediaBuys({
media_buy_ids: ['mb_12345'],
include_webhook_activity: true,
webhook_activity_limit: 20,
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuysResponseSchema.parse(result.data);
for (const mediaBuy of validated.media_buys) {
// Three-state semantics — distinguish "seller does not surface" from "no recent fires".
if (mediaBuy.webhook_activity === undefined) {
console.log(`${mediaBuy.media_buy_id}: seller does not surface webhook activity for this buy`);
continue;
}
const fires = mediaBuy.webhook_activity;
if (fires.length === 0) {
console.log(`${mediaBuy.media_buy_id}: no recent fires for this principal`);
continue;
}
// Group attempts by idempotency_key so we can see the retry trail per logical fire.
const trails = new Map();
for (const fire of fires) {
const trail = trails.get(fire.idempotency_key) ?? [];
trail.push(fire);
trails.set(fire.idempotency_key, trail);
}
for (const [idempotencyKey, trail] of trails) {
// Pick the latest attempt by `attempt` number — robust against any iteration order.
const latest = latestAttempt(trail);
if (latest.status === 'success') continue;
const detail = latest.error_message ?? latest.http_status_code ?? '—';
console.log(
`${mediaBuy.media_buy_id} ${idempotencyKey} ` +
`(${latest.notification_type} seq=${latest.sequence_number}): ` +
`${latest.status} after ${trail.length} attempt(s) — ${detail}`
);
}
}
```
```python Python theme={null}
import asyncio
from collections import defaultdict
from adcp.testing import test_agent
from adcp.types import GetMediaBuysRequest, WebhookActivityRecord
# WebhookActivityRecord is regenerated by the SDK from
# /schemas/core/webhook-activity-record.json — once the SDK rebuilds against this
# branch's schemas the import resolves. The same type appears on every AdCP resource
# that surfaces webhook_activity[].
def latest_attempt(trail: list[WebhookActivityRecord]) -> WebhookActivityRecord:
return max(trail, key=lambda f: f.attempt)
async def main():
result = await test_agent.get_media_buys(
GetMediaBuysRequest(
media_buy_ids=['mb_12345'],
include_webhook_activity=True,
webhook_activity_limit=20,
)
)
for media_buy in result.media_buys:
# Three-state semantics: distinguish "seller does not surface" from "no recent fires".
if media_buy.webhook_activity is None:
print(f"{media_buy.media_buy_id}: seller does not surface webhook activity for this buy")
continue
fires = media_buy.webhook_activity
if not fires:
print(f"{media_buy.media_buy_id}: no recent fires for this principal")
continue
trails = defaultdict(list)
for fire in fires:
trails[fire.idempotency_key].append(fire)
for idempotency_key, trail in trails.items():
latest = latest_attempt(trail)
if latest.status == 'success':
continue
detail = latest.error_message or latest.http_status_code or '—'
print(f"{media_buy.media_buy_id} {idempotency_key} "
f"({latest.notification_type} seq={latest.sequence_number}): "
f"{latest.status} after {len(trail)} attempt(s) — {detail}")
asyncio.run(main())
```
## Valid Actions Mapping
The `valid_actions` array tells agents what operations are permitted on a media buy in its current state. Sellers SHOULD include this field. Expected values by status:
| Status | Expected `valid_actions` |
| - | - |
| `pending_creatives` | `pause`, `cancel`, [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) |
| `pending_start` | `pause`, `cancel`, `sync_creatives` |
| `active` | `pause`, `cancel`, `update_budget`, `update_dates`, `update_packages`, `add_packages`, `sync_creatives` |
| `paused` | `resume`, `cancel`, `update_budget`, `update_dates`, `update_packages`, `add_packages`, `sync_creatives` |
| `completed` | *(empty array)* |
| `rejected` | *(empty array)* |
| `canceled` | *(empty array)* |
Sellers MAY omit actions based on business rules (e.g., omit `cancel` when the media buy has contractual obligations that prevent cancellation).
For creative changes, `sync_creatives` in `valid_actions` is a legacy creative-change action label, not proof that the `sync_creatives` task exists. Use the creative path the seller advertises: `sync_creatives` and `creative_assignments` for sellers with `creative.has_creative_library: true`, or `packages[].creatives` on [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) for inline-only sellers.
## Common Scenarios
### Check creative approval status
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuysResponseSchema } from '@adcp/sdk';
const result = await testAgent.getMediaBuys({
media_buy_ids: ['mb_12345']
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuysResponseSchema.parse(result.data);
if (validated.errors?.length > 0) {
throw new Error(`Query failed: ${JSON.stringify(validated.errors)}`);
}
for (const mediaBuy of validated.media_buys) {
for (const pkg of mediaBuy.packages) {
// Check for missing creatives
if (pkg.formats_pending?.length > 0) {
const labels = pkg.formats_pending.map(f => f.format_option_id ?? f.format_kind);
console.log(`Package ${pkg.package_id}: missing formats ${labels.join(', ')}`);
}
// Check approval states
for (const approval of pkg.creative_approvals ?? []) {
if (approval.approval_status === 'rejected') {
console.log(`Creative ${approval.creative_id} rejected: ${approval.rejection_reason}`);
} else if (approval.approval_status === 'partially_approved') {
console.log(`Creative ${approval.creative_id} has mixed publisher approval`, approval.approval_scopes);
} else if (approval.approval_status === 'pending_review') {
console.log(`Creative ${approval.creative_id} pending review`);
}
}
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuysRequest
async def main():
result = await test_agent.get_media_buys(
GetMediaBuysRequest(media_buy_ids=['mb_12345'])
)
if result.errors:
raise Exception(f"Query failed: {result.errors}")
for media_buy in result.media_buys:
for pkg in media_buy.packages:
# Check for missing creatives
if pkg.formats_pending:
labels = [f.format_option_id or f.format_kind for f in pkg.formats_pending]
print(f"Package {pkg.package_id}: missing formats {', '.join(labels)}")
# Check approval states
for approval in pkg.creative_approvals or []:
if approval.approval_status == 'rejected':
print(f"Creative {approval.creative_id} rejected: {approval.rejection_reason}")
elif approval.approval_status == 'partially_approved':
print(f"Creative {approval.creative_id} has mixed publisher approval: {approval.approval_scopes}")
elif approval.approval_status == 'pending_review':
print(f"Creative {approval.creative_id} pending review")
asyncio.run(main())
```
### Monitor delivery with snapshots
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuysResponseSchema } from '@adcp/sdk';
const result = await testAgent.getMediaBuys({
status_filter: 'active',
include_snapshot: true
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuysResponseSchema.parse(result.data);
for (const mediaBuy of validated.media_buys) {
for (const pkg of mediaBuy.packages) {
const snap = pkg.snapshot;
if (!snap) continue;
if (snap.delivery_status === 'not_delivering') {
console.log(`Package ${pkg.package_id}: zero delivery (data up to ${snap.staleness_seconds}s old)`);
} else if (snap.pacing_index !== undefined && snap.pacing_index < 0.8) {
console.log(`Package ${pkg.package_id}: underpacing at ${(snap.pacing_index * 100).toFixed(0)}%`);
} else {
console.log(`Package ${pkg.package_id}: ${snap.impressions.toLocaleString()} impressions, pacing ${snap.pacing_index?.toFixed(2)}`);
}
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuysRequest
async def main():
result = await test_agent.get_media_buys(
GetMediaBuysRequest(
status_filter='active',
include_snapshot=True
)
)
if result.errors:
raise Exception(f"Query failed: {result.errors}")
for media_buy in result.media_buys:
for pkg in media_buy.packages:
snap = pkg.snapshot
if not snap:
continue
if snap.delivery_status == 'not_delivering':
print(f"Package {pkg.package_id}: zero delivery (data up to {snap.staleness_seconds}s old)")
elif snap.pacing_index is not None and snap.pacing_index < 0.8:
print(f"Package {pkg.package_id}: underpacing at {snap.pacing_index * 100:.0f}%")
else:
print(f"Package {pkg.package_id}: {snap.impressions:,} impressions, pacing {snap.pacing_index:.2f}")
asyncio.run(main())
```
### Campaign readiness check
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
import { GetMediaBuysResponseSchema } from '@adcp/sdk';
const result = await testAgent.getMediaBuys({
media_buy_ids: ['mb_12345']
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = GetMediaBuysResponseSchema.parse(result.data);
const [mediaBuy] = validated.media_buys;
const issues = [];
for (const pkg of mediaBuy.packages) {
if (pkg.formats_pending?.length > 0) {
issues.push(`Package ${pkg.package_id}: ${pkg.formats_pending.length} format(s) not yet uploaded`);
}
const rejected = (pkg.creative_approvals ?? []).filter(a => a.approval_status === 'rejected');
if (rejected.length > 0) {
issues.push(`Package ${pkg.package_id}: ${rejected.length} creative(s) rejected`);
}
}
if (issues.length === 0) {
console.log('Campaign ready to launch');
} else {
console.log('Campaign has blocking issues:');
issues.forEach(issue => console.log(` - ${issue}`));
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
from adcp.types import GetMediaBuysRequest
async def main():
result = await test_agent.get_media_buys(
GetMediaBuysRequest(media_buy_ids=['mb_12345'])
)
media_buy = result.media_buys[0]
issues = []
for pkg in media_buy.packages:
if pkg.formats_pending:
issues.append(f"Package {pkg.package_id}: {len(pkg.formats_pending)} format(s) not yet uploaded")
rejected = [a for a in (pkg.creative_approvals or []) if a.approval_status == 'rejected']
if rejected:
issues.append(f"Package {pkg.package_id}: {len(rejected)} creative(s) rejected")
if not issues:
print("Campaign ready to launch")
else:
print("Campaign has blocking issues:")
for issue in issues:
print(f" - {issue}")
asyncio.run(main())
```
## Snapshot vs. `get_media_buy_delivery`
| | `get_media_buys` (with snapshot) | [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) |
| - | - | - |
| **Purpose** | Operational monitoring | Reporting and reconciliation |
| **Freshness** | Minutes (entity-level stats) | Hours (batch report jobs) |
| **Accuracy** | Best-effort | Authoritative, billing-grade |
| **Date range** | Always "since campaign start" | Configurable period |
| **Daily breakdown** | No | Yes |
| **Creative status** | Yes | No |
| **Missing assets** | Yes | No |
Use `get_media_buys` to answer "what is the current state of my campaigns?" and `get_media_buy_delivery` for "how did my campaigns perform over a period?"
Status taxonomy is shared for lifecycle filters across both tasks (`pending_creatives`, `pending_start`, `active`, `paused`, `completed`). `get_media_buy_delivery` may additionally return reporting-only statuses (`reporting_delayed`, `failed`) in webhook contexts.
## Data Freshness
Snapshot `staleness_seconds` varies by platform:
| Platform type | Typical `staleness_seconds` |
| - | - |
| Entity-level stats (e.g., GAM LineItemService) | 900 (15 min) |
| Near-real-time insights API | 60–300 |
| Batch-only reporting | 14400 (4 hr) |
When the platform only has batch reporting, the seller agent should return the most recent cached data with the appropriate `staleness_seconds`.
If `include_snapshot: true` and `snapshot` is omitted for a package, check `snapshot_unavailable_reason`:
* `SNAPSHOT_UNSUPPORTED`: the seller does not support package snapshots for this integration
* `SNAPSHOT_TEMPORARILY_UNAVAILABLE`: snapshot pipeline is delayed or degraded; retry later
* `SNAPSHOT_PERMISSION_DENIED`: caller lacks permission to view snapshot metrics for that package
## Pagination
Use cursor pagination for broad status queries to avoid large payloads:
* Request: set `pagination.max_results` (1-100, default 50) and optional `pagination.cursor`
* Response: read `pagination.has_more`; when true, pass `pagination.cursor` into the next request
* ID-targeted queries (`media_buy_ids`) can omit pagination unless the ID set is very large
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`MEDIA_BUY_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-media-buy-not-found) | Media buy ID does not exist | Verify `media_buy_id` |
| [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing) | No credentials presented | Provide credentials via auth header |
| [`AUTH_INVALID`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-invalid) | Credentials rejected (expired / revoked) | Human credential rotation required; do not auto-retry |
A valid query with no matching media buys succeeds with an empty `media_buys` array.
## Next Steps
* **Upload missing creatives**: Use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) for library-backed sellers, or `packages[].creatives` on [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) for inline-only sellers
* **Investigate zero delivery**: Check `delivery_status: "not_delivering"` and `start_time` to confirm the flight is active, then use [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) to adjust pricing or targeting
* **Detailed reporting**: Use [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) for date-range reporting and daily breakdowns
* **Optimize campaigns**: Use [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) to share results with the seller
# get_products
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/get_products
get_products task — discover advertising inventory in AdCP using natural language campaign briefs or structured filters. Returns matched products with pricing and formats.
Discover available advertising products based on campaign requirements using natural language briefs or structured filters.
> [!WARNING]
>
> `get_products` is deprecated for new integrations in AdCP 3.2, but remains fully supported throughout 3.x. Use [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products), [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals), [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals), or [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals). Its `idempotency_key` remains optional. Split-task retries keep the same tool name; they are not cross-name replays of this compatibility facade.
> [!NOTE]
>
> **Opportunity context on AdCP 3.2 (non-normative guidance).** Buyers and sellers that support the AdCP-owned [`ext.adcp.opportunity` binding](https://github.com/adcontextprotocol/adcp/blob/main/docs/building/by-layer/L2/context-sessions.mdx#adcp-opportunity-extension) can carry planning-cycle context through the existing `ext` object. Confirm support for this specific binding through `get_adcp_capabilities.extensions_supported` before relying on seller-side association.
>
> This example uses a seller-issued account ID and the unchanged [published 3.2.1 OpportunityContext](https://adcontextprotocol.org/schemas/3.2.1/core/opportunity-context.json). It validates against the published 3.2.1 request schema, so adopting the binding does not require a protocol upgrade to 3.2.2:
>
> ```json theme={null}
> {
> "$schema": "https://adcontextprotocol.org/schemas/3.2.1/media-buy/get-products-request.json",
> "buying_mode": "brief",
> "brief": "Video inventory for a spring launch.",
> "account": {
> "account_id": "acc_spring_launch"
> },
> "ext": {
> "adcp": {
> "opportunity": {
> "opportunity_id": "opp_spring_launch"
> }
> }
> }
> }
> ```
>
> The base request's open `ext` schema admits the namespace without validating the nested opportunity object. The linked extension agreement covers inner validation, authorized account scope, and proposal association; coordinate buyer and seller adoption of that agreement. This guidance adds no baseline 3.2 conformance requirement. New integrations can already carry core `opportunity` on [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals).
> [!NOTE]
>
> **Why this shape.** Targeting, pricing, and curation are folded into one round-trip — the brief drives discovery, the publisher curates against it, and `pricing_options` carry firm prices the buyer commits against via `pricing_option_id`. We rejected a separate `get_price_quote` step between products and buy creation: it splits one expert decision into two underspecified ones and breaks the brief→curation contract. Iteration is `buying_mode: "refine"` with a typed change array — not a new task. → [Design principle: the brief drives discovery](/dist/docs/3.2.8/protocol/design-principles#3-the-brief-drives-discovery-targeting-is-an-input-not-a-step).
**Authentication**: Optional (returns limited results without credentials)
**Response Time**: \~60 seconds (AI inference with back-end systems)
**Request Schema**: [`/schemas/3.2.8/media-buy/get-products-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-request.json)
**Response Schema**: [`/schemas/3.2.8/media-buy/get-products-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-response.json)
## Quick Start
Discover products with a natural language brief:
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441000',
buying_mode: 'brief',
brief: 'Premium athletic footwear with innovative cushioning',
brand: {
domain: 'acmecorp.com'
}
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
// result.data is the get_products response: a discriminated union on status
const response = result.data;
if (response.status === 'rejected') {
console.log(`Seller declined the brief: ${response.reason}`);
for (const suggestion of response.suggestions ?? []) {
console.log(`- ${suggestion}`);
}
} else {
console.log(`Found ${response.products.length} products`);
for (const product of response.products) {
console.log(`- ${product.name} (${product.delivery_type})`);
console.log(` Formats: ${product.format_options.map(option => option.format_kind).join(', ')}`);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_products():
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441001',
buying_mode='brief',
brief='Premium athletic footwear with innovative cushioning',
brand={
'domain': 'acmecorp.com'
}
)
if result.status == 'rejected':
print(f"Seller declined the brief: {result.reason}")
for suggestion in result.suggestions or []:
print(f"- {suggestion}")
else:
print(f"Found {len(result.products)} products")
asyncio.run(discover_products())
```
```bash CLI requires-env=ADCP_AUTH_TOKEN theme={null}
uvx adcp \
https://test-agent.adcontextprotocol.org/sales/mcp \
get_products \
'{"idempotency_key":"550e8400-e29b-41d4-a716-446655441002","buying_mode":"brief","brief":"Premium athletic footwear with innovative cushioning","brand":{"domain":"acmecorp.com"}}' \
--auth $ADCP_AUTH_TOKEN
```
### Using Structured Filters
Use structured filters for hard product requirements such as channel, delivery type, format, currency, and reporting support. Filters are valid and have the same exclusion semantics in `brief`, `wholesale`, and `refine` modes; the mode changes curation and lifecycle behavior, not whether filters apply. Concrete delivery targeting belongs in `targeting_overlay`; future selectable targeting belongs in `required_overlay_support`.
For every deterministic predicate in `filters`, every returned product MUST
satisfy that predicate according to the field's documented match semantics.
Sellers MUST exclude non-matching products in all three buying modes; they MUST
NOT accept a schema-valid filter and return the unfiltered curated set, wholesale
feed, or refinement result. A filter can validly produce the same result as an
unfiltered request, so conformance is established from the returned products'
membership and field values—not merely by requiring two responses to differ.
Natural-language relevance to a `brief` remains a curation judgment and is not
part of this deterministic filter rule.
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
const result = await testAgent.getProducts({
buying_mode: 'brief',
brief: 'Premium connected-TV inventory for a national launch',
brand: {
domain: 'acmecorp.com'
},
filters: {
channels: ['ctv'],
delivery_type: 'guaranteed',
standard_formats_only: true
}
});
if (result.success && result.data) {
console.log(`Found ${result.data.products.length} guaranteed CTV products`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_with_filters():
result = await test_agent.simple.get_products(
buying_mode='brief',
brief='Premium connected-TV inventory for a national launch',
brand={
'domain': 'acmecorp.com'
},
filters={
'channels': ['ctv'],
'delivery_type': 'guaranteed',
'standard_formats_only': True
}
)
print(f"Found {len(result.products)} guaranteed CTV products")
asyncio.run(discover_with_filters())
```
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `idempotency_key` | string | No | Optional on every arm of this 3.x compatibility facade. A seller MAY ignore it on a guaranteed side-effect-free synchronous read. Buyers SHOULD supply it whenever the request may allocate a task, finalize a proposal, or otherwise change observable state. When supplied and the seller declares `adcp.idempotency.supported: true`, the seller applies replay before the effect. If the key is omitted or the seller declares `adcp.idempotency.supported: false`, an ambiguous result has no portable at-most-once retry guarantee. The key is 16–255 characters using letters, digits, `_`, `.`, `:`, and `-`. Retry a replay-protected operation with the same key and exact payload. Poll the resulting task through [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) or MCP task APIs without reusing this operation key. Use a new key whenever any request parameter changes. |
| `buying_mode` | string | Yes | `"brief"`, `"wholesale"`, or `"refine"`. `"brief"`: publisher curates products from the brief. `"wholesale"`: raw product feed access for buyer-directed targeting, `brief` must not be provided. `"refine"`: iterate on products and proposals from a previous response using the `refine` array of change requests. v3 clients MUST include `buying_mode`. Sellers receiving requests from pre-v3 clients without `buying_mode` SHOULD default to `"brief"`. **Timing semantics:** `"wholesale"` is a wholesale product feed read — sellers SHOULD return a synchronous response and MUST NOT route a `"wholesale"` request through the async/Submitted arm. Partial completion is signalled via [`incomplete[]`](#incomplete-array), not a task handoff. `"brief"` and `"refine"` MAY complete synchronously OR MAY return a `Submitted` envelope when curation requires upstream-system queries or HITL review the seller cannot complete inside `time_budget`. Buyers needing predictable fast wholesale product feed access MUST use `"wholesale"`. |
| `brief` | string | Conditional | Natural-language campaign goals, context, preferences, and requirements without a structured representation. Required when `buying_mode` is `"brief"`. Must not be provided when `buying_mode` is `"wholesale"` or `"refine"`. Explicit hard requirements remain binding, but buyers SHOULD use an available structured field instead. When a seller's structured interpretation of hard prose materially affects eligibility, pricing, or forecasting, the response MUST confirm it in `targeting_resolution.brief_targeting`. |
| `refine` | [Refine\[\]](#refine-array) | Conditional | Array of change requests for iterating on products and proposals. Required when `buying_mode` is `"refine"`. Must not be provided when `buying_mode` is `"brief"` or `"wholesale"`. See [Refine array](#refine-array) below. |
| `brand` | BrandRef | No | Brand reference (domain + optional brand_id). Resolved to full identity at execution time. |
| `account` | AccountRef | No | Account reference for account-specific pricing. Returns products with pricing from this account's rate card. The account must already be provisioned: a reference that doesn't resolve returns [`ACCOUNT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-account-not-found), not public products, unless the seller provisions lazily. Omit it before [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) succeeds. See [Account references before provisioning](/dist/docs/3.2.8/accounts/overview#account-references-before-provisioning). |
| `catalog` | [Catalog](/dist/docs/3.2.8/creative/catalogs) | No | Catalog of items the buyer wants to promote. The seller matches catalog items against its inventory and returns products where matches exist. Requires `brand`. See [Catalog discovery](#catalog-discovery) below. |
| `filters` | Filters | No | Offer filters such as channel, format, delivery type, dates, budget, currency, and reporting support. They decide which products may be returned but do not become package delivery targeting. Valid in `brief`, `wholesale`, and `refine`; non-matching products are excluded in every mode. Legacy targeting-like fields remain accepted during migration but are deprecated. |
| `targeting_overlay` | TargetingOverlay | No | Concrete delivery constraints the buyer expects to carry into [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy). Prefer this over equivalent brief prose: it is compact, deterministic, and avoids lossy extraction. Returned products, pricing, and forecasts MUST account for the effective targeting. A product that cannot honor the request exactly is omitted or returned with sparse Product `targeting_resolution.modifications`; absence of Product resolution confirms exact acceptance of the structured overlay for that product. |
| `media_buy_frequency_cap` | MediaBuyFrequencyCap | No | Exact aggregate max-impression cap intended for the MediaBuy root. Every returned product must support one shared counter for it, so when the value is known this field alone suffices. Legacy `get_products` proposals echo it as `frequency_cap`; compact proposals carry it in `commercial_terms.frequency_cap`. |
| `required_overlay_support` | TargetingOverlayRequirements | No | Buyer minimums for targeting dimensions whose values will be supplied on packages later. This requests selectable capability, not current values, value-specific availability or forecasts, and not one product per value. Requirement `true` matches support `true` or any valid support object; an object requirement matches `true` or a containing support object. The daypart exception is that legacy `daypart_targets: true` satisfies only `inventory_local`, not `iana`, requirements. Unrequested fields and numeric seller limits do not participate. Missing or unknown requirements exclude the product. For frequency caps, send `frequency_cap_support` (an empty object requests any support); it also matches legacy `frequency_cap: true`. A requirement carrying both fields is rejected by the schema, because `frequency_cap: true` matches only the broad legacy declaration and would exclude every product that declares constraints. |
| `required_media_buy_support` | MediaBuySupportRequirements | No | Product participation required for shared MediaBuy controls when the exact cap is not yet known. `frequency_cap: true` requires aggregate-counter participation; sibling constraints use subset containment after seller-wide inheritance. |
| `fields` | string\[] | No | Specific product fields to include for lightweight discovery. `product_id` and `name` are always included; request `identity` to receive the experimental product-scoped identity declaration, and `execution_requirements` to receive the experimental resources a package needs before creation. Request `audience_evidence` for the full evidence payload. Projection never suppresses required decision readback: modified products include `targeting_resolution` and `expires_at`; a request with `required_overlay_support` receives `overlay_support`; and when an audience-evidence policy affects inclusion or ranking, the seller returns `audience_evidence_selections`. When requesting signal metadata, buyers SHOULD request `included_signals` for bundled/planned signals and the `signal_targeting_*` fields for package-level selection. A request with `required_media_buy_support` or `media_buy_frequency_cap` receives `media_buy_support`. |
| `property_list` | PropertyListRef | No | Deprecated discovery-only property filter. Use `targeting_overlay.property_list` for a concrete delivery constraint or `required_overlay_support.property_list` when the list will be selected later. |
| `pagination` | PaginationRequest | No | Cursor-based pagination to cap returned `products[]` in curated/refined responses or walk wholesale product feeds (see below) |
| `if_wholesale_feed_version` | string | No | Opaque `wholesale_feed_version` token from a prior wholesale-mode `get_products` response from this agent. Only valid with `buying_mode: "wholesale"`. Version scope excludes `pagination.cursor`: `public` is keyed by (agent, `buying_mode`, `filters`, `targeting_overlay`, `media_buy_frequency_cap`, `required_overlay_support`, `required_media_buy_support`, deprecated `property_list`, `catalog`); `account` adds account identity. See [Wholesale feed versioning](#wholesale-feed-versioning). |
| `if_pricing_version` | string | No | Opaque `pricing_version` token from a prior response. MUST only be sent together with `if_wholesale_feed_version`. Evaluation order: `if_wholesale_feed_version` mismatch → full payload; `if_wholesale_feed_version` matches but `if_pricing_version` mismatches → full payload (so the buyer sees updated `pricing_options`); both match → seller MAY return `unchanged: true`. Sellers that don't track pricing separately ignore this. |
| `time_budget` | Duration | No | Maximum time the buyer will commit to this request. The seller returns the best results achievable within this budget and does not start processes (human approvals, expensive external queries) that cannot complete in time. When omitted, the seller decides timing. Example: `{"interval": 30, "unit": "seconds"}`. |
| `push_notification_config` | PushNotificationConfig | No | Optional webhook channel for async terminal completion/failure notifications on `brief` / `refine` curated discovery. `submitted` responses with a `task_id` remain pollable through [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) (legacy `tasks/get`) whether or not this field is present. If the request includes this field and the seller returns `submitted`, the seller MUST deliver at least the terminal completion/failure notification to the configured webhook; intermediate progress notifications are MAY. If the seller cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. Ignored for `wholesale`; sellers MUST NOT route wholesale reads through the Submitted arm because this field is present. |
> [!NOTE]
>
> ### Targeting-aware discovery
>
> #### Brief versus structured targeting
>
> Anything that can be expressed in a structured request field SHOULD be. For
> example, put “US only” and “ages 18–44” in `targeting_overlay`, not just in the
> brief. Structured values use fewer tokens, can be validated by code, and do not
> lose meaning through natural-language extraction. Keep the brief for campaign
> goals, semantic audience descriptions, preferences, and requirements for which
> AdCP has no structured field.
>
> Hard requirements remain hard wherever they appear. A seller MUST apply an
> explicit hard targeting requirement stated only in a brief. When the seller's
> structured interpretation materially affects product eligibility, pricing, or
> forecasting, it MUST confirm that shared interpretation once on the response;
> otherwise confirmation remains a best practice:
>
> ```json theme={null}
> {
> "targeting_resolution": {
> "brief_targeting": {
> "geo_countries": ["US"],
> "demographics": {
> "age": { "min": 18, "max": 44, "include_unknown": false }
> }
> }
> }
> }
> ```
>
> This is a confirmation of brief-derived targeting, not a reason to echo a
> structured overlay. When `targeting_overlay` already contains those values and
> the seller accepts them exactly, the response omits them. Selecting any product
> from the response accepts the confirmed request-level brief interpretation;
> product-specific alternatives remain sparse Product targeting modifications.
>
> Only predicates supported by the structured targeting vocabulary can appear in
> `brief_targeting`. Other hard prose requirements remain binding but must be
> confirmed in the seller's natural-language response until AdCP defines a typed
> representation.
>
> Provide exact targeting once during discovery so product availability, pricing,
> and forecasts already reflect the constraints that will be booked:
>
> ```json theme={null}
> {
> "buying_mode": "brief",
> "brief": "Premium national video for outdoor enthusiasts",
> "filters": {
> "channels": ["ctv"],
> "delivery_type": "guaranteed",
> "pricing_currencies": ["USD"]
> },
> "targeting_overlay": {
> "geo_countries": ["US"]
> },
> "required_overlay_support": {
> "geo_metros": { "systems": ["nielsen_dma"] },
> "placement_selection": true
> }
> }
> ```
>
> `targeting_overlay` is real targeting. The seller resolves it through inherent
> product scope or selectable execution, and every returned forecast is scoped to
> the resulting inventory. `required_overlay_support` says that the buyer needs to
> choose DMA and placement values on packages later; it does not request products
> or packages broken out by DMA or placement.
>
> Request requirements and product support deliberately use different schemas.
> The buyer request contains dimensions and required systems, never seller maxima.
> A requirement value of `true` matches product support `true` or any valid
> support object. An object requirement matches support `true` or a support object
> where every requested boolean is true and every requested array is a subset of
> the corresponding product array. For frequency caps, a product field omitted
> from `frequency_cap_support` inherits the seller-wide `frequency_capping`
> declaration before the subset test, and a requested window or suppression unit
> matches when the resolved unit list contains it; exact count and interval
> acceptance is tested by supplying the concrete cap in discovery. For dayparts,
> legacy `daypart_targets: true`
> satisfies only `inventory_local` requirements; structured support is required
> for `iana`. For `geo_places` and `geo_places_exclude`,
> every requested identifier system and country key must exist, and requested
> place-type and catalog-version arrays must be subsets of the corresponding
> product support arrays. Unrequested object fields and numeric seller limits do
> not participate. Missing or unknown requirements do not match.
>
> Frequency-cap detail is additive rather than changing the legacy boolean's
> type or meaning. Constrained package support uses an independently positive
> field. Aggregate capability remains separate:
>
> ```json theme={null}
> {
> "required_overlay_support": {
> "frequency_cap_support": {
> "mutable_fields": ["max_impressions"],
> "supported_per_units": ["households"]
> }
> },
> "required_media_buy_support": {
> "frequency_cap": true
> },
> "media_buy_frequency_cap": {
> "max_impressions": 3,
> "per": "households",
> "window": { "interval": 7, "unit": "days" }
> }
> }
> ```
>
> The exact aggregate value filters compatible products but does not become a
> package overlay. Every returned product advertises
> `media_buy_support.frequency_cap: true` and supports the requested `per` unit.
> New request fields are sent only after negotiating a release that includes
> them. Older clients ignore `frequency_cap_support` and therefore do not mistake
> constrained support for the broad legacy promise.
>
> For country inclusion, country exclusion, and proximity targeting, Product
> support may disclose `max_values_per_package`. Country support uses either
> legacy `true` or `{ "max_values_per_package": N }`; proximity support places
> the limit alongside its supported methods and transport modes. The numeric
> limit never belongs in `required_overlay_support`. It applies independently to
> one targeting field on one package and is not a value allowlist,
> media-buy-wide constraint, or inventory promise. A create or update that
> exceeds the limit fails atomically with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) and identifies
> the overflowing targeting field.
>
> Although numeric limits do not participate in requirement matching, every
> returned Product's accepted effective targeting must satisfy the limits it
> discloses. A candidate whose concrete `targeting_overlay` exceeds a maximum is
> excluded unless the seller returns a distinct configured Product with a
> disclosed, compliant targeting modification.
>
> Support guarantees the ability to select a value subject to disclosed limits;
> it does not guarantee inventory or forecast every possible value. Forecasts
> returned when only future support was requested describe the product's
> discovery/default scope. Rediscover with concrete `targeting_overlay` values for
> a value-specific forecast. Fixed prices and floors remain binding uniformly
> for supported selections; price guidance remains non-binding. Sellers with
> value-dependent rates must return a concretely targeted configured product,
> split the rate tiers into products, or withhold binding pricing until concrete
> rediscovery. They cannot reinterpret a selected `pricing_option_id` at a new
> price. If a supported selection has no current inventory, creation returns
> [`PRODUCT_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-unavailable)
> rather than silently substituting or repricing it.
>
> For ISO subdivisions, known values belong in
> `targeting_overlay.geo_regions` / `geo_regions_exclude` and therefore scope the
> configured product's price and aggregate forecast. Values intentionally chosen
> later use structured `required_overlay_support` independently for inclusion and
> exclusion. Each country requirement uses either `all_values: true` or an exact
> candidate `values` set. A matching Product `overlay_support` must contain every
> requested country and value; product support with `all_values: true` satisfies
> any finite requirement for that country. `all_values` is evaluated against the
> seller's support snapshot when the declaration is issued and does not
> automatically include values introduced by a later catalog revision.
> Configured discovery or refinement
> with the exact overlay is the authoritative value-level preflight—there is no
> separate region resolver task.
>
> If the seller can honor a structured overlay exactly, the returned product
> omits Product `targeting_resolution`. Request-level brief confirmation appears
> once on the response, not on each product. Every request-specific configured
> product issued through targeting-aware discovery carries `is_custom: true` and
> `expires_at`, including exact products without a resolution echo. The generic
> Product schema still accepts legacy custom products without an expiry. If a
> product offers a different executable structured
> constraint, it contains only the changed paths. Selecting that request-scoped
> `product_id` accepts the disclosed resolution.
> [!NOTE]
>
> **Property governance**
>
> `targeting_overlay.property_list` references a property list created via [`create_property_list`](/dist/docs/3.2.8/governance/property/tasks/property_lists#create_property_list) on a property governance agent. Property lists define which publisher properties meet compliance requirements — COPPA-certified sites, sustainability-scored inventory, brand-safe publishers, etc. The legacy top-level `property_list` discovery filter is deprecated.
>
> To use property list filtering:
>
> 1. Call [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) on a property governance agent to discover available `property_features`
> 2. Create a property list via `create_property_list` with your feature requirements
> 3. Pass the resulting list reference in `targeting_overlay.property_list` so returned products and forecasts reflect the constrained inventory
>
> The seller-wide `media_buy.execution.targeting.property_list` capability is a
> routing rollup; each returned product must also make the requested constraint
> executable through inherent scope or selectable property targeting. The legacy
> `features.property_list_filtering` capability applies only to the deprecated
> top-level discovery filter. See the [Property Governance overview](/dist/docs/3.2.8/governance/property/index) for the full workflow.
### Filters Object
Filters decide which offers may be returned; they do not become package
delivery targeting. Exact
audience or inventory eligibility belongs in `targeting_overlay`. When the
buyer needs a targeting dimension but does not know its values yet, use
`required_overlay_support`.
During the compatibility window, sellers may translate a deprecated
targeting-like filter into its overlay equivalent. If both legacy and new forms
are present, they MUST be semantically identical; otherwise the seller rejects
the request with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request). This rule applies to every deprecated
targeting filter and the legacy top-level `property_list`.
| Parameter | Type | Description |
| - | - | - |
| `delivery_type` | string | Filter by `"guaranteed"` or `"non_guaranteed"` |
| `is_fixed_price` | boolean | Legacy filter for fixed-price vs auction products. `true` returns options with `fixed_price`; `false` returns options established through `bid_price`. Contingent options such as `revenue_share` match neither value and are omitted whenever this filter is present. |
| `pricing_structures` | string\[] | Filter by how the payable price is determined: `fixed`, `auction`, or `contingent`. Sellers return only matching `pricing_options`. Use `contingent` to discover `revenue_share`. When combined with `is_fixed_price`, both filters apply. |
| `pricing_currencies` | string\[] | Filter by ISO 4217 currencies the buyer can use for the media product transaction (e.g., `["USD"]`). Products match when they offer at least one product-level `pricing_options` entry in one of the requested currencies and any seller-applied or otherwise mandatory product-scoped signal charges are satisfiable in one of those currencies or have no incremental price. Sellers MUST return only matching product `pricing_options` so buyers can select deterministically from discovery. Optional signal or vendor add-on pricing is not pruned by this filter. |
| `format_kinds` | string\[] | Filter by canonical format kinds |
| `format_option_refs` | FormatOptionRef\[] | Filter by exact publisher- or product-scoped canonical format options |
| `format_ids` | FormatID\[] | Deprecated 3.x named-format compatibility filter |
| `standard_formats_only` | boolean | Only return products accepting IAB standard formats |
| `min_exposures` | integer | Minimum exposures needed for measurement validity |
| `start_date` | string | Campaign start date in ISO 8601 format (YYYY-MM-DD) for availability checks |
| `end_date` | string | Campaign end date in ISO 8601 format (YYYY-MM-DD) for availability checks |
| `budget_range` | object | Budget range to filter appropriate products (see Budget Range Object below) |
| `countries` | string\[] | Deprecated. Use `targeting_overlay.geo_countries`. |
| `regions` | string\[] | Deprecated. Use `targeting_overlay.geo_regions`. |
| `metros` | object\[] | Deprecated. Use `targeting_overlay.geo_metros` for known values or `required_overlay_support.geo_metros` for future selection. |
| `channels` | string\[] | Filter by advertising channels (e.g., `["display", "ctv", "social", "streaming_audio"]`). See [Media Channel Taxonomy](/dist/docs/3.2.8/reference/media-channel-taxonomy) |
| `video_placement_types` | string\[] | Match product metadata when the declared video placement types intersect `instream`, `accompanying_content`, `interstitial`, or `standalone`. Classification only; it does not promise exclusive delivery on a requested type. |
| `audio_distribution_types` | string\[] | Match product metadata when declared audio distribution types intersect the requested values. Classification only; it does not promise exclusive delivery on a requested type. |
| `sponsored_placement_types` | string\[] | Match retail-media product metadata when declared sponsored-placement types intersect the requested values. Classification only. |
| `social_placement_surfaces` | string\[] | Match social-product metadata when declared surfaces intersect `feed`, `stories`, `short_video`, `explore`, or `search`. Classification only; exact public-placement inventory uses `targeting_overlay.placement_selection`. |
| `postal_areas` | object\[] | Deprecated. Use `targeting_overlay.geo_postal_areas` or `required_overlay_support.geo_postal_areas`. |
| `geo_proximity` | object\[] | Deprecated. Use `targeting_overlay.geo_proximity`. |
| `keywords` | object\[] | Deprecated. Use `targeting_overlay.keyword_targets`; broad thematic intent remains in `brief`. |
| `signal_targeting` | SignalTargeting\[] | Deprecated. Use `targeting_overlay.signal_targeting_groups` for known selections or `required_overlay_support.signal_targeting_groups` for later selection. |
| `required_performance_standards` | [PerformanceStandard\[\]](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#measurement-terms-and-performance-standards) | Filter to products that can meet the buyer's performance standard requirements. Each entry specifies a metric, threshold, and vendor (e.g., "DoubleVerify for viewability at 70% MRC"). Products that cannot meet these thresholds or do not support the specified vendors are excluded. |
| `required_metrics` | string\[] ([metric vocabulary](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting)) | Filter to products whose `reporting_capabilities.available_metrics` is a superset of these metrics — i.e., products that commit to reporting all listed metrics in delivery. Use for capability discovery (e.g., `["completed_views"]` for a CTV CPCV buy). Sellers MUST silently exclude products that cannot meet the list — filter-not-fail; do not return an error. The product's declared `available_metrics` becomes the binding reporting contract carried into the resulting media buy. |
| `required_vendor_metrics` | object\[] | Filter to products whose `reporting_capabilities.vendor_metrics` covers vendor-defined metrics (proprietary attention, emissions, panel demographics, brand-lift surveys, etc.). Each entry pins `vendor` (BrandRef) and/or `metric_id` — at least one. Cross-vendor discovery (e.g., "any attention measurement") is the buyer agent's responsibility: resolve which vendors offer a category via the vendors' `brand.json` records, then enumerate them as filter entries. Same filter-not-fail semantics as `required_metrics`. |
| `audience_evidence_requirements` | AudienceEvidenceRequirements | Apply buyer-authored admissibility or ranking policy to `Product.audience_evidence`. `requirement_mode` distinguishes hard filtering from preference; `evidence_presence` distinguishes evidence-must-exist from apply-when-published. |
| `audience_activation_methods` | object\[] | **Experimental** (`media_buy.audience_activation` — check the seller's `experimental_features` before filtering; sellers that do not list the feature ignore this filter, so do not rely on it without checking. See [Experimental status](/dist/docs/3.2.8/reference/experimental-status)). Filter to products whose [`audience_activation.methods`](/dist/docs/3.2.8/media-buy/product-discovery/media-products#audience-activation) matches at least one requested entry (OR across entries). Within an entry every specified field must match (AND); omitted optional fields are wildcards; `directions` matches on non-empty intersection, and a method that omits `directions` matches any requested directions; `vendor` matches on `domain`, plus `brand_id` when specified. Each entry requires `pattern` ([`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences), `tmp_identity_match`, `file_transfer`, `dataset_query`, `clean_room`, `platform_distribution`) plus optional `vendor`, `transport`, `directions`, `buyer_agent` — fields inapplicable to the requested pattern make that entry unsatisfiable. Sellers MUST exclude products with no `audience_activation` declaration when this filter is present; exclusions MAY be reported via `filter_diagnostics.excluded_by`. |
### Audience evidence requirements
The reusable `audience_evidence_requirements` object attaches under `filters`, so the same contract applies to natural-language brief curation, wholesale feeds, and refine requests.
```json theme={null}
{
"filters": {
"audience_evidence_requirements": {
"requirement_mode": "required",
"evidence_presence": "required",
"accepted_methodologies": ["observed", "declared", "derived", "projected"],
"excluded_methodologies": ["inferred", "modeled"],
"accepted_evidence_types": ["measured"],
"accepted_subject_types": ["individual", "household"],
"minimum_confidence": 0.8,
"maximum_age": { "interval": 90, "unit": "days" },
"methodology_documentation_required": true,
"independent_attestation_required": true
}
}
}
```
Seller behavior is normative:
* `requirement_mode: "required"` excludes a product when it publishes evidence but no item satisfies every constraint. With `evidence_presence: "required"`, a product that publishes no evidence is also excluded. With `when_available`, a product with no evidence remains eligible.
* `requirement_mode: "preferred"` never turns a mismatch into a hard exclusion. Sellers rank products with matching evidence higher and explain the selected evidence when returning or constructing a package.
* When evidence affects product inclusion or rank, the returned product MUST carry the exact matching snapshots in `audience_evidence_selections[]`, with `decision_use` set to `eligibility` or `recommendation`, even if the request's `fields` projection omitted that field. A product admitted because `when_available` found no published evidence has no selection to report.
* Sellers evaluate freshness from `last_updated` at request evaluation time. They do not synthesize missing provider, confidence, methodology, documentation, or attestation data.
* Accepted lists and excluded lists are evaluated together; `excluded_methodologies` and `excluded_providers` always win when the same value appears in both lists.
* `independent_attestation_required` requires `accepted_attestation_issuers` and is satisfied only by one exact reference/evaluation pair. The reference must be published on the evidence, its issuer and claim type must match the buyer allowlists and seller's shared `adcp.attestations` policy, its subject digest must equal the evidence digest, the evaluation must cover that same reference with outcome `verified`, and its action-binding digest must equal the evidence digest. Buyer issuer and claim-type constraints narrow seller policy; they never broaden it.
* Buyers inspect `media_buy.audience_evidence` capabilities first. Sellers MUST NOT silently ignore unsupported hard requirement or presence modes; they return a structured unsupported/invalid-request error. A preferred mode the seller does not support may be omitted by the buyer or explicitly rejected by the seller, but is never misrepresented as applied.
Audience evidence does not populate `targeting_overlay`, `demographic_targeting`, or an age-verification field. If the buyer also needs exact execution, it requests that independently through the corresponding product and package targeting surfaces.
Known place IDs belong in `targeting_overlay`, so the returned product's
availability, pricing, and forecast are scoped to the effective place
constraint. If the buyer will choose IDs later, `required_overlay_support`
asks for the country, identifier system, place type, and optional catalog
version that the product must let the buyer select:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/get-products-request.json",
"buying_mode": "brief",
"brief": "Local video inventory for a municipal services campaign",
"targeting_overlay": {
"geo_places": [{
"country": "NL",
"system": "geonames",
"system_version": "2026-05",
"place_type": "city",
"values": ["2759794"]
}]
},
"required_overlay_support": {
"geo_places": {
"systems": {
"geonames": {
"countries": { "NL": ["city"] },
"system_versions": ["2026-05"]
}
}
}
}
}
```
The returned Product `overlay_support.geo_places` is binding permission to
supply matching place IDs on packages later, subject to disclosed limits. It
does not guarantee value-specific inventory or preserve an earlier forecast
before the IDs are provided. Fixed prices and floors retain their binding
semantics for every value within declared support; price guidance remains
non-binding. If the eventual values have no current inventory, create returns
[`PRODUCT_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-unavailable)
without silent substitution or repricing. Inclusion and exclusion permission
are independent; request `geo_places_exclude` separately when exclusions will
be chosen later.
### Placement fields
`get_products` returns product placement data when the seller includes `placements` or the buyer asks for it through `fields`. Placement IDs are publisher-scoped. Product placements should reference the publisher's public `adagents.json` placement declarations with `{publisher_domain, placement_id}` when a publisher declaration exists. Seller-private placement IDs, source/origin details, and delivery-system mappings must stay out of the response.
Each returned placement may carry:
| Field | Meaning |
| - | - |
| `placement_id` | Placement identifier. `publisher_ref` IDs are scoped by `publisher_domain`; `seller_inline` IDs are scoped by `seller_agent` or, for legacy rows, the enclosing seller and product. Creative-assignment refs remain product-context routing references. |
| `publisher_domain` | For `publisher_ref`, the required domain whose `adagents.json` owns the placement ID. For `seller_inline`, optional inventory-publisher attribution only. |
| `seller_agent` | Defining sales agent for self-contained `seller_inline` identity. New 3.2 products SHOULD include it; legacy inline rows remain product-scoped. |
| `mode` | `targetable` means the buyer may purchase the publisher-scoped placement through `targeting_overlay.placement_selection`. `included` means fixed/default product inventory that cannot be independently selected. Creative routing is permitted only after the placement is purchased. |
| `video_placement_types` | Declared video placement types for OLV and other video inventory, using the IAB Tech Lab/OpenRTB 2.6 `video.plcmt` definitions with AdCP-native names. Concrete placements usually declare one value; aggregate placements may declare multiple. |
| `audio_distribution_types` | Declared audio distribution types for radio, streaming-audio, podcast, gaming, and other audio inventory, using the IAB Tech Lab/OpenRTB 2.6 `audio.feed` definitions with AdCP-native names. Concrete placements usually declare one value; aggregate placements may declare multiple. |
| `sponsored_placement_types` | Declared sponsored-placement types for catalog-driven retail-media inventory. Concrete placements usually declare one value; aggregate placements may declare multiple. |
| `social_placement_surfaces` | Declared social-placement surfaces for social inventory. Concrete placements usually declare one value; aggregate placements may declare multiple. |
| `format_options` | Placement-specific canonical creative support. Product-level formats are the upper bound; placement-level formats narrow the effective accepted set for that placement and must not add formats or `locale_policy` language ranges the product does not accept. Deprecated `format_ids` may appear only on the 3.x compatibility path. |
Publishers can authorize sales agents for specific publisher placements using `authorized_agents[].placement_ids` or `authorized_agents[].placement_tags` in `adagents.json`. Sellers should only return publisher-referenced placements they are authorized to sell.
`mode: "targetable"` means the placement may be selected through
`packages[].targeting_overlay.placement_selection`. A placement with
`mode: "included"` is part of the fixed/default product and cannot be selected
independently. A request whose complete selected set exactly equals the
product's complete included set is satisfied inherently and may be echoed on
the booked package. That exact-equality rule applies during discovery, create,
and update and does not require `overlay_support.placement_selection`; partial
selection does. Because `placement_selection` represents the complete purchased
set, a product with any included placement does not declare selectable placement
overlay support; sellers expose a separate selectable product when needed.
`creative_assignments[].placement_refs` only route different creatives across
placements already selected for the package; they do not purchase inventory.
These refs retain product-context matching even when forward-compatible fields
make them resemble a canonical placement identity: `kind` and `seller_agent`
cannot expand or reinterpret the committed set, and the seller rejects any ref
that does not resolve to one unambiguous placement within that set.
Signal-targeting filter example:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/get-products-request.json",
"idempotency_key": "550e8400-e29b-41d4-a716-446655441005",
"buying_mode": "wholesale",
"filters": {
"signal_targeting": [
{
"signal_ref": {
"scope": "data_provider",
"data_provider_domain": "pinnacle-data.example",
"signal_id": "auto_intenders"
},
"value_type": "binary",
"value": true,
"targeting_mode": "include"
}
]
},
"fields": [
"product_id",
"name",
"included_signals",
"signal_targeting_allowed",
"signal_targeting_options",
"signal_targeting_rules",
"pricing_options"
]
}
```
### Currency filtering
Use `filters.pricing_currencies` when the buyer's constraint is "only show products whose media price I can transact in." Use `budget_range.currency` when the buyer is also providing a budget amount or range.
Buyers MAY send both. Sellers apply them conjunctively: `budget_range.currency` denominates the budget amounts, while `pricing_currencies` narrows which returned product `pricing_options` are eligible. If the two fields conflict, sellers SHOULD return zero matching products rather than reject the request solely because of the conflict. Because product-scoped signal pricing is a separate add-on surface, this filter only gates mandatory seller-applied signal charges; optional signal or vendor add-ons may still advertise other currencies, and buyers should not select unsupported add-on prices.
When combined with `is_fixed_price` or `pricing_structures`, returned product `pricing_options` MUST satisfy every filter: each retained option must have a requested pricing structure and its `currency` must be in `pricing_currencies`.
Currency-only filter example:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/get-products-request.json",
"idempotency_key": "550e8400-e29b-41d4-a716-446655441006",
"buying_mode": "wholesale",
"filters": {
"pricing_currencies": ["USD"]
},
"fields": ["product_id", "name", "pricing_options"]
}
```
If a product has both USD and EUR media pricing and the buyer sends `pricing_currencies: ["USD"]`, the seller returns the product with only its USD product-level `pricing_options`. If the product also has a fixed or otherwise mandatory product-scoped signal charge, that mandatory charge must either be priced in USD or have no incremental price; otherwise the product does not match the filter. A mandatory `custom` signal price without `currency` is not satisfiable for this filter unless the seller can truthfully treat it as having no incremental price. Optional signal add-ons do not affect product matching.
### Budget Range Object
| Parameter | Type | Required | Description |
| - | - | - | - |
| `currency` | string | Yes | ISO 4217 currency code (e.g., `"USD"`, `"EUR"`, `"GBP"`) |
| `min` | number | No\* | Minimum budget amount |
| `max` | number | No\* | Maximum budget amount |
\*At least one of `min` or `max` must be specified.
### Refine array
The `refine` array is a list of change requests. Each entry declares a `scope` and what the buyer is asking for. At least one entry is required. The seller considers all entries together when composing the response, and replies to each via `refinement_applied`.
Each entry is a discriminated union on `scope`:
#### scope: "request"
| Field | Type | Required | Description |
| - | - | - | - |
| `scope` | string | Yes | `"request"` |
| `ask` | string | Yes | Direction for the selection as a whole (e.g., `"more video options"`, `"suggest how to combine these products"`). |
#### scope: "product"
| Field | Type | Required | Description |
| - | - | - | - |
| `scope` | string | Yes | `"product"` |
| `product_id` | string | Yes | Product ID from a previous `get_products` response |
| `action` | string | No | `"include"` (default): return this product with updated pricing and data. `"omit"`: exclude from the response. `"more_like_this"`: find similar products (the original is also returned). When omitted, the seller treats the entry as `"include"`. |
| `ask` | string | No | What the buyer is asking for. For `"include"`: specific changes (e.g., `"add 16:9 format"`). For `"more_like_this"`: what "similar" means (e.g., `"same audience but video format"`). Ignored when `action` is `"omit"`. |
#### scope: "proposal"
| Field | Type | Required | Description |
| - | - | - | - |
| `scope` | string | Yes | `"proposal"` |
| `proposal_id` | string | Yes | Proposal ID from a previous `get_products` response |
| `action` | string | No | `"include"` (default): return with updated allocations and pricing. `"omit"`: exclude from the response. `"finalize"`: request firm pricing and inventory hold (transitions a draft proposal to committed). When omitted, the seller treats the entry as `"include"`. |
| `ask` | string | No | What the buyer is asking for (e.g., `"shift more budget toward video"`, `"reduce total by 10%"`). Ignored when `action` is `"omit"`. |
### refinement_applied (response)
When the seller receives a `refine` array, the response includes `refinement_applied` — an array matched by position. Each entry reports whether the ask was fulfilled:
| Field | Type | Required | Description |
| - | - | - | - |
| `scope` | string | Yes | Echoes the scope (`"request"` / `"product"` / `"proposal"`) from the corresponding `refine` entry. |
| `product_id` | string | Yes when `scope` is `"product"` | Echoes `product_id` from the corresponding refine entry. |
| `proposal_id` | string | Yes when `scope` is `"proposal"` | Echoes `proposal_id` from the corresponding refine entry. |
| `status` | string | Yes | `"applied"`: ask fulfilled. `"partial"`: partially fulfilled. `"unable"`: could not fulfill. |
| `notes` | string | No | Seller explanation. Recommended when status is `"partial"` or `"unable"`. |
### Catalog discovery
Pass a `catalog` to find advertising products that can promote your catalog items. The seller matches your catalog items against its inventory and returns products where matches exist. Supports all catalog types — a product catalog finds sponsored product slots, a job catalog finds job ad products, a flight catalog finds dynamic travel ads.
The `catalog` field uses the same [Catalog](/dist/docs/3.2.8/creative/catalogs) object used throughout AdCP. You can reference a synced catalog by `catalog_id`, provide inline items, or use selectors to filter:
| Field | Type | Description |
| - | - | - |
| `type` | CatalogType | Catalog type (required) — `product`, `job`, `hotel`, `flight`, `offering`, etc. |
| `catalog_id` | string | Reference a synced catalog by ID |
| `ids` | string\[] | Filter to specific item IDs |
| `gtins` | string\[] | Filter by GTIN for cross-retailer matching (product type only) |
| `tags` | string\[] | Filter by tags (OR logic) |
| `category` | string | Filter by category |
| `query` | string | Natural language filter |
Products in the response include `catalog_types` (what catalog types they support) and `catalog_match` (which items matched).
## Response
Returns an array of `products` and optionally `proposals`. When the seller's
structured interpretation of hard brief targeting materially affects product
eligibility, pricing, or forecasting, it MUST include one response-level
`targeting_resolution.brief_targeting` confirmation shared by the curated
result set. Otherwise confirmation remains a best practice.
### Products Array
| Field | Type | Description |
| - | - | - |
| `product_id` | string | Opaque buyable identifier. A non-custom wholesale ID remains stable for the same logical offer within the seller and declared `cache_scope`, including across reads and webhooks. A custom ID is stable only in its issuing discovery/refinement lineage. Selecting it accepts any disclosed `targeting_resolution`. |
| `is_custom` | boolean | `true` for a request-specific configured offer. Products issued through targeting-aware discovery include `expires_at`, including exact targeting configurations with no Product resolution echo. Legacy custom products remain schema-valid when expiry is absent. |
| `name` | string | Human-readable product name |
| `description` | string | Detailed product description |
| `publisher_properties` | PublisherProperty\[] | Array of publisher entries, each with `publisher_domain` and either `property_ids` or `property_tags` |
| `channels` | MediaChannel\[] | (Optional in 3.x) Buying contexts this product is sold as. Sellers SHOULD explicitly declare at least one channel on every product; existing 3.x property-based inheritance remains unchanged. Buyers should request `channels` in a `fields` projection before classification; omission from an unrequested projection does not establish an absent seller declaration. Creative formats and seller-wide capabilities do not independently declare product channels. See [Product channel declarations](/dist/docs/3.2.8/media-buy/product-discovery/media-products#product-channel-declarations). |
| `format_options` | ProductFormatDeclaration\[] | Closed canonical creative contracts this product can deliver, including optional seller-enforced `locale_policy.accepted_language_ranges` that buyers use to preflight planned creative languages before purchase. |
| `format_ids` | FormatID\[] | Deprecated 3.x compatibility projection, when emitted. Locale-constrained options cannot be represented on this path. |
| `delivery_type` | string | `"guaranteed"` or `"non_guaranteed"` |
| `delivery_measurement` | DeliveryMeasurement | (Optional) How delivery is measured (impressions, views, etc.) |
| `pricing_options` | PricingOption\[] | Available pricing models (CPM, CPCV, etc.). Auction options may include `floor_price` and optional `price_guidance`. Bid-based auction models (CPM, vCPM, CPC, CPCV, CPV) may also include optional `max_bid` (boolean). |
| `collections` | CollectionSelector\[] | (Optional) Collections available in this product. Each entry has `publisher_domain` and `collection_ids`. The publisher domain may be an external channel owner's — buyers resolve full collection objects from the referenced `adagents.json`. See [Collections and installments](/dist/docs/3.2.8/media-buy/product-discovery/collections-and-installments). |
| `collection_targeting_allowed` | boolean | (Optional, default: false) Whether buyers can target a subset of this product's `collections`. When false, the product is a bundle. |
| `identity` | ProductIdentity | (Optional, experimental) Product-scoped persistent-identifier and custom reach-methodology facts. Request explicitly in a sparse response. |
| `execution_requirements` | ProductExecutionRequirement\[] | (Optional, experimental) Account resources a package on this product needs before [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) succeeds: `event_source`, `catalog`, or `downstream_connection`. Account-independent, so it does not change `cache_scope`. See [Product execution requirements](/dist/docs/3.2.8/media-buy/specification#product-execution-requirements-experimental). Request explicitly in a sparse response. |
| `overlay_support` | TargetingOverlaySupport | Product-scoped targeting dimensions that may be selected later. Required when the discovery request includes `required_overlay_support`. This guarantees selectable capability subject to disclosed limits, not inventory or a value-specific forecast for every possible selection. |
| `media_buy_support` | MediaBuySupport | Product participation in shared MediaBuy controls. Required when discovery includes `required_media_buy_support` or `media_buy_frequency_cap`. For frequency capping, every selected product must participate in the same aggregate counter. |
| `targeting_resolution` | ProductTargetingResolution | Sparse product-specific modifications between requested and executable structured targeting. Omitted when the product accepts the structured overlay exactly. When present, `expires_at` is also required. |
| `list_applications` | InventoryListApplication\[] | Required once per effective property- or collection-list targeting reference and regardless of `fields`. Exclusion applications carry zero-match receipts; zero matches for any inclusion application make the product ineligible, so it is not returned. The deprecated top-level `property_list` produces a property `include` receipt and still sets `property_list_applied: true`. Identifies the list without its credential, timestamps the list resolution and seller evaluation, and reports product-scoped matched and unmatched entry counts. Pricing and forecast reflect post-application inventory. |
| `expires_at` | string | Expiration of this request-scoped configured product or quote. A recognized expired ID issued to the authenticated account and lineage returns [`PRODUCT_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-expired); after the seller no longer retains its tombstone, or when the ID belongs to another account/lineage, [`PRODUCT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-not-found) applies. The error choice never reveals cross-tenant existence. Buyers rediscover in either case. |
| `data_provider_signals` | DataProviderSignalSelector\[] | (Optional, deprecated) Legacy/non-selectable metadata for data-provider signals already bundled into or associated with this product. New implementations should use `included_signals`. |
| `included_signals` | SignalListing\[] | (Optional) Non-selectable signal metadata for signals already included in, bundled with, or planned into this product. These describe what the product is; buyers do not select them in package `signal_targeting_groups`. Data-provider and signal-source refs may be reference-only; product-local refs include inline `name` and `value_type`. |
| `signal_targeting_allowed` | boolean | (Optional, default: false) Whether this product has a package-level signal targeting surface. Editability is controlled by `signal_targeting_rules`; fixed/default-only products still set this to true when applied signal groups are echoed. |
| `signal_targeting_options` | ProductSignalTargetingOption\[] | (Optional) Inline product-scoped signal options the buyer may select, or the seller may apply when fixed/default, through `packages[].targeting_overlay.signal_targeting_groups`. May include per-signal `pricing_options`; product-scoped prices are authoritative for this product. Data-provider and signal-source refs may be reference-only; product-local refs include inline `name` and `value_type`. |
| `signal_targeting_rules` | SignalTargetingRules | (Optional) Product-scoped composition rules for selectable signals, such as direct vs seller-planned resolution, optional, required, maximum, mutually exclusive, fixed selections, and group size limits. These limits belong on the product, not seller-wide [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities), because products may be backed by different ad servers or seller planning layers. Fixed/default selections are applied by the seller and echoed on the resulting package state. |
| `demographic_targeting` | DemographicTargetingCapability | (Optional) Product-scoped exact execution for canonical demographic intent. `age.execution_modes` declares continuous bounds, enumerated seller intervals, and/or signal-backed resolution; continuous mode explicitly declares `supports_unbounded_min` and `supports_unbounded_max`, while `unknown_handling` states whether unknown age is selectable, always excluded, or always included. Buyers must inspect this field before sending `targeting_overlay.demographics`. |
| `brief_relevance` | string | Why this product matches the brief (when brief provided) |
| `measurement_readiness` | [MeasurementReadiness](/dist/docs/3.2.8/media-buy/conversion-tracking/#measurement-readiness) | (Optional) Whether the buyer's event setup is sufficient for this product's optimization. Only present when the seller can evaluate the buyer's account context. |
| `measurement_terms` | [MeasurementTerms](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#measurement-terms-and-performance-standards) | (Optional) Seller's default billing measurement and makegood terms. Buyers may propose different terms at [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy). |
| `performance_standards` | [PerformanceStandard\[\]](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#measurement-terms-and-performance-standards) | (Optional) Seller's default performance standards (viewability, IVT, completion rate, brand safety, attention score). Buyers may propose different standards at `create_media_buy`. |
| `cancellation_policy` | [CancellationPolicy](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models#cancellation-policy) | (Optional) Cancellation notice period and penalties for guaranteed products. Buyers accept these terms by creating a media buy against the product. |
### Publisher properties for non-URL inventory
`publisher_properties[].publisher_domain` is the domain that anchors the publisher's `adagents.json` namespace. It is not required to be the URL where an ad is displayed, and it is not a placeholder for a physical venue, publication, station, screen network, or print title.
Use the same selector shape for digital and non-digital products:
* **Digital properties**: `publisher_domain` is usually the publisher domain whose `adagents.json` declares the website, app, channel, or CTV property.
* **Print, static OOH, radio, cinema, and local TV**: `publisher_domain` is the operating publisher or network domain that publishes the authoritative property catalog. The actual inventory is identified by `property_ids`, `property_tags`, placements, collections, product metadata, and channel fields.
* **Aggregated networks**: use `property_tags` when the product spans many properties, such as a tagged set of venues, publications, screens, stations, or local markets.
Do not invent values like `"print"` or `"ooh"` for `publisher_domain`. Put channel meaning in `channels`, property meaning in the referenced property declarations, and sellable-package meaning in the product itself.
For example, a product that spans tagged metro properties can use this selector inside its `publisher_properties` array:
```json theme={null}
[
{
"selection_type": "by_tag",
"property_tags": ["metro", "station"]
}
]
```
### Proposals Array (Optional)
Publishers may return proposals alongside products - structured media plans with budget allocations. See [Proposals](/dist/docs/3.2.8/media-buy/product-discovery/media-products#proposals) for details.
| Field | Type | Description |
| - | - | - |
| `proposal_id` | string | Unique identifier for finalizing this proposal and, once committed, executing it via `create_media_buy` |
| `proposal_status` | string | Lifecycle state. `draft` means the proposal must be finalized via `get_products` refine action `finalize` before create. `committed` means the proposal can be executed via `create_media_buy` before `expires_at`. When absent, treat the proposal as ready to buy for backward compatibility. |
| `name` | string | Human-readable name for the media plan |
| `budget_allocation` | BudgetAllocation | Optional cross-product allocation configuration. Omission means a fixed proposal; `seller_optimized` delegates continuous allocation to the seller. |
| `pacing` | string | Optional aggregate media-buy pacing recommendation. On a committed proposal this is part of the firm delivery terms. |
| `allocations` | ProductAllocation\[] | Fixed proposals use exact `allocation_percentage` values summing to 100. Seller-optimized proposals omit exact percentages and may use `min_spend_target_percentage` and `max_spend_percentage`. Each allocation may include optional flight dates and subordinate `pacing`, which becomes package pacing on execution. In a seller-optimized proposal, a seller includes each of these package constraints only when it advertises the matching `seller_optimized_min_spend_targets`, `seller_optimized_package_budgets`, or `seller_optimized_package_pacing` capability. |
| `forecast` | DeliveryForecast | Aggregate delivery forecast for the proposal. Contains forecast points with metric ranges. See [Delivery Forecasts](/dist/docs/3.2.8/media-buy/product-discovery/media-products#delivery-forecasts) |
| `total_budget_guidance` | object | Optional min/recommended/max budget guidance |
| `brief_alignment` | string | How this proposal addresses the campaign brief |
| `expires_at` | string | ISO 8601 timestamp when this proposal expires. For committed proposals, this is the inventory-hold deadline for `create_media_buy`. |
Each `ForecastPoint` is one forecast row. Composite slices are encoded by multiple `dimensions[]` items on the same point, such as placement x country. Sibling points are parallel rows, not nested children. Dimension order has no meaning; buyers normalize row identity from `(forecast_range_unit, budget if present, product_id if present, dimensions sorted by kind)`. Buyers may compare rows at the same grain, but MUST NOT sum them unless the seller documents that the returned rows form a complete, non-overlapping partition. Standard delivery reporting mostly verifies one-dimensional marginals; `collection_property`, `installment_property`, and `placement_property` are explicit standardized intersections with property delivery.
### Pagination
`pagination` is valid in all `get_products` modes, but its meaning follows the
buying mode:
* In `brief` mode, pagination bounds the seller's curated answer to the brief.
A page is not a promise that every product matching the words in the brief has
been enumerated.
* In `refine` mode, pagination bounds the refined `products[]` result implied by
the `refine` array and current filters. Proposals may accompany the page as
plan metadata, but `pagination.max_results`, `has_more`, `cursor`, and
`total_count` are scoped to the product result set, not to a separate
proposal list or a combined product/proposal count.
* In `wholesale` mode, pagination walks the wholesale product feed. This is the
exhaustive/feed-style read and is the mode that pairs with wholesale feed
versioning.
Use cursor-based pagination to cap returned products in curated/refined
responses or walk wholesale product feeds:
| Request Parameter | Type | Description |
| - | - | - |
| `pagination.max_results` | integer | Maximum products per page (1-100, default: 50) |
| `pagination.cursor` | string | Cursor from previous response for next page |
| Response Field | Type | Description |
| - | - | - |
| `pagination.has_more` | boolean | Whether more products are available |
| `pagination.cursor` | string | Cursor to pass for the next page |
| `pagination.total_count` | integer | Total products in this paginated result set (optional, not all backends support this). In `brief` / `refine`, this is the curated/refined product set, not the full seller catalog. |
Pagination is optional. When omitted, the server returns the complete result set
or a server-chosen default page. When the response includes
`pagination.has_more: true`, pass `pagination.cursor` in the next request to get
the next page using the same result-defining request context, except for the
updated `pagination.cursor`.
### Response Metadata
| Field | Type | Description |
| - | - | - |
| `property_list_applied` | boolean | \[AdCP 3.0] `true` if the agent filtered products based on the provided `property_list`. Absent or `false` if not provided or not supported. |
| `catalog_applied` | boolean | `true` if the seller filtered results based on the provided `catalog`. Absent or `false` if no catalog was provided or the seller does not support catalog matching. |
| `refinement_applied` | [RefinementResult\[\]](#refinement_applied-response) | Seller acknowledgment of each `refine` entry, matched by position. Only present when `buying_mode` is `"refine"`. See [refinement_applied](#refinement_applied-response) above. |
| `incomplete` | [IncompleteEntry\[\]](#incomplete-array) | Declares what the seller could not finish within the `time_budget` or due to internal limits. Each entry identifies a scope with a human-readable explanation. Absent when the response is fully complete. See [incomplete array](#incomplete-array) below. |
| `filter_diagnostics` | object | Optional non-fatal observability block describing how `filters` narrowed the candidate set — `total_candidates` plus per-filter `excluded_by` counts (keyed by filter name). Disambiguates "no inventory" from "your filter excluded everything" when the result list is empty or unexpectedly small. Counts only — never product names — to avoid leaking competitive intelligence. See [filter_diagnostics](#filter_diagnostics) below. |
| `wholesale_feed_version` | string | Opaque token representing the version of the wholesale product feed state used to compose this response. Sellers implementing conditional-fetch (`if_wholesale_feed_version`) MUST return this on every wholesale-mode response so buyers can cache and probe later. Treat as opaque — no format, no ordering, no inspection. See [Wholesale feed versioning](#wholesale-feed-versioning). |
| `pricing_version` | string | Optional opaque token representing the version of the pricing layer, including product `pricing_options` and nested `signal_targeting_options[].pricing_options`. When the seller supports independent pricing versioning, `pricing_version` changes when prices move but `wholesale_feed_version` changes only when structure/metadata moves. Sellers not separating these MAY omit `pricing_version` and use `wholesale_feed_version` for both. |
| `cache_scope` | string | `"public"` or `"account"`. **REQUIRED on every response** (schema-enforced — the safety property of the two-layer cache depends on it). When the request had no `account`, MUST be `"public"`. When the request had `account`, the seller declares either `"public"` (account prices off the rate card — buyer dedupes) or `"account"` (account-specific overrides). See [Cache layering](#cache-layering). |
| `unchanged` | boolean | Present and `true` ONLY when the request carried `if_wholesale_feed_version` (and/or `if_pricing_version`) matching the seller's current version for the buyer's `cache_scope`, in which case `products[]` MUST be omitted; `wholesale_feed_version`, `cache_scope`, and `pricing_version` (when used) MUST still be echoed. Sellers MUST NOT emit `unchanged: false` — absence of the field IS the "response carries products" signal (one shape per state). Buyers receiving `unchanged: true` MUST NOT mutate their local wholesale product mirror. |
### filter_diagnostics
When the seller can attribute exclusions to specific filters, the response MAY include a `filter_diagnostics` block. This is observability — not error reporting; sellers still silently exclude unmatched products per the filter-not-fail convention. Buyers use this to triage empty/small results without depending on its presence. `total_candidates` and `excluded_by` are independently optional — sellers whose baseline candidate set size is sensitive MAY emit `excluded_by` without `total_candidates`.
| Field | Type | Description |
| - | - | - |
| `semantics` | string | `"only"` (deterministic; counts products that would have been included if not for *this* filter alone — recommended for triage), `"any"` (counts products excluded by any filter; counts may overlap), or `"approximate"` (seller can't cleanly attribute exclusions to a single filter). Buyers SHOULD inspect `semantics` before doing arithmetic on counts. |
| `total_candidates` | integer | Number of products considered before filters were applied. May be sampled or capped when the candidate pool is large. Optional. |
| `excluded_by` | object | Keys are filter property names from the request (`pricing_currencies`, `required_metrics`, `required_geo_targeting`, `budget_range`, etc.). Each value is `{ count, values?, notes? }`. Only filters that meaningfully narrowed the set need appear. |
| `excluded_by..count` | integer | Count of products excluded by this filter, interpreted per the parent `semantics` field. |
| `excluded_by..values` | array | Optional list of the specific filter values that contributed to exclusions (e.g., `["completed_views"]` for `required_metrics`). Items are strings or objects depending on filter shape; opaque without filter-specific knowledge. |
| `excluded_by..notes` | string | Optional human-readable note about the narrowing. |
```json theme={null}
{
"products": [],
"filter_diagnostics": {
"semantics": "only",
"total_candidates": 47,
"excluded_by": {
"required_metrics": { "count": 31, "values": ["completed_views"] },
"required_geo_targeting": { "count": 9 },
"pricing_currencies": { "count": 3, "values": ["USD"] },
"budget_range": { "count": 7 }
}
}
}
```
### incomplete array
When the seller returns usable results but cannot complete all work within the `time_budget` (or due to its own internal limits), the response includes `incomplete` — an array declaring what is missing. `incomplete` is a completeness statement, not a retry classification: buyers MUST NOT infer that retrying the same request will succeed. `estimated_wait`, when present, lets a buyer decide whether to make a new attempt with a larger time budget.
| Field | Type | Required | Description |
| - | - | - | - |
| `scope` | string | Yes | `"products"`: not all inventory sources were searched. `"pricing"`: products returned but pricing is absent or unconfirmed. `"forecast"`: products returned but forecast data is absent. `"proposals"`: proposals were not generated or are incomplete. `"wholesale_feed"`: in wholesale mode, full feed enumeration could not complete. |
| `description` | string | Yes | Human-readable explanation of what is missing and why. |
| `estimated_wait` | Duration | No | Additional time expected to help resolve this scope. This is planning guidance, not a retry instruction or guarantee. |
### Wholesale feed versioning
A buyer that just synced a seller's wholesale product feed can ask "has anything changed since version X?" in one cheap call, regardless of feed size. Sellers return an opaque `wholesale_feed_version` on every wholesale-mode response; buyers pass it back via `if_wholesale_feed_version` on the next call and the seller MAY short-circuit with `unchanged: true` — no products payload, no per-page diff. Patterned on HTTP `ETag` / `If-None-Match`.
This is the seller-side wholesale product feed returned by `get_products`. It is not a [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs) feed; `sync_catalogs` manages buyer-provided campaign input feeds on the seller account.
**Unchanged response example:**
Request:
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/get-products-request.json",
"idempotency_key": "550e8400-e29b-41d4-a716-446655441007",
"buying_mode": "wholesale",
"if_wholesale_feed_version": "v2026-05-18T08:00:00Z-acme-rev412"
}
```
Response (wholesale product feed unchanged):
```json theme={null}
{
"$schema": "/schemas/3.2.8/media-buy/get-products-response.json",
"status": "completed",
"message": "Wholesale product feed unchanged since v2026-05-18T08:00:00Z-acme-rev412.",
"context_id": "ctx-abc-789",
"unchanged": true,
"wholesale_feed_version": "v2026-05-18T08:00:00Z-acme-rev412",
"pricing_version": "v2026-05-18T08:00:00Z-acme-rev412",
"cache_scope": "public"
}
```
Response (wholesale product feed changed — full payload returned, abbreviated):
```json test=false theme={null}
{
"message": "Returning 50 of 312 products (wholesale feed version advanced).",
"context_id": "ctx-abc-790",
"wholesale_feed_version": "v2026-05-18T10:15:00Z-acme-rev415",
"pricing_version": "v2026-05-18T10:15:00Z-acme-rev415",
"cache_scope": "public",
"products": [
{
"product_id": "prod_premium_ctv_us",
"name": "Premium CTV — US",
"description": "Run-of-network CTV inventory across premium publishers.",
"publisher_properties": [{ "publisher_domain": "streamhaus.example.com", "property_ids": ["primetime_ctv"] }],
"format_options": [{ "format_option_id": "video_ctv_1080p_30s", "format_kind": "video_hosted", "params": { "width": 1920, "height": 1080, "duration_ms_exact": 30000 } }],
"delivery_type": "guaranteed",
"pricing_options": [
{ "pricing_option_id": "po_cpm_v2", "pricing_model": "cpm", "currency": "USD", "fixed_price": 18.50 }
]
}
],
"pagination": { "has_more": true, "cursor": "eyJvIjo1MH0=", "total_count": 312 }
}
```
**Rules**
* Tokens are **opaque**. No format, no ordering, no inspection.
* A returned `wholesale_feed_version` is scoped to the request parameters that produced it. Buyers MUST cache the version alongside the `(account, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog)` tuple used.
* `pricing_version` is an optional finer-grained token: when present, it changes when prices move but `wholesale_feed_version` changes only when structure/metadata moves. Common for rate-card sweeps that don't change product metadata.
* **`if_pricing_version` requires `if_wholesale_feed_version`.** Pricing has no structural baseline of its own. Sending `if_pricing_version` without `if_wholesale_feed_version` is a schema-level error. The seller's evaluation is two-stage: wholesale feed mismatch returns the full payload (pricing is implicitly stale); wholesale feed match with pricing mismatch also returns the full payload (so the buyer sees updated `pricing_options`); both match → `unchanged: true`.
* **`filters` canonicalization.** Sellers MUST treat the `filters` object as canonicalized before hashing into the `wholesale_feed_version` keyspace: keys MUST be sorted lexicographically, omitted-and-default values MUST be treated identically (a missing `delivery_type` key is the same scope as `delivery_type: null`), array values MUST be sorted where the filter has set semantics (e.g., `channels`, `format_kinds`, `format_option_refs`, `required_metrics`) and preserved-order where the filter has sequence semantics (e.g., `preferred_delivery_types`). Buyers that pass equivalent-but-differently-shaped filter objects MUST receive the same `wholesale_feed_version` from the seller. This rule prevents silent stale-mirror bugs from key-order or default-elision differences between buyer SDKs. **Forward-compat default:** new filter fields added in 3.x minor versions MUST declare set-vs-sequence semantics in their schema (via `x-canonicalization: set | sequence` or equivalent prose); absent an explicit declaration, the rule defaults to **set-semantics** (sort before hashing). Sellers and SDKs that drift on this default produce cache misses that consumers can't explain.
* **Pagination interaction.** `wholesale_feed_version` describes the wholesale product feed as a whole, not individual pages. Sellers MUST return `wholesale_feed_version` on every paginated page (not only the first) when they declare `wholesale_feed_versioning.supported: true`; sellers that do not declare versioning SHOULD do the same. When the wholesale feed mutates between pages, the new version surfaces on the next page and the buyer MUST restart pagination from `cursor: null` — the partial pages they've already received describe a stale version. Sellers MAY alternatively snapshot the feed at the start of pagination and serve all pages from that snapshot under the original version; either implementation is conformant as long as `wholesale_feed_version` on a given page is the version that page belongs to.
* **`unchanged: true` and in-progress pagination.** A buyer that is mid-pagination on `cursor: X` MAY send `if_wholesale_feed_version` matching the version their pages so far were drawn from. If the seller confirms `unchanged: true`, the response omits `products[]` and pagination envelope entirely; the buyer abandons their in-progress walk under that version with confidence that no further pages would have produced new data. Sellers MAY NOT use the conditional-fetch short-circuit to skip individual pages within an active pagination — `unchanged` is feed-versus-cached-version, not per-page.
* Pre-v3.1 sellers that ignore `if_wholesale_feed_version` simply return the full payload — semantically correct, just inefficient (same as the unchanged-server path in HTTP).
For pushed change tracking beyond conditional fetch, see `specs/wholesale-feed-webhooks.md`. Wholesale feed webhooks carry the changed product payload, pricing payload, removal tombstone, or bulk-change summary; `get_products` remains the repair and reconciliation read.
### Cache layering
Sellers publish two notional layers: a **public layer** (the rate-card / structural view) and **per-account overlays** (custom deals, account-specific rate cards). The conditional-fetch path is layer-aware via `cache_scope`.
**Why this matters.** A buyer mirroring wholesale products across N accounts at one seller doesn't want to hold N copies of inventory that's actually identical for every buyer. The public layer is the seller's published rate card; most accounts at most sellers price off it directly. Premium custom deals are the exception.
**Two-layer cache.**
| Layer | Cache key | What's stored |
| - | - | - |
| Public | `(agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog)` | `wholesale_feed_version_public`, the wholesale product feed payload as seen without an account ref |
| Account overlay | `(agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, account_id)` | `wholesale_feed_version_account`, the wholesale product feed payload as seen WITH this account ref, when `cache_scope: "account"` was returned |
**Behavior.**
* Requests without `account` always return `cache_scope: "public"`. Buyers cache under the public key.
* Requests with `account` return `cache_scope: "public"` OR `"account"` (seller MUST declare; no default).
* `"public"`: this account prices off the rate card. Buyer MAY dedupe — the version and payload are the same as the unauthenticated view. The buyer can serve subsequent requests for any account in `"public"` cache_scope from a single public-layer entry.
* `"account"`: this response carries account-specific overrides. Buyer caches under the account overlay key.
* Sellers MAY downgrade an account from `"account"` back to `"public"` by returning `cache_scope: "public"` on a request that previously got `"account"` — buyers SHOULD interpret this as "this account no longer has overrides" and drop their account overlay.
**Conditional fetch with `if_wholesale_feed_version`.** Send the token paired with whichever scope it was returned in. The seller compares against the current version for that scope. If the buyer's token belongs to an `"account"` scope but the seller responds with `cache_scope: "public"`, that's the downgrade signal — buyer drops the overlay.
**Webhook invalidation.** Wholesale feed webhook events declare `applies_to.scope` on `*.priced` and `*.updated` payloads. Sellers MUST apply the same account/caller authorization predicate used by `get_products buying_mode: "wholesale"` when deciding which subscribers receive product webhooks:
* `applies_to: { scope: "public" }` → invalidate the public-layer cache for the entity. All account overlays referencing that public version are also stale and SHOULD be refetched.
* `applies_to: { scope: "account", account_ids: [...] }` → invalidate only the named accounts' overlays. The public layer is unaffected.
* `applies_to: { scope: "account" }` without `account_ids` → the seller is withholding the affected set; the per-subscriber scope filter routes the event only to subscribers whose principal is in the affected set. Receiving the event means "your overlay is stale."
See `specs/wholesale-feed-webhooks.md` §"Cache layering and event scoping" for the full webhook-side spec.
**See schema for complete field list**: [`get-products-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/get-products-response.json)
## Common Scenarios
### Time-budgeted discovery
Declare a time budget when you need fast results and can accept partial data. The seller returns what it can within the budget and declares what is incomplete:
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441008',
buying_mode: 'brief',
brief: 'CTV and display for brand awareness',
brand: {
domain: 'acmecorp.com'
},
time_budget: {
interval: 10,
unit: 'seconds'
}
});
if (result.success && result.data) {
console.log(`Found ${result.data.products.length} products`);
if (result.data.incomplete) {
for (const entry of result.data.incomplete) {
console.log(`Incomplete: ${entry.scope} — ${entry.description}`);
if (entry.estimated_wait) {
console.log(` Seller estimates more time may help: ${entry.estimated_wait.interval} ${entry.estimated_wait.unit}`);
}
}
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_with_time_budget():
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441009',
buying_mode='brief',
brief='CTV and display for brand awareness',
brand={
'domain': 'acmecorp.com'
},
time_budget={
'interval': 10,
'unit': 'seconds'
}
)
print(f"Found {len(result.products)} products")
for entry in result.get('incomplete', []):
print(f"Incomplete: {entry['scope']} — {entry['description']}")
if 'estimated_wait' in entry:
wait = entry['estimated_wait']
print(f" Seller estimates more time may help: {wait['interval']} {wait['unit']}")
asyncio.run(discover_with_time_budget())
```
A response with incomplete data — products are returned but some scopes are missing:
```json test=false theme={null}
{
"products": [
{
"product_id": "prog-display-ros",
"name": "Programmatic Display — Run of Site",
"delivery_type": "non_guaranteed",
"pricing_options": [{ "pricing_option_id": "cpm-ros", "pricing_model": "cpm", "currency": "USD", "fixed_price": 12.00 }]
}
],
"incomplete": [
{
"scope": "products",
"description": "Premium inventory not searched — requires publisher approval",
"estimated_wait": { "interval": 60, "unit": "minutes" }
},
{
"scope": "forecast",
"description": "Forecast model did not complete within budget",
"estimated_wait": { "interval": 45, "unit": "seconds" }
}
]
}
```
### Wholesale Product Discovery
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// wholesale mode: buyer applies their own audiences, no publisher curation
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441010',
buying_mode: 'wholesale',
brand: {
domain: 'acmecorp.com'
},
filters: {
delivery_type: 'non_guaranteed'
}
});
if (result.success && result.data) {
console.log(`Found ${result.data.products.length} standard wholesale products`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_standard_wholesale_products():
# wholesale mode: buyer applies their own audiences, no publisher curation
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441011',
buying_mode='wholesale',
brand={
'domain': 'acmecorp.com'
},
filters={
'delivery_type': 'non_guaranteed'
}
)
print(f"Found {len(result.products)} standard wholesale products")
asyncio.run(discover_standard_wholesale_products())
```
### Multi-Format Discovery
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// Find products supporting both video and display
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441012',
buying_mode: 'brief',
brief: 'Brand awareness campaign with video and display',
brand: {
domain: 'acmecorp.com'
},
filters: {
channels: ['display', 'ctv']
}
});
if (result.success && result.data) {
console.log(`Found ${result.data.products.length} products supporting video and display`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_multi_format():
# Find products supporting both video and display
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441013',
buying_mode='brief',
brief='Brand awareness campaign with video and display',
brand={
'domain': 'acmecorp.com'
},
filters={
'channels': ['display', 'ctv']
}
)
print(f"Found {len(result.products)} products supporting video and display")
asyncio.run(discover_multi_format())
```
### Budget and Date Filtering
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// Find products within budget and date range for specific countries and channels
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441014',
buying_mode: 'brief',
brief: 'Q2 campaign for athletic footwear in North America',
brand: {
domain: 'acmecorp.com'
},
filters: {
start_date: '2025-04-01',
end_date: '2025-06-30',
budget_range: {
min: 50000,
max: 100000,
currency: 'USD'
},
countries: ['US', 'CA'],
channels: ['display', 'ctv', 'podcast'],
delivery_type: 'guaranteed'
}
});
if (result.success && result.data) {
console.log(`Found ${result.data.products.length} products for Q2 within budget`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_with_budget_and_dates():
# Find products within budget and date range for specific countries and channels
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441015',
buying_mode='brief',
brief='Q2 campaign for athletic footwear in North America',
brand={
'domain': 'acmecorp.com'
},
filters={
'start_date': '2025-04-01',
'end_date': '2025-06-30',
'budget_range': {
'min': 50000,
'max': 100000,
'currency': 'USD'
},
'countries': ['US', 'CA'],
'channels': ['display', 'ctv', 'podcast'],
'delivery_type': 'guaranteed'
}
)
print(f"Found {len(result.products)} products for Q2 within budget")
asyncio.run(discover_with_budget_and_dates())
```
### Property Tag Resolution
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// Get products with property tags
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441016',
buying_mode: 'brief',
brief: 'Sports content',
brand: {
domain: 'acmecorp.com'
}
});
if (result.success && result.data) {
// Products with property_tags in publisher_properties represent large networks
// Use get_adcp_capabilities to discover the agent's portfolio
const productsWithTags = result.data.products.filter(p =>
p.publisher_properties?.some(pub => pub.property_tags && pub.property_tags.length > 0)
);
console.log(`${productsWithTags.length} products use property tags (large networks)`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_property_tags():
# Get products with property tags
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441017',
buying_mode='brief',
brief='Sports content',
brand={
'domain': 'acmecorp.com'
}
)
# Products with property_tags in publisher_properties represent large networks
# Use get_adcp_capabilities to discover the agent's portfolio
products_with_tags = [p for p in result.products
if any(pub.get('property_tags') for pub in p.get('publisher_properties', []))]
print(f"{len(products_with_tags)} products use property tags (large networks)")
asyncio.run(discover_property_tags())
```
### Guaranteed Delivery Products
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// Find guaranteed delivery products for measurement
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441018',
buying_mode: 'brief',
brief: 'Guaranteed delivery for lift study',
brand: {
domain: 'acmecorp.com'
},
filters: {
delivery_type: 'guaranteed',
min_exposures: 100000
}
});
if (result.success && result.data) {
console.log(`Found ${result.data.products.length} guaranteed products with 100k+ exposures`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_guaranteed():
# Find guaranteed delivery products for measurement
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441019',
buying_mode='brief',
brief='Guaranteed delivery for lift study',
brand={
'domain': 'acmecorp.com'
},
filters={
'delivery_type': 'guaranteed',
'min_exposures': 100000
}
)
print(f"Found {len(result.products)} guaranteed products with 100k+ exposures")
asyncio.run(discover_guaranteed())
```
### Standard Formats Only
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// Find products that only accept IAB standard formats
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441020',
buying_mode: 'wholesale',
brand: {
domain: 'acmecorp.com'
},
filters: {
standard_formats_only: true
}
});
if (result.success && result.data) {
console.log(`Found ${result.data.products.length} products with standard formats only`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_standard_formats():
# Find products that only accept IAB standard formats
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441021',
buying_mode='wholesale',
brand={
'domain': 'acmecorp.com'
},
filters={
'standard_formats_only': True
}
)
print(f"Found {len(result.products)} products with standard formats only")
asyncio.run(discover_standard_formats())
```
### Catalog-driven discovery
Use `catalog` with a brand to discover advertising products that can promote your catalog items. The seller matches your items against its inventory and returns products where matches exist:
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// Discover retail media products for specific catalog items
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441022',
buying_mode: 'wholesale',
brand: {
domain: 'acmecorp.com'
},
catalog: {
type: 'product',
tags: ['ketchup', 'organic'],
category: 'food/condiments'
},
filters: {
channels: ['retail_media']
}
});
if (result.success && result.data) {
if (result.data.catalog_applied) {
console.log(`Found ${result.data.products.length} products with catalog matches`);
} else {
console.log('Seller does not support catalog matching');
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_commerce_products():
# Discover retail media products for specific catalog items
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441023',
buying_mode='wholesale',
brand={
'domain': 'acmecorp.com'
},
catalog={
'type': 'product',
'tags': ['ketchup', 'organic'],
'category': 'food/condiments'
},
filters={
'channels': ['retail_media']
}
)
if result.get('catalog_applied'):
print(f"Found {len(result.products)} products with catalog matches")
else:
print("Seller does not support catalog matching")
asyncio.run(discover_commerce_products())
```
```bash CLI requires-env=ADCP_AUTH_TOKEN theme={null}
uvx adcp \
https://test-agent.adcontextprotocol.org/sales/mcp \
get_products \
'{"idempotency_key":"550e8400-e29b-41d4-a716-446655441024","buying_mode":"wholesale","brand":{"domain":"acmecorp.com"},"catalog":{"type":"product","tags":["ketchup","organic"],"category":"food/condiments"},"filters":{"channels":["retail_media"]}}' \
--auth $ADCP_AUTH_TOKEN
```
You can also use GTIN matching, reference a synced catalog, or discover products for other catalog types:
```json theme={null}
{
"catalog": {
"type": "product",
"gtins": ["00013000006040", "00013000006057"]
}
}
```
```json theme={null}
{
"catalog": {
"catalog_id": "gmc-primary",
"type": "product"
}
}
```
```json theme={null}
{
"catalog": {
"type": "job",
"catalog_id": "chef-vacancies"
}
}
```
### Property List Filtering
> [!NOTE]
>
> **AdCP 3.0** - Property list filtering requires governance agent support.
Filter products to only those available on properties in your approved list:
```javascript JavaScript theme={null}
import { testAgent } from '@adcp/sdk/testing';
// Filter products by property list from governance agent
const result = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441025',
buying_mode: 'brief',
brief: 'Brand-safe inventory for family brand',
brand: {
domain: 'acmecorp.com'
},
property_list: {
agent_url: 'https://governance.example.com',
list_id: 'pl_brand_safe_2024'
}
});
if (result.success && result.data) {
// Check if filtering was actually applied
if (result.data.property_list_applied) {
console.log(`Found ${result.data.products.length} products on approved properties`);
} else {
console.log('Agent does not support property list filtering');
console.log(`Found ${result.data.products.length} products (unfiltered)`);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def discover_with_property_list():
# Filter products by property list from governance agent
result = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441026',
buying_mode='brief',
brief='Brand-safe inventory for family brand',
brand={
'domain': 'acmecorp.com'
},
property_list={
'agent_url': 'https://governance.example.com',
'list_id': 'pl_brand_safe_2024'
}
)
# Check if filtering was actually applied
if result.get('property_list_applied'):
print(f"Found {len(result['products'])} products on approved properties")
else:
print("Agent does not support property list filtering")
print(f"Found {len(result['products'])} products (unfiltered)")
asyncio.run(discover_with_property_list())
```
**Note**: If `property_list_applied` is absent or `false`, the sales agent did not filter products. This can happen if:
* The agent doesn't support property governance features
* The agent couldn't access the property list
* The property list had no effect on the available inventory
#### Property Targeting Behavior
Products have a `property_targeting_allowed` flag that affects filtering:
* **`property_targeting_allowed: false` (default)**: Product is "all or nothing" - excluded unless your list contains all of its properties
* **`property_targeting_allowed: true`**: Product is included if there's any intersection between its properties and your list
This allows publishers to offer run-of-network products that can't be cherry-picked alongside flexible inventory that buyers can filter.
See [Property Targeting](/dist/docs/3.2.8/media-buy/product-discovery/media-products#property-targeting) for more details and [Property Governance](/dist/docs/3.2.8/governance/property/specification) for more on property lists.
## Refinement
After initial discovery, use `buying_mode: "refine"` to iterate on specific products and proposals. The `refine` array is a list of change requests — each entry declares a scope and what the buyer is asking for. The seller returns updated products with revised pricing and configurations, plus `refinement_applied` acknowledging each ask.
See the [Refinement guide](/dist/docs/3.2.8/media-buy/product-discovery/refinement) for the full walkthrough: scope types, action semantics, seller responses, and common patterns. The parameter shape is defined in the [Refine array](#refine-array) section above.
Minimal example:
```json test=false theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441027",
"buying_mode": "refine",
"refine": [
{ "scope": "request", "ask": "more video, less display" },
{ "scope": "product", "product_id": "prod_premium_video", "ask": "add 16:9 format option" },
{ "scope": "product", "product_id": "prod_display_run_of_site", "action": "omit" },
{ "scope": "proposal", "proposal_id": "prop_awareness_q2", "ask": "reallocate display budget to video" }
],
"filters": {
"start_date": "2026-04-01",
"end_date": "2026-04-30",
"budget_range": { "min": 200000, "max": 200000, "currency": "USD" }
}
}
```
Key rules to know before sending:
* **`refine` is only valid in `refine` mode.** Requests that include this field in `brief` or `wholesale` mode are rejected with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request).
* **Filters are absolute**, not deltas. Always send the full filter set you want applied.
* **Proposals are actionable through status.** `proposal_status: "draft"` requires finalization before create; `proposal_status: "committed"` can be executed with `create_media_buy(proposal_id)` before `expires_at`; absent status is legacy ready-to-buy.
* **Proposals are ephemeral.** Proposals typically include an `expires_at` timestamp. After expiration, the seller returns [`PROPOSAL_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-expired).
* **Wholesale product IDs are scoped stable identifiers.** A non-custom product keeps the same ID for the same logical offer within the seller and declared `cache_scope`, including across reads and webhooks. Feed and pricing versions communicate mutation; retirement or replacement may end that identity.
* **Targeting-aware custom product IDs are ephemeral configurations.** A request-specific product issued by this flow sets `is_custom: true`, is usable only in the authenticated account and discovery/refinement lineage that issued it, and includes `expires_at`. The generic Product schema remains compatible with earlier custom products that omitted expiry. After expiration, a seller that still recognizes the caller-authorized ID returns [`PRODUCT_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-expired); after the seller no longer retains a tombstone—or when the ID is outside the caller's account/lineage—it returns [`PRODUCT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-not-found) without revealing whether another tenant has that ID.
## Seller Declines
A seller that understands a well-formed `brief` or `refine` request but deliberately declines to offer products returns the `GetProductsRejected` arm. This is a successful business outcome, not a malformed request or technical failure:
```json theme={null}
{
"status": "rejected",
"reason": "The requested budget is below the minimum for this inventory.",
"suggestions": [
"Increase the campaign budget.",
"Consider display inventory for this flight."
]
}
```
| Situation | Response |
| - | - |
| Search completed and no inventory matched; seller takes no position | `status: "completed"`, `products: []` |
| Structured request filters excluded candidates | Completed response, optionally with `filter_diagnostics` |
| Seller understood the request and deliberately declines it | `status: "rejected"`, `reason`, optional `suggestions[]` |
| Seller needs clarification | `status: "input-required"` |
| Seller accepted work that will finish later | `status: "submitted"` / `"working"` |
| Seller could not produce a usable answer because a dependency timed out or was unavailable | [`SERVICE_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-service-unavailable), normally with `recovery: "transient"` and optional `retry_after` |
`reason` and `suggestions[]` MAY be sanitized to protect confidential merchandising, inventory, policy, and partner rules. Sellers MUST NOT include internal rule text, candidate product identifiers, stack traces, credentials, or private upstream details. Buyers MUST treat these values as untrusted seller-authored plain text: escape them before rendering and sanitize or isolate them before including them in an LLM prompt context.
Retry behavior belongs to the error channel, not this arm or `incomplete[]`. In particular, an upstream outage that leaves no usable product result is a technical failure, normally `SERVICE_UNAVAILABLE` with `error.recovery: "transient"`; buyers then follow `retry_after` or exponential backoff. A rejection without `suggestions[]` is final for that brief, and a rejection with suggestions invites a changed brief rather than an unchanged automatic retry.
The rejection arm carries no `products`, `proposals`, `incomplete`, `filter_diagnostics`, `refinement_applied`, `cache_scope`, `errors`, or envelope-level `adcp_error`. HTTP and MCP keep success markers (`200`, `isError: false`). A2A maps the transport task to `completed`; the AdCP artifact payload carries `status: "rejected"`:
```json theme={null}
{
"status": { "state": "TASK_STATE_COMPLETED" },
"artifacts": [
{
"parts": [
{
"data": {
"status": "rejected",
"reason": "The requested budget is below the minimum for this inventory."
}
}
]
}
]
}
```
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`AUTH_MISSING`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-missing) | No credentials presented | Provide credentials via auth header |
| [`AUTH_INVALID`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-auth-invalid) | Credentials rejected (expired / revoked) | Human credential rotation required; do not auto-retry |
| [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) | Brief too long or malformed filters | Check request parameters |
| [`PRODUCT_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-not-found) | One or more referenced product IDs are unknown | Remove invalid IDs and retry, or re-discover with a `brief` request |
| [`PRODUCT_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-expired) | One or more recognized configured products passed `expires_at` | Re-discover with a new `brief` or `wholesale` request |
| [`PROPOSAL_EXPIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-expired) | A referenced proposal ID has passed its `expires_at` timestamp | Re-discover with a new `brief` or `wholesale` request |
| [`PROPOSAL_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-proposal-not-found) | The referenced `proposal_id` is unknown to the seller (never issued, wrong tenant, or evicted from cache) | Re-issue `get_products` in `brief` or `wholesale` mode to obtain a fresh draft; finalize that recognized proposal before creating the media buy |
| [`MULTI_FINALIZE_UNSUPPORTED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-multi-finalize-unsupported) | `refine[]` carried multiple `action: 'finalize'` entries but the seller cannot guarantee atomic multi-proposal commit | Sequence single-proposal finalize calls — one finalize entry per `get_products` call |
| [`POLICY_VIOLATION`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-policy-violation) | The request itself violates an applicable policy and must be corrected | Review the structured policy details and revise the request. A seller making a deliberate business decision to decline an otherwise well-formed brief uses `status: "rejected"` instead. |
### Authentication Comparison
See the difference between authenticated and unauthenticated access. The hosted test agent requires authentication for every call, so this comparison is illustrative and is not executed by the snippet tests:
```javascript JavaScript test=false theme={null}
import { testAgent, testAgentNoAuth } from '@adcp/sdk/testing';
// WITH authentication - full product results with pricing
const fullProducts = await testAgent.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441028',
buying_mode: 'brief',
brief: 'Premium CTV inventory for brand awareness',
brand: {
domain: 'acmecorp.com'
}
});
if (!fullProducts.success) {
throw new Error(`Failed to get products: ${fullProducts.error}`);
}
console.log(`With auth: ${fullProducts.data.products.length} products`);
console.log(`First product pricing: ${fullProducts.data.products[0].pricing_options.length} options`);
// WITHOUT authentication - limited public product results
const publicProducts = await testAgentNoAuth.getProducts({
idempotency_key: '550e8400-e29b-41d4-a716-446655441029',
buying_mode: 'brief',
brief: 'Premium CTV inventory for brand awareness',
brand: {
domain: 'acmecorp.com'
}
});
if (!publicProducts.success) {
throw new Error(`Failed to get products: ${publicProducts.error}`);
}
console.log(`Without auth: ${publicProducts.data.products.length} products`);
console.log(`First product pricing: ${publicProducts.data.products[0].pricing_options?.length || 0} options`);
```
```python Python test=false theme={null}
import asyncio
from adcp.testing import test_agent, test_agent_no_auth
async def compare_auth():
# WITH authentication - full product results with pricing
full_products = await test_agent.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441030',
buying_mode='brief',
brief='Premium CTV inventory for brand awareness',
brand={
'domain': 'acmecorp.com'
}
)
print(f"With auth: {len(full_products['products'])} products")
print(f"First product pricing: {len(full_products['products'][0]['pricing_options'])} options")
# WITHOUT authentication - limited public product results
public_products = await test_agent_no_auth.simple.get_products(
idempotency_key='550e8400-e29b-41d4-a716-446655441031',
buying_mode='brief',
brief='Premium CTV inventory for brand awareness',
brand={
'domain': 'acmecorp.com'
}
)
print(f"Without auth: {len(public_products['products'])} products")
print(f"First product pricing: {len(public_products['products'][0].get('pricing_options', []))} options")
asyncio.run(compare_auth())
```
**Key Differences:**
* **Product Count**: Authenticated access returns more products, including private/custom offerings
* **Pricing Information**: Only authenticated requests receive detailed pricing options (CPM, CPCV, etc.)
* **Targeting Details**: Custom targeting capabilities may be restricted to authenticated users
* **Rate Limits**: Unauthenticated requests have lower rate limits
## Authentication Behavior
* **Without credentials**: Returns limited public product results, no pricing, no custom offerings
* **With credentials**: Returns complete product results with pricing and custom products
See [Authentication Guide](/dist/docs/3.2.8/building/by-layer/L2/authentication) for details.
## Asynchronous Operations
Most product searches complete immediately, but some scenarios require asynchronous processing. When this happens, you'll receive a status other than `completed`. A `submitted` response with `task_id` is always pollable through [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) (legacy `tasks/get`); `push_notification_config` adds webhook notification for background workflows.
#### SDK Status Handling
The `agent` handle below stands in for any configured `AgentClient`; this is TypeScript pseudo-code and is not executed by the snippet tests:
```typescript test=false theme={null}
import { randomUUID } from 'node:crypto';
const params = {
idempotency_key: randomUUID(),
buying_mode: 'brief',
brief: 'Premium CTV inventory for brand awareness',
};
const initial = await agent.getProducts(params);
const final =
initial.status === 'submitted'
? await initial.submitted!.waitForCompletion(30000)
: initial;
if (final.status === 'failed') {
throw new Error(final.error?.message ?? 'get_products failed');
} else if (final.status === 'rejected') {
console.log(`Seller declined the brief: ${final.reason}`);
console.log(final.suggestions ?? []);
} else if (final.status !== 'completed') {
throw new Error(`Unhandled get_products status: ${final.status}`);
} else {
for (const product of final.products) {
console.log(product.name);
}
}
```
### When Search Runs Asynchronously
Product search may require async processing in these situations:
* **Complex searches**: Searching across multiple inventory sources or custom curation
* **Needs clarification**: Your brief is vague and the system needs more information
* **Custom products**: Bespoke product packages that require human review
### Async Status Flow
> [tab] MCP
>
> #### Immediate Completion (Most Common)
>
> ```json theme={null}
> POST /api/mcp/call_tool
>
> {
> "name": "get_products",
> "arguments": {
> "idempotency_key": "550e8400-e29b-41d4-a716-446655441032",
> "buying_mode": "brief",
> "brief": "CTV inventory for sports audience",
> "brand": { "domain": "acmecorp.com" }
> }
> }
>
> Response (200 OK):
> {
> "status": "completed",
> "message": "Found 3 products matching your requirements",
> "products": [...]
> }
> ```
>
> #### Needs Clarification
>
> When the brief is unclear, the system asks for more details:
>
> ```json theme={null}
> Response (200 OK):
> {
> "status": "input-required",
> "message": "I need a bit more information. What's your budget range and campaign duration?",
> "task_id": "task_789",
> "context_id": "ctx_123",
> "reason": "CLARIFICATION_NEEDED",
> "partial_results": [],
> "suggestions": ["$50K-$100K", "1 month", "Q1 2024"]
> }
> ```
>
> Resume only with a verified continuation descriptor supplied by the transport or SDK. Do not send response `context_id` as an MCP tool argument. The helper names below are placeholders for your own transport plumbing, so this block is illustrative and not executed by the snippet tests:
>
> ```javascript test=false theme={null}
> const continuation = verifiedContinuationFor(response);
> if (!continuation) return requireReconciliation(response);
> await resumeContinuation(continuation, {
> message: "Budget is $75K for a 3-week campaign in March"
> });
>
> // Completed response:
> {
> "status": "completed",
> "message": "Perfect! Found 5 products within your budget",
> "products": [...]
> }
> ```
>
> #### Complex Search (With Webhook and Polling)
>
> For searches requiring deep inventory analysis, configure a webhook for terminal completion/failure notification. The returned `task_id` remains valid for polling via `get_task_status` (legacy `tasks/get`).
>
> ```json theme={null}
> POST /api/mcp/call_tool
>
> {
> "name": "get_products",
> "arguments": {
> "idempotency_key": "550e8400-e29b-41d4-a716-446655441033",
> "buying_mode": "brief",
> "brief": "Premium inventory across all formats for luxury automotive brand",
> "brand": { "domain": "acmecorp.com" },
> "push_notification_config": {
> "url": "https://buyer.com/webhooks/adcp/get_products",
> "authentication": {
> "schemes": ["Bearer"],
> "credentials": "secret_token_32_chars"
> }
> }
> }
> }
>
> Response (200 OK):
> {
> "status": "submitted",
> "message": "Custom curation queued; typical turnaround 10-30 minutes",
> "task_id": "task_456",
> "context_id": "ctx_123",
> "estimated_completion": "2025-01-22T10:30:00Z"
> }
>
> // Later, poll get_task_status/tasks/get with task_id, or receive webhook POST to https://buyer.com/webhooks/adcp/get_products
> {
> "task_id": "task_456",
> "task_type": "get_products",
> "status": "completed",
> "timestamp": "2025-01-22T10:30:00Z",
> "message": "Found 12 premium products across all formats",
> "result": {
> "products": [...]
> }
> }
> ```
> [tab] A2A
>
> #### Immediate Completion (Most Common)
>
> Send the profile URI in `A2A-Extensions` and use the structured invocation body:
>
> ```json theme={null}
> {
> "message": {
> "messageId": "msg-get-products-001",
> "role": "ROLE_USER",
> "parts": [{
> "data": {
> "skill": "get_products",
> "input": {
> "idempotency_key": "550e8400-e29b-41d4-a716-446655441034",
> "buying_mode": "brief",
> "brief": "CTV inventory for sports audience",
> "brand": { "domain": "acmecorp.com" }
> }
> }
> }]
> }
> }
> ```
>
> The non-streaming `SendMessage` response selects its `task` branch. The Task is
> completed and carries the direct AdCP response in its artifact:
>
> ```json theme={null}
> {
> "task": {
> "id": "a2a-task-123",
> "contextId": "ctx_456",
> "status": { "state": "TASK_STATE_COMPLETED" },
> "artifacts": [{
> "artifactId": "adcp-result",
> "parts": [
> { "text": "Found 3 products matching your requirements" },
> { "data": { "status": "completed", "cache_scope": "account", "products": [] } }
> ]
> }]
> }
> }
> ```
>
> #### Needs Clarification
>
> Real-time updates via SSE when clarification is needed:
>
> ```json theme={null}
> {
> "task": {
> "id": "task_789",
> "contextId": "ctx_123",
> "status": {
> "state": "TASK_STATE_INPUT_REQUIRED",
> "message": {
> "messageId": "msg-clarification-001",
> "taskId": "task_789",
> "contextId": "ctx_123",
> "role": "ROLE_AGENT",
> "parts": [
> { "text": "I need a bit more information. What's your budget range and campaign duration?" },
> {
> "data": {
> "reason": "CLARIFICATION_NEEDED",
> "suggestions": ["$50K-$100K", "1 month", "Q1 2024"]
> }
> }
> ]
> }
> }
> }
> }
> ```
>
> Send a new activated profile invocation in the same context, with the refined typed request:
>
> ```json theme={null}
> {
> "message": {
> "messageId": "msg-get-products-002",
> "taskId": "task_789",
> "contextId": "ctx_123",
> "role": "ROLE_USER",
> "parts": [{
> "data": {
> "skill": "get_products",
> "input": {
> "buying_mode": "brief",
> "brief": "CTV sports inventory with a $75K budget for three weeks in March"
> }
> }
> }]
> }
> }
> ```
>
> The resulting Task uses the same completed-artifact mapping as the immediate response:
>
> ```json theme={null}
> {
> "task": {
> "id": "task_789",
> "contextId": "ctx_123",
> "status": { "state": "TASK_STATE_COMPLETED" },
> "artifacts": [{
> "artifactId": "adcp-result",
> "parts": [
> { "text": "Found 5 products within your budget" },
> { "data": { "status": "completed", "cache_scope": "account", "products": [] } }
> ]
> }]
> }
> }
> ```
>
> #### Complex Search (AdCP Submitted and Polling)
>
> Activate the [AdCP A2A Profile Extension v3](/dist/docs/3.2.8/building/by-layer/L0/a2a-profile-extension) on the request:
>
> ```http theme={null}
> POST /api/a2a HTTP/1.1
> A2A-Version: 1.0
> A2A-Extensions: https://adcontextprotocol.org/extensions/adcp/v3
> Content-Type: application/json
> ```
>
> ```json theme={null}
> {
> "message": {
> "messageId": "msg-get-products-003",
> "role": "ROLE_USER",
> "parts": [{
> "data": {
> "skill": "get_products",
> "input": {
> "idempotency_key": "550e8400-e29b-41d4-a716-446655441035",
> "buying_mode": "brief",
> "brief": "Premium inventory across all formats for a luxury automotive brand",
> "brand": { "domain": "acmecorp.com" }
> }
> }
> }]
> }
> }
> ```
>
> If custom curation is queued, the A2A invocation is still complete. The AdCP Submitted response and its durable handle are inside the artifact DataPart:
>
> ```json theme={null}
> {
> "task": {
> "id": "a2a-task-456",
> "contextId": "ctx_789",
> "status": { "state": "TASK_STATE_COMPLETED" },
> "artifacts": [{
> "artifactId": "adcp-result",
> "parts": [{
> "data": {
> "status": "submitted",
> "task_id": "adcp-task-789",
> "message": "Custom curation queued; typical turnaround 10-30 minutes"
> }
> }]
> }]
> }
> }
> ```
>
> Later, send a fresh activated invocation of `get_task_status`. Do not poll `a2a-task-456`; it identifies the already-completed transport invocation.
>
> ```json theme={null}
> {
> "message": {
> "messageId": "msg-get-products-poll-001",
> "role": "ROLE_USER",
> "parts": [{
> "data": {
> "skill": "get_task_status",
> "input": {
> "task_id": "adcp-task-789",
> "include_result": true
> }
> }
> }]
> }
> }
> ```
### Status Overview
| Status | When It Happens | What You Do |
| - | - | - |
| `completed` | Search finished successfully | Process the product results |
| `input-required` | Need clarification on the brief | Answer the question and continue |
| `working` | Searching across multiple sources | Wait on the open connection / transport progress stream |
| `submitted` | Custom curation queued | Poll `get_task_status` with the AdCP `task_id`; on MCP, the seller may advertise the legacy AdCP `tasks/get` alias |
| `rejected` | Seller understood the brief but deliberately declined it | Read the sanitized reason; revise and resubmit only when `suggestions[]` offers a recovery path |
| `failed` | Search couldn't complete | Check error message, adjust brief |
**Note:** For the complete status list see [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle).
**Most searches complete immediately.** Async processing is only needed for complex scenarios or when the system needs your input.
## Next Steps
After discovering products:
1. **Review Options**: Compare products, pricing, and targeting capabilities
2. **Create Media Buy**: Use [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) to execute campaign
3. **Prepare Creatives**: Use each returned product's canonical `format_options[]` to see format requirements
4. **Supply Assets**: Use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) for library-backed sellers, or inline `packages[].creatives` for inline-only sellers
## Learn More
* [Product Discovery Guide](/dist/docs/3.2.8/media-buy/product-discovery/) - Understanding briefs and products
* [Pricing Models](/dist/docs/3.2.8/media-buy/advanced-topics/pricing-models) - CPM, CPCV, CPP explained
* [Brief Expectations](/dist/docs/3.2.8/media-buy/product-discovery/brief-expectations) - How to write effective briefs
* [Media Products](/dist/docs/3.2.8/media-buy/product-discovery/media-products) - Product structure and fields
# get_reporting_status
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status
get_reporting_status checks Reliable Reporting health, lists expected periods and retained revisions, or resolves one exact reporting resource.
> [!WARNING]
>
> **Reliable Reporting 1.0 ships in AdCP 3.2 and remains experimental.** 3.2
> includes the opt-in consumer-status sync and readback. Sellers implementing
> that extension advertise `consumer_status_task`; it stays opt-in until the notice window closes on
> October 24, 2026, and becomes required Core only in the next eligible minor
> after that date. Sellers declare
> `media_buy.reporting_delivery` in `get_adcp_capabilities.experimental_features`.
`get_reporting_status` is the authoritative status surface for AdCP 3.2
Reliable Reporting. It answers whether every report that should exist is present and
usable. It does not replace [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)
as the reporting-data API.
**Request schema:** [`get-reporting-status-request.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/get-reporting-status-request.json)
**Response schema:** [`get-reporting-status-response.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/get-reporting-status-response.json)
> [!NOTE]
>
> **Pinned 3.2 prerelease adopters.** The final 3.2 schemas include everything
> on this page. For integrations still pinned to a 3.2 prerelease: `3.2.0-rc.0`
> supports the `summary`, `periods`, and `revision` views, retained revisions,
> materializations, `receipts[]`, and cursor pagination. `3.2.0-rc.1` adds incremental `changes_after` repair and its checkpoint,
> post-official `adjustments[]` and `adjustment_receipts[]`, and their
> correction/reconciliation semantics. `3.2.0-rc.2` adds `consumer_statuses[]` for
> sellers advertising `consumer_status_task` and includes those immutable records
> in flat pagination and `changes_after` checkpoints. `3.2.0-rc.3` adds the
> consumer-status hardening: `obligation_counts.consumer_status_pending`, issue
> `opened_at` / `issue_state` / `external_ref`, and the
> `consumer_mismatch_escalation_seconds` and `operations_contact` capability
> fields. Do not infer a later tier's additions from an earlier baseline.
## Views
Every request explicitly selects one response shape:
| View | Use |
| - | - |
| `summary` | Answer “where is my reporting?” for an account, media-buy, and time scope. |
| `periods` | Enumerate a flat cursor-paginated ledger of obligations, retained revisions, post-official adjustments, consumer status statements, materialization attempts, and receipts. Use `changes_after` for incremental repair. |
| `revision` | Resolve one exact `reporting_revision_id` and a cursor-paginated page of its adjustments, consumer status statements naming that revision, materializations, and receipts. |
SDKs may default a convenience `status()` call to `summary`; the wire request remains
explicit so adding a filter never silently changes the response type.
```json theme={null}
{
"account": { "account_id": "acc_123" },
"view": "summary",
"delivery_config_ids": ["analytics-daily"],
"feed_purposes": ["analytics"],
"period": {
"start": "2026-08-01T00:00:00Z",
"end": "2026-08-28T00:00:00Z"
}
}
```
```json theme={null}
{
"status": "completed",
"view": "summary",
"ledger_snapshot_id": "ledger_20260828_001",
"ledger_as_of": "2026-08-28T12:00:00Z",
"account_id": "acc_123",
"scope": {
"period_start": "2026-08-01T00:00:00Z",
"period_end": "2026-08-28T00:00:00Z",
"scope_closed": false,
"all_accessible_media_buys": true,
"delivery_config_generations": [
{
"delivery_config_id": "analytics-daily",
"delivery_config_version": 1,
"feed_purpose": "analytics"
}
],
"feed_purposes": ["analytics"],
"finality": ["official"],
"ledger_retained_from": "2026-07-29T00:00:00Z",
"coverage_complete": true
},
"health": "action_required",
"coverage": {
"status": "full",
"evaluated_at": "2026-08-28T00:00:00Z",
"media_buy_ids": ["mb_123"],
"fully_covered_media_buy_ids": ["mb_123"],
"partially_covered_media_buy_ids": [],
"unsupported_media_buy_ids": [],
"unknown_media_buy_ids": [],
"package_ids": ["pkg_123"],
"covered_package_ids": ["pkg_123"],
"unsupported_package_ids": [],
"unknown_package_ids": [],
"limitations": []
},
"data_through": "2026-08-26T00:00:00Z",
"next_expected_at": "2026-08-28T04:00:00Z",
"obligation_counts": {
"total": 27,
"waiting": 1,
"healthy": 25,
"delayed": 0,
"action_required": 1,
"complete": 0,
"consumer_status_pending": 2
},
"issues": [
{
"issue_id": "iss_report_overdue_analytics_daily_20260826",
"code": "REPORT_OVERDUE",
"severity": "action_required",
"responsible_party": "seller",
"recommended_action": "contact_seller",
"media_buy_ids": ["mb_123"],
"period_start": "2026-08-26T00:00:00Z",
"period_end": "2026-08-27T00:00:00Z",
"expected_at": "2026-08-27T04:00:00Z"
}
]
}
```
## Health semantics
| Health | Meaning |
| - | - |
| `healthy` | Due obligations in this active scope are current and automatic delivery is working. |
| `waiting` | No obligation in this active scope is due yet. |
| `delayed` | At least one obligation is late but still inside automatic recovery, or — caller-scoped only — a buyer's `received` status was made stale by a seller restatement and is still inside its re-read grace window. In the second case nothing is actually late; read `issues[].code` before charting this as seller lateness. |
| `action_required` | An SLA or retry boundary was crossed, a Reconciled Billing receipt is missing/rejected, **or** the authenticated buyer reports that seller-healthy reporting is omitted, missing, unreadable, or contradictory; `issues[]` supplies the human action. |
| `complete` | This scope is closed, fully covered by retained ledger history, and every obligation over its configured covered denominator has the required finality and an authoritative readable revision — for Core (API-delivered) obligations that means published and retained per `status_retention_days`; managed-delivery obligations additionally require a verified readable materialization. Obligations configured for consumer reconciliation also have an accepted receipt for the current revision. This delivery state does not replace the separate `coverage.status` claim. |
Aggregate precedence is `action_required` before `delayed` before `healthy`.
`waiting` applies only when nothing is due. `complete` requires
both `scope.scope_closed: true` and `scope.coverage_complete: true`; a current
but open account scope is `healthy`, not `complete`.
Health is evaluated over the exact `delivery_config_generations`, `feed_purposes`,
finality, media buys, and time horizon echoed in `scope`. Buyers can query billing,
analytics, and pacing independently; a delayed analytics feed cannot silently taint or
hide billing status. A snapshot-required pacing obligation can become `complete` from
a snapshot revision—`complete` means required finality, not always `official`.
An unfiltered account with no caller-owned reporting configurations returns a valid
empty scope: `delivery_config_generations`, `feed_purposes`, and `finality` are empty,
all obligation and record counts are zero, and `data_through` is null. A closed empty
scope may be `complete`; this is distinct from naming an unknown or unauthorized
`delivery_config_id`, which uses the indistinguishable unavailable-lookup response.
This state is reachable after the caller intentionally sends
`reporting_delivery_configs: []`.
### Future expectation on a complete summary
Adopters still pinned to the immutable `3.2.0-rc.3` schemas see the earlier
prohibition on this field with complete health; later 3.2 artifacts carry this
correction.
For `view: summary` with `health: complete`, a seller MUST populate
`next_expected_at` when an active committed configuration generation in
`scope.delivery_config_generations` has a future scheduled period outside the
closed evaluated scope. Select the nearest future **period start**, strictly
after `ledger_as_of`, across all those active generations. Omit the field when
none has such a future period, including an account with no configurations.
This timestamp comes from the configuration schedule. Its presence does not
indicate that the evaluated scope is still open and does not represent an open
obligation in that scope. Projecting it MUST NOT create, expose, lease, count,
or alter an obligation whose period has not closed, or change `obligation_counts`,
`scope`, or `coverage`. Both complete-health scope guards still apply.
For example, at `ledger_as_of: 2026-08-01T04:05:00Z`, a completed evaluated
scope `[00:00, 01:00)` may select active hourly and daily UTC configurations.
Their next period starts are `2026-08-01T05:00:00Z` and
`2026-08-02T00:00:00Z`, so the summary returns the former as `next_expected_at`.
The completed obligation count and coverage remain those of `[00:00, 01:00)`.
This complete-scope projection applies to the summary view; a complete periods
response continues to omit the field. The existing open-scope value remains
the next obligation due time. An obligation's
`expected_at` remains `period.end + schedule.delivery_sla`, while the
similarly named field in
[`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)
remains the next webhook notification time and is omitted for final
notifications. Completing an evaluated reporting scope does not finalize an
active configuration's schedule or its notification stream.
## Reliability model
The periods view keeps six facts distinct:
* An **obligation** records what report was expected and when, so a missing first
webhook is detectable.
* A **revision** is one immutable logical publication. It is destination-independent,
so one revision can fan out to S3, BigQuery, Databricks, Snowflake, and other
delivery paths without changing identity. A zero-row revision is real;
provisional restatements get new snapshot IDs and retain supersession
lineage. An official revision is immutable billing-purpose reporting evidence.
* An **adjustment** is one immutable accounting-only post-official correction.
It carries signed control-total deltas in a period derived from a pinned billing
calendar/correction policy; it cannot reopen books or alter invoices.
* A **materialization** is one attempt to expose that revision through a durable file
transfer, dataset share, or warehouse for one obligation and destination. A retry
gets a new materialization ID but keeps the same revision ID.
* A **consumer status** is the authenticated buyer's immutable statement that an
expected period was received, omitted from the seller ledger, missing its
revision, unreadable, or contradictory to the accepted configuration
generation. It remains separately attributed and can identify a
missing seller obligation without a seller-issued obligation ID.
* A **receipt** is one authenticated consumer's accepted or rejected reconciliation
result for an exact materialization. Availability says the producer published it;
an accepted receipt says that consumer independently observed matching evidence.
All historical revisions and adjustments retained under the advertised capability
window appear in the ledger. Consumers must not assume the latest snapshot is the
only relevant record, and must never treat an adjustment as authority to rewrite an
invoice or accounting book.
If the seller cannot serve or verify the content of a revision it still owes — its
stored rows are missing or no longer match `revision_content_sha256` — it opens a
`REVISION_UNREADABLE` issue naming the revision and each affected obligation. The
revision stays listed, the obligation is neither `healthy` nor `complete` while the
issue is open, and exact reads return [`SERVICE_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-service-unavailable) rather than a not-found
result. The issue is `delayed` with `wait_for_retry` while automatic repair runs and
`action_required` with `contact_seller` once it cannot. It is retired when exact
reads again return the committed content or the revision's retention window ends.
An obligation whose official revision is lost never becomes `complete`.
`reporting_revision_id` is the portable AdCP identity. Every ready resource selects
immutable bytes or an immutable native snapshot/version—for example a Delta version,
Snowflake object identity, BigQuery snapshot, or manifest generation—and never
substitutes for the AdCP ID. Row counts and profile-defined control totals always
agree. The selected verification profile determines the stronger evidence required:
provider-native version, manifest and file checksums, or a canonical logical-content
digest. Billing requires the canonical-digest profile; frequent pacing and analytics
snapshots may use cheaper native or manifest verification.
Every obligation freezes an explicit `media_buy_ids` denominator at
`scope_resolved_at`, which equals the period end, including media buys that produced zero rows. For an
`all_media_buys` configuration, this is every caller-authorized media buy on the
account whose effective flight overlaps the half-open period and which was known at
the resolution cutoff. `[]` means definitively no media buys; omission never means
all, empty, or unknown. A later-created or backdated media buy does not rewrite that
historical obligation. This prevents current authorization state, deleted provider
objects, and zero-delivery campaigns from silently changing the denominator.
The period boundary is also the obligation's availability boundary. Before taking
any ledger snapshot whose `ledger_as_of` is later than `period.end`, the seller must
have committed the obligation independently of source availability and before
committing any revision for it. A `periods` view whose selected denominator includes
that configuration generation and period must return it in the paginated record set.
Snapshots whose `ledger_as_of` is at or before the boundary do not expose the
obligation; they may expose only the derived future `next_expected_at`.
Media-buy acceptance alone does not create an obligation, and a revision,
materialization, or doorbell is never a prerequisite. The applicable reporting
configuration generation defines the clock; `expected_at` remains `period.end +
schedule.delivery_sla`.
Per-buy `reporting_webhook` remains the existing low-latency data API. It is not a
durable materialization in this first managed-ledger version; a short-period pacing
configuration plus the signed readiness doorbell is the reliable fast path here.
Periods pagination applies to the flat union of `periods[]` obligation records,
`revisions[]`, `adjustments[]`, `consumer_statuses[]`, `materializations[]`, `receipts[]`, and
`adjustment_receipts[]`, so one
heavily restated, corrected, retried, or reconciled period cannot create an
unbounded nested response. Each obligation's record counts let the SDK prove it
found the complete associated history across pages.
## Consumer-status mismatch
After reading or repairing reporting, a buyer calls
[`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status).
`get_reporting_status` returns that authenticated caller's append-only statements
in `consumer_statuses[]`; no buyer can read another buyer's status.
The seller compares only the current unsuperseded statement with its own current
projection. If the seller says `healthy` or `complete` while that buyer's status
conflicts, this caller/account view is degraded with a stable
`CONSUMER_STATUS_MISMATCH` issue.
The issue carries `opened_at`, points at `reporting_status_id`, and names the
diagnosed `responsible_party`. Neither claim overwrites the other.
A conflict is `obligation_missing`, `revision_missing`, `unreadable`,
`content_mismatch`, or `received` naming an older revision after the seller
publishes a newer required restatement. The last one is how the seller can see
that reporting changed after the buyer already read it;
`content_mismatch` is how the buyer says the reporting arrived but contradicts
the accepted configuration generation — a contract-fact disagreement, not a
measurement dispute.
### Severity: immediate, except for stale `received`
| Current statement | Severity |
| - | - |
| `obligation_missing`, `revision_missing`, `unreadable`, `content_mismatch` | `action_required` immediately. |
| `received` naming a revision superseded by a seller restatement | `delayed` until the grace deadline below, then `action_required`. |
The stale-`received` carve-out exists because that buyer consumed exactly what
the seller required at the time and has not yet had a bounded chance to re-read.
Paging a human the instant a seller restates a provisional revision would train
buyers to ignore the signal.
The grace deadline is the `created_at` of the **first** revision that superseded
the one the consumer named, plus the configuration generation's
`schedule.delivery_sla`, as exact elapsed time in UTC. When that SLA resolves to
a zero duration, the seller uses `automated_recovery_window_seconds` instead so
a zero-SLA feed still gets a bounded window.
Two properties keep the window from becoming a hiding place. Later restatements
do **not** restart it — it is anchored to the first supersession, not to the
newest revision — and the issue keeps one `issue_id` and one `opened_at` across
the severity change, so it ages as a single work item. An advertised
`consumer_mismatch_escalation_seconds` boundary takes precedence when the two
overlap: at `opened_at` plus that window the issue is `action_required`
regardless of the grace deadline.
### Escalation, lifecycle, and contacts
A seller that advertises `consumer_mismatch_escalation_seconds` (which requires
advertising `operations_contact`) commits to escalating: once an issue has been
open that long measured from its `opened_at`, it MUST be `action_required` with
a `contact_*` `recommended_action` naming the diagnosed `responsible_party`.
Issues may also carry `issue_state` (`open`, `acknowledged`, `resolved`,
`waived`) and an inert `external_ref` for correlation with each side's own
ticketing. Only `open` and `acknowledged` issues appear in `issues[]`; retiring
an issue removes it rather than publishing it in a terminal state, so a reader
that treats a non-empty `issues[]` as degradation stays correct.
`resolved` means the underlying disagreement ended: the consumer superseded the
statement with one that agrees, or the seller's projection changed so the two no
longer conflict. `waived` is different. It records an explicit off-protocol
agreement by the authenticated consumer and seller to disregard that exact
caller/account issue; a seller cannot create the agreement unilaterally. The
waiver is bound to the `issue_id`, causing `reporting_status_id`, and diagnosed
conflict. It retires the issue and restores the underlying seller health in
both summary counts and the period projection, even while that immutable
consumer statement remains the current leaf in `consumer_statuses[]`. It does
not turn the statement into seller evidence. A later statement or materially
different conflict is evaluated independently and receives a new issue ID.
If the waiver removes the last impairment, sellers offering
`reporting.status_changed` emit the recovery transition only after the recovered
projection is readable; `issue_ids` is empty or absent. If another impairment
keeps health unchanged, no health-transition notification is required. Polling
remains authoritative in either case.
`operations_contact` is human-facing metadata: surface it to an
operator, never dereference it or treat it as an AdCP endpoint. Its URL is
constrained to the same hardened public-origin shape as the offering document
URIs, so it cannot name a loopback host, an IP literal, or a credentialed link.
### Silence is counted, not escalated
A buyer owes a current status for each elapsed expected period by
`expected_at` + `automated_recovery_window_seconds`. A seller that advertises
`consumer_status_task` reports how many obligations in scope are past that
deadline with no current statement from this caller in
`obligation_counts.consumer_status_pending`. A chain with any unsuperseded leaf
counts as current whatever that leaf says; only an empty chain is pending. It
counts obligations, so a period the seller omitted entirely is not in it — your
own derived denominator, not this field, stays the authority on omitted periods.
That count is visibility only: it
overlaps the health counts rather than partitioning them, and it never changes
`health`, another count, or seller-advertised `reliability_statistics`.
A `received` status does not satisfy seller production health and is not a billing
receipt. Missing buyer status stays unknown and never excuses an overdue seller
obligation. Buyer-attributed status also stays out of seller-advertised
`reliability_statistics` unless independently corroborated.
## Readiness and recovery
Push is **optional in every tier**: a polling-only seller that answers
`get_reporting_status` truthfully is fully Core-conformant, and buyers MUST
treat polling as the authoritative recovery path regardless of what is
offered. Three doorbells exist, with different purposes:
* **`reporting.status_changed`** (any tier, including Core) — invalidation
for health transitions in *either* direction, including clock-driven
`waiting → delayed` and `delayed → action_required` transitions that no
positive signal would ever announce, and recovery back to `healthy`/
`complete`. Payload carries identifiers, the new health, and stable
`issue_ids` matching `issues[].issue_id`, so consumers can project AdCP
reporting issues into durable work items. Repair it with a non-incremental
current summary or periods read: a clock-only transition may have no new
immutable ledger record and therefore no `changes_after` delta.
* **`reporting.delivery_ready`** (managed-delivery tier only) — positive
readiness for one materialization at a destination. Core configurations
never fire it.
* **`reporting.ledger_changed`** (any tier, including Core) — invalidation
for every new revision or adjustment, even when an already-healthy period
remains healthy. Its record identity lets receivers deduplicate; repair uses
the receiver's own durable checkpoint rather than trusting event order.
When offered (advertised via `readiness_notification`),
`reporting.delivery_ready` is an account-anchored doorbell registered through
[`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) `notification_configs[]`. It is
emitted only after the materialization is observable through the intended consumer
path. Provider job/grant completion alone is not readiness.
The webhook contains only account, configuration, revision, materialization, finality,
and freshness metadata. Receivers call `get_reporting_status` to resolve the resource.
Credentials, signed URLs, activation URLs, and object lists never belong in the event.
Delivery is signed, at least once, and may be out of order. SDKs deduplicate transport
retries by authenticated sender plus `idempotency_key`, deduplicate ingestion by
revision/materialization identity, and combine this with
periodic status polling, checksum verification, and a durable local checkpoint to
produce effectively-once downstream publication. `reporting.status_changed`
must not be used to detect content corrections: health and ledger content are
separate state machines. The protocol does not claim
exactly-once network delivery.
For configurations with `reconciliation_mode: consumer_receipt`, an SDK independently
reads the destination, records its row count and control totals plus the selected
digest/version evidence, and calls
[`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts).
It then re-reads this ledger until the receipt is visible. A rejected receipt keeps
the obligation unresolved and gives both parties a durable discrepancy to investigate.
## Configuration and capabilities
Reliable Reporting capability resolves in layers. The seller-wide
`get_adcp_capabilities.media_buy.reporting_delivery.offerings[]` catalog describes
atomic combinations the seller can provide: exact report definition and row grain,
feed purpose, period/alignment/SLA, supported `snapshot` and/or `official` finality,
verification/reconciliation profile, and delivery method. Thus a seller can advertise
an hourly snapshot-to-S3 offering separately from daily official billing delivery or a
versioned dataset share. Buyers never construct an unsupported cross-product from
independent capability arrays.
For the onboarding question **“Do you support Reliable Reporting?”**, use this
machine decision procedure:
1. `experimental_features` contains `media_buy.reporting_delivery`.
2. `media_buy.reporting_delivery.supported` is `true`.
3. `media_buy.reporting_delivery.reliable_reporting_version` is `"1.0"`.
4. Read `managed_delivery` and `reconciled_billing` for optional tier support,
then select an atomic `offerings[]` entry that the Product exposes through
`reporting_delivery_offering_ids`.
Legacy `reporting_delivery_methods`, generic reporting APIs, or another
protocol declaration do not answer this AdCP capability question. AAMP and
AdCP have overlapping reporting workflows but are not wire-compatible; assess
each protocol through its own discovery surface rather than inferring support.
Seller-wide support is not a claim that every product can produce every offering.
Each Product's `reporting_capabilities.reporting_delivery_offering_ids` declares the
applicable subset. Account, seat, credential, provider, or API constraints may narrow
that set further during configuration. Each period obligation freezes the resulting
media-buy and package coverage so later product or capability changes cannot rewrite
history.
Configurations select `coverage_requirement: full` or explicitly opt into
`allow_partial`. Coverage is reported as `full`, `partial`, `none`, or `unknown`, with
the covered and excluded buys/packages and stable reasons. It is independent of
freshness, finality, and delivery health: a partial snapshot may be fresh and delivered
without becoming complete campaign reporting. Sellers must not weaken the selected
profile to a lowest common denominator, silently omit unsupported packages, or label
covered-subset metrics as whole-buy totals. Official or billing completeness requires
official coverage for every required component.
Account durable-delivery desired state is configured through
`sync_accounts.accounts[].reporting_delivery_configs[]`. Replacement is scoped to the
authenticated caller and account; one caller cannot remove another caller's entries.
Each entry is an immutable `(delivery_config_id, delivery_config_version)` generation;
changing scope, schedule, profile, method, or destination requires a higher version.
It selects one atomic `offering_id` advertised by the seller and carries a
`destination` in one of two modes:
* `provision` supplies non-secret provider coordinates and asks the seller to create
or validate the binding; and
* `existing` supplies the seller-issued `destination_ref` returned by an earlier sync.
For a Databricks dataset share, the buyer selects an atomic offering with one provider,
access mode, transport, and orchestration combination, then sends its recipient
identity. The seller
creates the share/recipient binding. For a buyer-owned warehouse or object store, the
buyer sends its provider-native location and grants the seller the
`producer_identity` advertised in the selected atomic offering. A consumer-managed transfer such as
GAM to BigQuery uses the same provisioned-location shape even though the transfer
service, rather than the seller process, writes the table.
[`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts) and
[`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts) return
`reporting_delivery_configs[]` as resolved configuration state.
`pending_validation`, `pending_setup`, `ready`,
`action_required`, and `inactive` distinguish binding setup from report delivery
health. Once resolved, the seller returns a stable `destination_ref`. When a provider
requires an interactive grant or Open Sharing activation, `setup` may return an HTTPS
authenticated entry point and a concrete action. Agents must not fetch, preview, or
interpret it; they surface it for explicit human action. It must use a seller/provider
origin and never be a bearer URL or contain credentials.
Each configuration represents one independently reconciled feed. The selected
offering and immutable configuration generation both name the exact
`report_definition_id`. The offering also pins an immutable
`report_definition_uri` and SHA-256. Its bundled
`application/vnd.adcp.reporting-definition+json` document makes metric, grain,
attribution, action-report-time, timezone/calendar, source/API mapping, query
parameters, restatement behavior, and finality rules inspectable rather than leaving
those choices behind an opaque profile label. Official revisions echo the URI and
digest and select one matching finality policy from that definition. `feed_purpose`
distinguishes fast `pacing`, `analytics`, and invoice-authoritative `billing` data.
`reconciliation_mode: delivery_only` ends the protocol guarantee at verified
availability; `consumer_receipt` additionally requires authenticated consumer
agreement. Billing configurations use `consumer_receipt`.
Event-level exposure delivery is deferred until it has a separate privacy and
authorization contract. `schedule.period_duration`, `schedule.alignment`, and
`schedule.delivery_sla` determine which period obligations must exist and when they
become overdue. `billing_cycle` schedules also require an immutable `period_anchor`
and IANA `period_timezone`; calendar durations use local civil time and its DST rules
rather than a fixed number of seconds. Month/year boundaries preserve the anchor's
local day and time, clamp to the target month's last valid day, and are always derived
from the original anchor. A mid-period activation starts at the next full boundary.
Deactivation applies a boundary cutoff: already-started periods remain owed, while
later periods are not created. Install multiple configurations when the buyer needs, for example, a
15-minute snapshot pacing feed, daily official analytics, and billing-cycle official
billing data. Billing feeds require official finality.
`source_timezone` represents an upstream reporting calendar that differs from
the AdCP account clock—for example an ad server's network timezone. The
installed schedule always carries its resolved IANA `period_timezone`; an
offering either fixes that timezone or declares it `account_resolved`. Before a
configuration becomes ready, the seller must prove that every selected source
can produce the exact half-open periods natively or by lossless re-bucketing
from finer-grained data. An unsupported calendar is a configuration error, not
a reason to leave obligations `waiting`. If discovered after acceptance it is
seller-owned `action_required`.
Capability offerings advertise schedule constraints, not necessarily an
account-specific billing clock. A billing-cycle offering declares its anchor policy as
`fixed` or `configurable`. A fixed offering supplies the exact anchor and timezone; a
configurable offering lets the authorized account configuration supply both. This
avoids a separate global capability entry for every contract anniversary while still
making the installed schedule independently reproducible. For a January 31 monthly
anchor, February clamps to its last civil day and March is derived again from January
31 rather than drifting from February. DST boundaries retain the configured local
wall-clock time.
For non-billing schedules, phase is not implicit. `utc` counts intervals from
`1970-01-01T00:00:00Z`; `account_timezone` counts from local midnight on that date in
the resolved account timezone; `source_timezone` counts from local midnight in
its explicit upstream timezone. Boundaries are derived directly from that origin and
the interval ordinal. Nonexistent DST times advance by the gap and ambiguous times use
the earlier offset, so durations such as `P2D` or `PT7H` produce the same intervals in
independent implementations.
Supported patterns are:
* `file_transfer` — immutable objects plus a normative manifest-last commit. The
manifest binds revision, obligation, materialization, period, format, compression,
complete file list, sizes, cryptographic checksums, row counts, and control totals;
* `dataset_share` — consumer-observed access to a versioned relation/share; and
* `warehouse_materialization` — verified publication into a warehouse relation or
partition.
Orchestration is declared separately as `producer_managed` or `consumer_managed`.
It does not imply who owns the destination or which platform service writes it.
When `sync_agent_configuration` is supported, its `destination_ref` identifies one
immutable destination generation owned by the stable authenticated caller and may be
reused across that caller's separately authorized seller accounts. The account feed
configuration—not possession of the reference—is the disclosure authorization.
Changing proof-bound destination or recipient coordinates, accepted formats, access
mode, or verification contract produces a new reference; retained configurations and
history continue to resolve the old one.
The experimental capability advertises atomic feed/profile/schema/schedule/finality/
method offerings, automatic recovery duration, metadata retention, exact-resource
retention, authorization revocation latency, and reader constraints. The receipt
task is deliberately narrow: it records content reconciliation, not mere webhook
delivery. A separate replay mutation remains unnecessary in v1 because ordinary
missed-event recovery reads retained immutable resources through this task.
Capabilities may also publish evidence-scoped `reliability_statistics` for each
offering: due and on-time counts, p50/p95 publication latency, official revision
and adjustment counts, adjustment latency, and optional control-total magnitude.
These figures name their measurement window, sample size, and ledger or
third-party-attestation evidence. Sellers may not exclude late or corrected
periods or combine unlike offerings. This keeps a long nominal SLA visible as a
slower product rather than making it look equivalent to a short SLA that is
consistently met.
Each profile includes an exact HTTPS schema URI and SHA-256 digest. SDKs fetch only
from the authenticated seller, named provider, or AdCP registry origin; reject IP
literals, private/reserved DNS, userinfo, redirects, and DNS/connect mismatch; cap
response bytes/time/content type; and verify the digest before parsing. Schema content
and annotations are untrusted data, never agent instructions. Schemas are
self-contained bundles using the closed, SDK-bundled JSON Schema 2020-12 dialect.
SDKs install no network resolver and recursively reject every non-fragment `$ref`, all
`$dynamicRef`/`$recursiveRef` keywords, unknown metaschemas/vocabularies, reference
cycle, excessive depth/node count, and oversized regex before compilation.
Report definitions use the same authenticated-origin, redirect-free, DNS-pinned,
bounded-fetch and digest-verification rules. Their canonical JSON is data, not agent
instructions, and may not contain executable content or external references.
Canonical-digest profiles also include a `canonicalization_uri` and SHA-256 for the
exact ordering, value-encoding, null, and row-serialization contract. The identifier
and digest alone are not an executable agreement. The fetched
`application/vnd.adcp.reporting-canonicalization+json` document follows the bundled
`reporting-canonicalization-contract.json` schema, selects the closed
`adcp_jcs_rows_v1` algorithm, and contains cross-language golden vectors. SDKs fetch this contract under the
same origin, redirect, DNS, byte, time, and content-type controls and verify its bytes
and golden vectors before computing or accepting a billing digest.
## Complete reconciliation
Every response carries `ledger_snapshot_id` and `ledger_as_of`. A periods cursor is
bound to that immutable snapshot, every page repeats its identity, and
`pagination.total_count` is required. SDKs reject a changed snapshot identity, dedupe
each record by its type-specific immutable ID, and finish only when the unique stored
record count equals `total_count` and each obligation's
revision/adjustment/consumer-status/materialization/receipt counts match. A periods response also
returns `changes_checkpoint`. The buyer persists it only after `has_more: false`
and supplies it as `changes_after` on the next read. The seller must return every
later record and the current projection of affected obligations; it may safely
replay older immutable records. Later changes never move the result set underneath
an in-progress page walk.
The response ledger is not the buyer's only denominator. SDKs derive the exact
periods that should exist from the buyer's saved configuration generations and
resolved calendar boundaries, then require a matching obligation for every expected
period. This detects an omitted first obligation even if no webhook or materialization
ever existed. “Definitive for yesterday” therefore means: the requested scope is
closed and retained, every locally expected obligation exists, one official revision
provides the immutable close, a verified resource remains readable, all history counts
are present, and—when configured—every authenticated receipt for that revision and its
applicable adjustments is accepted. External billing systems MAY retain that exact
`reporting_revision_id` as supporting evidence; later corrections are accounting-only
adjustments in a billing-calendar-derived period.
An `official` revision also states why it is final and when that rule was applied.
`source_final`, `contractual_cutoff`, and `stabilized` distinguish a provider's
authoritative close from a versioned commercial cutoff or stabilization rule;
`finality_policy_id` is bound by the immutable report definition. Social attribution
feeds therefore do not have to pretend that a platform supplied a final bit it does
not expose. `schedule.delivery_sla` cannot promise an official revision before its
selected finality policy can become true.
`scope.ledger_retained_from` and `scope.coverage_complete` prevent expired history from
looking complete. Metadata may outlive physical resources; each completed obligation
also states `resource_retained_until`, and at least one exact verified resource remains
readable through that time and the advertised resource-retention window. Outside those boundaries, the seller reports an
explicit unavailable/error condition rather than silently claiming completeness.
Deferring a separate replay mutation does not defer recovery. Missing webhooks,
duplicates, out-of-order notifications, zero-row periods, failed materializations,
snapshot restatements, and post-official adjustments all converge through the
checkpointed obligation ledger. Campaign-control decisions
based on feed health belong to buyer policy or Campaign Pulse, not this reporting
delivery contract. This task reports evidence and never pauses or resumes spend.
Buyer and governance consumers reconcile independently. The seller may fan the same
canonical revision out through separately authorized obligations and destinations,
but each authenticated principal submits its own receipt; one principal's acceptance
never implies another's. The seller learns that a consumer agrees with the published
row count, control totals, and selected verification evidence—not that the consumer
used the data correctly after its stated `consumer_commit_ref`.
The authenticated caller identity comes from transport authentication, not payload
fields. Accounts, destination bindings, cursors, snapshots, revisions,
materializations, and resources are caller/account scoped; unknown and unauthorized
identifiers return indistinguishable errors.
# Task Reference
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/index
AdCP media buy task reference — all tasks for product discovery, campaign creation, delivery reporting, creatives, audiences, and conversion tracking with schemas and examples.
Complete reference for all AdCP Media Buy tasks. Each task is designed for AI agents to automate specific parts of the advertising workflow.
## All Tasks Overview
| Task | Purpose | Response Time | Phase |
| - | - | - | - |
| [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) | Enumerate structured product offers | \~1s | Discovery |
| [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) | Request seller-authored plans | \~60s | Planning |
| [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) | Revise proposals or finalize inventory holds | \~60s | Planning |
| [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals) | Record terminal proposal feedback | \~1s | Planning |
| [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) | Buy published offers directly | Minutes-Days | Media Buys |
| [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) | Accept new-buy, amendment, or cancellation terms | Minutes-Days | Media Buys |
| [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) | Apply operational delivery controls | Minutes-Days | Media Buys |
| [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) | 3.x compatibility discovery and refinement facade | \~60s | Compatibility |
| [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) | 3.x compatibility creation facade | Minutes-Days | Compatibility |
| [`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy) | 3.x compatibility update facade | Minutes-Days | Compatibility |
| [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) | View endpoint capabilities, including creative operations | \~1s | Capability |
| [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs) | Sync catalog feeds (products, stores, inventory) | Minutes-Days | Catalogs |
| [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) | Upload and manage creative assets | Minutes-Days | Creatives |
| [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) | Query creative library with filtering | \~1s | Creatives |
| [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) | Retrieve media buy status, creative approvals, and delivery snapshots | \~1s | Monitoring |
| [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) | Retrieve performance and delivery data | \~60s | Reporting |
| [`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status) | Check Reliable Reporting health and repair missed ledger changes | \~1s | Reporting |
| [`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status) | Tell a seller whether expected reporting was received, omitted, missing, unreadable, or contradictory | \~1s | Reporting |
| [`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts) | Record Reliable Reporting revision and adjustment reconciliation | \~1s | Reporting |
| [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) | Submit performance signals for optimization | \~1s | Optimization |
| [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) | Configure event sources for conversion tracking | \~1s | Conversion Tracking |
| [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event) | Send marketing events for attribution | \~1s | Conversion Tracking |
| [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) | Upload and manage first-party CRM audiences | Minutes-Days | Audiences |
## Response Time Categories
AdCP tasks fall into four response time categories:
### 🟢 Instant (\~1 second)
**Simple lookups and event ingestion**
* [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) - Published offers and canonical `Product.format_options[]`
* [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives) - Creative library queries
* [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) - Media buy status and creative approvals
* [`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status) - Managed-reporting health and revision resolution
* [`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status) - Authenticated buyer status for each expected reporting period
* [`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts) - Authenticated reporting reconciliation receipts
* [`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback) - Performance signal submission
* [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) - Event source configuration
* [`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event) - Event ingestion
### 🟡 Processing (\~60 seconds)
**AI/LLM inference with backend systems**
* [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) - Seller planning from a natural-language brief and structured criteria
* [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) - Typed proposal revision and finalization
* [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) - Performance data aggregation
### 🟠 Asynchronous (Minutes to Days)
**Complex operations with potential human approval**
* [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) - Direct published-offer commitment
* [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) - Negotiated commitment, amendment, or cancellation
* [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) - Revision-checked operational control
* [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs) - Catalog feed processing and review
* [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) - Creative asset processing
* [`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences) - Audience matching and processing
## Task Categories by Workflow
### Account Management
Before placing media buys, establish a commercial relationship with the seller. These tasks are shared across all vendor protocols and live in the Commerce Protocol section:
* **[`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts)** - Declare brand/operator pairs and billing; seller provisions accounts
* **[`list_accounts`](/dist/docs/3.2.8/accounts/tasks/list_accounts)** - Check account status and retrieve active `account_id` values
### Discovery & Planning
Start here to understand what's available and plan your campaign.
* **[`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities)** - Discover agent capabilities, portfolio, and supported features (protocol-level task)
* **[`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products)** - Read published offers or bootstrap and repair a wholesale mirror
* **[`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals)**, **[`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals)**, and **[`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals)** - Request seller-authored plans, create immutable successors, finalize holds, or record terminal feedback
* **[Canonical formats](/dist/docs/3.2.8/creative/canonical-formats)** - Understand creative requirements and authority
### Media Buy Management
Create and manage your advertising campaigns.
* **[`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products)** - Directly buy published product offers
* **[`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal)** - Apply negotiated new-buy, amendment, or cancellation terms
* **[`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy)** - Modify delivery controls inside accepted terms
### 3.x Compatibility
Use these only when capability discovery does not expose the compact lifecycle:
* **[`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy)** and **[`update_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/update_media_buy)** - Deprecated 3.x compatibility facades
* **[`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products)** - 3.x compatibility discovery facade; new integrations choose `list_products` or `request_proposals`
### Catalog Management
Sync product feeds, inventory, and store data to seller accounts.
* **[`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs)** - Push catalog feeds with platform review and approval
### Creative Management
Handle creative assets throughout their lifecycle.
* **[`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives)** - Upload assets to an agent-hosted creative library
* **[`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives)** - Search and manage your creative library (creative protocol)
* **`assignment_operations`** - Explicitly assign, unassign, or replace package creatives after compact commitment
### Performance & Optimization
Monitor and optimize campaign performance.
* **[`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys)** - Check campaign status, creative approvals, and near-real-time delivery snapshots
* **[`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)** - Track delivery and performance metrics for reporting
* **[`get_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/get_reporting_status)** - Check durable reporting obligations, revisions, and materializations
* **[`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status)** - Close the loop with the buyer's received, missing, unreadable, or contradictory status
* **[`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts)** - Record independently verified consumer totals and evidence
* **[`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback)** - Submit performance signals for publisher optimization
### Conversion Tracking
Configure event sources and send marketing events for attribution.
* **[`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources)** - Configure event sources on seller accounts
* **[`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event)** - Send marketing events for attribution
### Audience Management
Upload and manage first-party CRM audiences for targeting.
* **[`sync_audiences`](/dist/docs/3.2.8/media-buy/task-reference/sync_audiences)** - Upload hashed customer lists and check matching status
## Schema Reference
All tasks include JSON schema definitions for requests and responses:
* **Request Schemas**: `/schemas/3.2.8/media-buy/[task-name]-request.json`
* **Response Schemas**: `/schemas/3.2.8/media-buy/[task-name]-response.json`
**Task Management**: For tracking async operations across all AdCP domains, see [Task Lifecycle](/dist/docs/3.2.8/building/by-layer/L3/task-lifecycle).
Schemas are accessible at runtime via the documentation server for validation and tooling.
## Common Patterns
### Task Naming Conventions
Task names use snake_case and follow verb-first semantics consistently across Media Buy:
* `get_*`: Retrieve current state or scoped datasets (for example [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) and [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery))
* `list_*`: Enumerate collections with optional filtering (for example [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) and [`list_creatives`](/dist/docs/3.2.8/creative/task-reference/list_creatives))
* `request_*`, `refine_*`, and `decline_*`: Explicit lifecycle transitions over immutable resources; finalized proposals flow into [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal)
* `buy_*` and `accept_*`: Create or change a commercial commitment from versioned terms
* `control_*`: Apply revision-checked operational changes inside accepted terms
* `sync_*`: Reconcile external state into seller systems with upsert-like behavior ([`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs), [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives), [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources))
* [`sync_reporting_receipts`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_receipts): Reconcile consumer-observed reporting evidence into the seller's durable ledger
* [`sync_reporting_status`](/dist/docs/3.2.8/media-buy/task-reference/sync_reporting_status): Record what the authenticated buyer could actually consume without turning Core status into billing reconciliation
* `log_*`: Ingest append-only event records ([`log_event`](/dist/docs/3.2.8/media-buy/task-reference/log_event))
* `provide_*`: Submit optimization or feedback signals ([`provide_performance_feedback`](/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback))
### Error Handling
All tasks follow consistent error patterns with:
* HTTP status codes for different error types
* Structured error messages with context
* Retry guidance for transient failures
### Authentication
Tasks require proper authentication via:
* API keys for service-to-service calls
* Authenticated agent and account scope for multi-tenant operations
* Permission validation for resource access
### Asynchronous Operations
Long-running tasks provide:
* Immediate response with operation ID
* Status polling endpoints for progress
* Webhook notifications for completion
## Getting Started
1. **Discover capabilities**: Read `media_buy.lifecycle_tools` through [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities).
2. **Choose a commercial path**: Use [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) for published offers and wholesale mirrors, or [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) for seller planning.
3. **Understand formats**: Check each selected product's canonical `format_options[]` before commitment.
4. **Commit**: Call [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products), or revise and finalize a proposal before [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal).
5. **Supply creatives**: Use [`sync_creatives`](/dist/docs/3.2.8/creative/task-reference/sync_creatives) and explicit assignment operations after compact commitment.
6. **Read operational state**: Use [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) for status, revision, accepted terms, approvals, and missing formats.
7. **Control delivery**: Use [`control_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/control_media_buy) for in-envelope changes; start a proposal amendment when the seller returns [`REQUOTE_REQUIRED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-requote-required).
8. **Monitor performance**: Track billing-grade reporting with [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery).
For reporting and reconciliation, treat [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) as the authoritative, billing-grade source. Use [`get_media_buys`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buys) snapshots for operational monitoring only.
## Related Documentation
* **[Product Discovery](/dist/docs/3.2.8/media-buy/product-discovery/)** - Natural language inventory discovery
* **[Media Buys](/dist/docs/3.2.8/media-buy/media-buys/)** - Campaign lifecycle management
* **[Creatives](/dist/docs/3.2.8/media-buy/creatives/)** - Creative asset management
* **[Advanced Topics](/dist/docs/3.2.8/media-buy/advanced-topics/)** - Targeting, security, and architecture
# list_products
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/list_products
Read seller product offers with structured discovery criteria.
`list_products` is the side-effect-free entry point to the compact product lifecycle. Each invocation completes synchronously, while account-level wholesale feed webhooks keep long-lived buyer mirrors current without polling. It returns products only—never proposals. Buyers can purchase listed products through [`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) or pass returned `product_id` values to [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals) for seller planning.
Wholesale support is optional. A seller that omits `list_products` from `media_buy.lifecycle_tools` offers no wholesale feed, with no implication about its inventory or planning capability, and no conformance scenario requires the wholesale path. The feed is deliberately the lower-resolution discovery surface: buyers who want the seller's full capability applied to their intent send a brief through [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals). Buyers evaluating sellers SHOULD use both surfaces where advertised rather than treating feed contents — or feed absence — as a capability assessment.
**Request schema:** [`/schemas/3.2.1/media-buy/list-products-request.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/list-products-request.json)
```json theme={null}
{
"brand": { "domain": "acmeoutdoor.example" },
"criteria": {
"offer_filters": {
"channels": ["olv"],
"pricing_currencies": ["USD"]
},
"targeting_overlay": {
"geo_countries": ["US"]
},
"required_overlay_support": {
"geo_metros": { "systems": ["nielsen_dma"] }
}
},
"max_results": 25
}
```
`brand` is an identity-only key. Sellers resolve its canonical manifest from the domain; callers do not send logos, colors, or governance overrides in this request. Catalog ingestion belongs to [`sync_catalogs`](/dist/docs/3.2.8/media-buy/task-reference/sync_catalogs); discovery accepts only a compact catalog selection under `criteria.catalog`.
`offer_filters` select commercial offers. `targeting_overlay` instead constrains the inventory or impressions that may deliver, so every returned price and forecast must account for the effective overlay. `required_overlay_support` asks for targeting dimensions the buyer can select independently on packages later. For aggregate frequency capping, use `criteria.required_media_buy_support` to require product participation and `criteria.media_buy_frequency_cap` to preflight an exact shared cap.
`criteria.outcome_target` is inert here for every seller: `list_products` returns no proposals, so a reverse-forecast goal or cost target has no answer, does not filter or rank products, and MUST NOT cause a rejection beyond schema validation. Send it through [`request_proposals`](/dist/docs/3.2.8/media-buy/task-reference/request_proposals#reverse-forecasting-with-outcome_target).
Geographic coverage belongs in `offer_filters.countries`, `regions`, `metros`,
`postal_areas`, or `geo_proximity`. For example, a metro entry
`{"system": "nielsen_dma", "code": "501"}` asks for products with New York DMA
inventory. It does not request DMA-targeted delivery or require selectable metro
targeting. Entries within a coverage field are alternatives; different filters
combine with AND. Apply filters before pagination. Coverage preserves the
offer's pricing and forecast scope; only an explicit delivery overlay changes
that scope. See [filter migration](/dist/docs/3.2.8/reference/migration/targeting-aware-discovery#filter-migration).
When a product can honor the overlay exactly, it does not echo the request. A product that proposes a different executable overlay returns sparse `targeting_resolution.modifications`; selecting that configured product accepts those disclosed changes. Compact products have no `is_custom` flag: `expires_at` marks a request-specific configured product, whether it accepts the overlay exactly or discloses modifications, and a product carrying `targeting_resolution` always carries `expires_at`. Sellers return both whenever they return modifications, even when `fields` omits them.
Property and collection lists are the exception to the no-echo rule because the buyer cannot otherwise observe their seller-specific inventory effect. Every returned product carries one `list_applications` receipt per effective targeting reference. Exclusion applications carry zero-match receipts; zero matches for any inclusion application make the product ineligible, so it is not returned. The receipt contains no fetch credential; its counts are scoped to that product and its timestamps, and the product's price and forecast reflect the post-application inventory.
## Response
Every response has an explicit `outcome`:
| Field | Type | Description |
| - | - | - |
| `outcome` | string | `listed` when the response contains a product page; `unchanged` when a conditional request matches the current feed. |
| `products` | Product\[] | Product offers for this page. Required for `listed`, even when the array is empty; omitted for `unchanged`. |
| `next_cursor` | string | Cursor for the next page. Omitted on the final page. Pass it as `cursor` in the next request. |
| `feed_version` | string | Opaque version of the selected offer feed. Pass it as `if_feed_version` on a later request to avoid downloading an unchanged feed. |
| `pricing_version` | string | Opaque version of the selected pricing layer. Pass it as `if_pricing_version` together with `if_feed_version` when checking both versions. |
| `cache_scope` | string | Whether the version applies to the seller's `public` feed or an `account`-specific overlay. |
| `incomplete` | object\[] | Optional details about portions of the response the seller could not complete. |
A product page can include continuation and cache state:
```json theme={null}
{
"outcome": "listed",
"products": [],
"next_cursor": "page_2",
"feed_version": "feed_2026_08_10_1",
"pricing_version": "pricing_42",
"cache_scope": "account"
}
```
To check whether the same selection has changed, repeat the request with `if_feed_version`. Include `if_pricing_version` only when `if_feed_version` is also present:
```json theme={null}
{
"brand": { "domain": "acmeoutdoor.example" },
"criteria": {
"offer_filters": {
"channels": ["olv"],
"pricing_currencies": ["USD"]
},
"targeting_overlay": {
"geo_countries": ["US"]
}
},
"if_feed_version": "feed_2026_08_10_1",
"if_pricing_version": "pricing_42"
}
```
If the selected feed and pricing layer still match, the seller can omit `products`:
```json theme={null}
{
"outcome": "unchanged",
"feed_version": "feed_2026_08_10_1",
"pricing_version": "pricing_42",
"cache_scope": "account"
}
```
## Availability forecasts are a per-read overlay
For calendar-shaped guaranteed inventory (homepage takeovers, sponsorships), `list_products` can answer "which dates are open?" directly: pass `criteria.offer_filters.availability_horizon` and request `forecast` in `fields`, and each product's forecast comes back partitioned into `time`-dimensioned points carrying `availability_status`. See [Flexible Availability Windows](/dist/docs/3.2.8/media-buy/product-discovery/media-products#flexible-availability-windows) for window semantics.
Availability is volatile — every booking changes it — so it is never part of the versioned feed content:
* `feed_version` covers the durable offer definition only. Forecast data (including availability windows) does not participate in feed-version scoping and carries its own freshness via the forecast's `generated_at` and `valid_until`.
* A request whose `fields` includes `forecast` MUST NOT be answered with `outcome: "unchanged"` — that arm omits `products`, so it cannot carry the volatile data the buyer explicitly asked for. Sellers return a full `listed` response even when the feed token matches.
* Wholesale feed webhooks fire on definition and pricing changes, not on booking-state changes. Broadcasting window closures to all subscribers would leak demand signals; buyers who need current availability read it on demand, and buyers who need a guarantee take an inventory hold by finalizing a proposal.
In practice these are two different reads: mirror maintenance (conditional, no `forecast` in `fields`) and availability checks (`forecast` requested, never conditional). Any `availability_status` returned is a snapshot bounded by `valid_until`, never a hold — the buy itself remains the authoritative availability check and fails with [`PRODUCT_UNAVAILABLE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-product-unavailable) when a window has since closed.
## Wholesale feed webhooks
Buyers maintaining a wholesale product mirror register `product.*` and `wholesale_feed.bulk_change` subscribers through `sync_accounts.accounts[].notification_configs[]`. Registration is account-level and durable; `push_notification_config` on an individual `list_products` request does not create that subscription.
The normal mirror flow is:
1. Call `list_products` to bootstrap the mirror and store `feed_version` plus `cache_scope`.
2. Register the durable account subscriber through [`sync_accounts`](/dist/docs/3.2.8/accounts/tasks/sync_accounts).
3. Apply the webhook's `canonical_product` or `canonical_pricing_options` replacement payload directly.
4. On a gap, call `list_products` with the mirror's last successfully applied `feed_version`. On an uncertain or bulk-change repair, omit the conditional token and replace the mirror from a complete read.
The webhook version describes post-change state; it is not the conditional token for a stale mirror. Conditional reads are a repair path, not a requirement to poll while webhooks are healthy.
# log_event
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/log_event
log_event task — send conversion and marketing events to AdCP sellers in batches. Supports attribution, campaign optimization, ROAS measurement, and test events.
Send conversion or marketing events for attribution and optimization. Supports batch submissions, test events, and partial failure reporting.
**Response Time**: \~1s (events are queued for processing)
**Request Schema**: [`/schemas/3.2.8/media-buy/log-event-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/log-event-request.json)
**Response Schema**: [`/schemas/3.2.8/media-buy/log-event-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/log-event-response.json)
## Quick Start
Log a purchase event:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { LogEventResponseSchema } from "@adcp/sdk";
const result = await testAgent.logEvent({
event_source_id: "website_pixel",
events: [
{
event_id: "evt_purchase_12345",
event_type: "purchase",
event_time: "2026-01-15T14:30:00Z",
action_source: "website",
event_source_url: "https://www.example.com/checkout/confirm",
user_match: {
click_id: "abc123def456",
click_id_type: "gclid",
},
custom_data: {
value: 149.99,
currency: "USD",
order_id: "order_98765",
num_items: 3,
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
// Validate response against schema
const validated = LogEventResponseSchema.parse(result.data);
// Check for operation-level errors first (discriminated union)
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("events_received" in validated) {
console.log(`Received: ${validated.events_received}, Processed: ${validated.events_processed}`);
if (validated.match_quality !== undefined) {
console.log(`Match quality: ${(validated.match_quality * 100).toFixed(0)}%`);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.log_event(
event_source_id='website_pixel',
events=[{
'event_id': 'evt_purchase_12345',
'event_type': 'purchase',
'event_time': '2026-01-15T14:30:00Z',
'action_source': 'website',
'event_source_url': 'https://www.example.com/checkout/confirm',
'user_match': {
'click_id': 'abc123def456',
'click_id_type': 'gclid'
},
'custom_data': {
'value': 149.99,
'currency': 'USD',
'order_id': 'order_98765',
'num_items': 3
}
}]
)
# Check for operation-level errors first
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
print(f"Received: {result.events_received}, Processed: {result.events_processed}")
if hasattr(result, 'match_quality') and result.match_quality is not None:
print(f"Match quality: {result.match_quality * 100:.0f}%")
asyncio.run(main())
```
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `event_source_id` | string | Yes | Event source configured on the account via [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) |
| `events` | [Event](/dist/docs/3.2.8/media-buy/conversion-tracking/#event)\[] | Yes | Events to log (min 1, max 10,000) |
| `test_event_code` | string | No | Test event code for validation without affecting production data |
### Event Object
| Field | Type | Required | Description |
| - | - | - | - |
| `event_id` | string | Yes | Unique identifier for deduplication (scoped to event_type + event_source_id). Max 256 chars. |
| `event_type` | [EventType](/dist/docs/3.2.8/media-buy/conversion-tracking/#event-types) | Yes | Standard event type (e.g. `purchase`, `lead`, `add_to_cart`) |
| `event_time` | date-time | Yes | ISO 8601 timestamp when the event occurred |
| `user_match` | [UserMatch](/dist/docs/3.2.8/media-buy/conversion-tracking/#user-match) | No | User identifiers for attribution matching |
| `custom_data` | [CustomData](/dist/docs/3.2.8/media-buy/conversion-tracking/#custom-data) | No | Event-specific data (value, currency, items) |
| `action_source` | [ActionSource](/dist/docs/3.2.8/media-buy/conversion-tracking/#action-sources) | No | Where the event occurred (`website`, `app`, `in_store`, etc.) |
| `surface` | [EventSurface](/dist/docs/3.2.8/media-buy/conversion-tracking/#event-surfaces) | No | Structured surface context for the event, such as an owned channel, profile, feed, podcast, newsletter list, website, app, or store |
| `event_source_url` | uri | No | URL where the event occurred (required when action_source is `website`) |
| `custom_event_name` | string | No | Name for custom events (used when event_type is `custom`) |
### User Match Object
At least one of `uids`, `hashed_email`, `hashed_phone`, `click_id`, or `client_ip` + `client_user_agent` is required:
| Field | Type | Description |
| - | - | - |
| `uids` | UID\[] | Universal ID values (`rampid`, `id5`, `uid2`, `euid`, `pairid`, `maid`) |
| `hashed_email` | string | SHA-256 hash of lowercase, trimmed email address (64-char hex) |
| `hashed_phone` | string | SHA-256 hash of E.164-formatted phone number (64-char hex) |
| `click_id` | string | Platform click identifier (fbclid, gclid, ttclid, etc.) |
| `click_id_type` | string | Type of click identifier |
| `client_ip` | string | Client IP address for probabilistic matching |
| `client_user_agent` | string | Client user agent string for probabilistic matching |
**Hashing:** Hashed identifiers must be SHA-256 hex strings (64 characters, lowercase). Normalize before hashing: emails to lowercase with whitespace trimmed, phone numbers to E.164 format (e.g. `+12065551234`).
### Custom Data Object
| Field | Type | Description |
| - | - | - |
| `value` | number | Monetary value of the event. Requires `currency` when the source declares `value_currencies`; legacy sources remain compatible but cannot feed canonical ROAS. |
| `currency` | string | ISO 4217 code declared in the event source's `value_currencies` when that contract is present (e.g. `USD`, `EUR`, `GBP`) |
| `order_id` | string | Unique order or transaction identifier |
| `content_ids` | string\[] | Product or content identifiers. For catalog-driven campaigns, these match the catalog's `content_id_type` (e.g., SKUs, GTINs, job IDs). See [catalog-item attribution](/dist/docs/3.2.8/media-buy/conversion-tracking#catalog-item-attribution). |
| `content_type` | string | Category of content (product, service, etc.) |
| `num_items` | integer | Number of items in the event |
| `progress_percent` | number | Content progress percentage reached, primarily for `watch_milestone` events |
| `progress_seconds` | number | Content progress duration reached in seconds, primarily for time-based `watch_milestone` events |
| `contents` | Content\[] | Per-item details (id, quantity, price, brand) |
## Response
**Success Response:**
* `events_received` - Number of events received
* `events_processed` - Number of events successfully queued
* `partial_failures` - Events that failed validation (with event_id, code, message)
* `warnings` - Non-fatal issues (low match quality, missing fields)
* `match_quality` - Overall match quality score (0.0 to 1.0)
**Error Response:**
* `errors` - Array of operation-level errors (invalid event source, auth failure)
**Note:** Responses use discriminated unions - you get either success fields OR errors, never both. Partial failures are reported per-event within the success response.
## Common Scenarios
### Creator Engagement Events
Log creator or content engagement events against the configured owned-property source. Use `surface` to identify the property and put watch thresholds in `custom_data.progress_percent` or `custom_data.progress_seconds`.
```json test=false theme={null}
{
"event_source_id": "creator_channel",
"events": [
{
"event_id": "evt_watch_001",
"event_type": "watch_milestone",
"event_time": "2026-01-16T11:05:00Z",
"action_source": "system_generated",
"surface": {
"category": "owned_property",
"property_type": "channel",
"namespace": "video_platform",
"property_id": "channel_123"
},
"user_match": {
"uids": [{ "type": "uid2", "value": "CreatorViewer456" }]
},
"custom_data": {
"content_ids": ["episode_001"],
"progress_percent": 75
}
}
]
}
```
For free durable opt-ins, use `event_type: "follow"`. Reserve `event_type: "subscribe"` for paid subscriptions or paid memberships.
### Batch Events
Send multiple events in a single request:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { LogEventResponseSchema } from "@adcp/sdk";
const result = await testAgent.logEvent({
event_source_id: "website_pixel",
events: [
{
event_id: "evt_purchase_001",
event_type: "purchase",
event_time: "2026-01-15T10:00:00Z",
action_source: "website",
user_match: {
hashed_email: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
uids: [{ type: "uid2", value: "AbC123XyZ..." }],
},
custom_data: {
value: 89.99,
currency: "USD",
order_id: "order_001",
},
},
{
event_id: "evt_lead_002",
event_type: "lead",
event_time: "2026-01-15T11:30:00Z",
action_source: "website",
user_match: {
hashed_email: "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5",
click_id: "abc123def456",
click_id_type: "fbclid",
},
},
{
event_id: "evt_cart_003",
event_type: "add_to_cart",
event_time: "2026-01-15T12:15:00Z",
action_source: "app",
user_match: {
uids: [{ type: "rampid", value: "Def456Ghi..." }],
},
custom_data: {
content_ids: ["SKU-1234", "SKU-5678"],
num_items: 2,
value: 45.00,
currency: "USD",
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = LogEventResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("events_received" in validated) {
console.log(`${validated.events_processed}/${validated.events_received} events processed`);
if (validated.partial_failures?.length) {
for (const failure of validated.partial_failures) {
console.log(` Failed: ${failure.event_id} - ${failure.message}`);
}
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.log_event(
event_source_id='website_pixel',
events=[
{
'event_id': 'evt_purchase_001',
'event_type': 'purchase',
'event_time': '2026-01-15T10:00:00Z',
'action_source': 'website',
'user_match': {
'uids': [{'type': 'uid2', 'value': 'AbC123XyZ...'}]
},
'custom_data': {
'value': 89.99,
'currency': 'USD',
'order_id': 'order_001'
}
},
{
'event_id': 'evt_lead_002',
'event_type': 'lead',
'event_time': '2026-01-15T11:30:00Z',
'action_source': 'website',
'user_match': {
'click_id': 'abc123def456',
'click_id_type': 'fbclid'
}
},
{
'event_id': 'evt_cart_003',
'event_type': 'add_to_cart',
'event_time': '2026-01-15T12:15:00Z',
'action_source': 'app',
'user_match': {
'uids': [{'type': 'rampid', 'value': 'Def456Ghi...'}]
},
'custom_data': {
'content_ids': ['SKU-1234', 'SKU-5678'],
'num_items': 2,
'value': 45.00,
'currency': 'USD'
}
}
]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
print(f"{result.events_processed}/{result.events_received} events processed")
if hasattr(result, 'partial_failures') and result.partial_failures:
for failure in result.partial_failures:
print(f" Failed: {failure.event_id} - {failure.message}")
asyncio.run(main())
```
### Test Events
Validate event integration without affecting production data:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { LogEventResponseSchema } from "@adcp/sdk";
const result = await testAgent.logEvent({
event_source_id: "website_pixel",
test_event_code: "TEST_12345",
events: [
{
event_id: "test_evt_001",
event_type: "purchase",
event_time: new Date().toISOString(),
action_source: "website",
event_source_url: "https://www.example.com/checkout",
user_match: {
click_id: "test_click_abc",
click_id_type: "gclid",
},
custom_data: {
value: 99.99,
currency: "USD",
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = LogEventResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("events_received" in validated) {
console.log("Test event sent successfully");
if (validated.warnings?.length) {
console.log("Warnings:", validated.warnings);
}
}
```
```python Python theme={null}
import asyncio
from datetime import datetime, timezone
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.log_event(
event_source_id='website_pixel',
test_event_code='TEST_12345',
events=[{
'event_id': 'test_evt_001',
'event_type': 'purchase',
'event_time': datetime.now(timezone.utc).isoformat(),
'action_source': 'website',
'event_source_url': 'https://www.example.com/checkout',
'user_match': {
'click_id': 'test_click_abc',
'click_id_type': 'gclid'
},
'custom_data': {
'value': 99.99,
'currency': 'USD'
}
}]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
print('Test event sent successfully')
if hasattr(result, 'warnings') and result.warnings:
print(f"Warnings: {result.warnings}")
asyncio.run(main())
```
Test events appear in the seller's test events UI but do not affect production attribution or reporting.
### In-Store Conversions
Report offline conversions using CRM data:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { LogEventResponseSchema } from "@adcp/sdk";
const result = await testAgent.logEvent({
event_source_id: "crm_import",
events: [
{
event_id: "store_txn_20260115_001",
event_type: "purchase",
event_time: "2026-01-15T16:45:00Z",
action_source: "in_store",
user_match: {
uids: [{ type: "rampid", value: "XyZ789AbC..." }],
},
custom_data: {
value: 250.0,
currency: "USD",
order_id: "POS-2026-0115-001",
contents: [
{ id: "SKU-JACKET-L", quantity: 1, price: 189.0 },
{ id: "SKU-SCARF-01", quantity: 1, price: 61.0 },
],
},
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = LogEventResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("events_received" in validated) {
console.log(`In-store events processed: ${validated.events_processed}`);
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.log_event(
event_source_id='crm_import',
events=[{
'event_id': 'store_txn_20260115_001',
'event_type': 'purchase',
'event_time': '2026-01-15T16:45:00Z',
'action_source': 'in_store',
'user_match': {
'uids': [{'type': 'rampid', 'value': 'XyZ789AbC...'}]
},
'custom_data': {
'value': 250.00,
'currency': 'USD',
'order_id': 'POS-2026-0115-001',
'contents': [
{'id': 'SKU-JACKET-L', 'quantity': 1, 'price': 189.00},
{'id': 'SKU-SCARF-01', 'quantity': 1, 'price': 61.00}
]
}
}]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
print(f"In-store events processed: {result.events_processed}")
asyncio.run(main())
```
## Event Deduplication
Events are deduplicated by the combination of `event_id` + `event_type` + `event_source_id`. Sending the same event multiple times is safe - duplicates are silently ignored.
Choose `event_id` values that are stable across retries:
* Transaction IDs: `"order_98765"`
* Composite keys: `"purchase_user123_20260115"`
* UUIDs: `"550e8400-e29b-41d4-a716-446655440000"`
## Error Handling
| Error Code | Description | Resolution |
| - | - | - |
| [`REFERENCE_NOT_FOUND`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-reference-not-found) | Event source not configured or not accessible (`error.field` = `event_source_id`) | Run [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) first |
| [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) | An event field violates its schema, or the batch contains more than 10,000 events | Correct the field identified by `error.field` or split the request |
| [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) | The event type is disallowed for the configured source, the timestamp is outside the attribution window, or no usable user match is present | Check the event source configuration and correct the event values |
| [`RATE_LIMITED`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-rate-limited) | Too many requests | Wait and retry with exponential backoff |
## Best Practices
1. **Configure sources first** - Always run [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) before sending events. Events sent to unconfigured sources are rejected.
2. **Include user_match** - Events without user identifiers cannot be attributed. Provide the strongest identifiers available: hashed email/phone > UIDs > click IDs > IP/UA. Send multiple identifier types when available to maximize match rates.
3. **Use test events first** - Set `test_event_code` during integration to validate events appear correctly without affecting production data.
4. **Batch when possible** - Send up to 10,000 events per request to reduce API calls. Events within a batch are processed independently.
5. **Include contracted value and currency for ROAS** - A source used for canonical ROAS declares `value_currencies` through `sync_event_sources`; its monetary records require `custom_data.currency` from that list. Each ROAS buy consumes only records matching its media-buy currency. Legacy sources without this contract remain valid for non-ROAS events.
6. **Stable event IDs** - Use deterministic event IDs (order numbers, transaction IDs) rather than random UUIDs. This ensures safe retries without duplicate counting.
7. **Send events promptly** - Log events as close to real-time as possible. Events outside the seller's attribution window may not be matched.
## Next Steps
* [Conversion Tracking](/dist/docs/3.2.8/media-buy/conversion-tracking/) - Data model, optimization goals, and the end-to-end flow
* [sync_event_sources](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) - Configure event sources before logging events
* [create_media_buy](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy#campaign-with-conversion-optimization) - Set optimization goals on packages
* [get_media_buy_delivery](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) - Monitor conversion metrics in delivery reports
# provide_performance_feedback
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/provide_performance_feedback
Submit a compact buyer- or measurement-provider performance assertion that a seller can use for optimization.
`provide_performance_feedback` sends one optimizer-ready assertion across either hop of a buyer-controlled feedback path. A measurement provider submits to the orchestrator's gateway; the orchestrator validates and normalizes the assertion before forwarding appropriate feedback to each media-buy seller. The payload carries the decision signal and enough provenance to interpret it, not raw exposure logs, attribution models, or a complete measurement study.
The caller is therefore either:
* an authenticated measurement agent calling the buyer orchestrator; or
* the buyer orchestrator calling a seller.
Measurement agents do not receive seller credentials. In the first experimental gateway tier, the provider reads buyer-approved cross-seller delivery from the orchestrator's [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) task and returns compact assertions through its `provide_performance_feedback` task.
**Request schema:** [`provide-performance-feedback-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/provide-performance-feedback-request.json)
**Response schema:** [`provide-performance-feedback-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/provide-performance-feedback-response.json)
## Compact contract
```json theme={null}
{
"idempotency_key": "d8e9f0a1-b2c3-4456-d789-456789012345",
"media_buy_id": "mb_123",
"package_id": "pkg_streaming_video",
"measurement_period": {
"start": "2026-07-01T00:00:00Z",
"end": "2026-07-31T23:59:59Z"
},
"metric": {
"scope": "standard",
"metric_id": "conversion_value",
"qualifier": {
"attribution_methodology": "modeled"
}
},
"performance_index": 1.35,
"baseline": "control_group",
"producer": {
"domain": "measurement.example"
},
"methodology": "geo_incrementality",
"methodology_version": "2026-07",
"study_ref": "study_42",
"evidence": {
"sample_size": 14820,
"confidence_interval": {
"lower": 1.18,
"upper": 1.49,
"level": 0.95
}
},
"evidence_ref": "https://measurement.example/results/study_42",
"as_of": "2026-08-04T12:00:00Z",
"final": true
}
```
### Required fields
| Field | Meaning |
| - | - |
| `idempotency_key` | Unique key for this logical assertion. MUST be unique per receiving agent to prevent cross-agent correlation; use a fresh UUID v4 for each new assertion. Retries use the same key and payload. |
| `media_buy_id` | Receiver-scoped buy identifier: orchestrator-issued on the provider hop, seller-issued on the seller hop. |
| `measurement_period` | Period summarized by the assertion. |
| `performance_index` | Normalized decision signal: `1.0` equals the named baseline, lower underperforms it, and higher outperforms it. |
`baseline` is optional in the JSON Schema so legacy 3.x requests remain valid. Producers using the compact contract MUST populate it.
### Scope
| Field | Meaning |
| - | - |
| `package_id` | Narrows the assertion to one package. |
| `creative_id` | Narrows the assertion to one creative. |
Omit both for media-buy-level feedback. `media_buy_id`, `package_id`, and `creative_id` are scoped to the receiver: the gateway exposes measurement-facing identifiers to the provider and maps them to each seller's local identifiers during fan-out. The initial compact contract deliberately does not enumerate every delivery dimension. A later revision can add an opaque receiver-issued delivery key without copying the entire reporting-dimension taxonomy into this task.
### Metric identity
`metric` reuses the standard/vendor discriminator used by `committed_metrics`, `missing_metrics`, and delivery metric aggregates:
```json theme={null}
{ "scope": "standard", "metric_id": "roas" }
```
```json theme={null}
{
"scope": "vendor",
"vendor": { "domain": "attentionvendor.example" },
"metric_id": "attention_units"
}
```
The nested `metric.vendor` identifies who defines the metric. It can differ from top-level `producer`, which identifies who produced this assertion.
`metric_type` remains accepted for backwards compatibility but is deprecated. When both fields are present, consumers use `metric`.
### Baseline
`baseline` names what `performance_index = 1.0` represents:
| Value | Meaning |
| - | - |
| `campaign_target` | Target or expectation for this buy or package. |
| `control_group` | Buyer- or measurement-provider-defined counterfactual control. |
| `seller_history` | Historical performance for this seller or subject. |
| `buyer_portfolio` | Buyer-side portfolio benchmark. |
| `market_benchmark` | External market or category benchmark. |
| `other` | Another producer-defined baseline described in the linked evidence. |
The producer does not need to disclose the raw baseline value. For ratio-compatible metrics, compact-contract producers (baseline present) MUST use `observed / baseline` for higher-is-better measures and `baseline / observed` for lower-is-better measures such as CPA. In both cases values above `1.0` mean better performance.
### Producer and methodology
`producer` is the BrandRef of the party that produced the analysis. On the provider-to-orchestrator hop, authenticated caller identity is authoritative and the orchestrator verifies that `producer` matches it. On the orchestrator-to-seller hop, `producer` preserves analytical provenance while the authenticated orchestrator remains responsible for the submission. Sellers never need to authenticate or authorize the measurement provider directly.
`methodology` and `methodology_version` are producer-scoped open strings. AdCP does not impose a universal methodology enum: `geo_incrementality`, `media_mix_model`, and `deterministic_attribution` mean what the identified producer's catalog and methodology documentation say they mean.
`study_ref` is opaque correlation metadata. It does not instruct the seller to create experiment arms or assign users/geographies. Buyers and measurement providers define cohorts once and apply them consistently through ordinary audience and geographic targeting.
### Evidence and historical backfill
The inline `evidence` object is intentionally small:
* `sample_size`;
* `confidence_interval` on the performance-index scale.
`evidence_ref` points to the provider-hosted result for authorized reviewers. Large historical datasets and study artifacts stay with the measurement provider. Historical backfills use `measurement_period` plus `as_of`; submit one assertion per task call.
`final: false` means the producer expects maturation. A later correction is a new immutable assertion carrying `supersedes_feedback_id` from the prior response.
## Response and application status
```json theme={null}
{
"status": "completed",
"success": true,
"feedback_id": "fb_01J5Y5KQ2T8B2M8P0A4E6R3C9D",
"application_status": "applied",
"received_at": "2026-08-04T12:00:02Z",
"applied_at": "2026-08-04T12:00:02Z"
}
```
| Status | Meaning |
| - | - |
| `accepted` | Stored and eligible for evaluation. This is not a claim that an optimizer used it. |
| `applied` | Incorporated into the seller's optimization inputs. It does not guarantee a delivery change. |
| `not_applied` | Evaluated but not incorporated; `status_reason` explains why. |
Legacy task bodies may contain only `success`. Orchestrator gateways and sellers declaring `media_buy.performance_feedback` return a hop-local `feedback_id`. A gateway normally reports receipt only. Sellers declaring `reports_application_status: true` return an honest `application_status`. Top-level `status` remains the protocol task lifecycle and is not optimizer disposition.
The initial contract reports disposition at response time. A durable asynchronous status read or webhook is deferred until implementations demonstrate that optimizers can expose it reliably.
## Orchestrator-hosted measurement gateway
Measurement agents are discoverable through `brand.json` entries with `type: "measurement"` and publish their metric catalogs in `get_adcp_capabilities.measurement.metrics[]`.
A measurement agent that sets `measurement.produces_performance_feedback: true` can produce this task's compact assertion. A buyer orchestrator exposes the receiving boundary through the separate experimental `measurement_gateway` capability, without claiming to be a media-buy seller.
The orchestrator gives each provider a scoped account. The first experimental tier uses existing task authorization:
```json theme={null}
{
"authorization": {
"allowed_tasks": ["get_media_buy_delivery", "provide_performance_feedback"],
"read_only": false
}
}
```
Both tasks are part of the first-tier gateway contract. The provider never receives seller-account access. Webhook and offline interchange are deferred until AdCP defines their registration, credential, payload, and receipt contracts.
The resulting flow is:
1. The orchestrator discovers a measurement agent and its metrics.
2. The provider calls the orchestrator's [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery) task for buyer-approved, cross-seller delivery.
3. The provider calls `provide_performance_feedback` on the orchestrator gateway. The orchestrator authenticates the provider, validates provenance, and stores its own `feedback_id`.
4. The orchestrator decides what to share with each seller, maps its cross-seller identifiers to seller-local media-buy/package/creative IDs, and calls each seller's `provide_performance_feedback` under the buyer's identity.
5. Seller receipts and `application_status` values return to the orchestrator, which owns the cross-seller audit trail.
This hub-and-spoke boundary lets the buyer keep treatment users and geographies consistent across sellers, prevents a measurement provider from accumulating seller credentials, and gives the orchestrator control over normalization and disclosure. Measurement data MUST NOT be forced through [`report_usage`](/dist/docs/3.2.8/accounts/tasks/report_usage); that task reports consumption and billing for vendor services.
## Capability examples
Buyer orchestrator gateway:
```json theme={null}
{
"supported_protocols": ["measurement"],
"experimental_features": ["measurement.gateway"],
"measurement_gateway": {
"delivery_task": "get_media_buy_delivery",
"feedback_task": "provide_performance_feedback"
}
}
```
Seller:
```json theme={null}
{
"experimental_features": ["measurement.core"],
"media_buy": {
"performance_feedback": {
"reports_application_status": true
}
}
}
```
Measurement provider:
```json theme={null}
{
"supported_protocols": ["measurement"],
"experimental_features": ["measurement.core"],
"measurement": {
"produces_performance_feedback": true,
"metrics": [
{
"metric_id": "incremental_revenue_index",
"unit": "index",
"methodology_url": "https://measurement.example/methodology"
}
]
}
}
```
## Privacy and trust
* Submit aggregate decision signals, not user-level outcomes or identity paths.
* The orchestrator authorizes each measurement provider; sellers authorize only the orchestrator.
* A `producer` field cannot override provider identity at the gateway or orchestrator identity at the seller.
* `evidence_ref` remains subject to the provider's access controls.
* Accepted feedback is not necessarily true or applied. Identity, evidence, attestation, and disposition answer different questions.
## Related documentation
* [`get_media_buy_delivery`](/dist/docs/3.2.8/media-buy/task-reference/get_media_buy_delivery)
* [Measurement taxonomy](/dist/docs/3.2.8/measurement/taxonomy)
* [Caller authorization](/dist/docs/3.2.8/accounts/overview#caller-authorization)
* [Optimization and reporting](/dist/docs/3.2.8/media-buy/media-buys/optimization-reporting)
# refine_proposals
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/refine_proposals
Revise proposals or finalize drafts into inventory holds.
`refine_proposals` has two explicit operations over immutable proposal snapshots:
* `action: "revise"` applies structured discovery `criteria`, typed boundaries, product changes, requested alternatives, and/or the buyer's free-text `ask`, returning one or more new draft proposals.
* `action: "finalize"` changes no commercial terms and returns a new committed proposal backed by an inventory hold until `expires_at`.
For an end-to-end buyer and seller implementation workflow, see [Proposal negotiation](/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation).
Revision may target a draft, committed, or accepted proposal; finalization must target a draft. A request contains at most 25 refinements. Proposal IDs must be unique within the request, and results preserve request order. Every successful operation returns a new `proposal_id`; that ID is the complete version identity for the immutable commercial snapshot, and the source remains unchanged.
**Request schema:** [`/schemas/3.2.1/media-buy/refine-proposals-request.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/refine-proposals-request.json)
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441002",
"refinements": [
{
"proposal_id": "proposal_123",
"action": "revise",
"constraints": {
"total_budget": { "max": 50000, "currency": "USD" },
"cpm": { "max": 18, "currency": "USD" },
"flight": { "end_no_earlier_than": "2026-10-31T23:59:59Z" }
},
"product_changes": {
"premium_video": "include",
"display_ros": "omit"
},
"alternatives": { "count": 3 },
"ask": "Use materially different product mixes while preserving reach."
},
{
"proposal_id": "proposal_456",
"action": "revise",
"criteria": {
"targeting_overlay": {
"geo_countries": ["US", "CA"]
}
}
}
]
}
```
Typed fields are deliberately small and mechanically verifiable:
| Field | Meaning |
| - | - |
| `constraints.total_budget` | Inclusive `min`/`max` bounds checked against a present `commercial_terms.total_budget`; `currency` must match and `min` must not exceed `max`. Each `constraints` key is its own stable constraint identifier. |
| `constraints.cpm` | Hard rate ceiling. Satisfied only when every purchase carries fixed `cpm`/`vcpm` pricing in the requested `currency` with `fixed_price` at or below `max`; auction-priced or non-CPM purchases leave it unsatisfied. |
| `constraints.impressions` | Hard volume floor. Satisfied only when every purchase carries `impressions` and their sum is at least `min`. |
| `constraints.flight` | Flight-window bounds. `start_no_later_than` requires a concrete `commercial_terms.start_time` at or before the bound (`asap` is unverifiable and unsatisfied); `end_no_earlier_than` requires `end_time` at or after it. |
| `product_changes` | Map keyed by product ID. `include` requires a product in `commercial_terms.purchases`; `omit` requires it to be absent. Keying makes contradictory actions unrepresentable. |
| `alternatives.count` | Number of drafts with distinct commercial terms requested, from 2 through the protocol maximum of 10 and no higher than a seller's advertised `max_alternatives`. Returned alternatives have distinct `commercial_terms` and therefore unique `terms_digest` values; diversity strategy remains free text. |
| `criteria` | Structured discovery criteria to replace on the source proposal. Omitted criteria fields remain inherited; concrete targeting and offer filters belong here. |
| `remove_media_buy_frequency_cap` | Set to `true` to produce a revised draft without the inherited root frequency cap. Mutually exclusive with `criteria.media_buy_frequency_cap`. |
| `ask` | Free text for substitution, trade-offs, diversity, preferences, or other long-tail context. |
`vary` and typed preference enums are intentionally absent: concepts such as “prioritize reach” cannot be verified consistently against `commercial_terms`. A seller may interpret them from `ask`, but cannot report them as deterministically satisfied.
Each present `criteria` field replaces that field from the source proposal; omitted fields remain bound to the revision. This makes a targeting change deterministic and ensures the revised proposal's price and forecast use the new effective overlay. When hard targeting appears only in `ask`, the seller confirms any structured interpretation that materially affects the revision in that result's `targeting_resolution.brief_targeting`. Exact structured targeting is not repeated; product-specific alternatives remain sparse modifications on the returned configured products.
**Response schema:** [`/schemas/3.2.1/media-buy/refine-proposals-response.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/refine-proposals-response.json)
For `revise`, the seller reevaluates returned products against the revision's effective criteria. When those criteria contain property or collection lists, each affected canonical product carries fresh `list_applications` receipts with new evaluation timestamps and counts. `finalize` changes no commercial terms and does not trigger product reevaluation; a finalize-only response MAY repeat the receipts already bound to the source proposal.
The response contains one ordered `results[]` entry per requested source proposal. Each entry echoes `source_proposal_id`; buyers cross-check by that echo rather than by position alone. Every returned proposal carries `parent_proposal_id` equal to the entry's `source_proposal_id`, so negotiation lineage survives in the proposals themselves:
| Outcome | Proposal field | Meaning |
| - | - | - |
| `revised` | `proposals[]` | Every hard constraint is satisfied. Without `alternatives`, the array has one draft; with `alternatives.count`, it has exactly that many and every `terms_digest` is unique. |
| `partial` | `proposals[]` | Honest drafts were produced, but a hard constraint, typed change, requested count, or free-text ask was not fully applied. `reason_code` and `reason` are required. |
| `finalized` | `proposal` | One committed proposal backed by an inventory hold. |
| `unable` | none | No honest draft was produced. `reason_code` and `reason` are required. |
`reason_code` distinguishes commercial refusal from implementation limits:
| Code | Meaning |
| - | - |
| `commercially_declined` | The seller understood terms requested through the free-text `ask` but declined to offer them. |
| `constraint_unsatisfiable` | A typed constraint or product change was not satisfied — whether the seller cannot or will not meet it. |
| `unsupported_dimension` | The seller cannot parse or validate a requested typed dimension. |
| `uninterpreted` | Some or all of the free-text `ask` could not be interpreted. |
| `alternatives_unavailable` | Fewer distinct drafts were produced than requested. |
| `source_unavailable` | The source proposal was unavailable or ineligible for this caller. |
| `hold_unavailable` | The seller declined or failed to reserve inventory for a finalize. |
| `batch_aborted` | This entry failed only because a sibling in the all-or-none finalize batch failed. |
Typed failures always use `constraint_unsatisfiable`, regardless of whether the refusal is capability or commercial; won't-versus-can't nuance belongs in `reason` or a `commercially_declined` response to an `ask`. When multiple shortfalls co-occur, `constraint_unsatisfiable` takes precedence over every other code, and an alternatives shortfall remains visible through `proposals.length`.
A draft that violates a hard constraint MUST NOT be returned as `revised`. For `constraints.total_budget`, satisfaction requires a present `commercial_terms.total_budget`, the requested currency, and an amount inside every supplied bound. An absent total, currency mismatch, or out-of-range amount is unsatisfied: the seller returns `partial`, or `unable` when it cannot produce an honest draft, with `reason_code: "constraint_unsatisfiable"` and `unsatisfied_constraints: ["total_budget"]`. The other `constraints` keys behave identically under their satisfaction rules in the request schema.
Every draft on a `partial` result MUST satisfy every typed constraint whose key is absent from `unsatisfied_constraints` and every product action absent from `unsatisfied_product_changes`, whatever the `reason_code`. This is the invariant that lets a buyer trust typed compliance without parsing prose. Constraint failures are identified through `unsatisfied_constraints` (echoing request `constraints` keys), `unsatisfied_product_changes` (a subset of the requested product-action map), or both.
A `partial` response to the request above looks like:
```json theme={null}
{
"adcp_version": "3.2.0",
"status": "completed",
"results": [
{
"source_proposal_id": "proposal_123",
"outcome": "partial",
"reason_code": "alternatives_unavailable",
"reason": "Two commercially distinct packages are available at these terms.",
"proposals": [
{ "proposal_id": "proposal_9a1", "parent_proposal_id": "proposal_123", "proposal_status": "draft", "...": "..." },
{ "proposal_id": "proposal_9a2", "parent_proposal_id": "proposal_123", "proposal_status": "draft", "...": "..." }
]
},
{
"source_proposal_id": "proposal_456",
"outcome": "revised",
"proposals": [
{ "proposal_id": "proposal_9b7", "parent_proposal_id": "proposal_456", "proposal_status": "draft", "...": "..." }
]
}
],
"products": ["..."]
}
```
Every returned proposal carries typed `commercial_terms` and a `terms_digest` — the base64url SHA-256 of the [RFC 8785 JCS](https://www.rfc-editor.org/rfc/rfc8785) serialization of `commercial_terms`, prefixed with `sha256:`. Buyers can and should recompute it: digest agreement, not seller assertion, is what makes drafts comparable and alternatives verifiably distinct. Only `commercial_terms` is contractual. Narrative fields — `reason`, `suggestions`, `description`, and anything a buyer wrote in `ask` — are explanatory and never part of the deal a later [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal) binds.
## A realistic negotiation
Sam is buying a \$50,000 Acme Outdoor campaign from StreamHaus. Capability discovery says StreamHaus supports `total_budget`, `product_changes`, `alternatives`, and `criteria`, with `max_alternatives: 3`. Sam can therefore construct one mechanically checkable request: cap spend at USD 50,000, include premium video, omit run-of-site display, narrow geography to the US and Canada, and ask for three distinct mixes.
Suppose StreamHaus can satisfy the budget and targeting but can produce only two commercially distinct drafts. It returns `partial` with two proposals, `reason_code: "alternatives_unavailable"`, and unique `terms_digest` values. Sam does not need to parse sales prose to understand the counteroffer: the typed budget and product checks still pass, while the requested alternative count does not. Sam can compare the two drafts, revise one again, or finalize the preferred draft.
The failure paths are equally deterministic:
* If a returned draft omits `commercial_terms.total_budget`, uses another currency, or exceeds the cap, the result identifies `total_budget` as unsatisfied and cannot be `revised`.
* If Sam requests four alternatives against the advertised ceiling of three, the whole call fails with [`VALIDATION_ERROR`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-validation-error) at `refinements[0].alternatives.count`; StreamHaus creates no draft.
* If StreamHaus omits `criteria` from `supported_dimensions`, the whole call fails with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature) before mutation. Sam can remove or translate that field and retry with a new valid payload.
This separation is the value of the compact negotiation surface: capabilities prevent impossible asks, typed fields make compliance testable, and `ask` remains available for the commercial nuance that cannot be reduced to a reliable boolean.
Pass only a finalized committed proposal to [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal), or use [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals) when the buyer stops pursuing it.
## Relationship to legacy refinement
The deprecated [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) `buying_mode: "refine"` surface is the 3.x compatibility façade; it has no lossless representation of `refinements[].constraints.total_budget`. A compatibility adapter MUST NOT map that proposal-term constraint to `get_products.filters.budget_range`, because the latter filters product candidates and does not guarantee the returned proposal's aggregate `commercial_terms.total_budget`. The adapter MUST instead return a typed `PRE_MUTATION_UNSUPPORTED` result with an RFC 6901 path identifying the exact field before it sends a legacy request.
Initial proposal discovery is different: `request_proposals.criteria.offer_filters.budget_range` MAY map to `get_products.filters.budget_range` with exact amounts, exact currency, inclusive bounds, no currency conversion, and no proposal-level guarantee. Compact revision criteria use whole-field replacement, while legacy filters are absolute. Legacy finalize is compatible only when the adapter can guarantee unchanged complete commercial terms. See [Legacy budget compatibility](/dist/docs/3.2.8/media-buy/product-discovery/proposal-negotiation#legacy-budget-compatibility-normative) for the complete normative mapping, typed rejection shape, and lifecycle rules.
The surfaces otherwise share `ask` and product `include`/`omit` verbs, but not response envelopes. Adapters must not invent support for per-proposal constraints or alternatives that the legacy envelope cannot represent faithfully. The legacy `more_like_this` verb has no typed compact equivalent and maps only lossily into `ask`.
## Finalize and hold inventory
Finalization is seller commitment, not buyer acceptance. It locks the already-negotiated terms and reserves inventory until the returned `expires_at`:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441003",
"refinements": [
{
"proposal_id": "proposal_draft_789",
"action": "finalize"
}
]
}
```
For a committed proposal, `expires_at` is the inventory-hold deadline—not a
quote-freshness hint and not a channel-specific booking horizon. Until that
instant, the committed proposal remains executable under
[`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal). After it,
the hold lapses and the buyer must obtain and finalize a new proposal.
**The hold write is atomic.** For each finalized proposal, the seller MUST
persist the committed successor and reserve the inventory it represents as one
state transition. A committed proposal MUST NOT become observable without its
corresponding reservation, and a failed finalization MUST NOT leave an orphaned
reservation. If the seller cannot complete that transition synchronously, it
uses the task's `submitted` path and exposes the committed proposal only after
the reservation has succeeded.
A request containing `finalize` must contain only finalize entries. Sellers validate the complete batch before creating any holds; multi-proposal finalization is atomic. When any hold cannot be created, no result is `finalized`: the failing entry returns `unable` with `reason_code: "hold_unavailable"`, and otherwise-eligible siblings return `unable` with `reason_code: "batch_aborted"`. Exact retries use the same idempotency key. A new key does not extend or recreate an existing hold: while a committed successor's hold is unexpired, finalizing the same draft again MUST fail at task level with [`INVALID_STATE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-state) rather than minting a second hold; after expiry a new finalize MAY create a new one.
Holds are a seller commitment against real inventory, so hold policy is the seller's. Sellers MAY decline any hold (`hold_unavailable`), MAY cap concurrent unexpired holds per buyer to prevent inventory squatting, and choose `expires_at` themselves — the hold window should be long enough to complete acceptance and short enough that unaccepted holds do not function as free inventory options. Nothing in this task obliges a seller to grant holds without whatever credit or relationship checks it applies to reservations generally; the async `submitted` path exists for exactly that re-underwriting.
This contract does not define a pDOOH booking horizon, a frame/loop overlap
model, or a locking or scheduling algorithm for separate concurrent finalize
requests. Those policies cannot be inferred from `expires_at`. Whatever policy
a seller implements, every unexpired committed proposal retains the existing
acceptance guarantee; sellers cannot issue a committed hold and later reject it
merely because the same inventory was allocated elsewhere.
Every revised proposal inherits the source proposal's opportunity association. Callers do not repeat opportunity context during refinement.
## Negotiation security
Both sides of this task are agents, and both sides' inputs are untrusted. `ask` is attacker-controlled free text: sellers MUST NOT let it alter pricing floors, authorization, or policy, and MUST NOT expose other buyers' terms through it — fence it from any LLM with pricing authority and treat its interpretation as suggestion, never instruction. In the other direction, deterministic `constraint_unsatisfiable` responses form a price oracle: repeated budget or rate probes can binary-search a floor at no cost. Sellers SHOULD apply rate or commercial friction to sustained un-held revision rounds and MAY keep `reason` deliberately coarse rather than revealing how near a rejected constraint came to clearing.
## Amend an accepted MediaBuy
An accepted proposal is the immutable commercial envelope attached to its MediaBuy. Refining it forks a successor proposal rather than reopening or mutating the accepted snapshot:
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441013",
"refinements": [
{
"proposal_id": "proposal_accepted_123",
"action": "revise",
"change_kind": "amendment",
"ask": "Extend the flight by two weeks and add the premium video product."
}
]
}
```
Use `change_kind: "cancellation"` when cancellation requires counterparty agreement. The returned draft has `proposal_kind: "media_buy_cancellation"`, identifies the MediaBuy and base revision, and must be finalized before it can be applied through [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal).
Sellers MAY respond asynchronously with `status: "submitted"` when a complex multi-publisher revision or inventory hold requires upstream pricing queries or manual re-underwriting. In that case the response contains a `task_id` for polling via [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json); terminal results are delivered on the completion artifact or via push notification if `push_notification_config` was supplied.
# request_proposals
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/request_proposals
Request one or more seller-authored draft media plans.
`request_proposals` creates one or more immutable draft media-plan proposal snapshots from a brief. It can begin a consultative workflow directly or use `product_ids` returned by [`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products). Native seller success always contains at least one proposal; returning products without a proposal does not satisfy a native 3.2 implementation. The temporary projection-only exception for older peers is documented below.
`brand` contains only the stable BrandKey (`domain`, optional `brand_id`, and optional ISO country `countries[]`); the seller resolves the canonical brand manifest rather than receiving a full brand file in every call. Countries qualify commercial advertiser identity and do not target delivery. `account` is optional and adds seller-specific commercial terms. A natural-key account can supply the request's sole brand identity and qualify it with an operator-owned unit and fixed account currency.
**Request schema:** [`/schemas/3.2.1/media-buy/request-proposals-request.json`](https://adcontextprotocol.org/schemas/3.2.1/media-buy/request-proposals-request.json)
```json theme={null}
{
"idempotency_key": "550e8400-e29b-41d4-a716-446655441001",
"brief": "Reach outdoor enthusiasts with premium video inventory.",
"account": {
"brand": {
"domain": "nova-athletics.example",
"countries": ["DE", "NL"]
},
"operator": "pinnacle-media.example",
"operator_unit": {
"id": "seat_emea_01",
"name": "EMEA"
},
"currency": "EUR"
},
"opportunity": {
"opportunity_id": "opp_spring_launch_2027",
"phase": "active_sourcing",
"intent": "live_rfp",
"response_deadline": "2027-01-15T17:00:00Z"
},
"criteria": {
"product_ids": ["product_premium_video"],
"targeting_overlay": {
"geo_countries": ["US"]
},
"required_overlay_support": {
"geo_metros": { "systems": ["nielsen_dma"] }
}
}
}
```
Put machine-representable requirements in `criteria`: `offer_filters` select commercial offers, `targeting_overlay` supplies concrete package delivery constraints, and `required_overlay_support` identifies package dimensions the buyer must be able to choose later. `required_media_buy_support` and `media_buy_frequency_cap` separately request aggregate-counter participation and preflight an exact shared cap. Keep goals and requirements without a structured AdCP field in `brief`.
When refining an accepted proposal, omitted criteria inherit. Set
`remove_media_buy_frequency_cap: true` on the refinement to negotiate a draft
that clears the root cap; supplying `criteria.media_buy_frequency_cap` replaces it.
## Reverse forecasting with outcome_target
A proposal request is a solve over three coupled variables — time window, budget, and outcome. The buyer fixes what they know and the seller solves for the rest. Fixing dates and budget yields a delivery forecast; fixing the outcome inverts the question: "I need 10,000 clicks — what does my budget need to be?"
Sellers declaring `media_buy.outcome_target` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) accept the structured form in `criteria`:
```json theme={null}
{
"criteria": {
"outcome_target": {
"goal": { "kind": "metric", "metric": "clicks" },
"volume": 10000
}
}
}
```
The `goal` is a compact planning-time object with two variants: a delivery metric (`kind: "metric"`, using the same `forecastable-metric` vocabulary forecast points report) or a conversion event (`kind: "event"`, using the same `event-type` vocabulary). That construction means every permitted goal has a defined answer: the seller responds with `total_budget_guidance` (`min`/`recommended`/`max`) on each proposal and forecasts whose points carry the goal's metric or event key in `metrics`, with `forecast_range_unit` `clicks` or `conversions` structuring the curve where those units apply. Priorities, event sources, and vendor bindings live on the proposal's optimization goals (purchase `optimization_goals`, or `budget_allocation.optimization_goals` under seller-optimized allocation), which share this vocabulary, so buyers carry the same metric or event name from plan to buy.
An `outcome_target` is a planning input, not a delivery guarantee: pricing and delivery obligations arise only at proposal finalization, and any performance commitment lives in the committed terms, not in the forecast. Sellers that do not declare the capability MUST NOT silently ignore a structured `outcome_target` on `request_proposals` or a proposal refinement — they reject it with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature); buyers fall back to expressing the goal in `brief` prose. Declaring sellers MAY reject a goal they cannot plan against (for example `spend`, which restates budget) with [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) naming `criteria.outcome_target.goal`.
### Cost targets
A buyer who knows what it will pay per result, rather than how many results it needs, sends `cost_per` instead of, or alongside, `volume`. At least one of the two is required. `cost_per` is the 3.2 [`BiddingPolicy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy#biddingpolicy-object) `cost_per` plus a currency:
* `amount`: the average cost per goal result.
* `strength`: `cap` optimizes for an average at or below the amount and accepts underdelivery when necessary. `target` optimizes around the amount while balancing volume and spend. Neither is a per-result or per-auction guarantee.
* `currency`: the ISO 4217 currency of `amount`. `BiddingPolicy.cost_per` has no currency because it inherits the media-buy currency, and no media buy exists at request time, so the request states it.
A cost target requires a goal expressible as a canonical optimization goal. A goal without one (for example `impressions`, `grps`, `downloads`, `plays`, `frequency`, `coverage_rate`, `audience_size`, or `measured_impressions`) can still be planned by volume, so the seller rejects the cost target, not the goal: [`INVALID_REQUEST`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-invalid-request) naming `criteria.outcome_target.cost_per`.
The four request shapes are:
| Request | Seller plans |
| - | - |
| `volume` only | The budget that delivers the volume, answered with `total_budget_guidance`. Unchanged from the volume-only form above. |
| `cost_per` with a buyer budget (`offer_filters.budget_range` or the brief) | The volume it can deliver within that budget at or below (`cap`) or around (`target`) the amount. With `budget_range.max` it plans within `max`; with only `min`, at or above `min`. `total_budget` never exceeds `max` or falls below `min`. |
| `cost_per` plus `volume` | Toward the volume at the cost. Under a `cap`, the seller SHOULD keep the buyer's amount and forecast the lower volume it can deliver, unless no volume can be planned at that amount. Under a `target`, the ask is plannable when the seller can forecast the volume around it. |
| `cost_per` with neither volume nor budget | The volume it can deliver at the cost. The seller MUST state the spend for that volume in `total_budget_guidance`. |
**Answer.** Each proposal states the cost the seller can plan to in `commercial_terms.bidding.cost_per`, which the buyer adopts on acceptance. The `amount` MUST be greater than or equal to the ask: the requested amount when it is plannable, otherwise the lowest plannable amount. An amount is plannable when the seller can forecast goal volume at or below (`cap`) or around (`target`) it within the buyer's budget, and, when `budget_range.min` is present, only if the plan spends at least `min`. When the planned spend at the answered amount is below `commercial_terms.total_budget`, each forecast point MUST carry `metrics.spend`. A seller MAY return additional proposals at higher amounts under the same strength, to show what volume a higher cost buys. The seller keeps the buyer's `strength` and states only its own `amount`. A `cap` of 3 that the seller can only meet at 4.50 comes back as `{ "amount": 4.50, "strength": "cap" }`, never as `"target"`, because changing the strength would silently change the execution semantics the buyer asked for. A seller that will not plan under the buyer's strength at any amount rejects the request instead. The forecast's points carry the goal volume planned under that policy.
`bidding.cost_per.amount` is the execution control, not an expected price. Compare sellers on forecast volume and spend at the proposal's budget, not on the cap amount; billing stays on the selected pricing option.
**Goal binding.** The answering proposal MUST NOT carry purchase-level `bidding`, so the media-buy policy binds under the `BiddingPolicy` rules:
* Under fixed or omitted `budget_allocation`, every purchase's primary optimization goal matches `goal`, and all of them resolve to the same result unit as `BiddingPolicy.cost_per` defines it: identical result-defining qualifiers and, for event goals, an identical resolved `attribution_window`.
* Under `seller_optimized`, the primary goal of `budget_allocation.optimization_goals` matches `goal`.
"Matches" means the same `kind` and `metric` for a metric goal. For an event goal, every `event_sources[]` entry carries the goal's `event_type` (and `custom_event_name`). The seller MAY add result-defining qualifiers such as `view_duration_seconds` or `reach_unit`; they are visible in the proposal.
For an event goal, the seller fills `event_sources[]` from the event sources available on the buyer's account for that event, whether buyer-synced or seller-managed (`managed_by: "seller"`), as listed by [`sync_event_sources`](/dist/docs/3.2.8/media-buy/task-reference/sync_event_sources) discovery. It fills exactly one source unless it advertises `conversion_tracking.multi_source_event_dedup`. It also states `attribution_window`, which SHOULD be one it advertises in `conversion_tracking.attribution_windows` for that event type. The buyer sees both before accepting. With no source available for the event, the seller rejects with `INVALID_REQUEST` naming `criteria.outcome_target.cost_per`.
**Bidding capability.** A seller MUST NOT answer with a bidding policy outside its advertised `features.bidding_policy` profile for the proposal's scope and allocation mode. A seller that declares `media_buy.outcome_target` but advertises no such profile rejects cost targets with `INVALID_REQUEST` naming `criteria.outcome_target.cost_per`. The `media_buy.outcome_target` flag alone cannot distinguish a seller that predates cost targets from one that plans them, so buyers rely on the negotiated `adcp_version` together with `features.bidding_policy`.
**Currency.** `cost_per.currency` is the currency of the answer. Every answering proposal's `purchases[].pricing.currency`, which the bidding amounts are denominated in, and its `forecast.currency` MUST equal it, as MUST `commercial_terms.total_budget.currency` and `total_budget_guidance.currency` when present. When `offer_filters.budget_range` is present, `cost_per.currency` MUST equal `budget_range.currency`. Sellers MUST NOT convert currency. A conflict with `budget_range`, `pricing_currencies`, the account currency, or the currencies the requested products are priced in is rejected with `INVALID_REQUEST` naming `criteria.outcome_target.cost_per`. This deliberately differs from [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products), where a currency filter that matches nothing returns zero products: a cost target states the currency of the answer, so a conflict is a malformed request, not an empty result.
**Rejection.** `INVALID_REQUEST` naming `criteria.outcome_target.cost_per` covers a cost target that cannot be represented or bound: its strength, currency, goal, or the seller's bidding capability. A valid cost target for which the seller has no viable inventory returns `outcome: "rejected"` with a reason, like any other unplannable request. A seller that does not declare `media_buy.outcome_target` rejects the whole field with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature), as for volume.
The cost target is still a planning input. The execution policy is the accepted proposal's `bidding.cost_per`.
[`list_products`](/dist/docs/3.2.8/media-buy/task-reference/list_products) shares these criteria but returns products and never proposals, so `outcome_target` has no answer there, with or without `cost_per`. The field is inert on `list_products` for every seller, whether or not it declares `media_buy.outcome_target`: it does not filter or rank products, produces no guidance or bidding answer, and MUST NOT cause a rejection beyond schema validation. A buyer can therefore reuse one `criteria` object across `list_products` and `request_proposals`. A seller that does not declare the capability still rejects the field on proposal requests, and the capability flag, not a `list_products` error, tells the buyer whether a proposal request will be planned. Send outcome targets through `request_proposals`.
In this worked example, a buyer asks for clicks at €3 or less on a €5,000 budget. The seller advertises fixed media-buy `cost_per` caps in `features.bidding_policy`:
```json theme={null}
{
"$schema": "/schemas/3.2.8/latest/media-buy/request-proposals-request.json",
"idempotency_key": "550e8400-e29b-41d4-a716-446655441002",
"brief": "Drive traffic to the spring running collection page.",
"account": {
"brand": { "domain": "nova-athletics.example" },
"operator": "pinnacle-media.example"
},
"criteria": {
"product_ids": ["product_premium_video"],
"offer_filters": {
"budget_range": { "max": 5000, "currency": "EUR" }
},
"outcome_target": {
"goal": { "kind": "metric", "metric": "clicks" },
"cost_per": { "amount": 3, "currency": "EUR", "strength": "cap" }
}
}
}
```
The seller can't plan clicks at €3 on this inventory. The best it can plan is €4.50, so it answers with a €4.50 cap and the roughly 1,111 clicks that €5,000 buys at that cost:
```json theme={null}
{
"$schema": "/schemas/3.2.8/latest/core/canonical-proposal.json",
"proposal_id": "proposal_spring_clicks_01",
"proposal_kind": "new_media_buy",
"proposal_status": "draft",
"expires_at": "2027-01-16T17:00:00Z",
"name": "Spring collection traffic at a click cost cap",
"brief_alignment": "€3 per click is below what this inventory can plan to. The plan caps the average at €4.50 and plans about 1,111 clicks within €5,000.",
"commercial_terms": {
"brand": { "domain": "nova-athletics.example" },
"purchases": [
{
"product_id": "product_premium_video",
"pricing_option_id": "cpm_eur_fixed",
"pricing": {
"pricing_option_id": "cpm_eur_fixed",
"pricing_model": "cpm",
"currency": "EUR",
"fixed_price": 9
},
"budget": 5000,
"optimization_goals": [{ "kind": "metric", "metric": "clicks", "priority": 1 }],
"start_time": "2027-03-01T00:00:00Z",
"end_time": "2027-03-31T23:59:59Z"
}
],
"start_time": "2027-03-01T00:00:00Z",
"end_time": "2027-03-31T23:59:59Z",
"total_budget": { "amount": 5000, "currency": "EUR" },
"bidding": {
"cost_per": { "amount": 4.5, "strength": "cap" }
}
},
"terms_digest": "sha256:IO3B2jLn52O7-u_xeztyhTFDUJWbV4mQrCcTfCWpAQg",
"total_budget_guidance": { "min": 4000, "recommended": 5000, "max": 5000, "currency": "EUR" },
"forecast": {
"method": "modeled",
"currency": "EUR",
"forecast_range_unit": "clicks",
"points": [
{ "budget": 2500, "metrics": { "clicks": { "mid": 555 }, "spend": { "mid": 2497.5 } } },
{ "budget": 5000, "metrics": { "clicks": { "mid": 1111 }, "spend": { "mid": 4999.5 } } }
]
}
}
```
The purchase's only optimization goal is `clicks`, so the media-buy `cost_per` binds to clicks. €5,000 does not divide into whole clicks at €4.50, so each point carries the planned `spend`. If the buyer had sent `"currency": "USD"` against this EUR-only product, the seller would reject with `INVALID_REQUEST` naming `criteria.outcome_target.cost_per` rather than convert.
Explicit hard requirements in the brief remain binding. When the seller's structured interpretation materially affects product eligibility, pricing, or forecasting, the response includes `targeting_resolution.brief_targeting`. Exact structured overlays are not echoed; any product-specific alternative appears as sparse `Product.targeting_resolution.modifications` for buyer approval. A product carrying `targeting_resolution` also carries `expires_at`, which is how compact products mark request-specific configured offers; they have no `is_custom` flag.
When the effective criteria include property or collection lists, every product returned alongside the proposals carries its own `list_applications` receipts. Proposal objects do not duplicate them. The receipts show how each list snapshot intersected that product at evaluation time, and the proposal uses the resulting price and forecast.
Every returned purchase references the exact `product_id` and `pricing_option_id` whose pricing and forecast the seller used. The returned `proposal_id` is the only proposal linkage needed by [`refine_proposals`](/dist/docs/3.2.8/media-buy/task-reference/refine_proposals) and [`decline_proposals`](/dist/docs/3.2.8/media-buy/task-reference/decline_proposals). Each ID identifies one immutable commercial snapshot; refinement and finalization mint new IDs instead of adding a second version field. A draft is indicative and does not reserve inventory. Finalize it through `refine_proposals` before passing the resulting committed proposal to [`accept_proposal`](/dist/docs/3.2.8/media-buy/task-reference/accept_proposal). The deprecated [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) proposal mode remains the 3.x compatibility adapter.
`opportunity` is optional shared planning-cycle context and must be open when supplied here. Its buyer-assigned `opportunity_id` can span request, decline, and purchase calls without becoming part of proposal identity. Sellers associate it with every proposal created by the request, and revised proposals inherit the same association.
The native response uses `outcome: "proposed"` for a successful draft set and `outcome: "rejected"` with a reason when the seller cannot construct a viable plan. A compatibility coordinator may also return the projection-only `products_available` outcome defined below.
## Products-only legacy compatibility
A native 3.2 seller never reports products without a proposal as successful
`request_proposals`; `outcome: "proposed"` continues to require at least one
seller-authored immutable draft. Compatibility coordinators have one temporary
exception for older peers: a valid 2.5, 3.0, or 3.1 [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) brief may
return useful products and no proposal. The coordinator preserves that result
as the projection-only `products_available` outcome instead of dropping the
products or fabricating a proposal.
`products_available` carries one discriminated `purchase_continuation`:
* `listed_purchase` means the coordinator successfully re-read the exact
products from a real seller-issued, account-scoped feed and obtained its
feed and pricing fences. The buyer continues through ordinary
[`buy_products`](/dist/docs/3.2.8/media-buy/task-reference/buy_products) with those
seller-issued values.
* `legacy_create` means no truthful fence is available. The coordinator can
continue through explicit-package
[`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy), but
only after the caller accepts every named loss for that logical operation.
The response always names `feed_version_not_atomic` and
`pricing_version_not_atomic`; an AdCP 2.5 source also names
`mutation_idempotency_not_guaranteed` because that release has no mutation
replay contract.
The second path fails closed by default. A compatibility token may bind the
observed products and prices to the caller and account, but it is not a feed or
pricing fence. The coordinator MUST NOT synthesize a proposal,
`commercial_terms`, `terms_digest`, `feed_version`, or `pricing_version`.
Products with incomplete or unconfirmed pricing cannot use `listed_purchase`.
The legacy seller revalidates price, expiry, and availability at create time,
and its rejection is terminal for that attempt.
Legacy `incomplete[]` remains a completeness statement. The coordinator
preserves its compatible product, pricing, forecast, and proposal scopes;
`scope: "proposals"` explains the absence of a proposal and is not a business
rejection. Legacy brief pagination limits products, not proposals, and a legacy
`time_budget` instructs the seller not to begin work it cannot complete in
time. A 3.2 compatibility facade must preserve those semantics rather than
silently converting them into an unbounded, apparently complete proposal call.
This bridge is deprecated with the established lifecycle in 3.2 and removed in
AdCP 4.0. See the [full compatibility and transaction-boundary
matrix](https://github.com/adcontextprotocol/adcp/blob/main/specs/legacy-compact-lifecycle-compatibility.md).
Sellers MAY respond asynchronously with `status: "submitted"` when consultative planning requires upstream system queries or human sales-desk review. In that case the response contains a `task_id` for polling via [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json); terminal draft proposals are delivered on the completion artifact or via push notification if `push_notification_config` was supplied.
# sync_audiences
Source: https://docs.adcontextprotocol.org/dist/docs/3.2.8/media-buy/task-reference/sync_audiences
sync_audiences task — upload hashed first-party CRM audiences to AdCP seller accounts for retargeting, suppression, and lookalike expansion. Supports match status tracking.
Manage first-party CRM audiences on a seller account. Upload hashed customer lists, check matching status, and reference the resulting audiences in [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) targeting overlays for explicit retargeting or suppression.
Audiences are distinct from [signals](/dist/docs/3.2.8/signals/): signals are named targeting dimensions discovered through product signal options, provider-published signal definitions, or [`get_signals`](/dist/docs/3.2.8/signals/tasks/get_signals); audiences are data you own and upload. Use `audience_include` to target only members of an uploaded list. `audience_include` is a hard constraint — only users on the list are eligible. A signal returned by `get_signals` is not a synced audience ID and instead belongs in [`signal_targeting_groups`](/dist/docs/3.2.8/media-buy/advanced-topics/targeting#signal_targeting_groups). To find new users *similar to* an audience (lookalike expansion), describe that intent in your campaign brief — the seller handles expansion strategy. Note: lookalike intent expressed in the brief cannot be verified through the protocol; confirm via seller-side reporting.
**Response Time**: Upload accepted in \~1–2s. Per-audience matching is asynchronous — the task remains active until matching completes (1–48 hours depending on the seller). Configure `push_notification_config` to receive a webhook when the audience is ready. Sellers whose ingestion pipeline cannot return per-audience results in the synchronous response (batch ingestion, governance-gated upload, clean-room flows) MAY respond with an operation-level submitted task envelope — see [Response shapes](#response-shapes).
**Request Schema**: [`/schemas/3.2.8/media-buy/sync-audiences-request.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-audiences-request.json)
**Response Schema**: [`/schemas/3.2.8/media-buy/sync-audiences-response.json`](https://adcontextprotocol.org/schemas/3.2.8/media-buy/sync-audiences-response.json)
## Quick Start
Upload a customer list and check its status:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAudiencesResponseSchema } from "@adcp/sdk";
import { createHash } from "crypto";
const hashEmail = (email) =>
createHash("sha256").update(email.toLowerCase().trim()).digest("hex");
const hashPhone = (e164Phone) =>
createHash("sha256").update(e164Phone).digest("hex");
const result = await testAgent.syncAudiences({
account: { account_id: "acct_12345" },
audiences: [
{
audience_id: "existing_customers",
name: "Existing customers",
add: [
{ external_id: "crm_1001", hashed_email: hashEmail("alice@example.com") },
{ external_id: "crm_1002", hashed_email: hashEmail("bob@example.com"), hashed_phone: hashPhone("+12065551234") },
],
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAudiencesResponseSchema.parse(result.data);
// Three-shape discriminated union: errors | submitted | audiences
if ("status" in validated && validated.status === "submitted") {
// Whole sync queued asynchronously — invoke get_task_status with task_id or await webhook
console.log(`Sync queued as task ${validated.task_id}: ${validated.message ?? ""}`);
} else if ("errors" in validated && validated.errors && !("audiences" in validated)) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
} else if ("audiences" in validated) {
for (const audience of validated.audiences) {
console.log(`${audience.audience_id}: ${audience.action} (${audience.status ?? "n/a"})`);
if (audience.status === "ready") {
console.log(` Matched ${audience.matched_count} of ${audience.uploaded_count} members (this sync)`);
}
}
}
```
```python Python theme={null}
import asyncio
import hashlib
from adcp.testing import test_agent
def hash_email(email: str) -> str:
return hashlib.sha256(email.lower().strip().encode()).hexdigest()
def hash_phone(e164_phone: str) -> str:
return hashlib.sha256(e164_phone.encode()).hexdigest()
async def main():
result = await test_agent.simple.sync_audiences(
account={'account_id': 'acct_12345'},
audiences=[{
'audience_id': 'existing_customers',
'name': 'Existing customers',
'add': [
{'external_id': 'crm_1001', 'hashed_email': hash_email('alice@example.com')},
{'external_id': 'crm_1002', 'hashed_email': hash_email('bob@example.com'), 'hashed_phone': hash_phone('+12065551234')},
]
}]
)
# Three-shape discriminated union: errors | submitted | audiences
if getattr(result, 'status', None) == 'submitted':
# Whole sync queued asynchronously — invoke get_task_status with task_id or await webhook
print(f"Sync queued as task {result.task_id}: {getattr(result, 'message', '') or ''}")
return
if getattr(result, 'errors', None) and not getattr(result, 'audiences', None):
raise Exception(f"Operation failed: {result.errors}")
for audience in result.audiences:
status = getattr(audience, 'status', 'n/a')
print(f"{audience.audience_id}: {audience.action} ({status})")
if status == 'ready':
print(f" Matched {audience.matched_count} of {audience.uploaded_count} members (this sync)")
asyncio.run(main())
```
## Request Parameters
| Parameter | Type | Required | Description |
| - | - | - | - |
| `account` | [account-ref](/dist/docs/3.2.8/building/by-layer/L2/accounts-and-agents#account-references) | Yes | Account reference. Pass `{ "account_id": "..." }` or `{ "brand": {...}, "operator": "..." }` if the seller supports implicit resolution. |
| `audiences` | [Audience](#audience-object)\[] | No | Audiences to sync. When omitted, the call is discovery-only and returns all existing audiences without modification. |
| `delete_missing` | boolean | No | When true, buyer-managed audiences on the account not in this request are removed (default: false). Does not affect seller-managed audiences. Do not combine with an omitted `audiences` array or all buyer-managed audiences will be deleted. |
### Audience Object
| Field | Type | Required | Description |
| - | - | - | - |
| `audience_id` | string | Yes | Buyer's identifier for this audience. Used to reference the audience in targeting overlays. |
| `name` | string | No | Human-readable name |
| `delete` | boolean | No | When true, delete this audience from the account entirely. All other fields are ignored. |
| `add` | [AudienceMember](#audience-member)\[] | No | Members to add to this audience. Mutually exclusive with `source`. |
| `remove` | [AudienceMember](#audience-member)\[] | No | Members to remove from this audience. If the same identifier appears in both `add` and `remove`, remove takes precedence. Mutually exclusive with `source`. |
| `source` | [AudienceSource](#external-audience-sources-experimental) | No | **Experimental.** External source reference — the seller ingests membership from a shared dataset or vendor-distributed segment instead of inline member deltas. See [External audience sources](#external-audience-sources-experimental). |
| `consent_basis` | string | No | GDPR lawful basis: `consent`, `legitimate_interest`, `contract`, or `legal_obligation`. Required by some sellers in regulated markets. |
### Audience Member
Every member requires an `external_id` (buyer-assigned stable identifier) plus at least one matchable identifier. Hash all values with SHA-256 before sending — normalize emails to lowercase+trim, phone numbers to E.164 format (e.g. `+12065551234`).
| Field | Type | Description |
| - | - | - |
| `external_id` | string | **Required.** Buyer-assigned stable identifier for this member (e.g. CRM record ID, loyalty ID). Used for deduplication, removal, and cross-referencing with buyer systems. |
| `hashed_email` | string | SHA-256 hash of lowercase, trimmed email (64-char hex) |
| `hashed_phone` | string | SHA-256 hash of E.164-formatted phone number (64-char hex) |
| `uids` | UID\[] | Universal IDs: `type` (rampid, uid2, maid, etc.) + `value` |
Providing multiple identifiers for the same person improves match rates. Composite identifiers (e.g. hashed first name + last name + zip) are not yet standardized — use `ext` for platform-specific extensions.
**Identifier support varies by seller**: Check [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities) → `media_buy.audience_targeting.supported_identifier_types` and `media_buy.audience_targeting.supported_uid_types` before sending. MAID support is not universal (LinkedIn does not accept MAIDs; iOS IDFA requires App Tracking Transparency consent). The `media_buy.audience_targeting.matching_latency_hours` range and `media_buy.audience_targeting.minimum_audience_size` in capabilities are also seller-specific.
**Activation paths beyond inline push**: Inline members are one activation method. Sellers declare which paths they support — AdCP push, dataset sharing, clean rooms, platform distribution — via [`audience_activation`](/dist/docs/3.2.8/media-buy/product-discovery/media-products#audience-activation) on products and `media_buy.audience_targeting.supported_activation_methods` in [`get_adcp_capabilities`](/dist/docs/3.2.8/protocol/get_adcp_capabilities). Filter discovery with `filters.audience_activation_methods` on [`get_products`](/dist/docs/3.2.8/media-buy/task-reference/get_products) to find inventory compatible with your data pipeline. [External source references](#external-audience-sources-experimental) — pointing this task at a shared dataset or vendor-distributed segment instead of pushing members — are available experimentally on sellers that declare the corresponding activation patterns.
**Size limit**: Payloads are limited to 100,000 members per call across all audiences. For larger lists, chunk into sequential calls using `add` deltas.
**Concurrency**: Ensure that calls made to `sync_audience` are independent of eachother. They may be processed out-of-order. If you need sequential execution, wait for the callback to your configured webhook before making another call.
## Response shapes
Responses use discriminated unions — a response has exactly one of three shapes, never mixed:
**1. Synchronous success** — per-audience results:
* `audiences` — Results for each audience on the account, including audiences not in this request
* `sandbox` — Boolean indicating if this response is from sandbox mode (optional)
**2. Terminal failure** — no audiences processed:
* `errors` — Array of operation-level errors (auth failure, account not found, invalid request format)
**3. Submitted task envelope** — whole operation queued asynchronously (batch ingestion, governance-gated upload, clean-room flows where the seller cannot return per-audience results before the response is emitted):
* `status` — Always `"submitted"`
* `task_id` — Handle for polling via [`get_task_status`](https://adcontextprotocol.org/schemas/3.2.8/protocol/get-task-status-request.json) on the A2A profile (or the advertised AdCP polling task on MCP), or receiving a webhook on completion
* `message` — Optional human-readable explanation of the queue state
The final per-audience `audiences` array lands on the task completion artifact, not on the submitted envelope. Per-audience asynchronous matching (one audience in `processing` while the rest of the sync resolves synchronously) belongs on the synchronous success branch with `status: "processing"` on that item, not on the submitted envelope. Matching latency on the per-audience [audience-status](#audience-status) enum is the common case; the submitted envelope is for the less-common operation-level async case.
**Each audience in success response includes:**
| Field | Description |
| - | - |
| `audience_id` | Echoed from request (buyer's identifier) |
| `seller_id` | Seller-assigned ID in their ad platform |
| `action` | `created`, `updated`, `unchanged`, `deleted`, or `failed` |
| `status` | `processing`, `ready`, or `too_small`. Present when action is `created`, `updated`, or `unchanged`; absent when action is `deleted` or `failed`. |
| `uploaded_count` | Members submitted in this sync operation (delta, not cumulative). 0 for discovery-only calls. |
| `total_uploaded_count` | Cumulative members uploaded across all syncs. Compare with `matched_count` to calculate match rate. |
| `matched_count` | Total members matched to platform users across all syncs (cumulative). Populated when `status: "ready"`. |
| `effective_match_rate` | Deduplicated match rate across all identifier types (0–1). A single number for reach estimation. Populated when `status: "ready"`. |
| `match_breakdown` | Per-identifier-type match results. Shows which ID types resolve and at what rate. See [match breakdown](#match-breakdown). |
| `last_synced_at` | ISO 8601 timestamp of the most recent sync. Omitted if the seller does not track this. |
| `minimum_size` | Minimum matched audience size for targeting on this platform. Populated when `status: "too_small"`. |
| `errors` | Per-audience errors (only when `action: "failed"`) |
## Match breakdown
When a seller supports per-identifier-type reporting, the response includes `match_breakdown` — an array showing which identity types are resolving and at what rate. This helps buyers decide which identifiers to prioritize in future uploads.
```json theme={null}
{
"audience_id": "existing_customers",
"action": "updated",
"status": "ready",
"uploaded_count": 5000,
"total_uploaded_count": 25000,
"matched_count": 18750,
"effective_match_rate": 0.75,
"match_breakdown": [
{ "id_type": "hashed_email", "submitted": 25000, "matched": 17500, "match_rate": 0.70 },
{ "id_type": "hashed_phone", "submitted": 15000, "matched": 12000, "match_rate": 0.80 },
{ "id_type": "rampid", "submitted": 8000, "matched": 7200, "match_rate": 0.90 }
]
}
```
Key semantics:
* **`submitted` and `matched` are cumulative** across all syncs, matching `total_uploaded_count` semantics (not `uploaded_count`).
* **`effective_match_rate` is deduplicated** — a member matched via both email and phone counts once. It will be less than or equal to the sum of per-type match rates.
* **`match_rate` is server-authoritative** — consumers should prefer this value over computing their own from submitted/matched.
* **`id_type` values** combine hashed PII types (`hashed_email`, `hashed_phone`) with universal ID types (`rampid`, `uid2`, `id5`, `euid`, `pairid`, `maid`).
Sellers that only support aggregate match counts omit `match_breakdown` entirely.
## Common Scenarios
### Discovery Only
Check status of all existing audiences without making changes. The response includes all audiences on the account — filter by `audience_id` to find the one you care about:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAudiencesResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncAudiences({
account: { account_id: "acct_12345" },
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAudiencesResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("audiences" in validated) {
for (const audience of validated.audiences) {
console.log(`${audience.audience_id}: ${audience.status ?? "n/a"}`);
}
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_audiences(account={'account_id': 'acct_12345'})
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for audience in result.audiences:
status = getattr(audience, 'status', 'n/a')
print(f"{audience.audience_id}: {status}")
asyncio.run(main())
```
### Suppression List
Upload a list of existing customers to suppress from acquisition campaigns:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAudiencesResponseSchema } from "@adcp/sdk";
import { createHash } from "crypto";
const hashEmail = (email) =>
createHash("sha256").update(email.toLowerCase().trim()).digest("hex");
// Hashed customer emails from CRM export
const existingCustomers = [
{ hashed_email: hashEmail("customer1@example.com") },
{ hashed_email: hashEmail("customer2@example.com") },
];
const result = await testAgent.syncAudiences({
account: { account_id: "acct_12345" },
audiences: [
{
audience_id: "existing_customers",
name: "Existing customers — suppression",
add: existingCustomers,
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAudiencesResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("audiences" in validated) {
const audience = validated.audiences[0];
console.log(`Status: ${audience.status}`);
// When ready, reference audience_id in create_media_buy targeting_overlay.audience_exclude
}
```
```python Python theme={null}
import asyncio
import hashlib
from adcp.testing import test_agent
def hash_email(email: str) -> str:
return hashlib.sha256(email.lower().strip().encode()).hexdigest()
async def main():
existing_customers = [
{'hashed_email': hash_email('customer1@example.com')},
{'hashed_email': hash_email('customer2@example.com')},
]
result = await test_agent.simple.sync_audiences(
account={'account_id': 'acct_12345'},
audiences=[{
'audience_id': 'existing_customers',
'name': 'Existing customers — suppression',
'add': existing_customers
}]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
audience = result.audiences[0]
print(f"Status: {audience.status}")
# When ready, reference audience_id in create_media_buy targeting_overlay.audience_exclude
asyncio.run(main())
```
### Removing Members
Update an audience incrementally — add new members and remove ones that no longer qualify:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAudiencesResponseSchema } from "@adcp/sdk";
import { createHash } from "crypto";
const hashEmail = (email) =>
createHash("sha256").update(email.toLowerCase().trim()).digest("hex");
const result = await testAgent.syncAudiences({
account: { account_id: "acct_12345" },
audiences: [
{
audience_id: "lapsed_subscribers",
name: "Lapsed subscribers",
add: [{ hashed_email: hashEmail("newlapse@example.com") }],
remove: [{ hashed_email: hashEmail("reactivated@example.com") }],
},
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAudiencesResponseSchema.parse(result.data);
if ("errors" in validated && validated.errors) {
throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}
if ("audiences" in validated) {
for (const audience of validated.audiences) {
console.log(`${audience.audience_id}: ${audience.action}`);
}
}
```
```python Python theme={null}
import asyncio
import hashlib
from adcp.testing import test_agent
def hash_email(email: str) -> str:
return hashlib.sha256(email.lower().strip().encode()).hexdigest()
async def main():
result = await test_agent.simple.sync_audiences(
account={'account_id': 'acct_12345'},
audiences=[{
'audience_id': 'lapsed_subscribers',
'name': 'Lapsed subscribers',
'add': [{'hashed_email': hash_email('newlapse@example.com')}],
'remove': [{'hashed_email': hash_email('reactivated@example.com')}]
}]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
for audience in result.audiences:
print(f"{audience.audience_id}: {audience.action}")
asyncio.run(main())
```
### Deleting an Audience
Remove a specific audience from the account without affecting others. Set `delete: true` on the audience object:
```javascript JavaScript theme={null}
import { testAgent } from "@adcp/sdk/testing";
import { SyncAudiencesResponseSchema } from "@adcp/sdk";
const result = await testAgent.syncAudiences({
account: { account_id: "acct_12345" },
audiences: [
{ audience_id: "old_campaign_list", delete: true },
],
});
if (!result.success) {
throw new Error(`Request failed: ${result.error}`);
}
const validated = SyncAudiencesResponseSchema.parse(result.data);
if ("audiences" in validated) {
const audience = validated.audiences.find(a => a.audience_id === "old_campaign_list");
console.log(`${audience.audience_id}: ${audience.action}`); // "deleted"
}
```
```python Python theme={null}
import asyncio
from adcp.testing import test_agent
async def main():
result = await test_agent.simple.sync_audiences(
account={'account_id': 'acct_12345'},
audiences=[{'audience_id': 'old_campaign_list', 'delete': True}]
)
if hasattr(result, 'errors') and result.errors:
raise Exception(f"Operation failed: {result.errors}")
audience = next(a for a in result.audiences if a.audience_id == 'old_campaign_list')
print(f"{audience.audience_id}: {audience.action}") # "deleted"
asyncio.run(main())
```
To delete multiple audiences in one call, include each with `delete: true`. To delete all buyer-managed audiences at once, use `delete_missing: true` with an empty `audiences` array — but be careful, this removes everything.
### Using Audiences in a Media Buy
Once an audience is `ready`, reference it by `audience_id` in [`create_media_buy`](/dist/docs/3.2.8/media-buy/task-reference/create_media_buy) targeting overlays. Audience IDs are scoped to the seller account — they cannot be used across sellers.
```json test=false theme={null}
{
"brand": { "house_domain": "acme.com", "brand_id": "main" },
"start_time": "asap",
"end_time": "2026-03-31T23:59:59Z",
"packages": [
{
"product_id": "prod_sponsored_content",
"pricing_option_id": "cpm_standard",
"budget": 10000,
"targeting_overlay": {
"audience_include": ["high_value_prospects"],
"audience_exclude": ["existing_customers"]
}
}
]
}
```
## External Audience Sources (experimental)
> [!NOTE]
>
> **Experimental** (`media_buy.audience_activation`). External sources share the activation-declaration feature id: sellers implementing them MUST list `media_buy.audience_activation` in `experimental_features`, and the surface may change between 3.x releases with notice. See [Experimental status](/dist/docs/3.2.8/reference/experimental-status).
Instead of pushing hashed members inline, an audience can carry a **source reference** — a pointer to buyer data the seller ingests over a declared [activation rail](/dist/docs/3.2.8/media-buy/product-discovery/media-products#audience-activation). The data never transits AdCP: the protocol moves the pointer, ingestion happens on the vendor's rails, and the resulting audience lands in the same lifecycle (status enum, match reporting, discovery, targeting overlays) as a pushed audience.
Two source kinds, mapping 1:1 onto the seller's declared activation patterns. Buyers MUST only send kinds whose pattern the seller declared (`dataset_query` → `dataset`, `platform_distribution` → `platform_segment`); undeclared kinds are rejected with [`UNSUPPORTED_FEATURE`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-unsupported-feature).
**Schema**: [`/schemas/3.2.8/core/audience-source.json`](https://adcontextprotocol.org/schemas/3.2.8/core/audience-source.json)
### Dataset (grant-based)
The seller reads a table or share the buyer granted through the vendor's grantee-identified sharing mechanism (Snowflake Secure Data Sharing, Databricks Delta Sharing using D2D or OIDC token federation, BigQuery authorized views):
1. Read the seller's declared `consumer_identities` from its [`audience_activation`](/dist/docs/3.2.8/media-buy/product-discovery/media-products#audience-activation) declaration.
2. Grant access in the vendor's system (e.g. `ALTER SHARE audience_share ADD ACCOUNTS = SELLERORG.INGEST_US`). Out of band — AdCP never carries credentials. The grant MUST name a principal without conveying a secret through AdCP: Databricks D2D and open sharing with OIDC token federation qualify; the classic bearer-token recipient profile does not. A request carrying credential material is rejected with [`CREDENTIAL_IN_ARGS`](/dist/docs/3.2.8/building/verification/compliance-catalog#error-code-credential-in-args).
3. Call `sync_audiences` with the source reference:
```json test=false theme={null}
{
"audience_id": "high_value_customers",
"name": "High-value customers",
"audience_type": "crm",
"source": {
"kind": "dataset",
"vendor": { "domain": "data-cloud.example" },
"locator": "PINNACLE.AUDIENCES.HIGH_VALUE_V3",
"access_expires_at": "2026-12-01T00:00:00Z"
}
}
```
> [!NOTE]
>
> For Databricks, keep the two sharing identifiers distinct. The seller advertises its non-secret recipient identity in `consumer_identities[]` as `::`. The buyer passes what to read in `source.locator` using the Databricks-path convention `share:////.