Module `adcp.types.protocol`

AdCP protocol types — curated partial surface.

Cross-cutting protocol types — request / response envelopes, errors, pagination, task status, capabilities, and webhook challenge handshakes.

A stable, narrow alternative to importing the whole :mod:adcp.types namespace. Every name here is also exported from :mod:adcp.types; this module simply groups the ones a protocol integration reaches for, and never exposes the internal generated layer.

This module is for curation and discoverability, not a separate performance tier: importing it is cheap, but the first access to any AdCP type (here or via :mod:adcp.types / :mod:adcp) realizes the full generated Pydantic graph — there is no per-domain graph. Use it for a smaller, focused import surface.

from adcp.types.protocol import Request

Classes

class AdcpProtocol (*args, **kwds)

Expand source code

class AdcpProtocol(StrEnum):
    media_buy = 'media-buy'
    signals = 'signals'
    governance = 'governance'
    creative = 'creative'
    brand = 'brand'
    sponsored_intelligence = 'sponsored-intelligence'
    measurement = 'measurement'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var brand
var creative
var governance
var measurement
var media_buy
var signals
var sponsored_intelligence

class AdcpVersionEnvelope (**data: Any)

Expand source code

class AdcpVersionEnvelope(AdCPBaseModel):
    adcp_version: Annotated[
        str | None,
        Field(
            description='Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer\'s release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release\'s schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.',
            examples=['3.0', '3.1', '3.1-beta', '3.1-rc.1'],
            pattern='^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?)?$',
        ),
    ] = None
    adcp_major_version: Annotated[
        SchemaInt | None,
        Field(
            deprecated=True,
            description="DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.",
            ge=1,
            le=99,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var adcp_major_version : int | None
var adcp_version : str | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AgentDeclarations (**data: Any)

Expand source code

class AgentDeclarations(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    async_adcp_versions: Annotated[
        list[AsyncAdcpVersion] | None,
        Field(
            description='AdCP minor versions, such as 3.2, whose asynchronous payload shapes (webhooks and other seller-initiated pushes) the caller can parse. The seller selects payload shapes from the accepted intersection; without a declaration the seller uses its advertised default.',
            max_length=8,
            min_length=1,
        ),
    ] = None
    webhook_signing_algorithms: Annotated[
        list[WebhookSigningAlgorithm] | None,
        Field(
            description="RFC 9421 webhook-signing algorithms the caller can verify. The accepted intersection with the seller's webhook_signing.algorithms MUST be non-empty when the caller has any active webhook subscriber; an empty intersection fails the sync request with UNSUPPORTED_FEATURE because delivery would be unverifiable.",
            min_length=1,
        ),
    ] = None
    experimental_features: Annotated[
        list[experimental_feature_id.ExperimentalFeatureId] | None,
        Field(
            description="Experimental feature identifiers, matching the seller's experimental_features vocabulary, that the caller opts into receiving in asynchronous payloads. Unknown identifiers are accepted and excluded from the intersection rather than rejected, so a caller can declare once across sellers with different surfaces.",
            max_length=32,
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var async_adcp_versions : list[AsyncAdcpVersion] | None
var experimental_features : list[ExperimentalFeatureId] | None
var model_config
var webhook_signing_algorithms : list[WebhookSigningAlgorithm] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AgentNotificationConfig (**data: Any)

Expand source code

class AgentNotificationConfig(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    subscriber_id: Annotated[
        str,
        Field(
            description="Buyer- or registry-supplied identifier for this agent-level subscription endpoint. This is the stable logical key within the authenticated caller's agent-level notification config set: re-sending the same subscriber_id replaces that caller's subscriber URL, event_types, authentication selector, and active flag rather than creating a duplicate. Echoed on every webhook payload so multi-subscriber consumers can route by endpoint. MUST be unique within the submitted `notification_configs[]` array.",
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    url: Annotated[
        AnyUrl,
        Field(
            description='Webhook endpoint URL. Same wire contract as `push-notification-config.url` and account-level `notification-config.url`: `format: "uri"`, no destination-port allowlist enforced by the protocol, SSRF protection via the IP-range check defined in docs/building/by-layer/L1/security.mdx#webhook-url-validation-ssrf. Sellers MUST validate URL syntax, HTTPS usage, hostname normalization, and reserved-range rejection when writing any config, including `active: false` configs. Sellers MUST complete an activation challenge or equivalent proof-of-control before treating a new or changed active subscriber as active.'
        ),
    ]
    event_types: Annotated[
        list[notification_type.NotificationType],
        Field(
            description="Notification types this subscriber wishes to receive on the registered `url`. Caller-anchored types (`capabilities.changed`, `principal.changed`) always fire principal-wide. Account-anchored types additionally require the explicit all_authorized_accounts acknowledgment. Account-anchored types (such as `creative.status_changed` or `account.change_recorded`) are also accepted here: each fire then covers only accounts the authenticated caller is authorized for at each delivery attempt — the subscription is standing, authorization is evaluated per attempt including retries, and losing account authority both stops new fires and suppresses queued retries carrying that account's data. Media-buy-anchored types are rejected on this surface; their per-buy cadence configuration stays on `push_notification_config`. Caller-level and account-level subscriptions to the same event are independent — both fire, and receivers dedupe by the event's logical `notification_id`.",
            min_length=1,
        ),
    ]
    all_authorized_accounts: Annotated[
        StrictBool | None,
        Field(
            description="Explicit scope acknowledgment required whenever event_types includes any account-anchored type: true states that this subscriber intentionally receives those events for every account the principal is authorized for at each delivery attempt. Subscribing an endpoint to all accounts is never implicit. Authorization is evaluated per delivery attempt, including retries: losing authority for an account suppresses queued retries carrying that account's data."
        ),
    ] = None
    include_future_event_types: Annotated[
        StrictBool | None,
        Field(
            description='When true, the seller also fires caller-eligible notification types added to the enum by later AdCP versions — but only types classified invalidation-only, whose payloads carry identifiers and a repair pointer rather than domain data. Payload-bearing types always require explicit enumeration in event_types; this flag never silently opts a caller into more-sensitive payloads. There is deliberately no wildcard event type. Receivers setting this MUST tolerate unknown notification_type values.'
        ),
    ] = False
    authentication: Annotated[
        Authentication | None,
        Field(
            deprecated=True,
            description="Legacy authentication selector. Same precedence and semantics as `push-notification-config.authentication` and account-level `notification-config.authentication`: presence opts the seller into Bearer or HMAC-SHA256 signing; absence selects the default RFC 9421 webhook profile keyed off the seller's brand.json `agents[]` JWKS. Deprecated; removed in AdCP 4.0. Credentials are write-only and MUST NOT be echoed on reads.",
        ),
    ] = None
    active: Annotated[
        StrictBool | None,
        Field(
            description='When false, the seller persists the configuration but suppresses fires. Use to pause a subscriber without losing the registration. Paused configs 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. Reactivation requires full SSRF validation with connect pinning plus proof-of-control for any tuple without current valid proof.'
        ),
    ] = True
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var active : bool | None
var all_authorized_accounts : bool | None
var authentication : Authentication | None
var event_types : list[NotificationType]
var ext : ExtensionObject | None
var include_future_event_types : bool | None
var model_config
var subscriber_id : str
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AgentNotificationConfigState (**data: Any)

Expand source code

class AgentNotificationConfigState(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    subscriber_id: Annotated[
        str, Field(max_length=64, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,64}$')
    ]
    url: AnyUrl
    event_types: Annotated[list[notification_type.NotificationType], Field(min_length=1)]
    all_authorized_accounts: Annotated[
        StrictBool | None,
        Field(description='Echoed scope acknowledgment for account-anchored event types.'),
    ] = None
    include_future_event_types: Annotated[
        StrictBool | None, Field(description='Echoed from the desired configuration when set.')
    ] = None
    authentication: Annotated[Authentication | None, Field(deprecated=True)] = None
    active: StrictBool | None = True
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var active : bool | None
var all_authorized_accounts : bool | None
var authentication : Authentication | None
var event_types : list[NotificationType]
var ext : ExtensionObject | None
var include_future_event_types : bool | None
var model_config
var subscriber_id : str
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AgentReportingDestinationState (**data: Any)

Expand source code

class AgentReportingDestinationState(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    destination_id: Annotated[
        str,
        Field(
            description='Caller-selected key echoed from the desired configuration.',
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    destination_ref: Annotated[
        str,
        Field(
            description='Seller-issued opaque immutable destination-generation reference bound to the stable authenticated principal and destination_id. Exact replays preserve it; a proof-bound coordinate or delivery-contract change creates a new reference. Possession does not authorize account access, and sellers MUST NOT resolve it across callers.',
            max_length=255,
            min_length=1,
        ),
    ]
    prior_destination_refs: Annotated[
        list[PriorDestinationRef] | None,
        Field(
            description='Retained superseded generation references for this destination_id, newest first, still resolvable for existing authorized account bindings and retained reporting history. Enumerable only by the owning principal. Suspension and revocation of the destination apply to these generations too.',
            max_length=32,
        ),
    ] = None
    state: Annotated[
        reporting_destination_setup_state.ReportingDestinationSetupState,
        Field(
            description='Validation and setup state; see the enum for the per-pattern ready definition.'
        ),
    ]
    configuration: Annotated[
        agent_reporting_destination.AgentReportingDestination,
        Field(
            description='Credential-free desired configuration currently associated with this destination reference.'
        ),
    ]
    setup: Annotated[
        Setup | None,
        Field(
            description='Closed, non-secret setup instruction. Human-readable messages are deliberately excluded; agents dispatch only the typed action and treat setup_url as an untrusted navigation target.'
        ),
    ] = None
    issues: Annotated[
        list[error.Error] | None,
        Field(
            description='Structured validation or setup issues. Messages and details are untrusted display data and MUST NOT be executed as instructions.',
            max_length=16,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var configuration : AgentReportingDestination1 | AgentReportingDestination2 | AgentReportingDestination3
var destination_id : str
var destination_ref : str
var issues : list[Error] | None
var model_config
var prior_destination_refs : list[PriorDestinationRef] | None
var setup : Setup | None
var state : ReportingDestinationSetupState

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Authentication (**data: Any)

Expand source code

class Authentication(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    schemes: Annotated[
        list[Literal['Bearer']],
        Field(
            description='The seller authenticates outbound check_governance calls with the registered Bearer credential. Other shared webhook authentication schemes are not valid for this agent-to-agent call.',
            max_length=1,
            min_length=1,
        ),
    ]
    credentials: Annotated[
        str, Field(description='Authentication credential (e.g., Bearer token).', min_length=32)
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var credentials : str
var model_config
var schemes : list[typing.Literal['Bearer']]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AuthenticationScheme (*args, **kwds)

Expand source code

class AuthenticationScheme(StrEnum):
    Bearer = 'Bearer'
    HMAC_SHA256 = 'HMAC-SHA256'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var Bearer
var HMAC_SHA256

class AuthorizationRequiredDetails (**data: Any)

Expand source code

class AuthorizationRequiredDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    required_connections: Annotated[
        list[downstream_connection_requirement.DownstreamConnectionRequirement] | None,
        Field(
            description='Complete set of downstream connections known to be required for the relevant product, format, or request.'
        ),
    ] = None
    missing_connections: Annotated[
        list[downstream_connection_requirement.DownstreamConnectionRequirement] | None,
        Field(
            description='Subset of downstream connections that blocked the current request. Sellers SHOULD populate this array when the caller needs to route a human through a connections flow. Entries with `status` of `missing`, `pending`, `expired`, or `revoked` MUST include either `provider` or `authorization_url` so the buyer can route the remediation unambiguously.'
        ),
    ] = None
    authorization_url: Annotated[
        AnyUrl | None,
        Field(
            description='General recovery URL when there is a single obvious authorization step or when the seller has its own connection-management page.'
        ),
    ] = None
    authorization_instructions: Annotated[
        str | None,
        Field(
            description='Human-readable recovery instructions. Use `missing_connections[].authorization_instructions` when instructions differ per downstream connection.'
        ),
    ] = None
    reference_authorization: Annotated[
        dict[str, Any] | None,
        Field(
            deprecated=True,
            description='Legacy or provider-specific authorization hint for the referenced object. Prefer `missing_connections[]` for new implementations.',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_instructions : str | None
var authorization_url : pydantic.networks.AnyUrl | None
var missing_connections : list[DownstreamConnectionRequirement] | None
var model_config
var reference_authorization : dict[str, typing.Any] | None
var required_connections : list[DownstreamConnectionRequirement] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalConfiguration (**data: Any)

Expand source code

class Configuration(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    notification_configs: Annotated[
        list[agent_notification_config.AgentNotificationConfig] | None,
        Field(
            description='Complete desired agent-level subscriber set. The same caller-scoping, proof-of-control, secret handling, and replacement rules as sync_agent_notification_configs apply.',
            max_length=16,
        ),
    ] = None
    reporting_destinations: Annotated[
        list[agent_reporting_destination.AgentReportingDestination] | None,
        Field(
            description='Complete desired reusable reporting destination set. Omitting a previously present destination_id revokes it, and [] revokes every destination: the seller halts new deliveries to all of its generations within the advertised suspension_interval_seconds and retains it as a retired generation for reporting history. Revocation does not delete caller-owned data already delivered. destination_id values MUST be unique.',
            max_length=64,
        ),
    ] = None
    declarations: Annotated[
        principal_declarations.AgentDeclarations | None,
        Field(
            description='Complete declared consumption facts for this principal record. A present object replaces the declared set wholesale; {} clears it; omission leaves it unchanged. The seller computes and returns the accepted intersection in state.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var declarations : AgentDeclarations | None
var model_config
var notification_configs : list[AgentNotificationConfig] | None
var reporting_destinations : list[AgentReportingDestination1 | AgentReportingDestination2 | AgentReportingDestination3] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ContextObject (**data: Any)

Expand source code

class ContextObject(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Error (**data: Any)

Expand source code

class Error(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    code: Annotated[
        str,
        Field(
            description='Error code for programmatic handling. The error-code vocabulary is open: `error.code` is wire-typed `string` (not a closed enum), the standard codes published in `enums/error-code.json` are documentary, and senders MAY emit codes outside that set (platform-specific codes, or codes introduced in a later AdCP version). Receivers MUST decode unknown codes — treat the response as well-formed, read `error.recovery` for the recovery classification, and fall back to `transient` when `recovery` is absent. See `error-handling.mdx#forward-compatible-decoding-normative` for the full forward-compat contract — this rule is what lets future maintenance lines ship new codes additively.',
            max_length=64,
            min_length=1,
        ),
    ]
    message: Annotated[str, Field(description='Human-readable error message')]
    buyer_reason: Annotated[
        BuyerReason | None,
        Field(
            description='Optional buyer-actionable classification of the failure. Use this when the enclosing error code or message is too coarse or contains producer-internal context that must not cross the buyer trust boundary. `code` reuses the comprehensive standard vocabulary and recovery classifications published in `enums/error-code.json`, including policy, governance, account, commercial, inventory, and creative failures. The wire field remains open for forward compatibility. `message` MUST be safe to show to the buyer and MUST NOT contain vendor identifiers, ad-server type names, internal object names, internal IDs, stack traces, or other producer-private implementation details. When present, the enclosing `error.recovery` MUST classify the buyer-actionable reason. If both the enclosing code and buyer reason are registered, their standard recovery classifications MUST agree with each other and with `error.recovery`; sellers MUST choose the closest compatible enclosing code rather than retain a conflicting upstream transport wrapper. One buyer_reason classifies one error object. If a rejection contains independently actionable failures from different classes, sellers MUST emit separate error objects or omit buyer_reason rather than select a misleading single class.'
        ),
    ] = None
    field: Annotated[
        str | None,
        Field(
            description="Field path associated with the error in JSONPath-lite format (e.g., 'packages[0].targeting'). When `issues[]` is also present, sellers MUST set this to `issues[0].pointer` translated from RFC 6901 to JSONPath-lite (e.g., '/packages/0/targeting' → 'packages[0].targeting') so pre-3.1 consumers reading `field` only get deterministic behavior. Will be deprecated in a future major version in favor of `issues[].pointer`."
        ),
    ] = None
    suggestion: Annotated[str | None, Field(description='Suggested fix for the error')] = None
    retry_after: Annotated[
        StrictFloat | None,
        Field(
            description='Seconds to wait before retrying the operation. AdCP 3.2 producers MUST emit an integer from 1 through 3600. The 3.x schema continues to accept finite fractional values for backward compatibility with earlier producers; consumers receiving one MUST round up to the next whole second before clamping so the retry is never scheduled earlier than intended. Non-finite values are treated as absent.',
            ge=1.0,
            le=3600.0,
        ),
    ] = None
    issues: Annotated[
        list[Issue] | None,
        Field(
            description='Structured list of validation failures. Primary use is `VALIDATION_ERROR`, where multi-field rejections are common and `field` (singular) cannot carry the full pointer map. MAY appear on other error codes that reject multiple fields at once. When `issues` is present, sellers MUST also populate `field` from `issues[0]` for backward compatibility with pre-3.1 consumers that read `field` only — translating the RFC 6901 `pointer` format to the JSONPath-lite format `field` uses (e.g., `/packages/0/targeting` → `packages[0].targeting`). MUST (not SHOULD) so consumers reading `field` get deterministic behavior across sellers — the cost is one line of dual-write per seller; the cost of SHOULD is a long tail of seller-A-vs-seller-B inconsistency. Future major versions will deprecate `field` in favor of `issues[].pointer`.'
        ),
    ] = None
    details: Annotated[
        dict[str, Any] | None,
        Field(
            description='Additional task-specific error details. Sellers MAY mirror `issues[]` here as `details.issues` for backward compatibility with pre-3.1 consumers reading from `details`; new consumers SHOULD prefer the top-level `issues` field.\n\n**Canonical rejection-set shape (3.1+).** When the error reports a rejected value against a closed set of accepted values (e.g., enum mismatch, unsupported pricing option, invalid signal id), sellers SHOULD use the canonical key `accepted_values: <array>` under `details` rather than seller-specific variants observed in the wild (`available`, `allowed`, `accepted_values` at the error root, etc.). The canonical shape:\n\n```json\n{\n  "code": "INVALID_PRICING_OPTION",\n  "message": "Pricing option not found: po_prism_abandoner_cpm",\n  "field": "pricing_option_id",\n  "details": {\n    "rejected_value": "po_prism_abandoner_cpm",\n    "accepted_values": ["po_prism_cart_cpm", "po_prism_view_cpm"]\n  }\n}\n```\n\n- `rejected_value` (optional): the offending value the buyer supplied, echoed for buyer-side diagnostic clarity (especially when the offending field is nested or transformed before validation).\n- `accepted_values` (optional): the closed set the seller would have accepted at this field on this call. Sellers MUST NOT enumerate the full ecosystem-wide accepted set if it differs from what\'s accepted for *this caller in this context* (account, brand, scope) — leaking ecosystem-wide accepted sets to a per-caller rejection turns the error into an enumeration oracle.\n\nThis is **SHOULD-level guidance**, not MUST: `details` remains `additionalProperties: true` and pre-3.1 sellers using `available` / `allowed` / `accepted_values` at the error root remain conformant. The canonical shape lets buyer-side diagnostic tooling (SDK runner hints, dashboards, error classifiers) reliably surface the accepted-set without per-seller pattern matching. SDKs SHOULD accept any of the legacy variants and normalize on read; the canonical shape is what new sellers and 3.1+ adopters should emit going forward.'
        ),
    ] = None
    recovery: Annotated[
        Recovery | None,
        Field(
            description='Agent recovery classification. transient: retry after delay (rate limit, service unavailable, timeout). correctable: fix the request and resend (invalid field, budget too low, creative rejected). terminal: requires human action (account suspended, payment required, account not found). AdCP 3.2 producers MUST populate `recovery` on every error; 3.1 producers SHOULD populate it. The shared 3.x schema intentionally does not add `recovery` to `required` so retained and live errors from earlier 3.x producers remain decodable. When `buyer_reason` is present, `recovery` is required and MUST classify that buyer-actionable reason. If the enclosing code and buyer reason are both registered, their standard recovery classifications MUST agree with each other and with this field. A receiver that does not recognize `error.code` (a newer code, or a platform-specific code) MUST still be able to classify the error from `recovery`. When a legacy error omits `recovery`, receivers use the registered classification for a known code and fall back to `transient` for an unknown code, subject to the bounded retry budget. The `enumMetadata.recovery` block in `enums/error-code.json` is the documentary mirror for known top-level and buyer-reason codes; `error.recovery` on the wire is authoritative when present.'
        ),
    ] = None
    source: Annotated[
        Source | None,
        Field(
            description='Who emitted this error entry. `producer` (default when absent): emitted by the response\'s authoring agent (the seller for `get_products`, the creative agent for `build_creative`, etc.). `sdk`: augmented by a consuming SDK that detected a non-fatal advisory condition on consumption (e.g., `FORMAT_PROJECTION_FAILED` when the buyer SDK couldn\'t project a v1 format to a canonical, or `FORMAT_DECLARATION_DIVERGENT` when the SDK detected a producer bug on read). SDK-augmented entries SHOULD also set `sdk_id` so downstream consumers can identify which intermediate processor inserted the entry.\n\n**Multi-hop propagation (normative).** AdCP is a federated agent network — responses commonly traverse multiple SDKs (e.g., sales agent → interchange → DSP → buyer). When an SDK augments `errors[]` with a consumption-detected entry, the augmented response carries the entry forward to subsequent hops. Each hop that detects the same condition independently SHOULD deduplicate by `(code, field)` rather than re-emit; the existing entry\'s `sdk_id` identifies which earlier processor saw it first. Producer entries (those without `source: "sdk"`) are authoritative for what the response\'s authoring agent self-detected; SDK entries are observations made on top.\n\n**Replay/audit safety.** Persisted or replayed responses carry `source` and `sdk_id` so the audit trail can distinguish seller-emitted entries from SDK-augmented ones. Without `source`, a downstream consumer can\'t tell whether a code came from the seller or an intermediate SDK, which corrupts attribution.'
        ),
    ] = None
    sdk_id: Annotated[
        str | None,
        Field(
            description='Optional identifier for the SDK that augmented this error entry. Format: `<sdk_package_name>@<version>` (e.g., `@adcontextprotocol/adcp@7.3.0`, `adcontextprotocol-adcp-python@1.2.0`). MUST be set when `source: "sdk"`; MUST be absent when `source: "producer"` or absent. Lets downstream consumers identify which intermediate processor inserted the entry, useful for debugging cross-SDK divergence (e.g., one SDK detects a projection failure that another SDK\'s registry version doesn\'t).'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

CatalogItemAvailabilityError

Class variables

var buyer_reason : BuyerReason | None
var code : str
var details : dict[str, typing.Any] | None
var field : str | None
var issues : list[Issue] | None
var message : str
var model_config
var recovery : Recovery | None
var retry_after : float | None
var sdk_id : str | None
var source : Source | None
var suggestion : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ErrorCode (*args, **kwds)

Expand source code

class ErrorCode(StrEnum):
    INVALID_REQUEST = 'INVALID_REQUEST'
    AUTH_REQUIRED = 'AUTH_REQUIRED'
    AUTH_MISSING = 'AUTH_MISSING'
    AUTH_INVALID = 'AUTH_INVALID'
    AUTHORIZATION_REQUIRED = 'AUTHORIZATION_REQUIRED'
    RATE_LIMITED = 'RATE_LIMITED'
    SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE'
    CONFIGURATION_ERROR = 'CONFIGURATION_ERROR'
    POLICY_VIOLATION = 'POLICY_VIOLATION'
    PRODUCT_NOT_FOUND = 'PRODUCT_NOT_FOUND'
    PRODUCT_UNAVAILABLE = 'PRODUCT_UNAVAILABLE'
    PROPOSAL_EXPIRED = 'PROPOSAL_EXPIRED'
    BUDGET_TOO_LOW = 'BUDGET_TOO_LOW'
    CREATIVE_REJECTED = 'CREATIVE_REJECTED'
    CREATIVE_SIZE_MISMATCH = 'CREATIVE_SIZE_MISMATCH'
    CREATIVE_MISSING_CLICK_URL = 'CREATIVE_MISSING_CLICK_URL'
    CREATIVE_VALIDATION_FAILED_GENERIC = 'CREATIVE_VALIDATION_FAILED_GENERIC'
    CREATIVE_LOCALE_NOT_ACCEPTED = 'CREATIVE_LOCALE_NOT_ACCEPTED'
    CREATIVE_VALUE_NOT_ALLOWED = 'CREATIVE_VALUE_NOT_ALLOWED'
    CREATIVE_REVISION_CONTENT_MISMATCH = 'CREATIVE_REVISION_CONTENT_MISMATCH'
    UNSUPPORTED_FEATURE = 'UNSUPPORTED_FEATURE'
    UNPRICEABLE_OUTPUT = 'UNPRICEABLE_OUTPUT'
    UNSUPPORTED_GRANULARITY = 'UNSUPPORTED_GRANULARITY'
    UNSUPPORTED_PROVISIONING = 'UNSUPPORTED_PROVISIONING'
    AUDIENCE_TOO_SMALL = 'AUDIENCE_TOO_SMALL'
    ACCOUNT_REQUIRED = 'ACCOUNT_REQUIRED'
    ACCOUNT_NOT_FOUND = 'ACCOUNT_NOT_FOUND'
    ACCOUNT_MOVED = 'ACCOUNT_MOVED'
    ACCOUNT_IDENTITY_CONFLICT = 'ACCOUNT_IDENTITY_CONFLICT'
    ACCOUNT_SETUP_REQUIRED = 'ACCOUNT_SETUP_REQUIRED'
    ACCOUNT_AMBIGUOUS = 'ACCOUNT_AMBIGUOUS'
    ACCOUNT_PAYMENT_REQUIRED = 'ACCOUNT_PAYMENT_REQUIRED'
    ACCOUNT_SUSPENDED = 'ACCOUNT_SUSPENDED'
    COMPLIANCE_UNSATISFIED = 'COMPLIANCE_UNSATISFIED'
    GOVERNANCE_DENIED = 'GOVERNANCE_DENIED'
    BUDGET_EXHAUSTED = 'BUDGET_EXHAUSTED'
    BUDGET_EXCEEDED = 'BUDGET_EXCEEDED'
    BUDGET_CAP_REACHED = 'BUDGET_CAP_REACHED'
    CONFLICT = 'CONFLICT'
    COMMITTED_RESOURCE_PURGED = 'COMMITTED_RESOURCE_PURGED'
    IDEMPOTENCY_CONFLICT = 'IDEMPOTENCY_CONFLICT'
    IDEMPOTENCY_EXPIRED = 'IDEMPOTENCY_EXPIRED'
    IDEMPOTENCY_IN_FLIGHT = 'IDEMPOTENCY_IN_FLIGHT'
    CURSOR_EXPIRED = 'CURSOR_EXPIRED'
    CREATIVE_DEADLINE_EXCEEDED = 'CREATIVE_DEADLINE_EXCEEDED'
    CREATIVE_INACCESSIBLE = 'CREATIVE_INACCESSIBLE'
    INVALID_STATE = 'INVALID_STATE'
    MEDIA_BUY_NOT_FOUND = 'MEDIA_BUY_NOT_FOUND'
    NOT_CANCELLABLE = 'NOT_CANCELLABLE'
    PACKAGE_NOT_FOUND = 'PACKAGE_NOT_FOUND'
    PLACE_TARGET_UNAVAILABLE = 'PLACE_TARGET_UNAVAILABLE'
    CREATIVE_NOT_FOUND = 'CREATIVE_NOT_FOUND'
    SIGNAL_NOT_FOUND = 'SIGNAL_NOT_FOUND'
    SIGNAL_TARGETING_INCOMPATIBLE = 'SIGNAL_TARGETING_INCOMPATIBLE'
    SESSION_NOT_FOUND = 'SESSION_NOT_FOUND'
    PLAN_NOT_FOUND = 'PLAN_NOT_FOUND'
    REFERENCE_NOT_FOUND = 'REFERENCE_NOT_FOUND'
    SESSION_TERMINATED = 'SESSION_TERMINATED'
    VALIDATION_ERROR = 'VALIDATION_ERROR'
    PRODUCT_EXPIRED = 'PRODUCT_EXPIRED'
    PROPOSAL_NOT_COMMITTED = 'PROPOSAL_NOT_COMMITTED'
    PROPOSAL_NOT_FOUND = 'PROPOSAL_NOT_FOUND'
    MULTI_FINALIZE_UNSUPPORTED = 'MULTI_FINALIZE_UNSUPPORTED'
    IO_REQUIRED = 'IO_REQUIRED'
    TERMS_REJECTED = 'TERMS_REJECTED'
    BIDDING_PLACEMENT_CONFLICT = 'BIDDING_PLACEMENT_CONFLICT'
    AMBIGUOUS_BIDDING_POLICY = 'AMBIGUOUS_BIDDING_POLICY'
    CONFLICTING_SELECTORS = 'CONFLICTING_SELECTORS'
    REQUOTE_REQUIRED = 'REQUOTE_REQUIRED'
    VERSION_UNSUPPORTED = 'VERSION_UNSUPPORTED'
    CAMPAIGN_SUSPENDED = 'CAMPAIGN_SUSPENDED'
    GOVERNANCE_UNAVAILABLE = 'GOVERNANCE_UNAVAILABLE'
    GOVERNANCE_AGENT_NOT_ACCEPTED = 'GOVERNANCE_AGENT_NOT_ACCEPTED'
    PERMISSION_DENIED = 'PERMISSION_DENIED'
    SCOPE_INSUFFICIENT = 'SCOPE_INSUFFICIENT'
    READ_ONLY_SCOPE = 'READ_ONLY_SCOPE'
    FIELD_NOT_PERMITTED = 'FIELD_NOT_PERMITTED'
    PROVENANCE_REQUIRED = 'PROVENANCE_REQUIRED'
    PROVENANCE_DIGITAL_SOURCE_TYPE_MISSING = 'PROVENANCE_DIGITAL_SOURCE_TYPE_MISSING'
    PROVENANCE_SYNTHETIC_DEPICTION_MISSING = 'PROVENANCE_SYNTHETIC_DEPICTION_MISSING'
    PROVENANCE_DISCLOSURE_MISSING = 'PROVENANCE_DISCLOSURE_MISSING'
    PROVENANCE_EMBEDDED_MISSING = 'PROVENANCE_EMBEDDED_MISSING'
    PROVENANCE_VERIFIER_NOT_ACCEPTED = 'PROVENANCE_VERIFIER_NOT_ACCEPTED'
    PROVENANCE_CLAIM_CONTRADICTED = 'PROVENANCE_CLAIM_CONTRADICTED'
    EVALUATOR_AGENT_NOT_ACCEPTED = 'EVALUATOR_AGENT_NOT_ACCEPTED'
    BILLING_NOT_SUPPORTED = 'BILLING_NOT_SUPPORTED'
    BILLING_NOT_PERMITTED_FOR_AGENT = 'BILLING_NOT_PERMITTED_FOR_AGENT'
    BILLING_OUT_OF_BAND = 'BILLING_OUT_OF_BAND'
    PAYMENT_TERMS_NOT_SUPPORTED = 'PAYMENT_TERMS_NOT_SUPPORTED'
    BRAND_REQUIRED = 'BRAND_REQUIRED'
    AGENT_SUSPENDED = 'AGENT_SUSPENDED'
    AGENT_BLOCKED = 'AGENT_BLOCKED'
    CREDENTIAL_IN_ARGS = 'CREDENTIAL_IN_ARGS'
    ACTION_NOT_ALLOWED = 'ACTION_NOT_ALLOWED'
    PRIVATE_FIELD_IN_PUBLIC_PLACEMENT = 'PRIVATE_FIELD_IN_PUBLIC_PLACEMENT'
    FORMAT_PROJECTION_FAILED = 'FORMAT_PROJECTION_FAILED'
    FORMAT_DECLARATION_DIVERGENT = 'FORMAT_DECLARATION_DIVERGENT'
    FORMAT_SHAPE_PROMOTED = 'FORMAT_SHAPE_PROMOTED'
    FORMAT_DECLARATION_V1_AMBIGUOUS = 'FORMAT_DECLARATION_V1_AMBIGUOUS'
    FORMAT_OPTION_UNRESOLVED = 'FORMAT_OPTION_UNRESOLVED'
    FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE = 'FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE'
    FORMAT_NOT_SUPPORTED = 'FORMAT_NOT_SUPPORTED'
    PIXEL_TRACKER_LOSSY_DOWNGRADE = 'PIXEL_TRACKER_LOSSY_DOWNGRADE'
    PIXEL_TRACKER_UPGRADE_INFERRED = 'PIXEL_TRACKER_UPGRADE_INFERRED'
    STALE_RESPONSE = 'STALE_RESPONSE'
    FEED_FETCH_FAILED = 'FEED_FETCH_FAILED'
    SOURCE_ACCESS_FAILED = 'SOURCE_ACCESS_FAILED'
    INVALID_FEED_FORMAT = 'INVALID_FEED_FORMAT'
    ITEM_VALIDATION_FAILED = 'ITEM_VALIDATION_FAILED'
    CATALOG_LIMIT_EXCEEDED = 'CATALOG_LIMIT_EXCEEDED'
    INVALID_PRICING_OPTION = 'INVALID_PRICING_OPTION'
    INVALID_USAGE_DATA = 'INVALID_USAGE_DATA'
    SIGNED_RESPONSE_ENVELOPE_EXPIRED = 'SIGNED_RESPONSE_ENVELOPE_EXPIRED'
    SIGNED_RESPONSE_REQUEST_HASH_MISMATCH = 'SIGNED_RESPONSE_REQUEST_HASH_MISMATCH'
    SIGNED_RESPONSE_TENANT_MISMATCH = 'SIGNED_RESPONSE_TENANT_MISMATCH'
    VAST_PARSE_FAILED = 'VAST_PARSE_FAILED'
    VAST_VERSION_MISMATCH = 'VAST_VERSION_MISMATCH'
    VAST_WRAPPER_DEPTH_EXCEEDED = 'VAST_WRAPPER_DEPTH_EXCEEDED'
    CREATIVE_REPRESENTATION_UNRESOLVED = 'CREATIVE_REPRESENTATION_UNRESOLVED'
    MACRO_RESOLUTION_FAILED = 'MACRO_RESOLUTION_FAILED'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var ACCOUNT_AMBIGUOUS
var ACCOUNT_IDENTITY_CONFLICT
var ACCOUNT_MOVED
var ACCOUNT_NOT_FOUND
var ACCOUNT_PAYMENT_REQUIRED
var ACCOUNT_REQUIRED
var ACCOUNT_SETUP_REQUIRED
var ACCOUNT_SUSPENDED
var ACTION_NOT_ALLOWED
var AGENT_BLOCKED
var AGENT_SUSPENDED
var AMBIGUOUS_BIDDING_POLICY
var AUDIENCE_TOO_SMALL
var AUTHORIZATION_REQUIRED
var AUTH_INVALID
var AUTH_MISSING
var AUTH_REQUIRED
var BIDDING_PLACEMENT_CONFLICT
var BILLING_NOT_PERMITTED_FOR_AGENT
var BILLING_NOT_SUPPORTED
var BILLING_OUT_OF_BAND
var BRAND_REQUIRED
var BUDGET_CAP_REACHED
var BUDGET_EXCEEDED
var BUDGET_EXHAUSTED
var BUDGET_TOO_LOW
var CAMPAIGN_SUSPENDED
var CATALOG_LIMIT_EXCEEDED
var COMMITTED_RESOURCE_PURGED
var COMPLIANCE_UNSATISFIED
var CONFIGURATION_ERROR
var CONFLICT
var CONFLICTING_SELECTORS
var CREATIVE_DEADLINE_EXCEEDED
var CREATIVE_INACCESSIBLE
var CREATIVE_LOCALE_NOT_ACCEPTED
var CREATIVE_MISSING_CLICK_URL
var CREATIVE_NOT_FOUND
var CREATIVE_REJECTED
var CREATIVE_REPRESENTATION_UNRESOLVED
var CREATIVE_REVISION_CONTENT_MISMATCH
var CREATIVE_SIZE_MISMATCH
var CREATIVE_VALIDATION_FAILED_GENERIC
var CREATIVE_VALUE_NOT_ALLOWED
var CREDENTIAL_IN_ARGS
var CURSOR_EXPIRED
var EVALUATOR_AGENT_NOT_ACCEPTED
var FEED_FETCH_FAILED
var FIELD_NOT_PERMITTED
var FORMAT_DECLARATION_DIVERGENT
var FORMAT_DECLARATION_V1_AMBIGUOUS
var FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE
var FORMAT_NOT_SUPPORTED
var FORMAT_OPTION_UNRESOLVED
var FORMAT_PROJECTION_FAILED
var FORMAT_SHAPE_PROMOTED
var GOVERNANCE_AGENT_NOT_ACCEPTED
var GOVERNANCE_DENIED
var GOVERNANCE_UNAVAILABLE
var IDEMPOTENCY_CONFLICT
var IDEMPOTENCY_EXPIRED
var IDEMPOTENCY_IN_FLIGHT
var INVALID_FEED_FORMAT
var INVALID_PRICING_OPTION
var INVALID_REQUEST
var INVALID_STATE
var INVALID_USAGE_DATA
var IO_REQUIRED
var ITEM_VALIDATION_FAILED
var MACRO_RESOLUTION_FAILED
var MEDIA_BUY_NOT_FOUND
var MULTI_FINALIZE_UNSUPPORTED
var NOT_CANCELLABLE
var PACKAGE_NOT_FOUND
var PAYMENT_TERMS_NOT_SUPPORTED
var PERMISSION_DENIED
var PIXEL_TRACKER_LOSSY_DOWNGRADE
var PIXEL_TRACKER_UPGRADE_INFERRED
var PLACE_TARGET_UNAVAILABLE
var PLAN_NOT_FOUND
var POLICY_VIOLATION
var PRIVATE_FIELD_IN_PUBLIC_PLACEMENT
var PRODUCT_EXPIRED
var PRODUCT_NOT_FOUND
var PRODUCT_UNAVAILABLE
var PROPOSAL_EXPIRED
var PROPOSAL_NOT_COMMITTED
var PROPOSAL_NOT_FOUND
var PROVENANCE_CLAIM_CONTRADICTED
var PROVENANCE_DIGITAL_SOURCE_TYPE_MISSING
var PROVENANCE_DISCLOSURE_MISSING
var PROVENANCE_EMBEDDED_MISSING
var PROVENANCE_REQUIRED
var PROVENANCE_SYNTHETIC_DEPICTION_MISSING
var PROVENANCE_VERIFIER_NOT_ACCEPTED
var RATE_LIMITED
var READ_ONLY_SCOPE
var REFERENCE_NOT_FOUND
var REQUOTE_REQUIRED
var SCOPE_INSUFFICIENT
var SERVICE_UNAVAILABLE
var SESSION_NOT_FOUND
var SESSION_TERMINATED
var SIGNAL_NOT_FOUND
var SIGNAL_TARGETING_INCOMPATIBLE
var SIGNED_RESPONSE_ENVELOPE_EXPIRED
var SIGNED_RESPONSE_REQUEST_HASH_MISMATCH
var SIGNED_RESPONSE_TENANT_MISMATCH
var SOURCE_ACCESS_FAILED
var STALE_RESPONSE
var TERMS_REJECTED
var UNPRICEABLE_OUTPUT
var UNSUPPORTED_FEATURE
var UNSUPPORTED_GRANULARITY
var UNSUPPORTED_PROVISIONING
var VALIDATION_ERROR
var VAST_PARSE_FAILED
var VAST_VERSION_MISMATCH
var VAST_WRAPPER_DEPTH_EXCEEDED
var VERSION_UNSUPPORTED

class ExtensionObject (**data: Any)

Expand source code

class ExtensionObject(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetAdcpCapabilitiesRequest (**data: Any)

Expand source code

class GetAdcpCapabilitiesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    protocols: Annotated[
        list[Protocol] | None,
        Field(
            description='Specific protocols to query capabilities for. If omitted, returns capabilities for all supported protocols.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The request message of a task in the pinned bundle's task registry.

A consumer holding one can resolve its account, decide at-most-once, echo its context and negotiate version – the whole transport-boundary job – before knowing which tool it is. issubclass(model, AdcpRequest) is the registration-time proof that a model is spec-derived rather than a hand-written parallel: a field test passes for a forged model, descent does not.

Each accessor returns the field's value, or None when this tool's schema declares no such field. Only 49 of the 87 request schemas declare an account and only 43 an idempotency_key, so asking the request is what replaces getattr(req, "account", None) against Any at the boundary.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpRequest
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var protocols : list[Protocol] | None

Inherited members

AdcpRequest:
- get_account
- get_adcp_major_version
- get_adcp_version
- get_context
- get_idempotency_key
- get_push_notification_config
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class GetAdcpCapabilitiesResponse (**data: Any)

Expand source code

class GetAdcpCapabilitiesResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp: Annotated[Adcp, Field(description='Core AdCP protocol information')]
    supported_protocols: Annotated[
        list[SupportedProtocol],
        Field(
            description='AdCP protocols this agent supports. Stable values both (a) declare which tools the agent implements and (b) commit the agent to pass the baseline compliance storyboard at /compliance/{version}/protocols/{protocol}/ (with snake_case → kebab-case path mapping, e.g. media_buy → /compliance/.../protocols/media-buy/). The `measurement` protocol is experimental and currently covers provider catalog/output declaration (`measurement.core`) and buyer-orchestrator interchange gateways (`measurement.gateway`). Measurement agents exchange delivery and feedback with the gateway rather than receiving direct seller access. Additional provider tasks and a baseline storyboard land only when concrete workflows require them. Compliance testing support is declared separately via the `compliance_testing` capability block (below), not as a protocol claim.',
            min_length=1,
        ),
    ]
    account: Annotated[
        Account | None,
        Field(
            description='Account management capabilities. Describes how accounts are established, what billing models are supported, and whether an account is required before browsing products.'
        ),
    ] = None
    media_buy: Annotated[
        MediaBuy | None,
        Field(
            description='Media-buy protocol capabilities. Expected when media_buy is in supported_protocols. Sellers declaring media_buy should also include account with supported_billing.'
        ),
    ] = None
    signals: Annotated[
        Signals | None,
        Field(
            description='Signals protocol capabilities. Only present if signals is in supported_protocols.'
        ),
    ] = None
    governance: Annotated[
        Governance | None,
        Field(
            description='Governance protocol capabilities. Only present if governance is in supported_protocols. Governance agents provide property and creative data like compliance scores, brand safety ratings, sustainability metrics, and creative quality assessments.'
        ),
    ] = None
    sponsored_intelligence: Annotated[
        SponsoredIntelligence | None,
        Field(
            description='Sponsored Intelligence protocol capabilities. Only present if sponsored_intelligence is in supported_protocols. SI agents handle conversational brand experiences.'
        ),
    ] = None
    brand: Annotated[
        Brand | None,
        Field(
            description='Brand protocol capabilities. Only present if brand is in supported_protocols. Brand agents provide identity data (logos, colors, tone, assets) and optionally rights clearance for licensable content (talent, music, stock media).'
        ),
    ] = None
    creative: Annotated[
        Creative | None,
        Field(
            description='Creative protocol capabilities. Only present if creative is in supported_protocols.'
        ),
    ] = None
    oauth: Annotated[
        Oauth | None,
        Field(
            description='Introduced in AdCP 3.2. OAuth 2.0 protected-resource support for inbound transport authentication. This is a capability claim, not a requirement that every caller use OAuth: `supported: true` means the agent publishes RFC 9728 protected-resource metadata for its advertised endpoint and RFC 8414 metadata for every referenced authorization server, and opts into the universal `oauth_setup` conformance storyboard. Agents that use only static Bearer, Basic, mTLS, or RFC 9421 authentication omit this block or declare `supported: false`. Operator credential acquisition remains separately described by `account.authorization_endpoint` when applicable.'
        ),
    ] = None
    request_signing: Annotated[
        RequestSigning | None,
        Field(
            description='RFC 9421 HTTP Signatures support for incoming requests. Signing remains optional through 3.2, but every accepted 3.2 signature on a request with a body MUST cover content-digest. Request signing becomes required for spend-committing operations in 4.0. The full profile is defined in docs/building/by-layer/L1/security.mdx (Signed Requests (Transport Layer)).'
        ),
    ] = None
    webhook_signing: Annotated[
        WebhookSigning | None,
        Field(
            description='RFC 9421 webhook-signature and delivery-retry support for outbound webhook callbacks (top-level peer of request_signing). Declares which AdCP webhook-signing profile version and algorithms this agent produces on delivery, whether it supports the legacy HMAC-SHA256 fallback for receivers that have not yet adopted RFC 9421, and the maximum retry horizon receivers use to retain immutable delivery evidence. See docs/building/by-layer/L3/webhooks.mdx.'
        ),
    ] = None
    identity: Annotated[
        Identity | None,
        Field(
            description='Operator identity posture — trust-root pointer (`brand_json_url`) plus key-scoping and compromise-response controls the agent operates. `brand_json_url` is **load-bearing** for signature verification: when the agent declares any signing posture (`request_signing.supported_for`/`required_for` non-empty, `webhook_signing.supported === true`, or any `key_origins` subfield), `brand_json_url` MUST be present (storyboard-enforced in 3.x; schema-required in 4.0). Verifiers use it to bootstrap from the agent URL to the operator\'s brand.json (and from there to signing keys); see [security.mdx §Discovering an agent\'s signing keys](https://adcontextprotocol.org/docs/building/by-layer/L1/security#discovering-an-agents-signing-keys-via-brand_json_url). The remaining fields (`per_principal_key_isolation`, `key_origins`, `compromise_notification`) are advisory and receivers use them to reason about blast radius and revocation latency at onboarding. Empty-object semantics: `identity: {}` means "posture block present but no posture claimed" — schema-valid but advisory-neutral and receivers MUST treat it as equivalent to omitting the block, **except** that an agent declaring a signing posture elsewhere in the response with an empty `identity` MUST be rejected by storyboard runners as missing `brand_json_url`.'
        ),
    ] = None
    measurement_gateway: Annotated[
        MeasurementGateway | None,
        Field(
            description='Buyer-controlled task gateway between an orchestrator and measurement providers. In the first experimental tier, providers read buyer-approved cross-seller delivery through get_media_buy_delivery and return compact assertions through provide_performance_feedback, without receiving seller credentials. Orchestrators implementing this block MUST include measurement in supported_protocols and measurement.gateway in experimental_features; this gateway role does not claim the media_buy seller protocol.'
        ),
    ] = None
    measurement: Annotated[
        Measurement | None,
        Field(
            description="Experimental measurement capability block. Presence indicates this agent computes one or more quantitative metrics about ad delivery, exposure, or effect, and is willing to be discovered as a measurement vendor. Agents implementing this block MUST list `measurement.core` in experimental_features. Returns metric definitions and whether the provider produces compact performance feedback, not pricing/coverage (negotiated via `measurement_terms` on `create_media_buy`) or raw/live datasets. Per-buy vendor values remain on delivery reports; optimizer-ready projections use provide_performance_feedback. AgenticAdvertising.org crawls each measurement agent's `metrics[]` on a TTL to populate the federated cross-vendor index."
        ),
    ] = None
    compliance_testing: Annotated[
        ComplianceTesting | None,
        Field(
            description="Compliance testing capabilities. The presence of this block declares that the agent supports deterministic testing via comply_test_controller for lifecycle state machine validation. Omit the block entirely if the agent does not support compliance testing. Sellers SHOULD list every canonical controller scenario they implement so buyers and runners can distinguish full deterministic coverage from partial coverage without probing each scenario one by one; the runtime source of truth remains comply_test_controller with scenario: 'list_scenarios'."
        ),
    ] = None
    specialisms: Annotated[
        list[specialism.AdcpSpecialism] | None,
        Field(
            description="Optional — specialized compliance claims this agent supports. Values MUST be kebab-case enum IDs (e.g., 'creative-generative', 'sales-non-guaranteed'). An agent that implements a specialism's tools but omits its ID from this array will receive 'No applicable tracks found' from the compliance runner — tracks for that specialism are not evaluated even if every tool works. Omitting the field means the agent declares no specialism claims (it still passes the universal + domain-baseline storyboards implied by supported_protocols). Each specialism maps to a storyboard bundle at /compliance/{version}/specialisms/{id}/ that the AAO compliance runner executes to verify the claim. Each specialism rolls up to one of the protocols in supported_protocols — the runner rejects a specialism claim whose parent protocol is missing. Only list specialisms your agent actually implements — the AAO Verified badge enumerates which specialisms were demonstrably passed."
        ),
    ] = None
    extensions_supported: Annotated[
        list[ExtensionsSupportedItem] | None,
        Field(
            description='Extension namespaces this agent supports. Buyers can expect meaningful data in ext.{namespace} fields on responses from this agent. Extension schemas are published in the AdCP extension registry.'
        ),
    ] = None
    experimental_features: Annotated[
        list[experimental_feature_id.ExperimentalFeatureId] | None,
        Field(
            description='Experimental AdCP surfaces this agent implements. A surface is experimental when its schema carries x-status: experimental and the working group has not yet frozen it. Sellers that implement any experimental surface MUST list its feature id here. Buyers inspect this array before relying on experimental surfaces — a seller that does not list a surface is asserting it does not implement it. Experimental surfaces MAY break between any two 3.x releases with at least 6 weeks notice; the full contract is in docs/reference/experimental-status.'
        ),
    ] = None
    wholesale_feed_versioning: Annotated[
        WholesaleFeedVersioning | None,
        Field(
            description="Conditional-fetch token capabilities for get_products and get_signals. Independent of wholesale feed webhooks: an agent MAY support cheap version probes via if_wholesale_feed_version without pushing change payloads (and vice versa). When supported is true, the agent returns wholesale_feed_version on every get_products / get_signals response and honors if_wholesale_feed_version on subsequent requests. When absent or supported is false, callers MAY still send if_wholesale_feed_version — pre-3.1 agents that ignore it just return the full payload (correct, just inefficient). Pre-flight declaration here lets buyers fast-path which agents to bother caching versions for. See get_products / get_signals 'Wholesale feed versioning' sections."
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp of when capabilities were last updated. Buyers can use this for cache invalidation.'
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None, Field(description='Task-specific errors and warnings')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    wholesale_feed_webhooks: Annotated[
        WholesaleFeedWebhooks | None,
        Field(
            description='Per-agent wholesale product-feed and wholesale signals-feed webhook capabilities. Consumers register durable sync_accounts notification subscribers and receive actual product.*, signal.*, or wholesale_feed.bulk_change payloads without polling. Product mirrors bootstrap and repair through list_products(if_feed_version); signal mirrors use get_signals(if_wholesale_feed_version). Deprecated wholesale get_products remains the 3.x product compatibility path. Webhook emission MUST apply the same caller/account authorization and cache-scope predicate as the corresponding read.'
        ),
    ] = None

The response message of a task in the pinned bundle's task registry.

A consumer holding one can route on task state, pick up an async task_id, split envelope from payload and log uniformly, before knowing which tool answered. Which makes one generic poll-to-terminal loop possible for all 77 tasks, where today each arm has no common type at all.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : Account | None
var adcp : Adcp
var brand : Brand | None
var compliance_testing : ComplianceTesting | None
var context : ContextObject | None
var creative : Creative | None
var errors : list[Error] | None
var experimental_features : list[ExperimentalFeatureId] | None
var ext : ExtensionObject | None
var extensions_supported : list[ExtensionsSupportedItem] | None
var governance : Governance | None
var identity : Identity | None
var last_updated : pydantic.types.AwareDatetime | None
var measurement : Measurement | None
var measurement_gateway : MeasurementGateway | None
var media_buy : MediaBuy | None
var model_config
var oauth : Oauth | None
var request_signing : RequestSigning | None
var signals : Signals | None
var specialisms : list[AdcpSpecialism] | None
var sponsored_intelligence : SponsoredIntelligence | None
var supported_protocols : list[SupportedProtocol]
var webhook_signing : WebhookSigning | None
var wholesale_feed_versioning : WholesaleFeedVersioning | None
var wholesale_feed_webhooks : WholesaleFeedWebhooks | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class GetPrincipalRequest (**data: Any)

Expand source code

class GetPrincipalRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The request message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpRequest
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var ext : ExtensionObject | None
var model_config

Inherited members

AdcpRequest:
- get_account
- get_adcp_major_version
- get_adcp_version
- get_context
- get_idempotency_key
- get_push_notification_config
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class GetPrincipalResponse (**data: Any)

Expand source code

class GetPrincipalResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    result: Result6 | Result7 | Result | Result9
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var result : Result6 | Result7 | Result | Result9

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class GetTaskStatusRequest (**data: Any)

Expand source code

class GetTaskStatusRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    task_id: Annotated[str, Field(description='Unique identifier of the task to retrieve')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account scope for the task lookup. Sellers MUST return REFERENCE_NOT_FOUND for a task_id that exists only under a different account or principal. When omitted, the seller MAY use the credential-bound singleton account, but multi-account credentials SHOULD require an explicit account.'
        ),
    ] = None
    include_history: Annotated[
        StrictBool | None,
        Field(
            description='Include full conversation history for this task (may increase response size)'
        ),
    ] = False
    include_result: Annotated[
        StrictBool | None,
        Field(
            description="Include the task's canonical terminal result payload when one exists. Defaults to false for lightweight status-only polls. When true, sellers MUST include result for completed, failed, or rejected terminal tasks when that task produced a terminal artifact; canceled tasks may have no result. The legacy singular error field remains a convenience for failed tasks but does not replace the canonical terminal result."
        ),
    ] = False
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The request message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpRequest
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference1 | AccountReference2 | None
var context : ContextObject | None
var ext : ExtensionObject | None
var include_history : bool | None
var include_result : bool | None
var model_config
var task_id : str

Inherited members

AdcpRequest:
- get_account
- get_adcp_major_version
- get_adcp_version
- get_context
- get_idempotency_key
- get_push_notification_config
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class GetTaskStatusResponse (**data: Any)

Expand source code

class GetTaskStatusResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    task_id: Annotated[str, Field(description='Unique identifier for this task')]
    task_type: Annotated[task_type_1.TaskType, Field(description='Type of AdCP operation')]
    protocol: Annotated[
        adcp_protocol.AdcpProtocol, Field(description='AdCP protocol this task belongs to')
    ]
    status: Annotated[task_status.TaskStatus, Field(description='Current task status')]
    created_at: Annotated[
        AwareDatetime, Field(description='When the task was initially created (ISO 8601)')
    ]
    updated_at: Annotated[
        AwareDatetime, Field(description='When the task was last updated (ISO 8601)')
    ]
    completed_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When the task completed (ISO 8601, only for completed/failed/canceled tasks)'
        ),
    ] = None
    has_webhook: Annotated[
        StrictBool | None, Field(description='Whether this task has webhook configuration')
    ] = None
    progress: Annotated[
        Progress | None, Field(description='Progress information for long-running tasks')
    ] = None
    error: Annotated[
        Error | None,
        Field(
            description='Convenience summary for failed tasks. When include_result was true and the canonical terminal result is also present, this error MUST agree with the canonical fatal error in result. A legacy poll carrying only this singular summary proves failure status but not equivalence to a richer terminal webhook artifact.'
        ),
    ] = None
    history: Annotated[
        list[HistoryItem] | None,
        Field(
            description='Complete conversation history for this task (only included if include_history was true in request)'
        ),
    ] = None
    result: Annotated[
        dict[str, Any] | None,
        Field(
            description='Canonical task-specific terminal payload. Present when include_result was true and a completed, failed, or rejected task produced a terminal artifact; canceled tasks may omit it. For failed tasks, the singular error field is a convenience summary and MUST agree with the canonical fatal error represented here. Consumers and sellers MUST resolve and validate the exact schema through manifest.task_result_resolution: use terminal_schema_overrides[task_type] when present, otherwise tools[task_type].response_schema. The polling envelope keeps this field generic so get_task_status does not embed every task response schema.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var completed_at : pydantic.types.AwareDatetime | None
var context : ContextObject | None
var created_at : pydantic.types.AwareDatetime
var error : Error | None
var ext : ExtensionObject | None
var has_webhook : bool | None
var history : list[HistoryItem] | None
var model_config
var progress : Progress | None
var protocol : AdcpProtocol
var result : dict[str, typing.Any] | None
var status : TaskStatus
var task_id : str
var task_type : TaskType
var updated_at : pydantic.types.AwareDatetime

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ListTasksRequest (**data: Any)

Expand source code

class ListTasksRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account scope for task reconciliation. Sellers MUST only return tasks created for the caller's authenticated account + principal pair. When omitted, the seller MAY use the credential-bound singleton account, but multi-account credentials SHOULD require an explicit account."
        ),
    ] = None
    filters: Annotated[Filters | None, Field(description='Filter criteria for querying tasks')] = (
        None
    )
    sort: Annotated[Sort | None, Field(description='Sorting parameters')] = None
    pagination: pagination_request.PaginationRequest | None = None
    include_history: Annotated[
        StrictBool | None,
        Field(
            description='Include full conversation history for each task (may significantly increase response size)'
        ),
    ] = False
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The request message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpRequest
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference1 | AccountReference2 | None
var context : ContextObject | None
var ext : ExtensionObject | None
var filters : Filters | None
var include_history : bool | None
var model_config
var pagination : PaginationRequest | None
var sort : Sort | None

Inherited members

AdcpRequest:
- get_account
- get_adcp_major_version
- get_adcp_version
- get_context
- get_idempotency_key
- get_push_notification_config
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ListTasksResponse (**data: Any)

Expand source code

class ListTasksResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    query_summary: Annotated[
        QuerySummary, Field(description='Summary of the query that was executed')
    ]
    tasks: Annotated[list[Task], Field(description='Array of tasks matching the query criteria')]
    pagination: pagination_response.PaginationResponse
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var pagination : PaginationResponse
var query_summary : QuerySummary
var tasks : list[Task]

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class McpWebhookPayload (**data: Any)

Expand source code

class McpWebhookPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Sender-generated delivery key stable across RFC 8785 JCS-equivalent retries of the complete authenticated webhook payload. Publishers MUST generate a cryptographically random value (UUID v4 recommended), bind it immutably to the first canonical payload for the advertised delivery retry horizon, and use a fresh key for a changed payload or distinct delivery. Receivers scope the binding to the authenticated sender identity. Same key plus identical payload while active returns retryable 503; after durable acknowledgement it returns 2xx; same key plus a different canonical payload returns non-retryable 409. This is the transport delivery identity, not request idempotency or stable logical notification identity.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    notification_id: Annotated[
        str | None,
        Field(
            description='Optional event-layer identifier for one logical notification. Stable across re-emissions of the same logical event and distinct from the per-delivery `idempotency_key`. For terminal task webhooks, the authoritative terminal identity remains the authenticated seller plus the bound task_id; when notification_id is present, different delivery keys carrying the same value are re-emissions and MUST NOT republish terminal effects. For other event families, population and repair identity remain event-shape-dependent (see notification-type.json enumDescriptions): impairment aliases impairment_id, creative and account notifications use transition identifiers, wholesale events alias event.event_id, and capability changes use a revision-event identifier. Point-in-time delivery events (scheduled, final, delayed, adjusted, window_update) omit this field and dedupe by idempotency_key plus their delivery-report identity. Charset is constrained to `[A-Za-z0-9_.:-]`.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    operation_id: Annotated[
        str,
        Field(
            description='Client-generated correlation identifier for the operation that produced this webhook. Buyers supply this value at webhook registration time via `push_notification_config.operation_id`; sellers MUST echo it verbatim in every webhook payload. Sellers MUST NOT derive `operation_id` by parsing `push_notification_config.url` — the URL is opaque to the seller. Receivers MAY dispatch endpoints by URL path or query string, but MUST correlate the operation using this payload field, not URL-derived values. See [Webhooks — Operation IDs and URL templates](/docs/building/by-layer/L3/webhooks#operation-ids-and-url-templates) for the full normative wire contract.'
        ),
    ]
    task_id: Annotated[
        str,
        Field(
            description='Unique identifier for this task. Use this to correlate webhook notifications with the original task submission.'
        ),
    ]
    task_type: Annotated[
        task_type_1.TaskType,
        Field(
            description='Type of AdCP operation that triggered this webhook. Enables webhook handlers to route to appropriate processing logic.'
        ),
    ]
    protocol: Annotated[
        adcp_protocol.AdcpProtocol | None,
        Field(
            description='AdCP protocol this task belongs to. Helps classify the operation type at a high level.'
        ),
    ] = None
    status: Annotated[
        task_status.TaskStatus,
        Field(
            description='Current task status. Webhooks are triggered for status changes after initial submission.'
        ),
    ]
    timestamp: Annotated[
        AwareDatetime,
        Field(
            description='ISO 8601 timestamp when this logical webhook delivery was first generated. Every retry under the same idempotency_key MUST repeat this exact body value, along with every other payload member; only transport/signature metadata such as a fresh RFC 9421 nonce or created parameter may change between attempts.'
        ),
    ]
    message: Annotated[
        str | None,
        Field(
            description='Human-readable summary of the current task state. Provides context about what happened and what action may be needed.'
        ),
    ] = None
    context_id: Annotated[
        str | None,
        Field(
            description='Compatibility metadata copied from the originating response when present. This value alone is not continuation authority and MUST NOT be used to resume input-required or auth-required work or to select session state.'
        ),
    ] = None
    token: Annotated[
        str | None,
        Field(
            description='Authentication token echoed verbatim from [`PushNotificationConfig.token`](/schemas/core/push-notification-config.json). Receivers that configured a token MUST compare it to this value to validate request authenticity, and SHOULD use a constant-time equality check to mitigate timing attacks. Absent when no token was configured at registration. Length bounds mirror the config-side field — receivers MAY reject payloads whose token length falls outside the configured range as a defensive check, provided the length check is performed only after the configured token is known to exist for this subscription, and the length comparison is not used as a fast-path to short-circuit the constant-time compare on equal-length inputs. Receivers MUST NOT treat absence as an authenticity failure when no token was configured.',
            max_length=4096,
            min_length=16,
        ),
    ] = None
    result: Annotated[
        async_response_data.AdcpAsyncResponseData | None,
        Field(
            description='Task-specific payload matching the status. For completed/failed, contains the full task response. For working/input-required/submitted, contains status-specific data. This is the data layer that AdCP specs - same structure used in A2A status.message.parts[].data.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_id : str | None
var idempotency_key : str
var message : str | None
var model_config
var notification_id : str | None
var operation_id : str
var protocol : AdcpProtocol | None
var result : GetProductsResponse | GetProductsRejected | GetProductsWorking | GetProductsInputRequired | GetProductsSubmitted | RequestProposalsResponse1 | RequestProposalsResponse2 | RequestProposalsResponse3 | RequestProposalsResponse4 | RequestProposalsSubmitted | RefineProposalsResponse1 | RefineProposalsResponse2 | RefineProposalsSubmitted | DeclineProposalsResponse1 | DeclineProposalsResponse2 | MediaBuyCommitmentResponse1 | MediaBuyCommitmentResponse2 | MediaBuyCommitmentResponse3 | ControlMediaBuyResponse1 | ControlMediaBuyResponse2 | ControlMediaBuyResponse3 | CompactTaskSubmitted | CompactTaskWorking | CompactTaskInputRequired | GetSignalsResponse | GetSignalsWorking | GetSignalsSubmitted | CreateMediaBuyResponse1 | CreateMediaBuyResponse2 | CreateMediaBuyResponse3 | CreateMediaBuyWorking | CreateMediaBuyInputRequired | CreateMediaBuySubmitted | UpdateMediaBuyResponse1 | UpdateMediaBuyResponse2 | UpdateMediaBuyResponse3 | UpdateMediaBuyWorking | UpdateMediaBuyInputRequired | UpdateMediaBuySubmitted | MediaBuyDeliveryWebhookResult | BuildCreativeResponse1 | BuildCreativeResponse2 | BuildCreativeResponse3 | BuildCreativeResponse4 | BuildCreativeResponse5 | BuildCreativeResponse6 | PreviewCreativeResponse1 | PreviewCreativeResponse2 | PreviewCreativeResponse3 | PreviewCreativeResponse4 | BuildCreativeWorking | BuildCreativeInputRequired | BuildCreativeSubmitted | GetCreativeFeaturesResponse1 | GetCreativeFeaturesResponse2 | GetCreativeFeaturesResponse3 | GetCreativeFeaturesSubmitted | SyncCreativesResponse1 | SyncCreativesResponse2 | SyncCreativesResponse3 | SyncCreativesWorking | SyncCreativesInputRequired | SyncCreativesSubmitted | SyncCatalogsResponse1 | SyncCatalogsResponse2 | SyncCatalogsResponse3 | SyncCatalogsWorking | SyncCatalogsInputRequired | SyncCatalogsSubmitted | None
var status : TaskStatus
var task_id : str
var task_type : TaskType
var timestamp : pydantic.types.AwareDatetime
var token : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Metadata (**data: Any)

Expand source code

class Metadata(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    canonical: Annotated[AnyUrl | None, Field(description='Canonical URL')] = None
    author: Annotated[str | None, Field(description='Artifact author name')] = None
    keywords: Annotated[str | None, Field(description='Artifact keywords')] = None
    open_graph: Annotated[
        dict[str, Any] | None, Field(description='Open Graph protocol metadata')
    ] = None
    twitter_card: Annotated[dict[str, Any] | None, Field(description='Twitter Card metadata')] = (
        None
    )
    json_ld: Annotated[
        list[dict[str, Any]] | None, Field(description='JSON-LD structured data (schema.org)')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var author : str | None
var canonical : pydantic.networks.AnyUrl | None
var json_ld : list[dict[str, typing.Any]] | None
var keywords : str | None
var model_config
var open_graph : dict[str, typing.Any] | None
var twitter_card : dict[str, typing.Any] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class NotificationConfig (**data: Any)

Expand source code

class NotificationConfig(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    subscriber_id: Annotated[
        str,
        Field(
            description="Buyer-supplied identifier for this subscription endpoint. This is the stable logical key within one account's notification_configs[] set: re-sending the same subscriber_id for the same account replaces that subscriber's URL, event_types, authentication selector, and active flag rather than creating a duplicate. Echoed on every webhook payload and on every `webhook_activity[]` record fired against this config so the buyer can attribute fires across multiple endpoints. MUST be unique within the account's `notification_configs[]`. Sending two entries with the same `subscriber_id` in a single `sync_accounts` request array is rejected as a per-account validation failure with `INVALID_REQUEST` or `VALIDATION_ERROR`, and `error.field` MUST point at the duplicate entry. `subscriber_id` is the stable match key for the per-account declarative-replace diff. Always required (even with a single subscriber) so the SDK contract is uniform — no conditional required-when-multiple rules to trip up implementations. Format is opaque — recommended values are short kebab-case slugs (`buyer-primary`, `audit-bus`, `dx-team`).",
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    url: Annotated[
        AnyUrl,
        Field(
            description='Webhook endpoint URL. Same wire contract as `push-notification-config.url` — `format: "uri"`, no destination-port allowlist enforced by the protocol, SSRF protection via the IP-range check defined in docs/building/by-layer/L1/security.mdx#webhook-url-validation-ssrf. Sellers MUST validate URL syntax, HTTPS usage, hostname normalization, and reserved-range rejection when writing any config, including `active: false` configs. Sellers MUST complete an activation challenge or equivalent proof-of-control before treating a new or changed active subscriber as active.'
        ),
    ]
    event_types: Annotated[
        list[EventType],
        Field(
            description='Account-anchored notification types this subscriber wishes to receive on the registered `url`. The seller MUST NOT fire other types against this endpoint, and MUST NOT silently widen the filter when new account-anchored types are added. Creative lifecycle, assignment, indicator, account status, wholesale feed, reporting.delivery_ready, reporting.status_changed, and reporting.ledger_changed events are valid here; media-buy-anchored types (`scheduled`, `final`, `delayed`, `adjusted`, `window_update`, `impairment`) and agent-anchored types (`capabilities.changed`) are schema-invalid on this surface and sellers MUST reject those entries as per-account validation failures with `INVALID_REQUEST` or `VALIDATION_ERROR` and `error.field` pointing at the invalid `event_types` entry rather than silently dropping them.',
            min_length=1,
        ),
    ]
    product_payload_view: Annotated[
        ProductPayloadView | None,
        Field(
            description='Product webhook representation selected by this subscriber. Use canonical with lifecycle_tools.list_products; legacy is the default for 3.x get_products consumers. Sellers emit exactly canonical_product/canonical_pricing_options or product/pricing_options accordingly. Valid only when event_types includes a product.* event.'
        ),
    ] = ProductPayloadView.legacy
    authentication: Annotated[
        Authentication | None,
        Field(
            deprecated=True,
            description="Legacy authentication selector. Same precedence and semantics as `push-notification-config.authentication` — presence opts the seller into Bearer or HMAC-SHA256 signing; absence selects the default RFC 9421 webhook profile keyed off the seller's brand.json `agents[]` JWKS. The same signed-registration downgrade-resistance rules apply to accounts[].notification_configs[].authentication. Deprecated; removed in AdCP 4.0. Credentials are write-only and MUST NOT be echoed on `list_accounts` reads.",
        ),
    ] = None
    active: Annotated[
        StrictBool | None,
        Field(
            description="When false, the seller persists the configuration but suppresses fires. Use to pause a noisy subscriber without losing the registration. Sellers MUST NOT skip persisting the entry when `active: false` — the buyer's next `sync_accounts` MUST observe the same array, otherwise the buyer cannot distinguish pause from drop. Paused configs 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. Reactivation requires full SSRF validation with connect pinning plus proof-of-control for any tuple without current valid proof."
        ),
    ] = True
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

adcp.types.projections._NotificationConfigResponse

Class variables

var active : bool | None
var authentication : Authentication | None
var event_types : list[EventType]
var ext : ExtensionObject | None
var model_config
var product_payload_view : ProductPayloadView | None
var subscriber_id : str
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class NotificationType (*args, **kwds)

Expand source code

class NotificationType(StrEnum):
    scheduled = 'scheduled'
    final = 'final'
    delayed = 'delayed'
    adjusted = 'adjusted'
    window_update = 'window_update'
    impairment = 'impairment'
    creative_status_changed = 'creative.status_changed'
    creative_assignment_changed = 'creative.assignment_changed'
    indicators_changed = 'indicators.changed'
    creative_purged = 'creative.purged'
    account_status_changed = 'account.status_changed'
    account_change_recorded = 'account.change_recorded'
    product_created = 'product.created'
    product_updated = 'product.updated'
    product_priced = 'product.priced'
    product_removed = 'product.removed'
    signal_created = 'signal.created'
    signal_updated = 'signal.updated'
    signal_priced = 'signal.priced'
    signal_removed = 'signal.removed'
    wholesale_feed_bulk_change = 'wholesale_feed.bulk_change'
    capabilities_changed = 'capabilities.changed'
    reporting_delivery_ready = 'reporting.delivery_ready'
    reporting_status_changed = 'reporting.status_changed'
    reporting_ledger_changed = 'reporting.ledger_changed'
    principal_changed = 'principal.changed'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var account_change_recorded
var account_status_changed
var adjusted
var capabilities_changed
var creative_assignment_changed
var creative_purged
var creative_status_changed
var delayed
var final
var impairment
var indicators_changed
var principal_changed
var product_created
var product_priced
var product_removed
var product_updated
var reporting_delivery_ready
var reporting_ledger_changed
var reporting_status_changed
var scheduled
var signal_created
var signal_priced
var signal_removed
var signal_updated
var wholesale_feed_bulk_change
var window_update

class Pagination (**data: Any)

Expand source code

class Pagination(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    max_results: Annotated[
        SchemaInt | None,
        Field(description='Maximum number of collections to return per page', ge=1, le=10000),
    ] = 1000
    cursor: Annotated[
        str | None,
        Field(description='Opaque cursor from a previous response to fetch the next page'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var max_results : int | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PaginationRequest (**data: Any)

Expand source code

class PaginationRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    max_results: Annotated[
        SchemaInt | None,
        Field(description='Maximum number of items to return per page', ge=1, le=100),
    ] = 50
    cursor: Annotated[
        str | None,
        Field(description='Opaque cursor from a previous response to fetch the next page'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var max_results : int | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PaginationResponse (**data: Any)

Expand source code

class PaginationResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    has_more: Annotated[
        StrictBool, Field(description='Whether more results are available beyond this page')
    ]
    cursor: Annotated[
        str | None,
        Field(
            description='Opaque cursor to pass in the next request to fetch the next page. Only present when has_more is true.'
        ),
    ] = None
    total_count: Annotated[
        SchemaInt | None,
        Field(
            description='Total number of items matching the query across all pages. Optional because not all backends can efficiently compute this.',
            ge=0,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var has_more : bool
var model_config
var total_count : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalChangedWebhook (**data: Any)

Expand source code

class PrincipalChangedWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Sender-generated key stable across retries of the same fire. Sellers MUST generate a cryptographically random value (UUID v4 recommended) per distinct fire and reuse it on every retry of the same fire. Receivers MUST dedupe by this key, scoped to the authenticated sender identity.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    notification_id: Annotated[
        str,
        Field(
            description='Stable identifier for this logical principal-state transition. Re-emissions of the same transition reuse this value under a new idempotency_key; a later distinct transition receives a new id.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    notification_type: Annotated[
        Literal['principal.changed'],
        Field(
            description="Fixed notification type discriminator. Matches the value registered on the subscriber's `event_types`."
        ),
    ] = 'principal.changed'
    fired_at: Annotated[
        AwareDatetime,
        Field(
            description='ISO 8601 timestamp when the seller initiated this fire. Distinct from `changed_at`, which is when the seller recorded the state transition.'
        ),
    ]
    subscriber_id: Annotated[
        str,
        Field(
            description="Identifies which caller-scoped notification_configs[] entry is receiving this fire. Echoed verbatim from the entry's subscriber_id.",
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    agent_url: Annotated[
        AnyUrl,
        Field(
            description='Canonical seller agent URL whose principal state changed. Receivers connected to multiple agents use this to select which principal record to re-read.'
        ),
    ]
    changed_at: Annotated[
        AwareDatetime,
        Field(
            description='ISO 8601 timestamp when the seller recorded the principal-state transition.'
        ),
    ]
    reason: Annotated[
        Reason,
        Field(
            description='Coarse reason for the invalidation. Advisory routing/debug metadata; receivers MUST re-read get_principal rather than inferring the new state from the reason.'
        ),
    ]
    destination_id: Annotated[
        str | None,
        Field(
            description='Optional advisory hint naming the affected reporting destination for destination-scoped reasons. Receivers MAY use it for selective handling but MUST still treat the get_principal read as authoritative.',
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agent_url : pydantic.networks.AnyUrl
var changed_at : pydantic.types.AwareDatetime
var destination_id : str | None
var ext : ExtensionObject | None
var fired_at : pydantic.types.AwareDatetime
var idempotency_key : str
var model_config
var notification_id : str
var notification_type : Literal['principal.changed']
var reason : Reason
var subscriber_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalDeclarationsState (**data: Any)

Expand source code

class PrincipalDeclarationsState(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    declared: Annotated[
        principal_declarations.AgentDeclarations,
        Field(description="The caller's current declared set, echoed verbatim."),
    ]
    accepted: Annotated[
        principal_declarations.AgentDeclarations,
        Field(
            description="The intersection of the declared set with the seller's objective support. Sellers select asynchronous payload versions, signing algorithms, and experimental behavior only from this set. A change to this set caused by seller-side evolution fires principal.changed with reason declarations_intersection_changed."
        ),
    ]
    selected_async_adcp_version: Annotated[
        str | None,
        Field(
            description='The single AdCP minor version the seller will use for asynchronous payload shapes toward this principal. MUST be a member of accepted.async_adcp_versions and MUST be present whenever that set is non-empty, so the buyer knows the exact payload contract rather than inferring it from the intersection.',
            pattern='^\\d+\\.\\d+$',
        ),
    ] = None
    exclusions: Annotated[
        list[Exclusion] | None,
        Field(
            description="Every declared value that is absent from the accepted intersection, with the seller's reason. Present whenever declared and accepted differ, so a buyer can see why a capability it relies on was not accepted instead of diffing the two sets.",
            max_length=64,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accepted : AgentDeclarations
var declared : AgentDeclarations
var exclusions : list[Exclusion] | None
var model_config
var selected_async_adcp_version : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalKind (*args, **kwds)

Expand source code

class PrincipalKind(StrEnum):
    buyer_agent = 'buyer_agent'
    operator = 'operator'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var buyer_agent
var operator

class PrincipalState (**data: Any)

Expand source code

class PrincipalState(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    notification_configs: Annotated[
        list[agent_notification_config_state.AgentNotificationConfigState] | None,
        Field(
            description='Current agent-level webhook subscribers. authentication.credentials is always omitted because it is write-only.',
            max_length=16,
        ),
    ] = None
    reporting_destinations: Annotated[
        list[agent_reporting_destination_state.AgentReportingDestinationState] | None,
        Field(
            description='Current reusable reporting destination bindings and setup states. destination_id and destination_ref values MUST each be unique within this caller-scoped array; superseded generations of a current destination appear in its prior_destination_refs.',
            max_length=64,
        ),
    ] = None
    declarations: Annotated[
        principal_declarations_state.PrincipalDeclarationsState | None,
        Field(
            description='Declared consumption facts and the seller-computed accepted intersection. Present when and only when the seller supports the declarations section.'
        ),
    ] = None
    retired_destinations: Annotated[
        list[RetiredDestination] | None,
        Field(
            description='Destinations the caller revoked by omitting them from a submitted reporting_destinations section, retained while any generation remains resolvable for reporting history. Enumerable only by the owning principal. Reusing a retired destination_id requires fresh registration and proof and produces a new generation.',
            max_length=64,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var declarations : PrincipalDeclarationsState | None
var model_config
var notification_configs : list[AgentNotificationConfigState] | None
var reporting_destinations : list[AgentReportingDestinationState] | None
var retired_destinations : list[RetiredDestination] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Protocol (*args, **kwds)

Expand source code

class Protocol(str, Enum):
    """Supported protocols."""

    A2A = "a2a"
    MCP = "mcp"

Supported protocols.

Ancestors

builtins.str
enum.Enum

Class variables

var A2A
var MCP

class ProtocolEnvelope (**data: Any)

Expand source code

class ProtocolEnvelope(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    context_id: Annotated[
        str | None,
        Field(
            description='Transport-managed conversation identifier. On A2A, this maps to the native Message/Task `contextId` used to associate messages with a conversation; it is not carried inside the AdCP DataPart. On MCP, a request-body `context_id`, where admitted by the selected request schema, is a compatibility-only field: servers MUST ignore it, callers MUST NOT rely on it for continuity, and it MUST NOT select session state, identity, account, authorization, task continuation, or idempotency scope. MCP continuity, if provided, comes from the transport session. Distinct from `context` (per-request opaque echo, see below) and from `task_id` (AdCP operation tracking).'
        ),
    ] = None
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Per-request opaque caller-supplied correlation object echoed unchanged in the response. Used for buyer-side tracking (UI session IDs, trace IDs, custom metadata) that the agent MUST preserve byte-for-byte without parsing. Distinct from `context_id` (transport-managed A2A conversation correlation or MCP compatibility metadata) — `context` is caller-owned echo and never selects transport state. Both MAY appear on the same response.\n\n**Relationship to per-task body-level `context` declarations.** Many task request/response schemas (147 as of 3.1) already declare a body-level `context` field that `$ref`s `/schemas/core/context.json` at the body root. Under the flat-on-the-wire MCP serialization (see `notes` below), envelope-level `context` and body-level `context` occupy the same key on the response root — they are NOT separate fields, they MUST share the same value, and they MUST both `$ref` `core/context.json`. The envelope declaration is **authoritative** for the schema definition; per-task body declarations are mirrors retained for tooling reasons (SDK codegen completeness, per-task validation against the response schema in isolation). Future versions MAY drop body-level `context` declarations from per-task schemas; conformance does not require either declaration to be present, only that the wire value `$ref`s `core/context.json`.'
        ),
    ] = None
    task_id: Annotated[
        str | None,
        Field(
            description='Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete.'
        ),
    ] = None
    status: Annotated[
        task_status.TaskStatus,
        Field(
            description='Current AdCP task state or structured outcome. Indicates whether the task completed, is in progress, was submitted for async processing, failed, requires user input, or returned a typed business rejection. REQUIRED on every task response envelope. Synchronous tasks (including read-only metadata calls like `get_adcp_capabilities`) normally emit `status: "completed"`; a task-specific rejection arm emits `status: "rejected"` without turning the transport into a failure. Async tasks emit `submitted`, `working`, `input-required`, etc. per their lifecycle. Agents MUST NOT emit the legacy task_status or response_status fields alongside this field — the status field is the single authoritative AdCP response state.'
        ),
    ] = task_status.TaskStatus.completed
    message: Annotated[
        str | None,
        Field(
            description='Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response.'
        ),
    ] = None
    timestamp: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress.'
        ),
    ] = None
    replayed: Annotated[
        StrictBool | None,
        Field(
            description="Set to true when this response was returned from the idempotency cache rather than from a fresh execution. Set to false (or omitted) when the request was executed fresh. Buyers use this to distinguish cached replays from new executions — matters for billing reconciliation, audit logs, state-machine routing (cached state-tracking fields are historical snapshots, not current state — re-read via the resource's read endpoint), and any downstream system that assumes exactly-once event semantics. `replayed` appears only when the request actually resolved through the idempotency cache. Pure reads may ignore an optional `idempotency_key`; when a seller voluntarily caches keyed reads, those responses use the same replay indicator and full cache contract."
        ),
    ] = False
    adcp_error: Annotated[
        error.Error | None,
        Field(
            description="Transport-envelope error signal for fatal task failures. Per the two-layer model in `error-handling.mdx#envelope-vs-payload-errors-the-two-layer-model`, a fatal task failure SHOULD populate both this envelope-level field AND the payload's `errors[]` array — the envelope carries a typed, extractable error so MCP/A2A clients can dispatch without re-parsing the payload, while the payload's structured `errors[]` remains the canonical normative shape. Non-fatal warnings populate ONLY `payload.errors[]` with `severity: warning` — the envelope MUST NOT carry `adcp_error` for non-failures."
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='AdCP application-layer webhook configuration for async task updates over MCP, A2A, or REST. Echoed from the request to confirm webhook settings. It is distinct from transport-native progress or A2A TaskPushNotificationConfig delivery and can outlive the originating transport session.'
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque authorization context issued only by an approved check_governance decision. Buyers attach it to governed requests across protocol roles (media buys, rights acquisitions, signal activations, creative services); receiving services persist it and forward it on subsequent execution and lifecycle checks. The context is the authoritative plan binding at service boundaries, so a service MUST NOT require a separate plan_id.\n\nGovernance agents MUST emit a compact JWS per the AdCP JWS profile. Verifiers validate standard authorization claims such as signature, issuer, audience, expiry, and replay protection, but intermediaries MUST NOT interpret embedded governance state for business logic. A conditions or denied verdict never carries an authorization context.\n\nThis is the primary correlation key for audit and reporting across the governance lifecycle.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    payload: Annotated[
        dict[str, Any] | None,
        Field(
            description='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). `payload` is a documentary construct — it is NOT a required wire field, and its on-the-wire shape depends on transport (see Transport serialization below). Task response schemas declare body fields without wrapping them in a `payload` object; the wire representation places those body fields per transport convention. On MCP the body fields appear as siblings of envelope fields at the root of the tool response; on A2A they appear inside `task.artifacts[0].parts[].DataPart`; on REST they appear at the root of the JSON body.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var adcp_error : Error | None
var context : ContextObject | None
var context_id : str | None
var governance_context : str | None
var message : str | None
var model_config
var payload : dict[str, typing.Any] | None
var push_notification_config : PushNotificationConfig | None
var replayed : bool | None
var status : TaskStatus
var task_id : str | None
var timestamp : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProtocolResponse (**data: Any)

Expand source code

class ProtocolResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    message: Annotated[str, Field(description='Human-readable summary')]
    context_id: Annotated[
        str | None,
        Field(
            description='Transport-managed conversation identifier. Maps to native contextId on A2A; compatibility metadata only on MCP and not a continuation or authorization mechanism.'
        ),
    ] = None
    data: Annotated[
        Any | None,
        Field(
            description='AdCP task-specific response data (see individual task response schemas)'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_id : str | None
var data : typing.Any | None
var message : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PushNotificationConfig (**data: Any)

Expand source code

class PushNotificationConfig(AdCPBaseModel):
    url: Annotated[
        AnyUrl,
        Field(
            description='Webhook endpoint URL for task status notifications. The wire contract is unconstrained beyond `format: "uri"` — in particular, publishers SHOULD NOT enforce a destination-port allowlist by default, since buyers legitimately host receivers on non-standard TLS ports (`:9443`, `:4443`, path-routed multi-tenant gateways). The SSRF guard the protocol relies on is the IP-range check + DNS-rebinding-resistant connect pin defined in [Webhook URL validation (SSRF)](/docs/building/by-layer/L1/security#webhook-url-validation-ssrf), not port filtering. Operators who want a hardened destination-port allowlist as defense-in-depth (e.g., locked-down enterprise egress) opt in explicitly — see [Destination port: permissive by default](/docs/building/by-layer/L1/security#destination-port-permissive-by-default).'
        ),
    ]
    operation_id: Annotated[
        str | None,
        Field(
            description="Buyer-supplied correlation identifier for the operation that will produce webhooks against this registration. The seller MUST echo this value verbatim into every webhook payload's `operation_id` field (see [`mcp-webhook-payload.json`](/schemas/core/mcp-webhook-payload.json) and [Webhooks — Operation IDs](/docs/building/by-layer/L3/webhooks#operation-ids-and-url-templates)). Buyers SHOULD generate a unique value per task invocation (UUID recommended). This field is the canonical registration channel for `operation_id`; buyers MAY additionally embed routing values in the URL path or query as an aid for their own HTTP server, but the URL is opaque to the seller and the wire-level source of truth is this field. Sellers MUST NOT parse the URL to recover `operation_id`. For 3.x schema compatibility the member remains optional, but a seller MUST reject a task that registers an AdCP webhook without it using `INVALID_REQUEST`; otherwise the required webhook envelope cannot be emitted.",
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    token: Annotated[
        str | None,
        Field(
            description="Optional client-provided token for webhook validation. The seller MUST echo this value verbatim in every webhook payload's `token` field (see [`mcp-webhook-payload.json`](/schemas/core/mcp-webhook-payload.json) for the receiver-side validation obligation). Length bounds give receivers a defensive range check on the echoed value; senders SHOULD generate tokens with at least 128 bits of entropy (≥22 base64url characters). This is a complementary authenticity mechanism that can layer on top of the RFC 9421 webhook signature — unlike the `authentication` block below, it is not on the 4.0 removal track. Receivers that registered both a signing key (RFC 9421) and a `token` MUST NOT treat a valid token echo as authorization to skip signature verification; both checks remain independent obligations.",
            max_length=4096,
            min_length=16,
        ),
    ] = None
    authentication: Annotated[
        Authentication | None,
        Field(
            deprecated=True,
            description='Legacy authentication configuration (A2A-compatible). Opts the seller into Bearer or HMAC-SHA256 signing instead of the default RFC 9421 webhook profile. Deprecated; removed in AdCP 4.0. **Precedence is a switch, not a fallback:** presence of this block selects the legacy scheme; absence selects 9421. A seller MUST NOT sign the same webhook both ways, and a buyer MUST NOT attempt \'try 9421 first, fall back to HMAC\' verification — signature mode is determined solely by whether this block was present at registration time. The seller\'s baseline 9421 webhook key is published at its brand.json `agents[]` `jwks_uri` using `adcp_use: "request-signing"` (deprecated `webhook-signing` keys remain accepted during the compatibility window); it does not override this selector and is only used when `authentication` is omitted. See docs/building/by-layer/L1/security.mdx#webhook-callbacks for the full precedence and downgrade-resistance rules (including the `webhook_mode_mismatch` rejection a buyer MUST apply when a received webhook\'s signing mode does not match the registered mode).',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authentication : Authentication | None
var model_config
var operation_id : str | None
var token : str | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class QuerySummary (**data: Any)

Expand source code

class QuerySummary(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    total_matching: Annotated[
        SchemaInt | None,
        Field(description='Total number of tasks matching filters (across all pages)', ge=0),
    ] = None
    returned: Annotated[
        SchemaInt | None, Field(description='Number of tasks returned in this response', ge=0)
    ] = None
    domain_breakdown: Annotated[
        DomainBreakdown | None, Field(description='Count of tasks by domain')
    ] = None
    status_breakdown: Annotated[
        dict[str, SchemaInt] | None, Field(description='Count of tasks by status')
    ] = None
    filters_applied: Annotated[
        list[str] | None, Field(description='List of filters that were applied to the query')
    ] = None
    sort_applied: Annotated[
        SortApplied | None, Field(description='Sort order that was applied')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var domain_breakdown : DomainBreakdown | None
var filters_applied : list[str] | None
var model_config
var returned : int | None
var sort_applied : SortApplied | None
var status_breakdown : dict[str, int] | None
var total_matching : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Request (**data: Any)

Expand source code

class Request(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    target_capability_id: Annotated[
        str | None,
        Field(
            description='Canonical preview-operation selector for this batch item. Overrides the batch-level target_capability_id and MUST identify an advertised capability whose operations contains preview. If neither item nor batch supplies one, renderer inference is permitted only for a unique compatible preview capability.',
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ] = None
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format preview route. Use target_capability_id plus the canonical identity in creative_manifest.',
        ),
    ] = None
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest | None,
        Field(description='Complete creative manifest with all required assets.'),
    ] = None
    creative_id: Annotated[
        str | None,
        Field(
            description='Creative-library identifier. Use instead of creative_manifest to preview a stored canonical creative.'
        ),
    ] = None
    inputs: Annotated[
        list[Input10] | None,
        Field(
            description='Array of input sets for generating multiple preview variants', min_length=1
        ),
    ] = None
    template_id: Annotated[
        str | None, Field(description='Specific template ID for custom format rendering')
    ] = None
    quality: Annotated[
        creative_quality.CreativeQuality | None,
        Field(description='Render quality for this preview. Overrides batch-level default.'),
    ] = None
    output_format: Annotated[
        preview_output_format.PreviewOutputFormat | None,
        Field(description='Output format for this preview. Overrides batch-level default.'),
    ] = preview_output_format.PreviewOutputFormat.url
    item_limit: Annotated[
        SchemaInt | None,
        Field(description='Maximum number of catalog items to render in this preview.', ge=1),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var creative_id : str | None
var creative_manifest : CreativeManifest | None
var format_id : FormatReferenceStructuredObject | None
var inputs : list[Input10] | None
var item_limit : int | None
var model_config
var output_format : PreviewOutputFormat | None
var quality : CreativeQuality | None
var target_capability_id : str | None
var template_id : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Response (**data: Any)

Expand source code

class Response(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    previews: Annotated[list[Preview2], Field(min_length=1)]
    interactive_url: AnyUrl | None = None
    expires_at: AwareDatetime | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var expires_at : pydantic.types.AwareDatetime | None
var interactive_url : pydantic.networks.AnyUrl | None
var model_config
var previews : list[Preview2]

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ResponsePayloadJwsEnvelope (**data: Any)

Expand source code

class ResponsePayloadJwsEnvelope(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    protected: Annotated[
        str,
        Field(
            description='Base64url-encoded JWS protected header. The decoded header MUST include alg, kid, and typ: adcp-response-payload+jws, and MUST NOT include the RFC 7797 b64 header. Verifiers enforce the key purpose by resolving kid to a JWK with adcp_use: response-signing.',
            pattern='^[A-Za-z0-9_-]+$',
        ),
    ]
    payload: Annotated[
        ResponsePayload,
        Field(
            description='Decoded signed payload. Signers compute the JWS payload bytes from the RFC 8785/JCS canonicalization of this object.'
        ),
    ]
    signature: Annotated[
        str,
        Field(
            description='Base64url-encoded JWS signature over the protected header and canonicalized payload.',
            pattern='^[A-Za-z0-9_-]+$',
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var payload : ResponsePayload
var protected : str
var signature : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalUnconfiguredResult (**data: Any)

Expand source code

class Result(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['unconfigured'] = 'unconfigured'

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var kind : Literal['unconfigured']
var model_config

class PrincipalValidatedResult (**data: Any)

Expand source code

class Result(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['validated'] = 'validated'
    action: Action33
    dry_run: Literal[True]
    warnings: Annotated[list[error.Error] | None, Field(max_length=16)] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Action33
var dry_run : Literal[True]
var kind : Literal['validated']
var model_config
var warnings : list[Error] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalAppliedResult (**data: Any)

Expand source code

class Result17(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['applied'] = 'applied'
    action: Annotated[
        Action,
        Field(
            description="Persisted outcome for the submitted sections, computed solely against the caller's own prior state. cleared applies only when every submitted section was []; any other change is updated; unchanged means no submitted section differed."
        ),
    ]
    dry_run: Literal[False]
    principal_id: Annotated[
        str,
        Field(
            description='Seller-issued opaque identifier for this authenticated principal record. It is response-only, not a credential, not caller identity, and not advertiser-account authority.',
            max_length=255,
            min_length=1,
        ),
    ]
    principal_kind: Annotated[
        principal_kind_1.PrincipalKind,
        Field(
            description="Seller-resolved party kind of the authenticated principal: a buyer-agent workload, or an operator-side identity such as a person at the operator. Resolved solely from the seller's authorization system, never from request content, so per-party policy such as billing gates can rely on it."
        ),
    ]
    configuration_version: Annotated[
        str,
        Field(
            description='Opaque version of the persisted configuration. Compare only for equality and return it as expected_configuration_version on a later guarded replacement.',
            max_length=255,
            min_length=1,
        ),
    ]
    configuration: principal_state.PrincipalState
    warnings: Annotated[list[error.Error] | None, Field(max_length=16)] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Action
var configuration : PrincipalState
var configuration_version : str
var dry_run : Literal[False]
var kind : Literal['applied']
var model_config
var principal_id : str
var principal_kind : PrincipalKind
var warnings : list[Error] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalSyncFailedResult (**data: Any)

Expand source code

class Result19(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['failed'] = 'failed'
    errors: Annotated[list[error.Error], Field(max_length=16, min_length=1)]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var errors : list[Error]
var kind : Literal['failed']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalCurrentResult (**data: Any)

Expand source code

class Result6(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['current'] = 'current'
    principal_id: Annotated[
        str,
        Field(
            description='Seller-issued opaque identifier for this authenticated principal record. It is response-only, not a credential, not caller identity, and not advertiser-account authority.',
            max_length=255,
            min_length=1,
        ),
    ]
    principal_kind: Annotated[
        principal_kind_1.PrincipalKind,
        Field(
            description="Seller-resolved party kind of the authenticated principal: a buyer-agent workload, or an operator-side identity such as a person at the operator. Resolved solely from the seller's authorization system, never from request content, so per-party policy such as billing gates can rely on it."
        ),
    ]
    configuration_version: Annotated[
        str,
        Field(
            description='Opaque version of the persisted configuration. Compare only for equality and pass it as expected_configuration_version on a later guarded sync_principal replacement.',
            max_length=255,
            min_length=1,
        ),
    ]
    configuration: principal_state.PrincipalState

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var configuration : PrincipalState
var configuration_version : str
var kind : Literal['current']
var model_config
var principal_id : str
var principal_kind : PrincipalKind

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalRecognizedResult (**data: Any)

Expand source code

class Result7(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['recognized'] = 'recognized'
    principal_id: Annotated[
        str,
        Field(
            description='Seller-issued opaque identifier for the existing durable principal record. The read returns the same identifier after credential renewal or rotation when the new credential maps to this principal. It is not a credential and does not grant authority over an advertiser account.',
            max_length=255,
            min_length=1,
        ),
    ]
    principal_kind: Annotated[
        principal_kind_1.PrincipalKind,
        Field(
            description='Seller-resolved party kind of the authenticated principal. This is resolved from authenticated transport and authorization state, never request content.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var kind : Literal['recognized']
var model_config
var principal_id : str
var principal_kind : PrincipalKind

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PrincipalReadFailedResult (**data: Any)

Expand source code

class Result9(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['failed'] = 'failed'
    errors: Annotated[list[error.Error], Field(max_length=16, min_length=1)]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var errors : list[Error]
var kind : Literal['failed']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Security (**data: Any)

Expand source code

class Security(AdCPBaseModel):
    method: Annotated[
        webhook_security_method.WebhookSecurityMethod, Field(description='Authentication method')
    ]
    hmac_header: Annotated[
        str | None, Field(description="Header name for HMAC signature (e.g., 'X-Signature')")
    ] = None
    api_key_header: Annotated[
        str | None, Field(description="Header name for API key (e.g., 'X-API-Key')")
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var api_key_header : str | None
var hmac_header : str | None
var method : WebhookSecurityMethod
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Sort (**data: Any)

Expand source code

class Sort(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    field: Annotated[Field1 | None, Field(description='Field to sort by')] = Field1.created_at
    direction: Annotated[
        sort_direction.SortDirection | None, Field(description='Sort direction')
    ] = sort_direction.SortDirection.desc

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var direction : SortDirection | None
var field : Field1 | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SortApplied (**data: Any)

Expand source code

class SortApplied(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    field: str
    direction: Direction

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var direction : Direction
var field : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SortDirection (*args, **kwds)

Expand source code

class SortDirection(StrEnum):
    asc = 'asc'
    desc = 'desc'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var asc
var desc

class StatusSummary (**data: Any)

Expand source code

class StatusSummary(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    processing: Annotated[
        SchemaInt | None, Field(description='Number of creatives being processed', ge=0)
    ] = None
    approved: Annotated[
        SchemaInt | None, Field(description='Number of approved creatives', ge=0)
    ] = None
    pending_review: Annotated[
        SchemaInt | None, Field(description='Number of creatives pending review', ge=0)
    ] = None
    rejected: Annotated[
        SchemaInt | None, Field(description='Number of rejected creatives', ge=0)
    ] = None
    archived: Annotated[
        SchemaInt | None, Field(description='Number of archived creatives', ge=0)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var approved : int | None
var archived : int | None
var model_config
var pending_review : int | None
var processing : int | None
var rejected : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncPrincipalRequest (**data: Any)

Expand source code

class SyncPrincipalRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated key for at-most-once execution, at least 16 characters; a fresh UUID v4 per logical operation is recommended. Retries MUST reuse the same key with the same body.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    expected_configuration_version: Annotated[
        str | None,
        Field(
            description='Optional optimistic-concurrency fence returned by a previous successful sync. When present and stale, the seller rejects the whole request without mutation. Compare only for equality.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    expected_principal_kind: Annotated[
        principal_kind.PrincipalKind | None,
        Field(
            description='Optional assertion fence, not identity input: the caller states which party kind it believes it is authenticating as. When present and different from the seller-resolved principal_kind, the seller rejects the whole request with CONFLICT before mutation. The field never influences resolution.'
        ),
    ] = None
    configuration: Annotated[
        Configuration,
        Field(
            description='Sections to replace atomically. At least one section is required. A present array is complete desired state for that section; [] clears it; omission leaves it unchanged.'
        ),
    ]
    dry_run: Annotated[
        StrictBool | None,
        Field(
            description='Validate the proposed replacements and report the would-be action without persisting them, issuing durable identifiers or grants, or sending endpoint proof challenges.'
        ),
    ] = False
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The request message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpRequest
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var configuration : Configuration
var context : ContextObject | None
var dry_run : bool | None
var expected_configuration_version : str | None
var expected_principal_kind : PrincipalKind | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config

Inherited members

AdcpRequest:
- get_account
- get_adcp_major_version
- get_adcp_version
- get_context
- get_idempotency_key
- get_push_notification_config
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class SyncPrincipalResponse (**data: Any)

Expand source code

class SyncPrincipalResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    result: Result17 | Result | Result19
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdcpVersionEnvelope
ProtocolEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var result : Result17 | Result | Result19

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class TaskResult (**data: Any)

Expand source code

class TaskResult(BaseModel, Generic[T]):
    """Result from task execution."""

    model_config = ConfigDict(arbitrary_types_allowed=True)

    status: TaskStatus
    data: T | None = None
    message: str | None = None  # Human-readable message from agent (e.g., MCP content text)
    submitted: SubmittedInfo | None = None
    needs_input: NeedsInputInfo | None = None
    error: str | None = None
    # Structured AdCP error per transport-errors.mdx (``adcp_error`` object:
    # ``code``, ``message``, ``detail``, ``field_path``, ``recovery`` ...).
    # Always populated on the MCP FAILED path when the seller returned a
    # spec-shaped ``adcp_error`` — independent of ``debug``. Callers should
    # branch on ``adcp_error.code`` rather than regex-matching ``error``.
    adcp_error: dict[str, Any] | None = None
    success: bool = Field(default=True)
    metadata: dict[str, Any] | None = None
    debug_info: DebugInfo | None = None
    # The full idempotency_key the SDK used for this request — echoed here so
    # buyers can correlate against their own records. SENSITIVE inside the
    # seller's replay_ttl_seconds window (serves as a retry-pattern oracle);
    # do not emit to shared logs. The SDK's debug capture redacts keys by
    # default; avoid ``model_dump_json()``-ing a TaskResult into shared sinks.
    idempotency_key: str | None = None
    # True when the seller returned a cached response for a replayed key.
    # Agents that emit side effects on success (notifications, memory writes,
    # downstream tool calls) must check this flag and suppress duplicates.
    replayed: bool = False

Result from task execution.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel
typing.Generic

Subclasses

adcp.types.core.TaskResult[Annotated[Union[AcceptProposalResponse5, AcceptProposalResponse6, AcceptProposalResponse7], FieldInfo(annotation=NoneType, required=True, title='Accept Proposal Response', description='Compact proposal-acceptance result containing the resulting MediaBuy identity and accepted immutable proposal snapshot.')]]
adcp.types.core.TaskResult[Annotated[Union[BuyProductsResponse5, BuyProductsResponse6, BuyProductsResponse7], FieldInfo(annotation=NoneType, required=True, title='Buy Products Response', description='Compact direct-purchase result containing the MediaBuy identity and accepted immutable proposal snapshot.')]]
adcp.types.core.TaskResult[Annotated[Union[ControlMediaBuyResponse1, ControlMediaBuyResponse2, ControlMediaBuyResponse3], FieldInfo(annotation=NoneType, required=True, title='Control Media Buy Response', description='Result of applying operational controls without embedding the package or creative object graphs.', discriminator='status')]]
adcp.types.core.TaskResult[Annotated[Union[DeclineProposalsResponse1, DeclineProposalsResponse2], FieldInfo(annotation=NoneType, required=True, title='Decline Proposals Response', description='One ordered terminal result for each requested proposal decline.')]]
adcp.types.core.TaskResult[Annotated[Union[GetProductsResponse, GetProductsRejected, GetProductsWorking, GetProductsInputRequired, GetProductsSubmitted, Annotated[Union[RequestProposalsResponse1, RequestProposalsResponse2, RequestProposalsResponse3, RequestProposalsResponse4], FieldInfo(annotation=NoneType, required=True, title='Request Proposals Response', description='One or more immutable draft media-plan proposals and compact canonical products referenced by their purchases. Products always carry product_id and name and never carry legacy named-format identifiers. During the AdCP 3.x compatibility window, an SDK projecting a valid products-only get_products brief result may instead return the deprecated products_available outcome with an explicit purchase continuation. Native 3.2 sellers MUST NOT use that compatibility outcome, and adapters MUST NOT fabricate a proposal, terms digest, or feed version.')], RequestProposalsSubmitted, Annotated[Union[RefineProposalsResponse1, RefineProposalsResponse2], FieldInfo(annotation=NoneType, required=True, title='Refine Proposals Response', description='One ordered result per requested source proposal. Revision results may carry multiple immutable draft proposals when alternatives were requested; finalization remains one committed proposal per source. Products contains the compact canonical products needed to evaluate the resulting terms.')], RefineProposalsSubmitted, Annotated[Union[DeclineProposalsResponse1, DeclineProposalsResponse2], FieldInfo(annotation=NoneType, required=True, title='Decline Proposals Response', description='One ordered terminal result for each requested proposal decline.')], Annotated[Union[MediaBuyCommitmentResponse1, MediaBuyCommitmentResponse2, MediaBuyCommitmentResponse3], FieldInfo(annotation=NoneType, required=True, title='Media Buy Commitment Response', description='Shared result for clean product purchase and proposal acceptance. A successful result returns the MediaBuy identity and the immutable accepted commercial snapshot without embedding creative or package graphs. Optional warnings report non-blocking observations at the commitment boundary; continuing conditions remain readable as indicators through get_media_buys.', discriminator='status')], Annotated[Union[ControlMediaBuyResponse1, ControlMediaBuyResponse2, ControlMediaBuyResponse3], FieldInfo(annotation=NoneType, required=True, title='Control Media Buy Response', description='Result of applying operational controls without embedding the package or creative object graphs.', discriminator='status')], CompactTaskSubmitted, CompactTaskWorking, CompactTaskInputRequired, GetSignalsResponse, GetSignalsWorking, GetSignalsSubmitted, CreateMediaBuyResponse1, CreateMediaBuyResponse2, CreateMediaBuyResponse3, CreateMediaBuyWorking, CreateMediaBuyInputRequired, CreateMediaBuySubmitted, UpdateMediaBuyResponse1, UpdateMediaBuyResponse2, UpdateMediaBuyResponse3, UpdateMediaBuyWorking, UpdateMediaBuyInputRequired, UpdateMediaBuySubmitted, MediaBuyDeliveryWebhookResult, BuildCreativeResponse1, BuildCreativeResponse2, BuildCreativeResponse3, BuildCreativeResponse4, BuildCreativeResponse5, BuildCreativeResponse6, PreviewCreativeResponse1, PreviewCreativeResponse2, PreviewCreativeResponse3, PreviewCreativeResponse4, BuildCreativeWorking, BuildCreativeInputRequired, BuildCreativeSubmitted, GetCreativeFeaturesResponse1, GetCreativeFeaturesResponse2, GetCreativeFeaturesResponse3, GetCreativeFeaturesSubmitted, SyncCreativesResponse1, SyncCreativesResponse2, SyncCreativesResponse3, SyncCreativesWorking, SyncCreativesInputRequired, SyncCreativesSubmitted, SyncCatalogsResponse1, SyncCatalogsResponse2, SyncCatalogsResponse3, SyncCatalogsWorking, SyncCatalogsInputRequired, SyncCatalogsSubmitted], FieldInfo(annotation=NoneType, required=True, title='AdCP Async Response Data', description="Validation union of supported async webhook payloads. For completed/failed statuses, use the main task response schema. For rejected get_products outcomes and working/input-required/submitted statuses, use the status-specific schemas. Because this shared webhook union is not tagged with the originating task type, callers MUST also validate a terminal result against that task or event's specific schema. Polling responses use a generic result selected through manifest.task_result_resolution instead of embedding this union.")]]
adcp.types.core.TaskResult[Annotated[Union[ListProductsResponse1, ListProductsResponse2], FieldInfo(annotation=NoneType, required=True, title='List Products Response', description="Canonical product offers and continuation state. Every product carries product_id and name; other compact detail fields follow the request's fields selection. Legacy named-format identifiers are never returned. This response never contains proposals or proposal-lifecycle fields.", discriminator='outcome')]]
adcp.types.core.TaskResult[Annotated[Union[RefineProposalsResponse1, RefineProposalsResponse2], FieldInfo(annotation=NoneType, required=True, title='Refine Proposals Response', description='One ordered result per requested source proposal. Revision results may carry multiple immutable draft proposals when alternatives were requested; finalization remains one committed proposal per source. Products contains the compact canonical products needed to evaluate the resulting terms.')]]
adcp.types.core.TaskResult[Annotated[Union[RequestProposalsResponse1, RequestProposalsResponse2, RequestProposalsResponse3, RequestProposalsResponse4], FieldInfo(annotation=NoneType, required=True, title='Request Proposals Response', description='One or more immutable draft media-plan proposals and compact canonical products referenced by their purchases. Products always carry product_id and name and never carry legacy named-format identifiers. During the AdCP 3.x compatibility window, an SDK projecting a valid products-only get_products brief result may instead return the deprecated products_available outcome with an explicit purchase continuation. Native 3.2 sellers MUST NOT use that compatibility outcome, and adapters MUST NOT fabricate a proposal, terms digest, or feed version.')]]
TaskResult[Any]
adcp.types.core.TaskResult[CheckGovernanceResponse]
adcp.types.core.TaskResult[ComplyTestControllerResponse]
adcp.types.core.TaskResult[ContextMatchResponseRouterPublisher]
adcp.types.core.TaskResult[CreateCollectionListResponse]
adcp.types.core.TaskResult[CreateContentStandardsResponse]
adcp.types.core.TaskResult[CreatePropertyListResponse]
adcp.types.core.TaskResult[DeleteCollectionListResponse]
adcp.types.core.TaskResult[DeletePropertyListResponse]
adcp.types.core.TaskResult[GetAdcpCapabilitiesResponse]
adcp.types.core.TaskResult[GetCollectionListResponse]
adcp.types.core.TaskResult[GetCreativeDeliveryResponse]
adcp.types.core.TaskResult[GetCreativeDeliveryResponse]
adcp.types.core.TaskResult[GetMediaBuyDeliveryResponse]
adcp.types.core.TaskResult[GetMediaBuyDeliveryResponse]
adcp.types.core.TaskResult[GetMediaBuysResponse]
adcp.types.core.TaskResult[GetMediaBuysResponse]
adcp.types.core.TaskResult[GetPlanAuditLogsResponse]
adcp.types.core.TaskResult[GetPrincipalResponse]
adcp.types.core.TaskResult[GetProductsResponse]
adcp.types.core.TaskResult[GetProductsResponse]
adcp.types.core.TaskResult[GetPropertyListResponse]
adcp.types.core.TaskResult[GetReportingStatusResponse]
adcp.types.core.TaskResult[GetSignalsResponse]
adcp.types.core.TaskResult[GetTaskStatusResponse]
adcp.types.core.TaskResult[IdentityMatchResponseRouterPublisher]
adcp.types.core.TaskResult[ListAccountChangesResponse]
adcp.types.core.TaskResult[ListAccountsResponse]
adcp.types.core.TaskResult[ListCollectionListsResponse]
adcp.types.core.TaskResult[ListContentStandardsResponse]
adcp.types.core.TaskResult[ListCreativeFormatsResponse]
adcp.types.core.TaskResult[ListCreativesResponse]
adcp.types.core.TaskResult[ListCreativesResponse]
adcp.types.core.TaskResult[ListPropertyListsResponse]
adcp.types.core.TaskResult[ListTasksResponse]
adcp.types.core.TaskResult[ListTransformersResponseCreativeAgent]
adcp.types.core.TaskResult[ReportPlanAdjustmentResponse]
adcp.types.core.TaskResult[ReportPlanOutcomeResponse]
adcp.types.core.TaskResult[ReportUsageResponse]
adcp.types.core.TaskResult[SiGetOfferingResponse]
adcp.types.core.TaskResult[SiInitiateSessionResponse]
adcp.types.core.TaskResult[SiSendMessageResponse]
adcp.types.core.TaskResult[SiTerminateSessionResponse]
adcp.types.core.TaskResult[SyncAgentNotificationConfigsResponse]
adcp.types.core.TaskResult[SyncGovernanceResponse]
adcp.types.core.TaskResult[SyncPlansResponse]
adcp.types.core.TaskResult[SyncPrincipalResponse]
adcp.types.core.TaskResult[SyncReportingReceiptsResponse]
adcp.types.core.TaskResult[SyncReportingStatusResponse]
adcp.types.core.TaskResult[Union[AcquireRightsResponse1, AcquireRightsResponse2, AcquireRightsResponse3, AcquireRightsResponse4]]
adcp.types.core.TaskResult[Union[ActivateSignalResponse1, ActivateSignalResponse2]]
adcp.types.core.TaskResult[Union[BuildCreativeResponse1, BuildCreativeResponse2, BuildCreativeResponse3, BuildCreativeResponse4, BuildCreativeResponse5, BuildCreativeResponse6]]
adcp.types.core.TaskResult[Union[CalibrateContentResponse1, CalibrateContentResponse2]]
adcp.types.core.TaskResult[Union[CreateMediaBuyResponse1, CreateMediaBuyResponse2, CreateMediaBuyResponse3]]
adcp.types.core.TaskResult[Union[CreateMediaBuyResponse1, CreateMediaBuyResponse2, CreateMediaBuyResponse3]]
adcp.types.core.TaskResult[Union[GetAccountFinancialsResponse1, GetAccountFinancialsResponse2]]
adcp.types.core.TaskResult[Union[GetBrandIdentityResponse1, GetBrandIdentityResponse2]]
adcp.types.core.TaskResult[Union[GetContentStandardsResponse1, GetContentStandardsResponse2]]
adcp.types.core.TaskResult[Union[GetCreativeFeaturesResponse1, GetCreativeFeaturesResponse2, GetCreativeFeaturesResponse3]]
adcp.types.core.TaskResult[Union[GetMediaBuyArtifactsResponse1, GetMediaBuyArtifactsResponse2]]
adcp.types.core.TaskResult[Union[GetRightsResponse1, GetRightsResponse2]]
adcp.types.core.TaskResult[Union[LogEventResponse1, LogEventResponse2]]
adcp.types.core.TaskResult[Union[PreviewCreativeResponse1, PreviewCreativeResponse2, PreviewCreativeResponse3, PreviewCreativeResponse4]]
adcp.types.core.TaskResult[Union[ProvidePerformanceFeedbackResponse1, ProvidePerformanceFeedbackResponse2]]
adcp.types.core.TaskResult[Union[SyncAccountsResponse1, SyncAccountsResponse2]]
adcp.types.core.TaskResult[Union[SyncAudiencesResponse1, SyncAudiencesResponse2, SyncAudiencesResponse3]]
adcp.types.core.TaskResult[Union[SyncCatalogsResponse1, SyncCatalogsResponse2, SyncCatalogsResponse3]]
adcp.types.core.TaskResult[Union[SyncCreativesResponse1, SyncCreativesResponse2, SyncCreativesResponse3]]
adcp.types.core.TaskResult[Union[SyncEventSourcesResponse1, SyncEventSourcesResponse2]]
adcp.types.core.TaskResult[Union[UpdateMediaBuyResponse1, UpdateMediaBuyResponse2, UpdateMediaBuyResponse3]]
adcp.types.core.TaskResult[Union[UpdateMediaBuyResponse1, UpdateMediaBuyResponse2, UpdateMediaBuyResponse3]]
adcp.types.core.TaskResult[Union[UpdateRightsResponse1, UpdateRightsResponse2]]
adcp.types.core.TaskResult[Union[ValidateContentDeliveryResponse1, ValidateContentDeliveryResponse2]]
adcp.types.core.TaskResult[UpdateCollectionListResponse]
adcp.types.core.TaskResult[UpdateContentStandardsResponse]
adcp.types.core.TaskResult[UpdatePropertyListResponse]

Class variables

var adcp_error : dict[str, typing.Any] | None
var data : ~T | None
var debug_info : DebugInfo | None
var error : str | None
var idempotency_key : str | None
var message : str | None
var metadata : dict[str, typing.Any] | None
var model_config
var needs_input : NeedsInputInfo | None
var replayed : bool
var status : TaskStatus
var submitted : SubmittedInfo | None
var success : bool

class GeneratedTaskStatus (*args, **kwds)

Expand source code

class TaskStatus(StrEnum):
    submitted = 'submitted'
    working = 'working'
    input_required = 'input-required'
    completed = 'completed'
    canceled = 'canceled'
    failed = 'failed'
    rejected = 'rejected'
    auth_required = 'auth-required'
    unknown = 'unknown'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var auth_required
var canceled
var completed
var failed
var input_required
var rejected
var submitted
var unknown
var working

class TaskType (*args, **kwds)

Expand source code

class TaskType(StrEnum):
    create_media_buy = 'create_media_buy'
    update_media_buy = 'update_media_buy'
    buy_products = 'buy_products'
    accept_proposal = 'accept_proposal'
    control_media_buy = 'control_media_buy'
    media_buy_delivery = 'media_buy_delivery'
    sync_creatives = 'sync_creatives'
    build_creative = 'build_creative'
    preview_creative = 'preview_creative'
    get_creative_features = 'get_creative_features'
    activate_signal = 'activate_signal'
    get_products = 'get_products'
    request_proposals = 'request_proposals'
    refine_proposals = 'refine_proposals'
    decline_proposals = 'decline_proposals'
    get_signals = 'get_signals'
    create_property_list = 'create_property_list'
    update_property_list = 'update_property_list'
    get_property_list = 'get_property_list'
    list_property_lists = 'list_property_lists'
    delete_property_list = 'delete_property_list'
    sync_accounts = 'sync_accounts'
    get_account_financials = 'get_account_financials'
    get_creative_delivery = 'get_creative_delivery'
    sync_event_sources = 'sync_event_sources'
    sync_audiences = 'sync_audiences'
    sync_catalogs = 'sync_catalogs'
    log_event = 'log_event'
    get_brand_identity = 'get_brand_identity'
    search_brands = 'search_brands'
    get_rights = 'get_rights'
    acquire_rights = 'acquire_rights'
    update_rights = 'update_rights'
    sync_agent_notification_configs = 'sync_agent_notification_configs'
    sync_principal = 'sync_principal'
    get_principal = 'get_principal'
    sync_reporting_status = 'sync_reporting_status'
    sync_reporting_receipts = 'sync_reporting_receipts'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var accept_proposal
var acquire_rights
var activate_signal
var build_creative
var buy_products
var control_media_buy
var create_media_buy
var create_property_list
var decline_proposals
var delete_property_list
var get_account_financials
var get_brand_identity
var get_creative_delivery
var get_creative_features
var get_principal
var get_products
var get_property_list
var get_rights
var get_signals
var list_property_lists
var log_event
var media_buy_delivery
var preview_creative
var refine_proposals
var request_proposals
var search_brands
var sync_accounts
var sync_agent_notification_configs
var sync_audiences
var sync_catalogs
var sync_creatives
var sync_event_sources
var sync_principal
var sync_reporting_receipts
var sync_reporting_status
var update_media_buy
var update_property_list
var update_rights

class WebhookChallenge (**data: Any)

Expand source code

class WebhookChallenge(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    type: Annotated[
        Literal['webhook.challenge'],
        Field(description='Discriminator for endpoint proof-of-control challenges.'),
    ] = 'webhook.challenge'
    challenge: Annotated[
        str,
        Field(
            description='Opaque, cryptographically random value that the receiver must echo in the response body. Recommended encoding: base64url without padding.',
            max_length=255,
            min_length=32,
            pattern='^[A-Za-z0-9_.:-]{32,255}$',
        ),
    ]
    account_id: Annotated[
        str,
        Field(
            description='Seller account identifier for the account whose notification_configs[] entry is being challenged.'
        ),
    ]
    subscriber_id: Annotated[
        str,
        Field(
            description='Buyer-supplied subscriber identifier from the notification_configs[] entry being challenged.',
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    seller_agent_url: Annotated[
        AnyUrl,
        Field(
            description='Exact seller agent URL whose RFC 9421 webhook profile key signs this challenge and that will send subsequent webhooks.'
        ),
    ]
    delivery_auth: Annotated[
        DeliveryAuth,
        Field(
            description='Authentication/signing mode the seller will use for subsequent webhooks delivered to this notification config.'
        ),
    ]
    event_types: Annotated[
        list[notification_type.NotificationType],
        Field(
            description='Normalized notification types requested by the subscriber at the time of the challenge. Part of the endpoint proof scope; changing event_types[] requires a fresh challenge before the new set can become active.',
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account_id : str
var challenge : str
var delivery_auth : DeliveryAuth
var event_types : list[NotificationType]
var model_config
var seller_agent_url : pydantic.networks.AnyUrl
var subscriber_id : str
var type : Literal['webhook.challenge']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class WebhookChallengeResponse (**data: Any)

Expand source code

class WebhookChallengeResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    challenge: Annotated[
        str | None,
        Field(
            description='Echo of the challenge value supplied by the seller.',
            max_length=255,
            min_length=32,
            pattern='^[A-Za-z0-9_.:-]{32,255}$',
        ),
    ] = None
    token: Annotated[
        str | None,
        Field(
            description='Backward-compatible alias for `challenge`. Receivers SHOULD prefer `challenge`; sellers MUST accept either field.',
            max_length=255,
            min_length=32,
            pattern='^[A-Za-z0-9_.:-]{32,255}$',
        ),
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> WebhookChallengeResponse:
        # ``required`` asks whether the caller supplied the field, which is what
        # model_fields_set answers. An explicit null is a supplied value — on a
        # mutation input it is the command to clear — and a default the caller
        # never sent is not.
        for group in (('challenge',), ('token',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'WebhookChallengeResponse requires at least one of these field groups: challenge | token'
        )

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var challenge : str | None
var model_config
var token : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class WebhookMetadata (**data: Any)

Expand source code

class WebhookMetadata(BaseModel):
    """Metadata passed to webhook handlers."""

    operation_id: str
    agent_id: str
    task_type: str
    status: TaskStatus
    sequence_number: int | None = None
    notification_type: Literal["scheduled", "final", "delayed"] | None = None
    timestamp: str

Metadata passed to webhook handlers.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var agent_id : str
var model_config
var notification_type : Literal['scheduled', 'final', 'delayed'] | None
var operation_id : str
var sequence_number : int | None
var status : TaskStatus
var task_type : str
var timestamp : str

class WebhookResponseType (*args, **kwds)

Expand source code

class WebhookResponseType(StrEnum):
    html = 'html'
    json = 'json'
    xml = 'xml'
    javascript = 'javascript'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var html
var javascript
var json
var xml