Release Notes

​

Version 3.0.6

​

Adopter action

​

GOVERNANCE_DENIED / GOVERNANCE_UNAVAILABLE wire-placement guidance (#3929, closes the doc-comment item on #3918; companion to #3914)

• GOVERNANCE_DENIED — structured business outcome, not a system error. When the task response defines a structured rejection arm, that arm IS the canonical denial shape: populate status: "rejected" + reason, do NOT additionally emit the code in errors[] or adcp_error, and do NOT flip transport-level failure markers. When the task has no rejection arm, populate errors[].code AND adcp_error.code per the two-layer model and DO flip transport markers.
• GOVERNANCE_UNAVAILABLE — system error, governance call failed at all. Always populate both layers with the code and flip transport markers. Sellers MUST NOT use a structured rejection arm for unavailability even when the task offers one — the buyer’s recovery semantics differ (retry-with-backoff vs. restructure-or-escalate).

​

ctx_metadata reserved as adapter-internal round-trip key (#3640)

​

Implementation-dependent issues[] fields documented in SKILL.md (#3927 backport)

​

Storyboard-schema documents task_completion.<inner> prefix (#3955, closes #3950)

​

comply_test_controller is deployment-scoped, not request-gated (#3992)

​

Storyboard fixture fixes

• inventory_list_targeting — the 5 account blocks across this scenario use the brand+operator natural-key variant of AccountReference but omitted the sandbox flag. Sellers whose accounts.resolve has separate code paths for sandbox vs production refs were routing create_media_buy and get_media_buys through different account-id namespaces, breaking mediaBuyStore backfill of targeting_overlay. Setting sandbox: true on every account block keeps both create and get on the sandbox path. Mirror of #3989 on main. Follow-up to align the SDK runner’s enricher asymmetry tracked at adcp-client#1487.
• sales_guaranteed/create_media_buy — the context_outputs[0].path was bare "media_buy_id", which the runner resolved against the immediate submitted-arm response — a step that fails with capture_path_not_resolvable and masks downstream phases. Updated to "task_completion.media_buy_id" so the runner polls tasks/get and captures the seller-issued id from the terminal artifact, per the runner contract introduced in adcp-client#1426. Mirror of #3990 on main.

​

Version 3.0.5

​

Adopter action

​

identity.additionalProperties: true on get_adcp_capabilities (#3896, closes Scope3 adoption gap)

​

Storyboard-level default_agent field (#3897, closes #3894)

1. Step-level agent: override.
2. Specialism-claimant match against the runtime agents map. Multi-claim grades unrouted_step (operator-config error); slots 3/4 do not rescue. Zero claimants falls through to slot 3.
3. Storyboard-level default_agent (this field). Set-but-unmatched grades default_agent_unresolved — the runner does NOT silently fall through to slot 4, because that would invisibly override the storyboard author’s encoded intent.
4. Run-options default_agent. Same set-but-unmatched rule.
5. Fail-fast — unrouted_step.

​

Brand-rights storyboard acquire_rights capture fix (#3893, closes #3892)

​

Release mechanics (#3820)

​

Detailed changelog

​

Version 3.0.4

​

Adopter action

​

manifest.json + structured enumMetadata (#3725, #3738)

1. enums/error-code.json gains an enumMetadata block. Every error code now carries structured recovery (correctable | transient | terminal) and suggestion fields. SDKs MUST consume this block instead of parsing Recovery: X prose out of enumDescriptions — a build-time lint enforces structured/prose parity. Closes the root cause of adcp-client#1135 (17 missing codes, 3 wrong recovery classifications shipped in TS SDK for over a year).
2. /schemas/3.0.4/manifest.json. Single canonical artifact listing every tool (with protocol, mutating, request_schema, response_schema, async_response_schemas, specialisms), every error code (with recovery, description, suggestion), an error_code_policy block (defining default_unknown_recovery so SDKs handle non-spec codes correctly), and every storyboard specialism (with protocol, entry_point_tools, exercised_tools). Validates against manifest.schema.json. Lets SDKs derive their internal tool/error tables from one place at codegen time.

​

core/error.json — issues[] field (#3059, #3562)

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "field": "creatives[0].assets.image",
  "issues": [
    {
      "pointer": "/creatives/0/assets/image",
      "message": "Required",
      "keyword": "required"
    },
    {
      "pointer": "/creatives/0/format_id",
      "message": "Must match pattern",
      "keyword": "pattern"
    }
  ]
}

​

AUTH_REQUIRED retry-storm prose (#3730 partial, #3739 backport)

​

Detailed changelog

​

Version 3.0.3

​

Adopter action

​

provides_state_for storyboard field (#3734)

​

runner-output-contract.yaml — peer_substituted skip reason

​

url_type: tracker → tracker_pixel (#2986 step 1)

​

Detailed changelog

​

Version 3.0.2

​

Adopter action

​

envelope_field_present check kind

​

Canonical core/assets/asset-union.json

​

Detailed changelog

​

Version 3.0.1

​

Adopter action

​

Why 3.0.1 exists

​

Spec polish — no wire change

• acquire_rights request validation — Brand agents MUST reject expired campaign windows (campaign.end_date in the past) with INVALID_REQUEST. CPM-priced rights under a governed plan must include campaign.estimated_impressions. Closes implementer disagreement on identical requests. (#2680, #2681)
• get_signals pagination precedence — When both top-level max_results and pagination.max_results are present, agents MUST honor pagination.max_results. Top-level max_results deprecated; removed in 4.0.
• URL canonicalization — Now applies uniformly to brand.json agent URLs (brand_agent_entry.url, brand_agent.url, rights_agent.url). Two URLs differing only in case, default port, or percent-encoded unreserved characters compare equal during agent resolution. New reference page at URL canonicalization.
• v3 envelope integrity — Schema-level constraint on protocol-envelope.json formally prohibits legacy v2 task_status / response_status field names. The prose MUST NOT was already in 3.0.0; the constraint is now machine-detectable by validators. Companion universal storyboard v3-envelope-integrity exercises the assertion. Conformant 3.0 implementations are unaffected. (#3041)
• Format asset codegen — Title annotations on format.json oneOf branches enable codegen tools (json-schema-to-typescript, datamodel-code-generator, oapi-codegen) to emit named per-asset-type interfaces instead of untyped unions. Annotation-only.
• Inline-enum hoisting — Source schemas now $ref shared enum files for payment-terms, audio-channel-layout, media-buy-valid-action, match-type, governance-decision, billing-party, and 11 others. Bundled wire format unchanged in all cases.

​

Experimental surfaces — additive only

• Governance — mode field added to check-governance-response.json and get_plan_audit_logs audit entries. Records the enforcement posture (enforce/advisory/audit) active at check time. Closes a gap where audit and enforce modes produced identical-looking trails.
• Trusted Match Protocol (TMP) — seller_agent: { agent_url, id? } added to AvailablePackage, making seller identity explicit on every package cached by a TMP provider. New seller_not_authorized error code for sync-time rejection when the seller’s agent_url is not present in the property publisher’s adagents.json. All TMP schemas now carry x-status: experimental.

​

Conformance harness — sandbox-only

• force_task_completion — Resolves a previously-submitted async task to completed with a buyer-supplied result payload. Closes the loop on the async create_media_buy submitted → completed roundtrip. Result is delivered via the seller’s webhook (canonical 3.0 path); a typed result projection on the polling response is tracked for 3.1 in #3123.
• seed_creative_format — Pre-populates a deterministic set of creative formats for pagination-integrity storyboards. Companion: list_creative_formats now applies cursor-based pagination matching the list_creatives pattern.

​

Release mechanics

• Cosign signing on private packages so future Version Packages merges auto-tag and changesets/action auto-creates the GitHub Release with artifacts.
• dist/protocol/ retained in the Fly.io image so cosign-signed versioned tarballs ship and /protocol/{version}.tgz actually serves end-to-end.
• Skills bundled at /protocol/3.0.1.tgz: call-adcp-agent plus the per-protocol adcp-{brand,creative,governance,media-buy,si,signals}.

​

Detailed changelog

​

Version 3.0.0

​

What’s New

1. Trust surface: four cryptographic primitives for agent-to-agent ad buying — Grouped by symmetry on the wire, so what’s true of a request is true of a webhook: Requests — buyer → seller:
   • idempotency_key required on every mutating request — fresh key per logical operation, matching ^[A-Za-z0-9_.:-]{16,255}$ (UUID v4 for Verified). Sellers declare dedup semantics via adcp.idempotency = { supported: true, replay_ttl_seconds: ... } (1h–7d, 24h recommended) or { supported: false }. When supported: true: replayed: true on exact replay, IDEMPOTENCY_CONFLICT on payload mismatch, IDEMPOTENCY_EXPIRED past TTL. When supported: false: retries double-process — buyers MUST use natural-key checks instead. Extended to activate_signal. Conformance runners probe supported: true claims with a deliberate payload-mutation replay. (#2315, #2407, #2436, #2447)
   • RFC 9421 HTTP Message Signatures — optional in 3.0, required for AdCP Verified. Ed25519 over a canonicalized covered-component list (including content-digest). sf-binary and URL canonicalization pinned so independent implementations produce bit-identical canonical inputs. Verifier follows a 15-step checklist (keyid cap-before-crypto, SSRF-validated JWKS fetch, jti replay dedup, audience binding) — see the Security guide. Published test vectors under static/compliance/source/test-vectors/request-signing/. (#2323, #2341, #2342, #2343)
   Webhooks — seller → buyer, same profile in reverse:
   • Webhook signing unified on the RFC 9421 profile — baseline-required for sellers emitting webhooks — Sellers sign outbound webhooks with a key published in their JWKS at jwks_uri (discoverable via brand.json agents[]). The JWK carries adcp_use: "webhook-signing" to distinguish it from the request-signing key; kid values MUST be unique across purposes within a JWKS. No shared secret crosses the wire. Verification failures return typed webhook_signature_* reason codes defined in the Security guide. HMAC-SHA256 remains a legacy fallback through 3.x (opt-in via push_notification_config.authentication.credentials); removed in 4.0. (#2423)
   • Webhook payloads carry a required idempotency_key — Every webhook is dedupable by a sender-generated UUID v4, using the same ^[A-Za-z0-9_.:-]{16,255}$ format as request-side keys. Replaces fragile (task_id, status, timestamp) dedup across five webhook payload schemas. revocation-notification.notification_id renamed to idempotency_key for protocol-wide consistency. (#2416, #2417)
   Governance — signed authority:
   • Signed JWS governance_context — governance decisions are cryptographically verifiable offline. The governance agent issues a JWS signed with its key from sync_governance; sellers verify and bind decisions to sub (buyer), aud (seller), phase, and exp without round-tripping. Stale or forged decisions are rejected at the transport layer. Sellers with a configured governance agent MUST call check_governance before committing budget (rejection with PERMISSION_DENIED on missing or invalid context). (#2316, #2403, #2419)
   See Security implementation guide for the threat model, adcp_use JWK taxonomy, and per-primitive verification paths.
2. Specialisms, compliance storyboards, and AdCP Verified — Trust primitives define the bar; storyboards test that an agent actually meets it; AdCP Verified certifies the result. Storyboards move into the protocol at /compliance/{version}/ (universal + protocols + specialisms + test-kits). Every agent runs /compliance/{version}/universal/security.yaml regardless of claims — unauth rejection, API key enforcement, OAuth discovery per RFC 9728, audience binding, and (when signing is claimed) the signed_requests and signed_webhooks runner harnesses. Runner output is a structured, verifiable runner-output.json with a hash chain over the test-kit corpus. Cross-instance state persistence is required. New specialisms field on get_adcp_capabilities lets agents claim narrow capability specialisms across 6 protocols (media-buy, creative, signals, governance, brand, sponsored_intelligence). sponsored_intelligence is promoted from specialism to full protocol. broadcast-platform → sales-broadcast-tv, social-platform → sales-social. property-governance + collection-governance split into sibling property-lists and collection-lists specialisms. Compliance taxonomy renames domains → protocols; audience-sync reclassified from governance to media-buy. Per-version protocol tarball at /protocol/{version}.tgz. The formal AdCP Verified program launches with 3.1 once reference implementations (training agent, SDKs) and ambiguous-storyboard work reach full compliance on a 4–6 week cadence; 3.0 Verified is self-attested via published runner output. See the Compliance Catalog and What’s new in v3 for the rationale and timeline. (#2176, #2300, #2304, #2332, #2336, #2350, #2352, #2363, #2381)
3. Broadcast TV Support — Linear TV sellers can now fully participate in AdCP. Ad-ID identifiers on creative assets and manifests. Broadcast spot formats for :15, :30, and :60 spots. agency_estimate_number on media buys and packages. Measurement windows (Live, C3, C7) on reporting capabilities. Delivery data completeness flags (is_final, measurement_window) for provisional vs. closed numbers. Broadcast forecast schema adds measurement_source and guaranteed_impressions. station_id and facility_id identifier types. (#2046, #1853, #1912)
4. Governance Generalization and Regulatory Invariants — Governance extends beyond media buys to cover brand rights licensing, signal activation, and creative services. governance_context replaces media_buy_id as the identifier tying governance actions across a campaign’s lifecycle. New purchase_type field distinguishes the governed activity. GDPR Art 22 / EU AI Act Annex III are enforced as schema invariants: budget.authority_level splits into budget.reallocation_threshold (autonomy) and plan.human_review_required (Art 22 review); cross-field if/then rejects human_review_required: false for regulated verticals (fair housing, fair lending, fair employment, pharmaceutical). Append-only revisionHistory; downgrades require a human_override artifact. eu_ai_act_annex_iii seeded in the registry. data_subject_contestation on brand.json satisfies Art 22(3) discovery. (#2014, #2310, #2338)
5. Capabilities Model Simplification — Redundant boolean gates are removed throughout get_adcp_capabilities. If a content_standards object exists in the response, the agent supports content standards — no separate boolean needed. reporting_capabilities is now required on every product. Geo capability fields keep their typed shapes (geo_countries, geo_regions, geo_metros, geo_postal_areas). (#2143, #2157)
6. Collection Lists — Program-level brand safety for shows, series, and podcasts. Collection lists parallel property lists but target content programs using distribution identifiers (IMDb, Gracenote, EIDR) for cross-publisher matching. New collection_list and collection_list_exclude fields on the targeting overlay. Genre taxonomy enum normalizes classification. 16 new collection schemas. (#2005)
7. Structured Measurement Terms — Guaranteed buys gain a formal negotiation surface. measurement_terms covers billing vendor, IVT threshold, and viewability floor. Sellers declare defaults; buyers propose overrides at create_media_buy; sellers accept, reject, or adjust. cancellation_policy schema declares notice periods and penalties. TERMS_REJECTED error code. (#1962)
8. Unified Vendor Pricing — Pricing extends from signals to creative, governance, and property list agents. All vendor pricing now uses a shared schema covering CPM, percent-of-media, and flat-fee models. pricing_options[] on list_creatives, build_creative, get_creative_features, and property lists. (#1937)
9. Per-Request Version Declaration — adcp_major_version on all 56+ request schemas lets buyers declare which major version their payloads conform to. Sellers return VERSION_UNSUPPORTED on mismatch. When omitted, sellers default to their highest supported version. (#1959)
10. Offline Reporting Delivery — Sellers can push reports to buyer-provided cloud storage. reporting_delivery_methods on capabilities declares supported protocols (SFTP, S3, GCS, Azure Blob). reporting_bucket on accounts specifies the destination. Products declare supports_offline_delivery in reporting_capabilities. File formats: CSV, JSON, Parquet, Avro, and ORC. (#2198, #2205)
11. Error Codes and Schema Consistency — New GOVERNANCE_DENIED correctable error code. context and ext fields added to all request and response schemas across governance, collection, property, SI, and content-standards protocols. signal_id is now required on get_signals response items. comply_test_controller schema flattened from a oneOf union to a flat object with a scenario discriminant. Envelope-level replayed flag (from idempotency) is now accepted on 15 mutating-tool response schemas that previously rejected it — property-list, collection-list, and governance tools that return replay responses no longer fail schema validation (#2839). Formal audience-status enum extracted with explicit lifecycle transitions, paralleling the other lifecycle-bearing resource types (#2836). (#2194)
12. Media Buy Lifecycle — pending_activation splits into pending_creatives (approved, no creatives assigned) and pending_start (ready to serve, waiting for flight date). MediaBuy.pending_approval removed; IO approvals are now explicit task-layer objects with their own lifecycle and audit trail — decoupled from media-buy status. New submitted branch on create_media_buy indicates the seller accepted the payload for processing but has not yet confirmed the order. Top-level compliance_testing: { scenarios: [...] } capability block declares comply_test_controller support. (#2034, #2270, #2351, #2425)
13. TMP: Provider Registration, TMPX Exposure Tracking, and Multi-Identity Match — New provider-registration.json schema formalizes provider endpoints, capabilities, lifecycle status (active/inactive/draining), and timeout budgets. GET /health endpoint enables router-side monitoring. TMPX adds exposure tracking with country-partitioned identity and macro connectivity. Identity Match requests now accept an identities array (1-3 tokens per request) so publishers can maximize match rate across heterogeneous buyer identity graphs. Router filters per provider and re-signs; RFC 8785 JCS canonicalization eliminates delimiter-injection risk. TMP remains pre-release in 3.0; stable surface targeted for 3.1.0. (#2210, #2079, #2251)
14. Operating an Agent, Release Cadence, CHARTER — New “Operating an Agent” guide for publishers without engineering teams (partner / self-host / build). Named release cadence policy: patch monthly, minor quarterly, major annual if needed. v2 EOL August 1, 2026. Formal CHARTER.md linked from README, IPR, and intro. AI disclosure page. Known-limitations and privacy-considerations reference pages. status: experimental marker for in-production but not-yet-stable protocol fields; custom pricing-model escape hatch on signals. (#2202, #2309, #2311, #2312, #2321, #2329, #2362, #2382, #2422, #2427)
15. Trust-surface late hardening — Two normative tightenings from the external 3.0 security review land as MUST in GA:
    • Idempotency cache insert-rate limiting. Sellers MUST apply per-(authenticated_agent, account) rate limits on idempotency-cache inserts (separate from request rate limits) and return RATE_LIMITED with retry_after when exceeded. First-deployment ceiling: 60 inserts/sec sustained per agent (3,600/min), burst to 300/sec over rolling 10s windows — sized against realistic high-volume launch patterns (10 media buys/min × 10 packages × 10 creatives, 3–5× headroom) and consistent with the existing 100k-per-keyid webhook replay cap and 1M-per-keyid request replay cap. Tunable per deployment. Closes a nonce-flood DoS amplification vector. See security.mdx idempotency § bullet 8.
    • Webhook-registration signing MUST for signing-capable sellers. Sellers that support request signing MUST reject webhook-registration requests carrying push_notification_config.authentication over bearer-only (unsigned) transport, with request_signature_required. Structural defense against on-path mutators injecting or stripping the authentication block during onboarding — a 9421-signed registration cryptographically commits to the body. Sellers with no signing support keep the log-and-alarm posture. Scoped breakage: buyers that previously registered webhooks with authentication against a signing-capable seller over bearer transport must switch to 9421-signed registration. Negative test vector 027-webhook-registration-authentication-unsigned.json lands with the tightening.
16. Error-code vocabulary cleanup (#2704) — The uniform-response MUST (#2691) forbids sellers from minting custom *_NOT_FOUND codes for typed parameters; the spec itself was out of compliance in 12 places. Cleanup aligns the spec with the rule: PLAN_NOT_FOUND is promoted to standard vocabulary (used across report_plan_outcome, get_plan_audit_logs, check_governance; recovery via sync_plans). Eleven other custom codes (CHECK_NOT_FOUND, CAMPAIGN_NOT_FOUND, BRAND_NOT_FOUND, STANDARDS_NOT_FOUND, FORMAT_NOT_FOUND, AGENT_NOT_FOUND, SIGNAL_AGENT_SEGMENT_NOT_FOUND, SEGMENT_NOT_FOUND, AUDIENCE_NOT_FOUND, CATALOG_NOT_FOUND, EVENT_SOURCE_NOT_FOUND) collapse to REFERENCE_NOT_FOUND with error.field naming the failed parameter. Signals auth-uniformity tightened: private signal agents now return REFERENCE_NOT_FOUND uniformly for unauthorized accounts (preventing cross-tenant enumeration). None of the 12 codes appeared in JSON schemas — prose-level cleanup only; no schema-enum migration. Sellers returning any of the 11 collapsed codes today MUST switch to REFERENCE_NOT_FOUND.
17. Schema presence tightenings on governance decisions and catalog sync (#2612) — Conformant agents unchanged; non-conformant ones now fail at response_schema validation instead of a less-obvious downstream field_present check. check-governance-response.json enforces the spec-described presence rules via if/then: status: conditions requires conditions with minItems: 1 (a conditions decision with zero conditions is non-actionable), status: denied requires findings with minItems: 1 (a denial with no finding gives the buyer nothing to act on), and status: approved | conditions requires expires_at. sync-catalogs-response.json requires item_count on action: created | updated | unchanged (still omitted on failed | deleted).
18. Typed discriminators and id-naming consistency — Three structural tightenings that make the 3.0 wire shape unambiguous for validators and for readers of payloads:
    • asset_type discriminator on creative assets (#2776) — All 14 asset schemas declare asset_type as a required const, and composite schemas (core/creative-manifest.json, core/creative-asset.json, core/offering-asset-group.json, creative/list-creatives-response.json) switch from a 14-branch anyOf to oneOf + discriminator: { propertyName: "asset_type" }. ajv 8 consumers with discriminator: true report errors against only the selected branch — a single fixture’s lint footprint collapsed from 60+ fingerprints to 2. Payloads that omit asset_type now fail validation; some brief payloads that were passing under the prior anyOf only because ajv matched the text-asset branch (e.g. a bare { "content": "..." }) must conform to core/creative-brief.json — at minimum { "asset_type": "brief", "name": "<brief name>" }.
    • refine[] entity id naming on get_products (#2775) — Generic id replaced with product_id under scope: "product" and proposal_id under scope: "proposal", matching the <entity>_id convention used elsewhere in the protocol. action is now optional and defaults to "include"; callers only set it explicitly for "omit" / "more_like_this" / "finalize".
    • SI context → intent rename (#2774, experimental carve-out) — On si_get_offering and si_initiate_session, the natural-language user-intent field is renamed from context to intent, freeing context to carry the universal opaque-echo object (/schemas/core/context.json) — matching every other AdCP subprotocol. si_terminate_session was already conformant. Treated as a minor change under the x-status: experimental + 6-week notice policy for SI.
    • Governance plan scoping contract (#2777) — governance/report-plan-outcome-request.json, governance/check-governance-request.json, and governance/get-plan-audit-logs-request.json now state on plan_id / plan_ids that the plan uniquely scopes account and operator; an explicit account field is rejected by additionalProperties: false. The rejection is not new, but it is now a readable contract instead of a silent schema error.
19. url-asset accepts buyer macro templates (#2801) — core/assets/url-asset.json relaxes url.format from uri to uri-template (RFC 6570 Level 1). This matches the prose spec in docs/creative/universal-macros.mdx, which requires buyers to submit tracker URLs with raw AdCP macros like {SKU} / {DEVICE_ID} / {MEDIA_BUY_ID} at sync time — the ad server URL-encodes substituted values at impression time. uri-template accepts both plain URIs and Level 1 templates. A new Template Syntax section in universal-macros.mdx scopes AdCP to Level 1 — Level 2–4 operators ({+var}, {#var}, {.var}, {/var}, {;var}, {?var}, {&var}) are not used.

​

Breaking Changes

​

Migration Notes For rc.3 Adopters

• Webhooks — Migrate from HMAC-SHA256 to RFC 9421 signing. Publish a webhook-signing JWK in your JWKS at jwks_uri (JWKS is referenced from brand.json agents[]) with adcp_use: "webhook-signing" on the JWK and a kid unique across purposes. Drop push_notification_config.authentication from new configs; buyers opt into legacy HMAC via authentication.credentials. Receivers verify against the sender’s JWKS. Every outbound webhook payload must carry an idempotency_key matching ^[A-Za-z0-9_.:-]{16,255}$ (UUID v4 for Verified). Listeners must dedupe keyed by sender identity (signing keyid under 9421, or HMAC/Bearer credential under legacy) with a 24h minimum TTL. HMAC fallback remains available through 3.x; the full authentication object is removed in 4.0.
• Idempotency — Generate a fresh key on every mutating request, matching ^[A-Za-z0-9_.:-]{16,255}$ (UUID v4 for Verified). Same key + identical payload on retry → replayed: true. Same key + different payload → IDEMPOTENCY_CONFLICT. Key older than the seller-declared replay_ttl_seconds → IDEMPOTENCY_EXPIRED (1h–7d, 24h recommended — no protocol default). Your agent must persist keys across instances.
• Request signing (optional in 3.0, required for Verified) — If you plan to claim AdCP Verified, implement RFC 9421 Ed25519 signing per the signing profile and declare your signing key via the account surface. Test against static/compliance/source/test-vectors/request-signing/ and the runner’s signed_requests harness.
• Governance context — Switch from opaque-string governance_context to the signed JWS format. Verify using the governance agent’s JWKS (resolved via sync_governance). Bind signature to sub (buyer), aud (seller), phase, and exp before trusting.
• IO approval — Remove MediaBuy.pending_approval from state filters. Consume approval tasks from the task surface instead.
• Budget autonomy — Rewrite any budget.authority_level references: agent_full → reallocation_unlimited: true; agent_limited → reallocation_threshold: <positive>; human_required → plan.human_review_required: true.
• Regulated verticals — For credit, insurance, recruitment, or housing campaigns, declare policy_categories and either set human_review_required: true or let your governance agent do so automatically. Populate brand.data_subject_contestation for Art 22(3) discovery.
• Specialism claims — Rename inventory-lists → property-lists; add collection-lists if applicable. Reclassify audience-sync under media-buy (add media_buy to supported_protocols if you only declared governance).
• Compliance paths — Update any references to /compliance/{v}/domains/ → /compliance/{v}/protocols/.
• Capabilities — Remove all boolean capability checks (features.content_standards, brand.identity, trusted_match.supported, etc.). Test for object presence instead. See the prerelease upgrade notes for the full field list.
• Products — Ensure all products include reporting_capabilities. This field is now required.
• Media buy status — Replace pending_activation with pending_creatives and pending_start. See lifecycle states.
• update_media_buy — Pass account on all calls, matching create_media_buy behavior.
• preview_creative — Update request builders from the oneOf union to the flat schema with request_type discriminant.
• Signals — Include signal_id on all signal items in get_signals responses.
• Governance — Replace media_buy_id references with governance_context. Handle GOVERNANCE_DENIED as a correctable error code.
• Version negotiation — Include adcp_major_version on requests when interacting with multi-version sellers.
• Creative asset payloads — Add "asset_type": "<type>" to every asset value in creative_manifest.assets, creative.assets, offering_asset_group.items, and list_creatives responses. For brief assets, move free-text prompts out of a bare { "content": "..." } shape into core/creative-brief.json fields (at minimum { "asset_type": "brief", "name": "<brief name>" }). For vast / daast assets, asset_type at the root plus the existing nested delivery_type discriminator.
• Product refinement — Rename refine[].id to refine[].product_id (scope: product) or refine[].proposal_id (scope: proposal). Drop action when you mean include; keep it only for non-default values (omit, more_like_this, finalize).
• Sponsored Intelligence — Rename the user-intent field from context to intent on si_get_offering and si_initiate_session. If you echo a universal context object, place it under context (now typed per /schemas/core/context.json).
• url-asset tracker URLs — No action needed to accept macros — the validator now permits RFC 6570 Level 1 templates. Do not pre-encode AdCP macros at sync time; the ad server URL-encodes substituted values at impression time.

​

Next steps

• Upgrading from v2? Start with the migration guide.
• Upgrading from a prerelease? Go to the prerelease upgrade notes.
• New to AdCP? Read the 3.0 overview and then get started.

​

Version 3.0.0-rc.3

​

What’s New

1. Trusted Match Protocol (TMP) — Real-time execution layer for AdCP. 9 schemas, 12 documentation pages, provider discovery on products, typed artifacts for content resolution, and lightweight context matching. Deprecates AXE.
2. Order Lifecycle Management — confirmed_at on order creation, cancellation at media buy and package level with canceled_by attribution, per-package creative_deadline, valid_actions for state-aware agents, revision for optimistic concurrency, and include_history for revision audit trails. 7 new error codes.
3. Governance Simplification — Remove binding field from check_governance (inferred from discriminating fields), remove mode from sync_plans (governance agent configuration, not protocol), remove escalated status (handled via async task lifecycle). Three terminal statuses: approved, denied, conditions.
4. Seller-Assigned IDs — Remove buyer_ref, buyer_campaign_ref, and campaign_ref. Seller-assigned media_buy_id and package_id are canonical. idempotency_key on all mutating requests. Opaque governance_context string replaces structured schema.
5. Proposal Lifecycle — Draft/committed proposal status, finalization via refine action, insertion order signing, and expiry enforcement on create_media_buy. Guaranteed products start as draft with indicative pricing.
6. Audience Bias Governance — Structured audience data for fairness validation. New schemas for audience selectors, constraints, policy categories, and restricted attributes (GDPR Article 9). 10 policy category definitions, 8 restricted attribute definitions, 13 seed policies across US, EU, and platform regulations.
7. Streaming and Audio Delivery Metrics — completed_views (renamed from video_completions), reach, reach_unit, and frequency in aggregated totals. Audio/podcast-native metrics. reach_unit co-occurrence constraint on delivery-metrics.json.
8. Availability Forecasts — budget now optional on ForecastPoint for total available inventory. New availability forecast range unit. Guaranteed products include availability forecasts with estimated cost.
9. Advertiser Industry Taxonomy — Two-level dot-notation categories on brand manifest and create_media_buy. Restricted categories (gambling, cannabis, dating) require explicit declaration.
10. Content Standards — content_standards on get_adcp_capabilities for pre-buy visibility into local evaluation and artifact delivery capabilities. sampling removed from get_media_buy_artifacts (configured at creation time).
11. Event Source Health — Optional health on event sources (status, match rate, event volume, issues) and measurement_readiness on products for buyer event setup evaluation.
12. Collection/Installment Extensions — special and limited_series fields, installment deadlines with deadline policies, print-capable creative formats with physical units, DPI, bleed, and color space.
13. Scoped adagents.json Authorization — Delegation types, placement governance, signing keys, country and time-window constraints on authorized_agents.

​

Breaking Changes

​

Migration Notes For rc.2 Adopters

• Buyer references — Remove buyer_ref and campaign_ref from request payloads. Use idempotency_key for safe retries instead.
• Governance — Remove binding from check_governance calls, mode from sync_plans, and stop handling escalated status. Use async task polling for human review workflows.
• Artifacts — Remove sampling from get_media_buy_artifacts requests. Configure sampling at create_media_buy time.
• Format filtering — Replace format_types filters with asset_types on list_creative_formats or channels on get_products.
• Collections — Rename show/episode references to collection/installment throughout.

​

Version 3.0.0-rc.2

​

What’s New

1. Brand Protocol Rights Lifecycle — get_rights, acquire_rights, update_rights tasks for brand licensing. Generation credentials, creative approval webhooks, revocation notifications, and usage reporting. Authenticated webhooks (HMAC-SHA256), actionable vs final rejection convention, DDEX PIE mapping for music licensing, and sandbox tooling for scenario testing.
2. Visual Guidelines on Brand Manifest — Structured visual_guidelines field on brand.json: photography, graphic style, shapes, iconography, composition, motion, logo placement, colorways, type scale, asset libraries, and restrictions. Enables generative creative systems to produce on-brand assets.
3. Collections and Installments — Content dimension for products representing persistent programs (podcasts, TV series, YouTube channels). collections on products references collections declared in an adagents.json by domain and collection ID — collection creators can serve as canonical sources regardless of distribution. collection_targeting_allowed controls whether buyers can select a subset or get the bundle. Distribution identifiers for cross-seller matching, installment lifecycle states, break-based ad inventory, talent linking, collection relationships, international content ratings.
4. Sponsored Intelligence Channel — sponsored_intelligence added to the media channel taxonomy for AI platform advertising (AI assistants, AI search, generative AI experiences).
5. Property Governance Integration — Optional property_list parameter on get_products for filtering products by governance-evaluated property lists. property_list_applied response field confirms filtering.
6. Campaign Governance and Policy Registry — sync_plans, check_governance, report_plan_outcome, and get_plan_audit_logs for plan-level governance. Adds audit/advisory/enforce modes, delegated budget authority, seller-side governance checks, portfolio governance, registry-backed shared policies, and governance_context for canonical plan extraction.
7. Account Model Simplification — Removed account_resolution capability. require_operator_auth now determines both auth model and account reference style.
8. Creative Workflow Upgrades — build_creative now supports inline preview via include_preview, multi-format output via target_format_ids, quality tiers for draft vs production output, catalog-driven item_limit, and library retrieval using creative_id plus optional macro substitution and trafficking context. preview_creative also adds quality control parameters.
9. Creative Library Protocol Unification — list_creatives and sync_creatives now live in the Creative Protocol. Creative agents can advertise supports_generation, supports_transformation, and has_creative_library so buyers can route generation, transformation, and library retrieval intentionally.
10. Disclosure Persistence — Regulatory disclosure requirements can now specify persistence (continuous, initial, flexible) in addition to position and duration, with matching capability declarations on formats.
11. Product Discovery and Planning Ergonomics — Product discovery adds exclusivity and preferred_delivery_types; products may omit delivery_measurement; packages and proposals support per-package start_time / end_time; and get_products now supports time_budget with incomplete response reporting.
12. Accounts and Sandbox Refinements — sync_accounts adds payment_terms, sandbox capability moves to the account capability block, and sandbox now participates in the account natural key for implicit account flows.
13. Governance Agent Sync — sync_governance task for syncing governance agent endpoints to specific accounts. Supports both explicit accounts (account_id) and implicit accounts (brand + operator) via account references. Replace semantics per call. Governance sync is now a dedicated tool — removed from sync_accounts and list_accounts.

​

Breaking Changes

​

Migration Notes For rc.1 Adopters

• Creative task routing — If you adopted 3.0.0-rc.1, update any assumptions that creative library operations are Media Buy tasks. list_creatives and sync_creatives are Creative Protocol operations in rc.2, even when a sales agent implements them on the same endpoint.
• Capability discovery — Replace reads of account_resolution with require_operator_auth, and read sandbox support from account.sandbox instead of media_buy.features.sandbox.
• Creative request/response handling — build_creative can now return inline previews, multiple manifests, or a library-resolved manifest. Clients that assumed only single-format manifest-in / manifest-out behavior should update their response handling.
• DOOH validation — Existing v3 DOOH flat_rate integrations must add type: "dooh" inside parameters when those parameters are provided.

​

Other Updates

• Certification program — Three-tier certification (Basics, Practitioner, Specialist) taught by Addie through interactive chat, with vibe coding build projects for non-technical participants.
• Documentation — Illustrated protocol walkthroughs, buy-side guides, FAQ expansion, schema-compliant examples, and collapsed sidebar navigation.

​

Version 3.0.0-rc.1

​

What’s New

1. Keyword Targeting — keyword_targets and negative_keywords on the targeting overlay for search and retail media. Per-keyword bid prices with broad, phrase, and exact match types. Incremental management via keyword_targets_add and keyword_targets_remove on package updates. by_keyword breakdown in delivery reporting.
2. Optimization Goals Redesign — optimization_goal (singular) replaced by optimization_goals (array). Discriminated union on kind: metric for seller-native delivery metrics or event for conversion tracking. Priority ordering for multi-goal packages. New metric types: engagements, follows, saves, profile_visits. View duration configuration for video completion goals.
3. Reach Optimization — reach as a metric optimization goal with reach_unit (individuals, households, devices, accounts, cookies, custom) and optional target_frequency band (min/max/window). Products declare supported_reach_units when reach is in their supported metrics.
4. Expanded Frequency Cap — frequency_cap now supports max_impressions + per + window in addition to the existing suppress_minutes.
5. Signal Pricing Models — Discriminated union with three pricing models: cpm, percent_of_media (with optional max_cpm), and flat_fee. Structured pricing_options array replaces the legacy pricing object on signals. pricing_option_id on activate_signal. idempotency_key on report_usage for preventing double-billing.
6. Dimension Breakdowns — Opt-in reporting dimensions on get_media_buy_delivery: by_geo, by_device_type, by_device_platform, by_audience, by_placement — each with truncation flags. New reporting_dimensions request parameter with per-dimension limit and sort_by controls. Capability declaration at seller level (get_adcp_capabilities → media_buy.reporting) and product level (reporting_capabilities).
7. Device Type Targeting — New device_type field (form factor: desktop, mobile, tablet, ctv, dooh, unknown) distinct from existing device_platform (OS). With device_type_exclude for negative targeting. Declared in get_adcp_capabilities targeting capabilities.
8. Deliver-to Flattening — The nested deliver_to object in get_signals request replaced with two top-level fields: destinations and countries. Simplifies queries where the caller is querying a platform’s own signal agent.
9. Metric Optimization Capabilities — Products declare metric_optimization block with supported_metrics, supported_view_durations, and supported_targets. max_optimization_goals on products. Conversion tracking declares supported_targets. multi_source_event_dedup flag in get_adcp_capabilities.
10. Swiss & Austrian Postal Codes — ch_plz and at_plz added to the postal-system enum, with corresponding updates to get_adcp_capabilities.
11. Brand Identity Unification — brand-manifest.json deleted. Task schemas now reference brands by { domain, brand_id } (BrandRef) instead of passing inline manifests. Brand data is resolved from brand.json or the registry at execution time.
12. Delivery Forecasts on Products — estimated_exposures replaced with structured forecast field using the DeliveryForecast type. Products now return time periods, metric ranges, and methodology context during discovery.
13. Proposal Refinement via Buying Mode — proposal_id removed from get_products request. Refinement now uses buying_mode: "refine" with a typed refine array (see item 21). Session continuity (context_id in MCP, contextId in A2A) carries conversation history across calls. Proposal execution via create_media_buy with proposal_id is unchanged.
14. First-Class Catalogs — sync_catalogs task with 13 catalog types (structural and industry-vertical). Formats declare catalog_requirements. Catalogs include conversion_events and content_id_type for attribution alignment.
15. New Tasks — get_media_buys for operational campaign monitoring, get_creative_features for creative governance, sync_audiences for CRM-based audience management.
16. Buying Mode — buying_mode on get_products with three modes: brief (natural language discovery), wholesale (full catalog), and refine (typed change-requests on previous results). Now required on all get_products calls.
17. Sandbox Mode — sandbox protocol parameter on all tasks for testing without side effects.
18. Creative Brief Type — CreativeBrief type on build_creative request for structured creative direction.
19. Campaign Reference — campaign_ref field for cross-operation campaign grouping across multiple media buys.
20. Geo Proximity Targeting — geo_proximity targeting overlay for point-based proximity targeting. Three methods: travel_time isochrones (e.g., “within 2hr drive of Düsseldorf”), radius (e.g., “within 30km of Heathrow”), and pre-computed geometry (buyer provides a GeoJSON polygon). Structured capability declaration in get_adcp_capabilities with per-method and transport mode support.
21. Typed Refinement with Seller Acknowledgment — refine redesigned from nested object to typed change-request array with scope discriminator (request, product, proposal). Field renames: product_id/proposal_id → id, notes → ask. Seller responses include refinement_applied — a positionally-matched array with per-ask status (applied, partial, unable) and notes.
22. AI Provenance and Disclosure — provenance object on creative manifests, assets, and artifacts for AI content transparency. IPTC-aligned digital_source_type enum (9 values), ai_tool metadata, human_oversight levels, C2PA soft references via manifest_url, regulatory disclosure with per-jurisdiction requirements (EU AI Act, California SB 942), and third-party verification results. provenance_required on creative policy for seller enforcement.
23. Creative Compliance — compliance object on creative briefs with required_disclosures (structured items with text, position, jurisdictions, regulation, minimum duration) and prohibited_claims. New disclosure-position enum with 8 standard positions. Formats declare supported_disclosure_positions. supports_compliance capability flag replaces supports_brief.
24. Manifest Unification — Creative manifest model unified to format_id + assets. Briefs and catalogs become proper asset types (brief, catalog) within the assets map. All asset reference lists across creative-manifest, creative-asset, and list-creatives-response aligned to 14 asset types with consistent anyOf validation.
25. Structured Error Recovery — recovery field on errors with three classifications: transient (retry after delay), correctable (fix request and resend), terminal (requires human action). 18 standard error codes (INVALID_REQUEST, RATE_LIMITED, POLICY_VIOLATION, PRODUCT_UNAVAILABLE, etc.) with recovery mappings in the new error-code enum.
26. Agent Ergonomics — fields parameter on get_products for response projection (24 projectable fields). include_package_daily_breakdown opt-in on delivery reporting. Request-side attribution_window for cross-platform normalization. Buy-level start_time/end_time on get_media_buys. supported_pricing_models on seller capabilities. Audience metadata: description, audience_type (crm, suppression, lookalike_seed), tags, and total_uploaded_count for match rate calculation.
27. Signal Deactivation — action field on activate_signal with activate (default) and deactivate values for compliance-driven signal removal.
28. Signal Metadata — categories (valid values for categorical signals) and range (min/max for numeric signals) on signal entries in get_signals responses.
29. Media Buy Rejection — rejected status added to media-buy-status enum with rejection_reason on the MediaBuy object.
30. Idempotency — idempotency_key on update_media_buy and sync_creatives for at-most-once execution. idempotency_key added to create_media_buy for at-most-once creation.

​

Breaking Changes

​

Other Changes

• audience-source enum for breakdown-level audience attribution
• device-type enum (desktop, mobile, tablet, ctv, dooh, unknown) for form factor targeting and breakdown reporting
• sort-metric enum for controlling breakdown sort order
• geo-breakdown-support schema for declaring per-geography breakdown capabilities
• Keyword targeting capability flags in get_adcp_capabilities
• reporting object in get_adcp_capabilities for declaring dimension breakdown support
• geo_proximity capability object in get_adcp_capabilities for declaring supported proximity methods and transport modes
• error-code enum with 18 standard error codes and recovery classifications
• disclosure-position enum (8 standard positions for regulatory disclosures)
• digital-source-type enum (9 IPTC-aligned values for AI content classification)
• provenance core object for AI content transparency across creative schemas
• consent-basis enum extracted from sync_audiences (consent, legitimate_interest, contract, legal_obligation)
• date-range and datetime-range core types replacing inline period objects
• Property list filters relaxed: countries_all and channels_any no longer required
• Signal categories and range metadata on get_signals responses
• rejected media buy status with rejection_reason
• idempotency_key on update_media_buy and sync_creatives
• Removed not:{} patterns from 7 response schemas for Python codegen compatibility

​

Version 3.0.0-beta.3

​

What’s New

1. Delivery Forecasting - Predict campaign performance before committing budget. New DeliveryForecast type with budget curves, forecast methods (estimate, modeled, guaranteed), daypart targeting windows, and GRP demographic notation. Forecasts attach to product allocations and proposals, enabling budget curve analysis across spend levels.
2. Brand Protocol - Brand discovery and identity resolution via brand.json. Four manifest variants (authoritative redirect, house redirect, brand agent, house portfolio) with builder tools, registry, and admin UI. Brands declare authorized_operators to control which agents can represent them.
3. Account Management - sync_accounts task lets agents declare brand portfolios to sellers with upsert semantics. Account capabilities in get_adcp_capabilities describe billing requirements and operator authorization. Two billing models (operator, agent) with account lifecycle (active, pending_approval, payment_required, suspended, closed). account_id is optional on create_media_buy — single-account agents can omit it.
4. Commerce Media - Catalog-driven product discovery (catalog on get_products), catalog-driven packages, per-catalog-item delivery reporting (by_catalog_item), store catchment targeting, and catalog_types on products. Cross-retailer GTIN matching via catalog selectors. Commerce attribution metrics (roas, new_to_brand_rate) in delivery response. See the Commerce Media Guide and Catalogs.
5. Creative Delivery Reporting - Per-creative metrics breakdown within by_package in delivery responses. New get_creative_delivery task on creative agents for variant-level delivery data with manifests. Three variant tiers: standard (1:1), asset group optimization, and generative creative. Format-level reported_metrics declare which metrics each format can provide.
6. CPA & TIME Pricing Models - Two new pricing models. CPA (Cost Per Acquisition) for outcome-based campaigns — covers CPO, CPL, CPI use cases differentiated by event_type. TIME for sponsorship-based advertising where price scales with duration (hour, day, week, month) with optional min/max constraints.
7. Conversion Tracking - New events protocol with sync_event_sources and log_event tasks for attribution and measurement.
8. Signal Catalog - Data providers become first-class members with signal definitions, categories, targeting schemas, and value types. New schemas for signal discovery and integration into products.
9. Cursor-Based Pagination - All list operations (list_creatives, tasks_list, list_property_lists, get_property_list, get_media_buy_artifacts) standardized on cursor-based pagination with shared pagination-request.json and pagination-response.json schemas.
10. Accessibility in Creative Formats - Two-layer accessibility model. Format-level wcag_level (A/AA/AAA) and requires_accessible_assets flag. Asset-level metadata for inspectable assets (alt text, captions, transcripts) and self-declared properties for opaque assets (keyboard navigable, motion control). Buyers can filter by wcag_level in list_creative_formats.
11. Targeting Restrictions & Geo Exclusion - Functional restriction overlays for age (with verification methods), device platform (Sec-CH-UA-Platform values), and language localization. Geographic exclusion fields (geo_countries_exclude, geo_regions_exclude, geo_metros_exclude, geo_postal_areas_exclude) enable RCT holdout groups and regulatory exclusions.
12. Typed Asset Requirements - Discriminated union schemas for all 12 asset types (image, video, audio, text, markdown, HTML, CSS, JavaScript, VAST, DAAST, URL, webhook) using asset_type as discriminator.
13. Universal Macros - universal-macro.json enum defining all 54 standard ad-serving macros, including 6 new additions: GPP_SID, IP_ADDRESS, STATION_ID, COLLECTION_NAME, INSTALLMENT_ID, AUDIO_DURATION.
14. Brand Manifest Improvements - Structured tone object with voice, attributes, dos, donts fields. Logo objects gain orientation, background, variant, usage fields.

​

Breaking Changes

​

Other Changes

• optimization_goals on package requests — buyers can specify conversion and metric optimization goals when creating or updating media buys
• Attribution window metadata on delivery response: click_window_days, view_window_days, and attribution model (last_touch, first_touch, linear, time_decay, data_driven)
• Channel fields on property and product schemas: supported_channels and channels referencing Media Channel Taxonomy enum
• account_id added to get_media_buy_delivery and get_media_buy_artifacts requests
• date_range_support in reporting capabilities
• minItems: 1 on request-side arrays for stricter validation
• FormatCategory enum and type field removed from Format objects (use assets array instead)
• format_id optional in preview_creative (falls back to creative_manifest.format_id)
• selection_mode on repeatable asset groups to distinguish sequential (carousel) from optimize (asset pool) behavior
• Session ID fallback recommendation for MCP agent context_id

​

Version 3.0.0-beta.2

​

What’s New

1. Accounts & Agents - AdCP now distinguishes Brand (whose products are advertised), Account (who gets billed), and Agent (who places the buy). New account_id field on media buys, product queries, and creative operations enables multi-account billing with rate cards and credit limits.
2. Property Targeting - Products can declare property_targeting_allowed to let buyers target a subset of publisher properties. When enabled, buyers pass a property_list in their targeting overlay and the package runs on the intersection.
3. A2UI for Sponsored Intelligence - Sponsored Intelligence sessions now support agent-driven UI rendering via MCP Apps, enabling rich interactive experiences within AI assistants.
4. CTV & Streaming Constraints - Video formats gain technical constraint fields for frame rate, HDR, GOP structure, and moov atom position. Audio formats add codec, sampling rate, channel layout, and loudness normalization (LUFS/true peak) fields.
5. Creative Protocol Discovery - get_adcp_capabilities now includes "creative" in supported_protocols, letting agents discover creative services at runtime.

​

Schema Changes

• New account.json, list-accounts-request.json, list-accounts-response.json schemas
• account_id added to create-media-buy-request, get-products-request, sync-creatives-request, and their responses
• Shared price-guidance.json schema extracted to fix duplicate type generation across pricing options
• property_targeting_allowed and property_list fields added to product and targeting overlay schemas
• Video/audio asset schemas extended with CTV technical constraint fields

​

Removed

​

Version 3.0.0-beta.1

​

What’s New

1. Media Channel Taxonomy - Complete overhaul from 9 format-oriented channels to 19 planning-oriented channels that reflect how buyers allocate budgets. See Media Channel Taxonomy.
2. Governance Protocol - New protocol domain for property lists, content standards, and brand suitability evaluation with collaborative calibration workflows.
3. Sponsored Intelligence Protocol - Conversational brand experiences in AI assistants. Defines how hosts invoke brand agent endpoints for rich engagement without breaking conversational flow. See Sponsored Intelligence.
4. Protocol-Level Capability Discovery - get_adcp_capabilities task replaces agent card extensions, providing runtime discovery of capabilities, supported protocols, and geo targeting systems.
5. Creative Assignment Weighting - Replace simple creative ID arrays with weighted assignments supporting traffic allocation and placement targeting.
6. Global Geo Targeting - Structured geographic targeting with named systems (Nielsen DMA, UK ITL, Eurostat NUTS2, etc.) for international markets.

​

Breaking Changes Summary

​

New Protocol Domains

​

Governance Protocol

• Property Lists - create_property_list, get_property_list, update_property_list, delete_property_list, list_property_lists
• Content Standards - create_content_standards, get_content_standards, update_content_standards, calibrate_content, validate_content_delivery
• Product Filtering - Pass property lists to get_products for compliant inventory discovery

​

Sponsored Intelligence Protocol

• Session Management - si_get_offering, si_initiate_session, si_send_message, si_terminate_session
• Capability Negotiation - Brands declare modalities (voice, video, avatar), hosts respond with supported capabilities
• Commerce Handoff - Seamless transition to AdCP for transactions

​

New Features

• get_adcp_capabilities task - Runtime capability discovery replacing agent card extensions
• Unified asset discovery - assets array with required boolean for full asset visibility
• Property list filtering - Pass governance lists to get_products for brand-safe inventory

​

Removed in v3

​

Quick Migration Checklist

• Update channel enum values (taxonomy guide)
• Replace creative_ids with creative_assignments
• Add system specification to metro/postal targeting
• Implement get_adcp_capabilities task
• Update format parsing to use assets array

​

Version 2.5.0

​

What’s New

1. Type Safety & Code Generation - Comprehensive discriminator fields throughout the protocol enable excellent TypeScript/Python type inference and eliminate ambiguous union types.
2. Batch Creative Previews - Generate previews for up to 50 creatives in a single API call with optional direct HTML embedding, reducing preview generation time by 5-10x.
3. Schema Infrastructure - Build-time schema versioning with semantic paths (/schemas/2.5.0/, /schemas/v2/, /schemas/v2.5/) enables version pinning and automatic minor version tracking.
4. API Consistency - Atomic response semantics (success XOR error) and standardized webhook payloads eliminate ambiguity and improve reliability.
5. Signal Protocol Refinement - Activation keys returned per deployment with permission-based access, enabling proper multi-platform signal activation.
6. Template Formats - Dynamic creative sizing with accepts_parameters enables formats that accept runtime dimensions, durations, and other parameters.
7. Enhanced Product Discovery - Structured filters with date ranges, budget constraints, country targeting, and channel filtering improve product search precision.

​

Key Enhancements

​

Type Safety & Code Generation

• Discriminator fields added to all discriminated union types (destinations, pricing, property selectors, preview requests/responses)
• Atomic response semantics - All task responses now use strict success XOR error patterns with oneOf discriminators
• Explicit type declarations on all const fields for proper TypeScript literal type generation
• 31 new enum schemas extracted from inline definitions for better reusability

​

Schema Infrastructure

• Build-time versioning - Schemas now support semantic version paths (/schemas/2.5.0/), major version aliases (/schemas/v2/), and minor version aliases (/schemas/v2.5/)
• Consistent media buy responses - Both create_media_buy and update_media_buy now return full Package objects
• Standardized webhook payload - Protocol envelope at top-level with task data under result field

​

Product Discovery

• Structured filters - Extracted filter objects into separate schemas (product-filters.json, creative-filters.json, signal-filters.json)
• Enhanced filtering - Date ranges (start_date, end_date), budget ranges with currency, country targeting, and channel filtering
• Full enum support - Filters now accept complete enum values without artificial restrictions

​

Signal Protocol

• Activation keys - activate_signal now returns deployment-specific activation keys (segment IDs, key-value pairs) based on authenticated permissions
• Consistent terminology - Standardized on “deployments” throughout signal requests and responses

​

Creative Protocol

• Batch preview support - Preview multiple creatives in one request (preview_creative supports 1-50 items)
• Direct HTML embedding - Responses can include raw HTML for iframe-free rendering
• Simplified brand manifest - Single required field (name) eliminates duplicate type generation
• Template formats - accepts_parameters field enables dynamic formats (e.g., display_[width]x[height], video_[duration]s)
• Inline creative updates - sync_creatives task provides upsert semantics for updating creatives in existing campaigns

​

Documentation & Testing

• Testable documentation - All code examples can be validated against live schemas
• Client library prominence - NPM badges and installation instructions in intro
• Fixed 389 broken links across 50 documentation files

​

Migration Guide

​

Discriminator Fields (Breaking)

// Before
{
  "platform_id": "ttd"
}

// After
{
  "type": "platform",
  "platform_id": "ttd"
}

// Before
{
  "publisher_domain": "dailyplanet.com",
  "property_ids": ["cnn_ctv_app"]
}

// After
{
  "publisher_domain": "dailyplanet.com",
  "selection_type": "by_id",
  "property_ids": ["cnn_ctv_app"]
}

// Before
{
  "pricing_model": "cpm",
  "rate": 12.50
}

// After (fixed pricing uses fixed_price field)
{
  "pricing_model": "cpm",
  "fixed_price": 12.50
}

​

Webhook Payload Structure (Breaking)

{
  "task_id": "task_123",
  "status": "completed",
  "media_buy_id": "mb_456",
  "packages": [...]
}

{
  "task_id": "task_123",
  "task_type": "create_media_buy",
  "status": "completed",
  "timestamp": "2025-11-21T10:30:00Z",
  "result": {
    "media_buy_id": "mb_456",
    "packages": [...]
  }
}

​

Signal Activation Response (Breaking)

{
  "activation_key": "segment_123"
}

{
  "deployments": [
    {
      "destination": {"type": "platform", "platform_id": "ttd"},
      "activation_key": "segment_123",
      "status": "active"
    }
  ]
}

​

Template Formats

{
  "format_id": {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_static"},
  "accepts_parameters": ["dimensions"],
  "renders": [{
    "role": "primary",
    "parameters_from_format_id": true
  }]
}

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_static",
    "width": 300,
    "height": 250
  }
}

​

Enhanced Product Filtering

{
  "filters": {
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "budget_range": {
      "min": 10000,
      "max": 50000,
      "currency": "USD"
    },
    "countries": ["US", "CA"],
    "channels": ["display", "ctv"]
  }
}

​

Schema Versioning

• /schemas/2.5.0/ - Exact version
• /schemas/v2.5/ - Latest 2.5.x patch (auto-updates for patch releases)
• /schemas/v2/ - Latest 2.x release (auto-updates for minor/patch)
• /schemas/3.0.19/ - Backward compat alias (same as v2)

​

Breaking Changes

• Discriminator fields required in destinations, property selectors, pricing options, and preview requests
• Webhook payload structure - Task data moved under result field; domain no longer required
• Signal activation response - Changed from activation_key string to deployments array
• Removed legacy creative fields - media_url, click_url, duration removed from list_creatives response

​

Non-Breaking Additions

• Application context object (optional) in all task requests
• product_card and format_card fields (optional) for visual UI support
• Batch preview mode in preview_creative (backward compatible)
• Package pricing fields in delivery reporting (already documented, now schema-enforced)
• Minor version symlinks (/schemas/v2.5/)

​

Version 2.3.0

​

What’s New

​

Migration Guide

​

Publisher-Owned Properties

{
  "properties": [{
    "publisher_domain": "dailyplanet.com",
    "property_name": "CNN CTV App",
    "property_tags": ["ctv", "premium"]
  }]
}

{
  "publisher_properties": [
    {
      "publisher_domain": "dailyplanet.com",
      "property_tags": ["ctv"]
    }
  ]
}

​

Remove Media Buy Budget

{
  "budget": 50000,
  "packages": [...]
}

{
  "packages": [
    {"package_id": "p1", "budget": 30000},
    {"package_id": "p2", "budget": 20000}
  ]
}

​

Breaking Changes

• properties field in products → publisher_properties
• list_authorized_properties returns publisher_domains array
• Removed budget from create_media_buy/update_media_buy requests

​

Version 2.2.0

​

What’s New

​

Migration Guide

{
  "source_manifest": {...},
  "promoted_offerings": [...]
}

{
  "creative_manifest": {
    "format_id": {...},
    "assets": {
      "promoted_offerings": [...]
    }
  }
}

​

Breaking Changes

• build_creative parameter renamed: source_manifest → creative_manifest
• Removed promoted_offerings as top-level parameter (now in manifest assets)

​

Version 2.1.0

​

What’s New

​

Migration Guide

{
  "assets": {
    "banner_image": {
      "asset_type": "image",
      "url": "https://cdn.example.com/banner.jpg",
      "width": 300,
      "height": 250
    }
  }
}

{
  "assets": {
    "banner_image": {
      "url": "https://cdn.example.com/banner.jpg",
      "width": 300,
      "height": 250
    }
  }
}

​

Breaking Changes

• Removed asset_type field from creative manifest payloads
• Schema paths changed: /creative/asset-types/*.json → /core/assets/*-asset.json
• Constraint fields moved from asset payloads to format specifications

​

Version 2.0.0

​

What’s New

• 8 Media Buy Tasks - Complete workflow from product discovery to delivery reporting
• 3 Creative Tasks - AI-powered creative generation and management
• 2 Signals Tasks - First-party data integration
• Standard Formats - Industry-standard display, video, and native formats
• Multi-Protocol Support - Works with MCP and A2A

​

Core Features

• Natural language product discovery with brief-based targeting
• Asynchronous task management with human-in-the-loop approvals
• JSON Schema validation for all requests and responses
• Publisher-owned property definitions via .well-known/adagents.json
• Comprehensive format specifications with asset requirements

​

Versioning and deprecation

​

Additional Resources

• Technical Changelog - CHANGELOG.md
• GitHub Releases - Release Archive
• Community - Slack
• Issues - GitHub Issues
• Support - support@adcontextprotocol.org