AdCP 3.1.13 · Trusted Match
context_match
context_match is an operation in the Trusted Match area of AdCP 3.1.13, flagged x-status: experimental in its own schema. Sent by publisher to router or provider to evaluate packages against contextual signals.
context_match request fields
The required column reflects the top-level required array only. 6 of the 16 request fields carry a top-level required flag: type, request_id, property_rid, property_type, placement_id, seller_agent_url. A top-level if, anyOf, oneOf or dependencies block can make an unmarked field mandatory in the mode being called, and a flat table cannot render
a rule that fires in one mode only. Those branches are visible in the request schema itself.
| Field | Type | Required | Description |
|---|---|---|---|
$schema | string | Optional schema URI for validation. | |
adcp_version | string | Release-precision AdCP version (VERSION.RELEASE, e.g. | |
adcp_major_version | integer | DEPRECATED in favor of adcp_version. | |
type | string | required | Message type discriminator for deserialization. |
protocol_version | string | TMP protocol version. | |
request_id | string | required | Unique request identifier. |
property_rid | string | required | Property catalog UUID (UUID v7). |
property_id | property-id | Publisher's human-readable property slug (e.g., 'cnn_homepage'). | |
property_type | property-type | required | Type of the publisher property One of: website, mobile_app, ctv_app, desktop_app, dooh, podcast, radio, linear_tv, streaming_audio, ai_assistant. |
placement_id | string | required | Placement identifier from the publisher's placement registry in adagents.json. |
seller_agent_url | string | required | API endpoint URL of the seller agent issuing this request. |
artifact | artifact | Full content artifact adjacent to this ad opportunity. | |
artifact_refs | object[] | Public content references adjacent to this ad opportunity. | |
geo | object | Coarse geographic location of the viewer. | |
context_signals | object | Pre-computed classifier outputs for the content environment. | |
package_ids | string[] | Restrict evaluation to specific packages. |
context_match reads. 30 of the 64 registered operations are flagged x-mutates-state and its request schema is not one of them, so repeating the call is side-effect free. AdCP's release notes describe x-mutates-state as a non-normative tooling
hint that agents do not validate, so it is the registry's classification of the operation rather than
a contract, and it is the only machine-readable answer in the registry to whether an operation is
safe to retry.
context_match response fields
The first 13 rows are the shared protocol envelope from core/version-envelope.json and core/protocol-envelope.json. Only 5 of the 18 rows below belong to context_match itself, beginning with type, request_id and offers. 4 fields in the whole response are marked required: status, type, request_id, offers.
| Field | Type | Required | Description |
|---|---|---|---|
adcp_version | string | Release-precision AdCP version (VERSION.RELEASE, e.g. | |
adcp_major_version | integer | DEPRECATED in favor of adcp_version (release-precision string). | |
context_id | string | Session/conversation identifier for tracking related operations across multiple task invocations. | |
context | context | Per-request opaque caller-supplied correlation object echoed unchanged in the response. | |
task_id | string | Unique identifier for tracking asynchronous operations. | |
status | task-status | required | Current task execution state. One of: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown. |
message | string | Human-readable summary of the task result. | |
timestamp | string | ISO 8601 timestamp when the response was generated. | |
replayed | boolean | Set to true when this response was returned from the idempotency cache rather than from a fresh execution. | |
adcp_error | error | Transport-envelope error signal for fatal task failures. | |
push_notification_config | push-notification-config | Push notification configuration for async task updates (A2A and REST protocols). | |
governance_context | string | Governance context token issued by the account's governance agent during check_governance. | |
payload | object | Conceptual grouping for the task-specific response data defined by individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). | |
type | string | required | Message type discriminator for deserialization. |
request_id | string | required | Echoed request identifier from the context match request |
offers | offer[] | required | Offers from the buyer, one per activated package. |
cache_ttl | integer | Optional override for the default 5-minute cache TTL, in seconds. | |
signals | object | Response-level targeting signals for ad server pass-through. |
The shared protocol envelope
62 of AdCP's 64 registered operations carry every one of the 13 envelope fields. report_plan_outcome and check_governance compose core/version-envelope.json only, so they carry the version pair and none of the task fields.
status resolves to enums/task-status.json, which admits nine values:
submitted, working, input-required, completed, canceled, failed, rejected, auth-required,
unknown. The envelope marks it required on every response, and a synchronous call emits completed rather than omitting it. When it returns submitted or working instead, task_id is the
polling handle and
push_notification_config is the webhook the agent echoes back to confirm the callback.
Webhooks are A2A and REST only: MCP sends progress notifications and defines no webhook.
payload appears in the response field table typed object. core/protocol-envelope.json describes it as a documentary construct and states that it is not a required wire field. Body fields
are siblings of the envelope fields: on MCP at the root of the tool response, on A2A in task.artifacts[0].parts[].DataPart, on REST at the root of the JSON body. An accessor that reads response.payload finds
nothing there.
Field lists are not published over the wire
AdCP's integration guide, docs/protocol/calling-an-agent.mdx, states that its MCP
servers no longer publish per-tool parameter schemas: a tools/list call returns an empty
properties object for every tool, and the guide directs clients not to infer shape from it. A client
author reads the schema registry instead of the tool list.
Frequently asked
- What does context_match do?
- Sent by publisher to router or provider to evaluate packages against contextual signals.
- Which fields does a context_match request require?
- 6 of the 16 request fields carry a top-level required flag: type, request_id, property_rid, property_type, placement_id, seller_agent_url. AdCP also constrains requests with top-level if/then, anyOf, oneOf and dependencies blocks that no required array captures, so an unmarked field can still be mandatory in the mode being called.
- Which AdCP version do these context_match field tables describe?
- AdCP 3.1.13, the current published release, last updated 2026-08-11. The documentation tree is versioned separately from the schema tree in the same repository, so a doc page and a schema file can describe the same field differently.