Module adcp.types

AdCP Type System.

All AdCP types exported from a single location. Users should import from here or directly from adcp.

from adcp.types import Product, CreativeFilters
from adcp import Product, CreativeFilters

This package is lazy: import adcp.types is cheap and does not build the generated Pydantic schema graph. The graph (and its import-time coercion / forward-compat patching) is realized on first access to any type symbol, via :mod:adcp.types._eager. So from adcp.types import Product works as a stable compatibility path, resolved through __getattr__ (PEP 562).

For a narrower, curated surface, import a partial module instead:

from adcp.types.media_buy import CreateMediaBuyRequest
from adcp.types.creative import Format
from adcp.types.signals import GetSignalsRequest
from adcp.types.protocol import Error, Pagination
from adcp.types.buyer import GetProductsRequest
from adcp.types.seller import Offering, PropertyList

When the flat namespace cannot bind a name — two schemas declare the same class name, or a numbered variant has no semantic alias — import it by its schema path under adcp.types.domains, which mirrors the bundle's layout and is where codegen defines every class (see docs/type-surface.md):

from adcp.types.domains.creative.list_creatives_response import Creative

Never import from adcp.types._generated, adcp.types._eager or any other underscore-prefixed module: those are internal and change without notice. The pre-9.0 adcp.types.generated_poc path still resolves with a DeprecationWarning and is removed in v10; adcp migrate v3-to-v4 --apply<code> rewrites it to </code>adcp.types.domains.

Type Coercion: Request types accept flexible input for developer ergonomics:

- Enum fields accept string values:
    LegacyListCreativeFormatsRequest(type="video")  # Explicit legacy API

- Context fields accept dicts:
    GetProductsRequest(context={"key": "value"})  # Works!

- FieldModel lists accept strings:
    ListCreativesRequest(fields=["creative_id", "name"])  # Works!

See adcp.types._ergonomic for implementation details.

Sub-modules

adcp.types.aliases

Semantic type aliases for generated AdCP types …

adcp.types.base

adcp.types.buyer

AdCP buyer types — curated partial surface …

adcp.types.canonical_creative

Canonical-first creative models for the Python 7 public API …

adcp.types.canonical_decl

Wire-faithful Format for the v2 catalog surface …

adcp.types.capabilities

Capability sub-models surfaced from the bundled get_adcp_capabilities_response schema …

adcp.types.coercion

Type coercion utilities for improved type ergonomics …

adcp.types.core

Core type definitions.

adcp.types.creative

AdCP creative types — curated partial surface …

adcp.types.domains

Public types grouped by the AdCP schema that declares them …

adcp.types.error_details

The AdCP structured error-details models, with their field types …

adcp.types.error_narrowing

Narrow pydantic discriminated-union ValidationErrors to the variant the user actually intended …

adcp.types.guards

Type guards for ADCP discriminated union responses …

adcp.types.legacy

Explicit raw/legacy creative wire types …

adcp.types.media_buy

AdCP media buy types — curated partial surface …

adcp.types.media_buy_status_helpers

Shared helpers for media-buy lifecycle status compatibility …

adcp.types.projections

Response-shape projections that strip write-only fields …

adcp.types.protocol

AdCP protocol types — curated partial surface …

adcp.types.registry

Registry API types generated from OpenAPI spec …

adcp.types.response_dispatch

Compatibility dispatch for constructible generated response bases.

adcp.types.seller

AdCP seller types — curated partial surface …

adcp.types.signals

AdCP signals types — curated partial surface …

adcp.types.v30

Public AdCP 3.0 boundary models with a generated static typing stub.

adcp.types.v31

Public AdCP 3.1 boundary models with a generated static typing stub.

adcp.types.v32

Public AdCP 3.2 beta boundary models with a generated static typing stub.

adcp.types.variants

Schema-variant marker for cross-class entity overrides (#710) …

adcp.types.versioned

Version-scoped Pydantic models backed by bundled AdCP JSON Schemas …

adcp.types.versioned_bases

Named, subclassable bases pinned to bundled protocol schemas …

Functions

def is_canonical_format_kind(value: object,
vocabulary: Iterable[str] = adcp.types.domains.core.canonical_format_kind.CanonicalFormatKind) ‑> bool

Expand source code

def is_canonical_format_kind(
    value: object,
    vocabulary: Iterable[str] = CanonicalFormatKind,
) -> bool:
    """Is *value* one of *vocabulary*'s format kinds?

    The vocabulary defaults to :class:`CanonicalFormatKind`, the sixteen kinds
    the pinned AdCP bundle declares — but it is a PARAMETER, because the set
    that matters is the seller's, not this SDK's. A seller may support a kind
    promoted in a spec newer than the pin, or only four of the sixteen, and
    neither is expressible by anything this library knows.

    **The SDK never calls this for you.** ``format_kind`` is a ``str``
    everywhere, on the way out and on the way back, and no model refuses a
    value. That is deliberate: a pinned library cannot tell "a kind the seller
    invented" from "a kind defined after my pin", so refusing the second to
    prevent the first would make this SDK's version a ceiling on what the
    protocol permits. "I accept the request and then tell you I cannot process
    this creative" is a seller's answer, not a type error.

    This function is the sanctioned way to be strict, where the caller knows
    which spec version its counterpart speaks::

        from adcp.types import is_canonical_format_kind

        if not is_canonical_format_kind(creative.format_kind):
            route_as_declared_but_unsupported(creative)

        if not is_canonical_format_kind(manifest.format_kind, MY_SUPPORTED_KINDS):
            reject_with_unsupported_format(manifest)

    Comparison needs no helper: ``CanonicalFormatKind`` is a ``StrEnum``, so
    ``creative.format_kind == CanonicalFormatKind.image`` holds against a plain
    string field and an adopter never writes a literal.
    """

    return isinstance(value, str) and any(value == kind for kind in vocabulary)

Is value one of vocabulary's format kinds?

The vocabulary defaults to :class:CanonicalFormatKind, the sixteen kinds the pinned AdCP bundle declares — but it is a PARAMETER, because the set that matters is the seller's, not this SDK's. A seller may support a kind promoted in a spec newer than the pin, or only four of the sixteen, and neither is expressible by anything this library knows.

The SDK never calls this for you. format_kind is a str everywhere, on the way out and on the way back, and no model refuses a value. That is deliberate: a pinned library cannot tell "a kind the seller invented" from "a kind defined after my pin", so refusing the second to prevent the first would make this SDK's version a ceiling on what the protocol permits. "I accept the request and then tell you I cannot process this creative" is a seller's answer, not a type error.

This function is the sanctioned way to be strict, where the caller knows which spec version its counterpart speaks::

from adcp.types import is_canonical_format_kind

if not is_canonical_format_kind(creative.format_kind):
    route_as_declared_but_unsupported(creative)

if not is_canonical_format_kind(manifest.format_kind, MY_SUPPORTED_KINDS):
    reject_with_unsupported_format(manifest)

Comparison needs no helper: CanonicalFormatKind is a StrEnum, so creative.format_kind == CanonicalFormatKind.image holds against a plain string field and an adopter never writes a literal.

def project_geo_postal_areas(value: GeoPostalAreas | Mapping[str, Any],
version: str | None) ‑> dict[str, typing.Any]

Expand source code

def project_geo_postal_areas(
    value: GeoPostalAreas | Mapping[str, Any],
    version: str | None,
) -> dict[str, Any]:
    """Project postal capability declarations for the caller's AdCP version.

    AdCP 3.1 introduced native country-keyed postal capabilities such as
    ``{"US": ["zip"]}``. AdCP 3.0 clients expect the deprecated fused
    booleans such as ``{"us_zip": true}``. This helper lets sellers keep
    one typed :class:`GeoPostalAreas` declaration and serializes only the
    shape the caller negotiated.

    Native systems with no legacy 3.0 alias (currently BR ``cep``, IN
    ``pin``, and ZA ``postal_code``) are omitted from 3.0 projections.
    Legacy booleans set to ``False`` are treated as absent so projection
    never invents support.
    """
    payload = _geo_postal_payload(value)
    if _is_native_geo_postal_version(version):
        projected: dict[str, list[str]] = {}
        for country, systems in _iter_native_postal_systems(payload):
            for system in systems:
                _append_unique(projected, country, _postal_system_value(system))
        for legacy in LegacyPostalCodeSystem:
            if payload.get(legacy.value) is not True:
                continue
            country, system = _LEGACY_TO_NATIVE_POSTAL[legacy.value]
            _append_unique(projected, country, system)
        return projected

    projected_legacy: dict[str, bool] = {}
    for country, systems in _iter_native_postal_systems(payload):
        for system in systems:
            legacy_alias = _NATIVE_TO_LEGACY_POSTAL.get((country, _postal_system_value(system)))
            if legacy_alias is not None:
                projected_legacy[legacy_alias.value] = True
    for legacy in LegacyPostalCodeSystem:
        if payload.get(legacy.value) is True:
            projected_legacy[legacy.value] = True
    return projected_legacy

Project postal capability declarations for the caller's AdCP version.

AdCP 3.1 introduced native country-keyed postal capabilities such as {"US": ["zip"]}. AdCP 3.0 clients expect the deprecated fused booleans such as {"us_zip": true}. This helper lets sellers keep one typed :class:GeoPostalAreas declaration and serializes only the shape the caller negotiated.

Native systems with no legacy 3.0 alias (currently BR cep, IN pin, and ZA postal_code) are omitted from 3.0 projections. Legacy booleans set to False are treated as absent so projection never invents support.

def to_account_response(account: Account) ‑> AccountResponse

Expand source code

def to_account_response(account: Account) -> AccountResponse:
    """Project an internal ``Account`` to its response shape.

    Strips ``billing_entity.bank`` and notification authentication credentials,
    then returns an :class:`AccountResponse`.
    The remaining fields (legal_name, tax_id, address, contacts, vat_id,
    registration_number, ext) round-trip unchanged. ``reporting_bucket``,
    ``governance_agents``, and other non-write-only fields are preserved.

    Raises:
        ValidationError: if the source ``Account`` fails revalidation
            against the response shape (other than the bank strip).
    """
    payload = account.model_dump(mode="python")
    if isinstance(payload.get("billing_entity"), dict):
        payload["billing_entity"].pop("bank", None)
    for config in payload.get("notification_configs") or []:
        if isinstance(config, dict) and isinstance(config.get("authentication"), dict):
            config["authentication"].pop("credentials", None)
    return AccountResponse.model_validate(payload)

Project an internal Account to its response shape.

Strips billing_entity.bank and notification authentication credentials, then returns an :class:AccountResponse. The remaining fields (legal_name, tax_id, address, contacts, vat_id, registration_number, ext) round-trip unchanged. reporting_bucket, governance_agents, and other non-write-only fields are preserved.

Raises

-----=

ValidationError

if the source Account fails revalidation against the response shape (other than the bank strip).

Classes

class A2UiComponent (**data: Any)

Expand source code

class A2UiComponent(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    id: Annotated[str, Field(description='Unique identifier for this component within the surface')]
    parentId: Annotated[
        str | None, Field(description='ID of the parent component (null for root)')
    ] = None
    component: Annotated[
        dict[str, dict[str, Any]],
        Field(
            description='Component definition (keyed by component type)', max_length=1, min_length=1
        ),
    ]

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

Class variables

var component : dict[str, dict[str, typing.Any]]

var id : str

var model_config

var parentId : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class A2UiSurface (**data: Any)

Expand source code

class A2UiSurface(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    surfaceId: Annotated[str, Field(description='Unique identifier for this surface')]
    catalogId: Annotated[
        str | None, Field(description='Component catalog to use for rendering')
    ] = 'standard'
    components: Annotated[
        list[component.A2UiComponent],
        Field(description='Flat list of components (adjacency list structure)'),
    ]
    rootId: Annotated[
        str | None,
        Field(description='ID of the root component (if not specified, first component is root)'),
    ] = None
    dataModel: Annotated[
        dict[str, Any] | None, Field(description='Application data that components can bind to')
    ] = 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

Class variables

var catalogId : str | None

var components : list[A2UiComponent]

var dataModel : dict[str, typing.Any] | None

var model_config

var rootId : str | None

var surfaceId : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AcceptProposalRequest (**data: Any)

Expand source code

class AcceptProposalRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str, Field(max_length=255, min_length=16, pattern='^[A-Za-z0-9_.:-]{16,255}$')
    ]
    name: Annotated[
        str | None,
        Field(
            description='Human-readable MediaBuy name supplied by the buyer for trafficking UI display and operational communication. When supplied, this value wins over proposal.name; the seller MUST persist it and echo it unchanged on the commitment success response and subsequent get_media_buys reads. It is operational metadata outside accepted_proposal and is not covered by proposal_terms_digest or terms_digest. When an acceptance creates a MediaBuy and name is absent, the seller MAY seed the MediaBuy name from proposal.name only when proposal.name already satisfies the MediaBuy name constraints (non-whitespace and no longer than 255 characters); the seller MUST NOT silently truncate or otherwise rewrite it. A seeded value counts as a name created through AdCP and MUST be reported on commitment and read surfaces. This display label is not an identifier or financial reference.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    account: canonical_account_ref.CanonicalAccountReference
    proposal_id: Annotated[str, Field(min_length=1)]
    proposal_terms_digest: Annotated[
        str,
        Field(
            description='terms_digest from the committed proposal. The seller MUST atomically verify both ID and digest before acceptance.',
            pattern='^sha256:[A-Za-z0-9_-]{43}$',
        ),
    ]
    total_budget: Annotated[
        TotalBudget | None,
        Field(
            description='Execution amount when the committed proposal defines scalable percentages or constraints rather than a fixed total.'
        ),
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Optional hard aggregate daily spend ceiling applied when the committed proposal is accepted. It constrains execution without changing the proposal's negotiated pricing.",
            ge=0.0,
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='Optional shared IANA cap-day timezone override. Requires buyer_timezone_override support. When omitted, budget_capping.timezone_basis selects Account.timezone or fixed_timezone.',
            min_length=1,
        ),
    ] = None
    io_acceptance: IoAcceptance | None = None
    purchase_order_ref: Annotated[str | None, Field(max_length=255, min_length=1)] = None
    governance_context: Annotated[str | None, Field(max_length=4096, min_length=1)] = None
    push_notification_config: push_notification_config_1.PushNotificationConfig | None = None
    reporting_webhook: Annotated[
        reporting_webhook_1.ReportingWebhook | None,
        Field(
            description='Optional reporting delivery configuration established atomically when the proposal is accepted. This is execution metadata and does not alter the accepted commercial terms digest.'
        ),
    ] = None
    opportunity: Annotated[
        Opportunity | None,
        Field(
            description='Optional planning-cycle closure. Success infers closed with accepted_with_seller when status is omitted. If the proposal carries opportunity_id, a supplied ID MUST match; the accepted proposal preserves that association.'
        ),
    ] = 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 account : CanonicalAccountReference1 | CanonicalAccountReference2

var budget_cap_timezone : str | None

var context : ContextObject | None

var daily_budget_cap : float | None

var ext : ExtensionObject | None

var governance_context : str | None

var idempotency_key : str

var io_acceptance : IoAcceptance | None

var model_config

var name : str | None

var opportunity : Opportunity | None

var proposal_id : str

var proposal_terms_digest : str

var purchase_order_ref : str | None

var push_notification_config : PushNotificationConfig | None

var reporting_webhook : ReportingWebhook | None

var total_budget : TotalBudget | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 AcceptanceContext (**data: Any)

Expand source code

class AcceptanceContext(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    subjects: Annotated[list[Subject] | None, Field(min_length=1)] = None
    advertiser_roles: Annotated[list[AdvertiserRole] | None, Field(min_length=1)] = None
    advertiser_industry: advertiser_industry_1.AdvertiserIndustry | None = None
    advertiser_jurisdictions: Annotated[
        list[AdvertiserJurisdiction] | None,
        Field(
            description='Jurisdictions in which the advertiser is established or legally organized. This is distinct from where an ad will be delivered.',
            min_length=1,
        ),
    ] = None
    delivery_jurisdictions: Annotated[
        list[DeliveryJurisdiction] | None,
        Field(
            description="Jurisdictions in which the proposed advertising will be delivered. Seller acceptance rules' jurisdictions and jurisdiction_groups match this field.",
            min_length=1,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var advertiser_industry : AdvertiserIndustry | None

var advertiser_jurisdictions : list[AdvertiserJurisdiction] | None

var advertiser_roles : list[AdvertiserRole] | None

var delivery_jurisdictions : list[DeliveryJurisdiction] | None

var ext : ExtensionObject | None

var model_config

var subjects : list[Subject] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AcceptancePolicyCatalog (**data: Any)

Expand source code

class AcceptancePolicyCatalog(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    catalog_version: Annotated[str, Field(min_length=1)]
    generated_at: AwareDatetime | None = None
    profiles: Annotated[
        list[acceptance_policy_profile.AcceptancePolicyProfile] | None, Field(min_length=1)
    ] = None
    registry_profiles: Annotated[
        list[acceptance_policy_profile_ref.RegistryAcceptancePolicyProfileReference] | None,
        Field(
            description='Exact reusable profiles adopted from the shared policy registry. Resolution failure is unknown, never allowed. A seller adds a distinct local profile to narrow a registry profile.',
            min_length=1,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> AcceptancePolicyCatalog:
        # ``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 (('profiles',), ('registry_profiles',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'AcceptancePolicyCatalog requires at least one of these field groups: profiles | registry_profiles'
        )

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

Class variables

var catalog_version : str

var ext : ExtensionObject | None

var generated_at : pydantic.types.AwareDatetime | None

var model_config

var profiles : list[AcceptancePolicyProfile] | None

var registry_profiles : list[RegistryAcceptancePolicyProfileReference] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AcceptancePolicyDiscovery (**data: Any)

Expand source code

class AcceptancePolicyDiscovery(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    catalog_url: Annotated[
        AnyUrl,
        Field(description='HTTPS document that validates against acceptance-policy-catalog.json.'),
    ]
    catalog_digest: Annotated[
        str,
        Field(
            description='SHA-256 digest of the exact catalog representation fetched from catalog_url.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ]
    default_profile_ids: Annotated[
        list[DefaultProfileId] | None,
        Field(
            description='Local or registry-referenced catalog profiles that apply seller-wide unless a product adds further profiles. IDs MUST resolve uniquely across profiles and registry_profiles; all referenced profiles compose restrictively.',
            min_length=1,
        ),
    ] = 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

Class variables

var catalog_digest : str

var catalog_url : pydantic.networks.AnyUrl

var default_profile_ids : list[DefaultProfileId] | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AcceptancePolicyProfile (**data: Any)

Expand source code

class AcceptancePolicyProfile(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    profile_id: Annotated[str, Field(pattern='^[A-Za-z0-9_.:-]+$')]
    version: Annotated[str, Field(min_length=1)]
    content_digest: Annotated[
        str,
        Field(
            description='SHA-256 digest of the RFC 8785 JCS serialization of this profile with content_digest omitted. A profile_id/version pair is immutable; consumers reject a resolved profile whose digest differs.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ]
    policy_refs: Annotated[
        list[PolicyRef],
        Field(
            description='Exact registry policy versions from which this profile was derived. Consumers MUST NOT silently substitute a different version.',
            min_length=1,
        ),
    ]
    coverage: Annotated[
        Coverage,
        Field(
            description='partial means additional unpublished rules may apply and omission is unknown. complete means this profile is exhaustive only for its declared scope and version.'
        ),
    ]
    scope: Annotated[
        Scope | None,
        Field(
            description='The boundary within which a complete profile claims exhaustiveness. It is informative for partial profiles and mandatory for complete profiles.'
        ),
    ] = None
    region_aliases: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[A-Z][A-Z0-9_-]*$')], list[RegionAliase]] | None,
        Field(
            description='Profile-local named country groups. Rules may reference only keys declared here; consumers expand them before matching.'
        ),
    ] = None
    description: Annotated[str | None, Field(min_length=1)] = None
    rules: Annotated[list[acceptance_policy_rule.AcceptancePolicyRule], Field(min_length=1)]
    ext: ext_1.ExtensionObject | None = 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

Class variables

var content_digest : str

var coverage : Coverage

var description : str | None

var ext : ExtensionObject | None

var model_config

var policy_refs : list[PolicyRef]

var profile_id : str

var region_aliases : dict[str, list[RegionAliase]] | None

var rules : list[AcceptancePolicyRule]

var scope : Scope | None

var version : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AcceptancePolicyProfileId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class AcceptancePolicyProfileId(ScalarStr):
    __slots__ = ()
    _constraints = {'min_length': 1}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class AcceptancePolicyProfileIds (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class AcceptancePolicyProfileIds(RootModel[list[AcceptancePolicyProfileId]]):
    root: Annotated[
        list[AcceptancePolicyProfileId],
        Field(
            description='Acceptance-policy profiles from the seller catalog that apply to this product in addition to seller defaults. Profiles compose restrictively; the most restrictive matching disposition wins.',
            min_length=1,
            title='Acceptance Policy Profile IDs',
        ),
    ]

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

-----=

root

The root object of the model.

__pydantic_root_model__

Whether the model is a RootModel.

__pydantic_private__

Private fields in the model.

__pydantic_extra__

Extra fields in the model.

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.root_model.RootModel[list[AcceptancePolicyProfileId]]
• pydantic.root_model.RootModel
• pydantic.main.BaseModel
• typing.Generic

Class variables

var model_config

var root : list[AcceptancePolicyProfileId]

class AcceptancePolicyRule (**data: Any)

Expand source code

class AcceptancePolicyRule(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    rule_id: Annotated[str, Field(pattern='^[A-Za-z0-9_.:-]+$')]
    subject_category: Annotated[
        str,
        Field(
            description='Registry policy-category-definition category_id. Named subject_category to avoid collision with PolicyEntry.category, whose values are regulation and standard.',
            pattern='^[a-z][a-z0-9_]*$',
        ),
    ]
    subject_facets: Annotated[
        list[SubjectFacet] | None,
        Field(
            description='Facet IDs defined by the selected policy category. Omission means the rule applies to every facet in the category.',
            min_length=1,
        ),
    ] = None
    advertiser_roles: Annotated[
        list[AdvertiserRole] | None,
        Field(
            description='Registry-extensible roles such as political_actor, election_authority, government_entity, news_publisher, or commercial_advertiser.',
            min_length=1,
        ),
    ] = None
    jurisdictions: Annotated[
        list[Jurisdiction] | None,
        Field(
            description='Delivery jurisdictions where this rule applies. Omission means every jurisdiction served by the seller.',
            min_length=1,
        ),
    ] = None
    jurisdiction_groups: Annotated[
        list[JurisdictionGroup] | None,
        Field(
            description="Named country groups declared by the containing profile's region_aliases. Unknown group IDs invalidate the profile; they never match permissively.",
            min_length=1,
        ),
    ] = None
    applies_to: Annotated[list[AppliesToEnum], Field(min_length=1)]
    disposition: Disposition
    requirements: Annotated[
        list[acceptance_policy_requirement.AcceptancePolicyRequirement] | None, Field(min_length=1)
    ] = None
    policy_ids: Annotated[
        list[PolicyId] | None,
        Field(
            description='Registry policies that define the exact obligations behind this coarse rule.',
            min_length=1,
        ),
    ] = None
    description: Annotated[
        str | None,
        Field(
            description='Display-only explanation. Matchers MUST NOT interpret this text as executable instructions or use it to override typed fields.',
            max_length=1000,
            min_length=1,
        ),
    ] = None
    effective_at: AwareDatetime | None = None
    expires_at: AwareDatetime | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var advertiser_roles : list[AdvertiserRole] | None

var applies_to : list[AppliesToEnum]

var description : str | None

var disposition : Disposition

var effective_at : pydantic.types.AwareDatetime | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var jurisdiction_groups : list[JurisdictionGroup] | None

var jurisdictions : list[Jurisdiction] | None

var model_config

var policy_ids : list[PolicyId] | None

var requirements : list[AcceptancePolicyRequirement1 | AcceptancePolicyRequirement2 | AcceptancePolicyRequirement3 | AcceptancePolicyRequirement4 | AcceptancePolicyRequirement5 | AcceptancePolicyRequirement6 | AcceptancePolicyRequirement7 | AcceptancePolicyRequirement8 | AcceptancePolicyRequirement9 | AcceptancePolicyRequirement10 | AcceptancePolicyRequirement11 | AcceptancePolicyRequirement12 | AcceptancePolicyRequirement13 | AcceptancePolicyRequirement14 | AcceptancePolicyRequirement15 | AcceptancePolicyRequirement16 | AcceptancePolicyRequirement17] | None

var rule_id : str

var subject_category : str

var subject_facets : list[SubjectFacet] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AcceptedLoss (*args, **kwds)

Expand source code

class AcceptedLoss(StrEnum):
    feed_version_not_atomic = 'feed_version_not_atomic'
    pricing_version_not_atomic = 'pricing_version_not_atomic'
    mutation_idempotency_not_guaranteed = 'mutation_idempotency_not_guaranteed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var feed_version_not_atomic

var mutation_idempotency_not_guaranteed

var pricing_version_not_atomic

class AccessibilityViolationDetails (**data: Any)

Expand source code

class AccessibilityViolationDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    violations: Annotated[
        list[Violation],
        Field(
            description='Accessibility requirements the creative or its assets failed. This is distinct from error.issues, which carries JSON Schema validator failures.',
            max_length=4,
            min_length=1,
        ),
    ]
    truncated: Annotated[
        StrictBool | None,
        Field(
            description='True when the producer omitted additional violations or remediation text to keep the complete serialized error within the 4096-byte transport safety limit. Omission means false.'
        ),
    ] = 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

Class variables

var model_config

var truncated : bool | None

var violations : list[Violation]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Account (**data: Any)

Expand source code

class Account(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    account_id: Annotated[str, Field(description='Unique identifier for this account')]
    name: Annotated[
        str, Field(description="Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle')")
    ]
    advertiser: Annotated[
        str | None, Field(description='The advertiser whose rates apply to this account')
    ] = None
    billing_proxy: Annotated[
        str | None,
        Field(
            description='Optional intermediary who receives invoices on behalf of the advertiser (e.g., agency)'
        ),
    ] = None
    status: Annotated[
        account_status.AccountStatus,
        Field(
            description='Account lifecycle status. See the Accounts Protocol overview for the operations matrix showing which tasks are permitted in each state.'
        ),
    ]
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(description='Brand reference identifying the advertiser'),
    ] = None
    operator: Annotated[
        str | None,
        Field(
            description="Domain of the entity operating this account. When the brand operates directly, this is the brand's domain.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    operator_unit: Annotated[
        operator_unit_1.OperatorUnit | None,
        Field(
            description='Operator-owned business unit, agency seat, or platform account associated with this advertiser account. The id round-trips from the natural key; name is mutable display metadata. This is distinct from account_id, which belongs to the seller/storefront namespace.'
        ),
    ] = None
    revision: Annotated[
        SchemaInt | None,
        Field(
            description='Monotonically increasing optimistic-concurrency token for this account. Incremented on every persisted settings change, identity-change request, and identity-change disposition; reads, dry runs, validation failures, and exact idempotency replays do not increment it. Pass the latest observed value in a sync_accounts settings-update entry to prevent lost updates.',
            ge=1,
        ),
    ] = None
    identity_change: Annotated[
        account_identity_change.AccountIdentityChange | None,
        Field(
            description='Pending or rejected operator-identity transition. While present, the top-level operator and operator_unit remain the current canonical identity. Re-read list_accounts until the request is applied (canonical fields change and this object disappears) or rejected.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description="Immutable transaction currency when the seller's advertiser object is currency-bound. Media buys on this account MUST use this currency. Omit when the account selects currency independently per media buy.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    timezone: Annotated[
        str | None,
        Field(
            description='Immutable operational timezone for this account, expressed as UTC or an IANA timezone identifier. AdCP 3.2 sellers return it on every account. It is the default calendar-day boundary for account-scoped behavior unless a feature explicitly declares another timezone basis. For buyer-selected account_fixed provisioning it participates in the natural account key.',
            min_length=1,
        ),
    ] = None
    billing: Annotated[
        billing_party.BillingParty | None,
        Field(
            description="Who is invoiced on this account. See billing_entity for the invoiced party's business details."
        ),
    ] = None
    billing_entity: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description='Current canonical business entity for the party responsible for payment. Contains the legal name, tax IDs, and address needed for formal B2B invoicing. Corresponds to whoever billing points to (operator, agent, or advertiser). When this account appears in a response, bank details MUST be omitted and the request-only destination_billing_entity MUST NOT be exposed.'
        ),
    ] = None
    destination_billing_entity: Annotated[
        Any | None,
        Field(description='Request-only staging field. It MUST NOT appear in account read models.'),
    ] = None
    rate_card: Annotated[
        str | None, Field(description='Identifier for the rate card applied to this account')
    ] = None
    payment_terms: Annotated[
        payment_terms_1.PaymentTerms | None,
        Field(
            description='Payment terms agreed for this account. Binding for all invoices when the account is active.'
        ),
    ] = None
    credit_limit: Annotated[
        CreditLimit | None, Field(description='Maximum outstanding balance allowed')
    ] = None
    setup: Annotated[
        Setup | None,
        Field(
            description="Present when status is 'pending_approval'. Contains next steps for completing account activation."
        ),
    ] = None
    account_scope: account_scope_1.AccountScope | None = None
    governance_agents: Annotated[
        list[GovernanceAgent] | None,
        Field(
            description="Governance agent endpoint registered on this account. Exactly one entry per sync_governance's one-agent-per-account invariant. The array shape is preserved for wire compatibility with 3.0; `maxItems: 1` is load-bearing and mirrors the singular `governance_context` on the protocol envelope. Authentication credentials are write-only and not included in responses — use sync_governance to set or update credentials.",
            max_length=1,
            min_length=1,
        ),
    ] = None
    reporting_bucket: Annotated[
        ReportingBucket | None,
        Field(
            description="Cloud storage bucket where the seller delivers offline reporting files for this account. Seller provisions a dedicated bucket or a per-account prefix within a shared bucket, and grants the buyer read access out-of-band. Access MUST be scoped at the IAM layer so each account can only read its own prefix — bucket-wide grants are non-compliant even with per-account prefixes. Seller MUST revoke access when the account's status transitions to inactive, suspended, or closed. See security considerations for offline delivery in docs/media-buy/media-buys/optimization-reporting. Only present when the seller supports offline delivery (reporting_delivery_methods includes 'offline' in capabilities)."
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(
            description='When true, this is a sandbox account — no real platform calls, no real spend. For account-id namespaces, sandbox accounts are pre-existing test accounts on the platform discovered via list_accounts or supplied out-of-band. For buyer-declared accounts, sandbox is part of the natural key: the same brand/operator pair can have both a production and sandbox account.'
        ),
    ] = None
    notification_configs: Annotated[
        list[notification_config.NotificationConfig] | None,
        Field(
            description='Account-level webhook subscriptions for creative lifecycle/assignment changes, indicators.changed, account status, durable account-change wake-ups, wholesale feed changes, and reporting.delivery_ready. Buyers manage entries via sync_accounts and verify persisted state on list_accounts. account.change_recorded wakes receivers to drain list_account_changes; reporting.delivery_ready is repaired through get_reporting_status; indicator and assignment payloads are invalidations repaired completely through get_media_buys; list_creatives may provide a bounded reverse projection. Distinct from per-resource push_notification_config. Entries are keyed by account-scoped subscriber_id; credentials are write-only.',
            max_length=16,
        ),
    ] = None
    reporting_delivery_configs: Annotated[
        list[reporting_delivery_config_state.ReportingDeliveryConfigurationState] | None,
        Field(
            description="Resolved durable reporting delivery configurations owned by the authenticated caller for this account. list_accounts MUST expose only the calling principal's set. State and seller-issued destination_ref are returned; credentials and bearer profiles MUST NOT appear. Any setup URL is a secret-free authenticated entry point, not a bearer credential.",
            max_length=16,
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook delivery attempts scoped to this account when the caller requested webhook activity on list_accounts and the seller surfaces the log. Includes account-anchored notifications such as account.status_changed and MAY include other account-level fires relevant to this account. Three-state presence follows the shared webhook_activity[] contract: omitted means unsupported or not requested, [] means supported but no retained fires, non-empty lists recent attempts most-recent-first.',
            max_length=200,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

• AccountWithAuthorization
• AccountResponse

Class variables

var account_id : str

var account_scope : AccountScope | None

var advertiser : str | None

var billing : BillingParty | None

var billing_entity : BusinessEntity | None

var billing_proxy : str | None

var brand : BrandReference | None

var credit_limit : CreditLimit | None

var currency : str | None

var destination_billing_entity : typing.Any | None

var ext : ExtensionObject | None

var governance_agents : list[GovernanceAgent] | None

var identity_change : AccountIdentityChange1 | AccountIdentityChange2 | None

var model_config

var name : str

var notification_configs : list[NotificationConfig] | None

var operator : str | None

var operator_unit : OperatorUnit | None

var payment_terms : PaymentTerms | None

var rate_card : str | None

var reporting_bucket : ReportingBucket | None

var reporting_delivery_configs : list[ReportingDeliveryConfigurationState] | None

var revision : int | None

var sandbox : bool | None

var setup : Setup | None

var status : AccountStatus

var timezone : str | None

var webhook_activity : list[WebhookActivityRecord] | None

class CoreAccount (**data: Any)

Expand source code

class Account(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    account_id: Annotated[str, Field(description='Unique identifier for this account')]
    name: Annotated[
        str, Field(description="Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle')")
    ]
    advertiser: Annotated[
        str | None, Field(description='The advertiser whose rates apply to this account')
    ] = None
    billing_proxy: Annotated[
        str | None,
        Field(
            description='Optional intermediary who receives invoices on behalf of the advertiser (e.g., agency)'
        ),
    ] = None
    status: Annotated[
        account_status.AccountStatus,
        Field(
            description='Account lifecycle status. See the Accounts Protocol overview for the operations matrix showing which tasks are permitted in each state.'
        ),
    ]
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(description='Brand reference identifying the advertiser'),
    ] = None
    operator: Annotated[
        str | None,
        Field(
            description="Domain of the entity operating this account. When the brand operates directly, this is the brand's domain.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    operator_unit: Annotated[
        operator_unit_1.OperatorUnit | None,
        Field(
            description='Operator-owned business unit, agency seat, or platform account associated with this advertiser account. The id round-trips from the natural key; name is mutable display metadata. This is distinct from account_id, which belongs to the seller/storefront namespace.'
        ),
    ] = None
    revision: Annotated[
        SchemaInt | None,
        Field(
            description='Monotonically increasing optimistic-concurrency token for this account. Incremented on every persisted settings change, identity-change request, and identity-change disposition; reads, dry runs, validation failures, and exact idempotency replays do not increment it. Pass the latest observed value in a sync_accounts settings-update entry to prevent lost updates.',
            ge=1,
        ),
    ] = None
    identity_change: Annotated[
        account_identity_change.AccountIdentityChange | None,
        Field(
            description='Pending or rejected operator-identity transition. While present, the top-level operator and operator_unit remain the current canonical identity. Re-read list_accounts until the request is applied (canonical fields change and this object disappears) or rejected.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description="Immutable transaction currency when the seller's advertiser object is currency-bound. Media buys on this account MUST use this currency. Omit when the account selects currency independently per media buy.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    timezone: Annotated[
        str | None,
        Field(
            description='Immutable operational timezone for this account, expressed as UTC or an IANA timezone identifier. AdCP 3.2 sellers return it on every account. It is the default calendar-day boundary for account-scoped behavior unless a feature explicitly declares another timezone basis. For buyer-selected account_fixed provisioning it participates in the natural account key.',
            min_length=1,
        ),
    ] = None
    billing: Annotated[
        billing_party.BillingParty | None,
        Field(
            description="Who is invoiced on this account. See billing_entity for the invoiced party's business details."
        ),
    ] = None
    billing_entity: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description='Current canonical business entity for the party responsible for payment. Contains the legal name, tax IDs, and address needed for formal B2B invoicing. Corresponds to whoever billing points to (operator, agent, or advertiser). When this account appears in a response, bank details MUST be omitted and the request-only destination_billing_entity MUST NOT be exposed.'
        ),
    ] = None
    destination_billing_entity: Annotated[
        Any | None,
        Field(description='Request-only staging field. It MUST NOT appear in account read models.'),
    ] = None
    rate_card: Annotated[
        str | None, Field(description='Identifier for the rate card applied to this account')
    ] = None
    payment_terms: Annotated[
        payment_terms_1.PaymentTerms | None,
        Field(
            description='Payment terms agreed for this account. Binding for all invoices when the account is active.'
        ),
    ] = None
    credit_limit: Annotated[
        CreditLimit | None, Field(description='Maximum outstanding balance allowed')
    ] = None
    setup: Annotated[
        Setup | None,
        Field(
            description="Present when status is 'pending_approval'. Contains next steps for completing account activation."
        ),
    ] = None
    account_scope: account_scope_1.AccountScope | None = None
    governance_agents: Annotated[
        list[GovernanceAgent] | None,
        Field(
            description="Governance agent endpoint registered on this account. Exactly one entry per sync_governance's one-agent-per-account invariant. The array shape is preserved for wire compatibility with 3.0; `maxItems: 1` is load-bearing and mirrors the singular `governance_context` on the protocol envelope. Authentication credentials are write-only and not included in responses — use sync_governance to set or update credentials.",
            max_length=1,
            min_length=1,
        ),
    ] = None
    reporting_bucket: Annotated[
        ReportingBucket | None,
        Field(
            description="Cloud storage bucket where the seller delivers offline reporting files for this account. Seller provisions a dedicated bucket or a per-account prefix within a shared bucket, and grants the buyer read access out-of-band. Access MUST be scoped at the IAM layer so each account can only read its own prefix — bucket-wide grants are non-compliant even with per-account prefixes. Seller MUST revoke access when the account's status transitions to inactive, suspended, or closed. See security considerations for offline delivery in docs/media-buy/media-buys/optimization-reporting. Only present when the seller supports offline delivery (reporting_delivery_methods includes 'offline' in capabilities)."
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(
            description='When true, this is a sandbox account — no real platform calls, no real spend. For account-id namespaces, sandbox accounts are pre-existing test accounts on the platform discovered via list_accounts or supplied out-of-band. For buyer-declared accounts, sandbox is part of the natural key: the same brand/operator pair can have both a production and sandbox account.'
        ),
    ] = None
    notification_configs: Annotated[
        list[notification_config.NotificationConfig] | None,
        Field(
            description='Account-level webhook subscriptions for creative lifecycle/assignment changes, indicators.changed, account status, durable account-change wake-ups, wholesale feed changes, and reporting.delivery_ready. Buyers manage entries via sync_accounts and verify persisted state on list_accounts. account.change_recorded wakes receivers to drain list_account_changes; reporting.delivery_ready is repaired through get_reporting_status; indicator and assignment payloads are invalidations repaired completely through get_media_buys; list_creatives may provide a bounded reverse projection. Distinct from per-resource push_notification_config. Entries are keyed by account-scoped subscriber_id; credentials are write-only.',
            max_length=16,
        ),
    ] = None
    reporting_delivery_configs: Annotated[
        list[reporting_delivery_config_state.ReportingDeliveryConfigurationState] | None,
        Field(
            description="Resolved durable reporting delivery configurations owned by the authenticated caller for this account. list_accounts MUST expose only the calling principal's set. State and seller-issued destination_ref are returned; credentials and bearer profiles MUST NOT appear. Any setup URL is a secret-free authenticated entry point, not a bearer credential.",
            max_length=16,
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook delivery attempts scoped to this account when the caller requested webhook activity on list_accounts and the seller surfaces the log. Includes account-anchored notifications such as account.status_changed and MAY include other account-level fires relevant to this account. Three-state presence follows the shared webhook_activity[] contract: omitted means unsupported or not requested, [] means supported but no retained fires, non-empty lists recent attempts most-recent-first.',
            max_length=200,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

• AccountWithAuthorization
• AccountResponse

Class variables

var account_id : str

var account_scope : AccountScope | None

var advertiser : str | None

var billing : BillingParty | None

var billing_entity : BusinessEntity | None

var billing_proxy : str | None

var brand : BrandReference | None

var credit_limit : CreditLimit | None

var currency : str | None

var destination_billing_entity : typing.Any | None

var ext : ExtensionObject | None

var governance_agents : list[GovernanceAgent] | None

var identity_change : AccountIdentityChange1 | AccountIdentityChange2 | None

var model_config

var name : str

var notification_configs : list[NotificationConfig] | None

var operator : str | None

var operator_unit : OperatorUnit | None

var payment_terms : PaymentTerms | None

var rate_card : str | None

var reporting_bucket : ReportingBucket | None

var reporting_delivery_configs : list[ReportingDeliveryConfigurationState] | None

var revision : int | None

var sandbox : bool | None

var setup : Setup | None

var status : AccountStatus

var timezone : str | None

var webhook_activity : list[WebhookActivityRecord] | None

class SyncAccountsAccount (**data: Any)

Expand source code

class Account(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    account_id: str | None = None
    account: account_ref_1.AccountReference | None = None
    brand: brand_ref_1.BrandReference | None = None
    operator: str | None = None
    operator_unit: operator_unit_1.OperatorUnit | None = None
    revision: Annotated[int, Field(ge=1)] | None = None
    identity_change: account_identity_change_1.AccountIdentityChange | None = None
    identity_change_preview: account_identity_change_preview_1.AccountIdentityChangePreview | None = None
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')] | None = None
    timezone: Annotated[str, StringConstraints(min_length=1)] | None = None
    name: str | None = None
    action: Literal['created', 'updated', 'unchanged', 'failed']
    status: Literal['active', 'pending_approval', 'rejected', 'payment_required', 'suspended', 'closed'] | None = None
    billing: billing_party_1.BillingParty | None = None
    billing_entity: business_entity_1.BusinessEntity | None = None
    destination_billing_entity: Any | None = None
    account_scope: account_scope_1.AccountScope | None = None
    setup: Setup | None = None
    rate_card: str | None = None
    payment_terms: payment_terms_1.PaymentTerms | None = None
    credit_limit: CreditLimit | None = None
    errors: Annotated[list[error_1.Error], Field(min_length=1)] | None = None
    warnings: list[str] | None = None
    sandbox: bool | None = None
    notification_configs: Annotated[list[notification_config_1.NotificationConfig], Field(max_length=16)] | None = None
    reporting_delivery_configs: Annotated[list[reporting_delivery_config_state_1.ReportingDeliveryConfigurationState], Field(max_length=16)] | None = None
    authorization: account_authorization_1.AccountAuthorization | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var account : AccountReference1 | AccountReference2 | None

var account_id : str | None

var account_scope : AccountScope | None

var action : Literal['created', 'updated', 'unchanged', 'failed']

var authorization : AccountAuthorization | None

var billing : BillingParty | None

var billing_entity : BusinessEntity | None

var brand : BrandReference | None

var credit_limit : CreditLimit | None

var currency : str | None

var destination_billing_entity : typing.Any | None

var errors : list[Error] | None

var identity_change : AccountIdentityChange1 | AccountIdentityChange2 | None

var identity_change_preview : AccountIdentityChangePreview1 | AccountIdentityChangePreview2 | AccountIdentityChangePreview3 | None

var model_config

var name : str | None

var notification_configs : list[NotificationConfig] | None

var operator : str | None

var operator_unit : OperatorUnit | None

var payment_terms : PaymentTerms | None

var rate_card : str | None

var reporting_delivery_configs : list[ReportingDeliveryConfigurationState] | None

var revision : int | None

var sandbox : bool | None

var setup : Setup | None

var status : Literal['active', 'pending_approval', 'rejected', 'payment_required', 'suspended', 'closed'] | None

var timezone : str | None

var warnings : list[str] | None

class SyncGovernanceAccount (**data: Any)

Expand source code

class Account(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    account: Annotated[
        account_ref.AccountReference,
        Field(
            description='Account to sync governance agents for. Use account_id for account-id namespaces or brand + operator for buyer-declared accounts.'
        ),
    ]
    governance_agents: Annotated[
        list[GovernanceAgent],
        Field(
            description="Governance agent endpoint for this account. Exactly one entry — the single agent that owns the account's full governance lifecycle. The seller calls this agent via check_governance during media buy lifecycle events. The array shape is preserved for wire compatibility with 3.0 senders; `maxItems: 1` is load-bearing and mirrors the singular `governance_context` on the protocol envelope.",
            max_length=1,
            min_length=1,
        ),
    ]

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

Class variables

var account : AccountReference1 | AccountReference2

var governance_agents : list[GovernanceAgent]

var model_config

class CapabilitiesAccount (**data: Any)

Expand source code

class Account(AdCPBaseModel):
    require_operator_auth: Annotated[
        StrictBool | None,
        Field(
            description="Whether the seller requires operator-level credentials. This declares who must authenticate; it does not by itself declare whether OAuth is used, whether list_accounts is exposed, or which sync_accounts modes are supported. When true, operators authenticate independently with the seller and account-scoped calls use seller/storefront-assigned account_id values because the seller or upstream platform owns the canonical account namespace. If a credential may access more than one account, the seller MUST expose list_accounts and buyers MUST resolve an explicit account_id before the first account-scoped request. If a credential is bound to exactly one account, the seller SHOULD expose list_accounts returning that singleton; a seller MAY omit list_accounts only when it provides the same explicit account_id through another declared path or out-of-band onboarding. When false (default, buyer-declared accounts), the seller trusts the agent's identity claims and account-scoped calls use the advertiser natural key: brand + operator + optional operator_unit, fixed currency, optional buyer-selected account timezone, and sandbox. operator_unit.id is owned by the operator and is distinct from the seller's account_id. The seller normally provisions through sync_accounts, but MAY lazily provision on the first account-scoped request when billing and other required settings are unambiguous from capabilities or onboarding defaults. A lazy-provisioning seller MUST keep accepting the natural key and MUST expose list_accounts for recovery; if buyer input is needed before use, the seller MUST expose sync_accounts."
        ),
    ] = False
    authorization_endpoint: Annotated[
        AnyUrl | None,
        Field(
            description='OAuth authorization endpoint for obtaining operator-level credentials. Present when the seller supports OAuth for operator authentication. The agent directs the operator to this URL to authenticate and obtain a bearer token. If absent and require_operator_auth is true, operators obtain credentials out-of-band (e.g., seller portal, API key).'
        ),
    ] = None
    supported_billing: Annotated[
        list[billing_party.BillingParty],
        Field(
            description="Billing models this seller supports. operator: seller invoices the operator (agency or brand buying direct). agent: agent consolidates billing. advertiser: seller invoices the advertiser directly, even when a different operator places orders on their behalf. When the buyer calls sync_accounts, it must pass one of these values. A lazy-provisioning seller may omit sync_accounts only when billing can be resolved unambiguously from this capability or the authenticated agent's onboarding defaults.",
            min_length=1,
        ),
    ]
    supported_account_currency_modes: Annotated[
        list[account_currency_mode.AccountCurrencyMode] | None,
        Field(
            description='Required for sellers implementing AdCP 3.2 advertiser-account provisioning, but optional in this shared 3.x response schema so existing 3.0 and 3.1 capability responses remain valid. Declares whether advertiser accounts are bound to one immutable currency (`fixed`), select currency independently per proposal or media buy (`per_media_buy`), or support both models. When only `fixed` is advertised, buyer-declared provisioning entries MUST include `currency`. When only `per_media_buy` is advertised, they MUST omit it. When both are advertised, presence of `currency` selects a fixed-currency account and omission selects per-media-buy currency. Buyers MUST treat absence as an older seller whose currency mode is not discoverable, not as support for either mode.',
            min_length=1,
        ),
    ] = None
    timezone: Annotated[
        account_timezone_capability.AccountTimezoneCapability | None,
        Field(
            description='Required for sellers implementing AdCP 3.2 advertiser-account provisioning, but optional in the shared 3.x response schema for compatibility. Declares whether the account timezone is seller-wide or fixed per account and whether a buyer must select it during sync_accounts provisioning. Account timezone is the default for account-scoped calendar semantics; feature-specific capability fields explicitly declare exceptions.'
        ),
    ] = None
    required_for_products: Annotated[
        StrictBool | None,
        Field(
            description='Whether an account reference is required for get_products. When true, the buyer must establish an account before browsing products. When false (default), the buyer can browse products without an account — useful for price comparison and discovery before committing to a seller.'
        ),
    ] = False
    account_financials: Annotated[
        StrictBool | None,
        Field(
            description='Whether this seller exposes the `get_account_financials` task for querying account-level financial status (spend, credit, invoices). Acts as a **pre-call discriminator** — buyers MUST consult this field before issuing `get_account_financials`; when `false` (or absent), sellers MAY reject the call with an `UNSUPPORTED_FEATURE` / `OPERATION_NOT_SUPPORTED` error. Companion pattern to `creative.bills_through_adcp` (issue #2881) — both fields let buyers gate optional capability calls on a single declared boolean rather than probing for support. Only applicable to operator-billed accounts; sellers using buyer-billed flows omit or set to `false`.'
        ),
    ] = False
    notifications: Annotated[
        Notifications2 | Notifications3 | None,
        Field(
            description='Whether the seller supports durable account-lifecycle webhooks through account-level `notification_configs[]`. This capability is specifically for account status changes such as approval, rejection, payment-required, suspension, recovery, and closure. When supported, buyers register subscribers with `sync_accounts.accounts[].notification_configs[]`; each `account.status_changed` fire is an invalidation payload, and buyers repair by re-reading `list_accounts` for the account_id.'
        ),
    ] = None
    change_feed: Annotated[
        ChangeFeed | ChangeFeed1 | None,
        Field(
            description='Whether the seller exposes a durable, ordered feed of material changes to authoritative account-scoped state. This is distinct from webhook_activity transport diagnostics and from current-state reads. Sellers claiming support MUST retain changes for at least 90 days after recording and MUST produce records regardless of whether a mutation originated through AdCP, a seller surface, another authorized principal, seller automation, or a connected platform within declared coverage. Experimental in 3.2 (RFC #6810): sellers advertising supported: true MUST list account.change_feed in experimental_features.'
        ),
    ] = None
    identity_updates: Annotated[
        IdentityUpdates | IdentityUpdates1 | None,
        Field(
            description='Whether the seller accepts buyer-desired operator identity reconciliation through sync_accounts settings-update entries. Sellers declaring support expose the exact identity transitions they implement, MUST return account revisions from sync_accounts and list_accounts, and MUST return identity_change_preview for dry-run identity updates.'
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(
            description='Whether this seller supports sandbox accounts for testing. Buyer-declared accounts use sandbox: true in sync_accounts or, for an unambiguous lazy-provisioning seller, in the natural-key account reference. Sellers with account_id namespaces expose sandbox accounts as pre-existing test accounts through list_accounts or supply them out-of-band. Requests using a sandbox account perform no real platform calls or spend.'
        ),
    ] = False

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

Class variables

var account_financials : bool | None

var authorization_endpoint : pydantic.networks.AnyUrl | None

var change_feed : ChangeFeed | ChangeFeed1 | None

var identity_updates : IdentityUpdates | IdentityUpdates1 | None

var model_config

var notifications : Notifications2 | Notifications3 | None

var require_operator_auth : bool | None

var required_for_products : bool | None

var sandbox : bool | None

var supported_account_currency_modes : list[AccountCurrencyMode] | None

var supported_billing : list[BillingParty]

var timezone : AccountTimezoneCapability | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AccountAuthorization (**data: Any)

Expand source code

class AccountAuthorization(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    allowed_tasks: Annotated[
        list[AllowedTask],
        Field(
            description='Canonical snake_case task names the caller may invoke against this account (for example get_media_buys, buy_products, accept_proposal, control_media_buy, or sync_creatives). Absence of a task from this list means not permitted and returns SCOPE_INSUFFICIENT. Compact 3.2 tools are authorized by their own names; grants for deprecated get_products/create_media_buy/update_media_buy do not silently transfer across aliases.'
        ),
    ]
    field_scopes: Annotated[
        dict[str, list[str]] | None,
        Field(
            description='Optional per-task allowlist of request fields the caller may set. Keys are task names (which MUST also appear in allowed_tasks). Values are arrays of top-level request-field paths permitted for that task. When a task appears in field_scopes, requests to that task with any field outside the allowlist MUST be rejected with FIELD_NOT_PERMITTED. Compact product tools use their own task names and top-level fields such as criteria and refinements. Implicit framing fields are always permitted and do NOT need to appear in the allowlist — they identify the resource or shape the call rather than mutating business state. Tasks absent from field_scopes have no field-level restriction beyond what the task schema already enforces.'
        ),
    ] = None
    scope_name: Annotated[
        Literal['attestation_verifier'] | ScopeName | None,
        Field(
            description='Optional named scope identifier. When present, callers and the vendor agent can reason about the grant by name rather than by enumerating allowed_tasks and field_scopes. Modeled as a discriminated union so code generators produce a literal type for the standard scope(s) and a distinct type for agent-defined values — this prevents a typo of `attestation_verifier` from being silently accepted as a custom scope. Agent-defined scope names MUST use a `custom:` prefix to avoid collision with future standard scopes. The prefix is protocol-neutral: a signals agent, a governance agent, or a creative agent defines custom scopes the same way a media-buy sales agent does.'
        ),
    ] = None
    read_only: Annotated[
        StrictBool | None,
        Field(
            description='Convenience flag. When true, the caller is permitted only non-mutating tasks. Sellers MUST reject any mutation from a read-only caller with READ_ONLY_SCOPE. For the AdCP 3.2 product split, read-only permits list_products but rejects request_proposals, refine_proposals, and decline_proposals; a legacy get_products call is permitted only when the seller can guarantee the selected arm is a synchronous side-effect-free read. Sellers MAY omit this field; omission is equivalent to `false`. Callers MUST NOT infer read-only from `allowed_tasks` alone — the seller MUST set this explicitly when it applies.'
        ),
    ] = False

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

Class variables

var allowed_tasks : list[AllowedTask]

var field_scopes : dict[str, list[str]] | None

var model_config

var read_only : bool | None

var scope_name : Literal['attestation_verifier'] | ScopeName | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AccountMovedDetails (**data: Any)

Expand source code

class AccountMovedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    current_account: Annotated[
        canonical_account_ref.CanonicalAccountReference,
        Field(
            description='Current canonical reference. Buyer-declared account sellers return the complete current natural key; account-id namespaces may return account_id.'
        ),
    ]
    revision: Annotated[
        SchemaInt | None,
        Field(
            description='Current account revision when the seller exposes account revisions.', ge=1
        ),
    ] = 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

Class variables

var current_account : CanonicalAccountReference1 | CanonicalAccountReference2

var model_config

var revision : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AccountReferenceById (**data: Any)

Expand source code

class AccountReference1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    account_id: Annotated[
        str,
        Field(
            description="Seller-assigned account identifier. For upstream-managed account namespaces, this value comes from list_accounts; for seller-defined namespaces without a list_accounts surface, it is supplied out-of-band. Buyer-declared account sellers MAY echo account_id from sync_accounts as an internal handle, but they MUST continue accepting the account's current natural-key AccountRef on subsequent calls. A former key tombstoned by identity reconciliation returns ACCOUNT_MOVED to authorized callers."
        ),
    ]

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

Class variables

var account_id : str

var model_config

class AccountIdReference (**data: Any)

Expand source code

class AccountReference1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    account_id: Annotated[
        str,
        Field(
            description="Seller-assigned account identifier. For upstream-managed account namespaces, this value comes from list_accounts; for seller-defined namespaces without a list_accounts surface, it is supplied out-of-band. Buyer-declared account sellers MAY echo account_id from sync_accounts as an internal handle, but they MUST continue accepting the account's current natural-key AccountRef on subsequent calls. A former key tombstoned by identity reconciliation returns ACCOUNT_MOVED to authorized callers."
        ),
    ]

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

Class variables

var account_id : str

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AccountReferenceByNaturalKey (**data: Any)

Expand source code

class AccountReference2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    brand: Annotated[
        brand_ref.BrandReference, Field(description='Brand reference identifying the advertiser')
    ]
    operator: Annotated[
        str,
        Field(
            description="Domain of the entity operating on the brand's behalf. When the brand operates directly, this is the brand's domain.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    operator_unit: Annotated[
        operator_unit_1.OperatorUnit | None,
        Field(
            description='Optional operator-owned business unit, agency seat, or platform account. Only id participates in the natural account key; name is mutable display metadata.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description="Immutable ISO 4217 transaction currency when the seller's advertiser object is currency-bound. When present, this is part of the natural account key and media buys on the account MUST use it. Omit when currency is selected independently per media buy.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    timezone: Annotated[
        str | None,
        Field(
            description='Immutable account timezone. Include it in the natural key when get_adcp_capabilities.account.timezone declares account_fixed with buyer_selected; omit it for seller_fixed or seller_assigned accounts.',
            min_length=1,
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(
            description='When true, references the sandbox account for this brand/operator pair. Defaults to false (production account).'
        ),
    ] = False

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

Class variables

var brand : BrandReference

var currency : str | None

var model_config

var operator : str

var operator_unit : OperatorUnit | None

var sandbox : bool | None

var timezone : str | None

class InlineAccountReference (**data: Any)

Expand source code

class AccountReference2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    brand: Annotated[
        brand_ref.BrandReference, Field(description='Brand reference identifying the advertiser')
    ]
    operator: Annotated[
        str,
        Field(
            description="Domain of the entity operating on the brand's behalf. When the brand operates directly, this is the brand's domain.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    operator_unit: Annotated[
        operator_unit_1.OperatorUnit | None,
        Field(
            description='Optional operator-owned business unit, agency seat, or platform account. Only id participates in the natural account key; name is mutable display metadata.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description="Immutable ISO 4217 transaction currency when the seller's advertiser object is currency-bound. When present, this is part of the natural account key and media buys on the account MUST use it. Omit when currency is selected independently per media buy.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    timezone: Annotated[
        str | None,
        Field(
            description='Immutable account timezone. Include it in the natural key when get_adcp_capabilities.account.timezone declares account_fixed with buyer_selected; omit it for seller_fixed or seller_assigned accounts.',
            min_length=1,
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(
            description='When true, references the sandbox account for this brand/operator pair. Defaults to false (production account).'
        ),
    ] = False

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

Class variables

var brand : BrandReference

var currency : str | None

var model_config

var operator : str

var operator_unit : OperatorUnit | None

var sandbox : bool | None

var timezone : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AccountResponse (**data: Any)

Expand source code

class AccountResponse(Account):
    """Response projection of :class:`Account` — billing_entity is the
    bank-stripped variant.

    Use this on the response edge of any handler that returns account
    state (``list_accounts``, ``get_account_financials``, etc.) when
    your internal ``Account`` records carry bank details. For convenience,
    :func:`to_account_response` projects an existing ``Account`` instance
    to an ``AccountResponse`` and drops bank along the way.
    """

    billing_entity: BusinessEntityResponse | None = None
    notification_configs: SchemaVariant[
        Annotated[list[_NotificationConfigResponse], Field(max_length=16)] | None
    ] = None

Response projection of :class:Account — billing_entity is the bank-stripped variant.

Use this on the response edge of any handler that returns account state (list_accounts, get_account_financials, etc.) when your internal Account records carry bank details. For convenience, :func:to_account_response() projects an existing Account instance to an AccountResponse and drops bank along the way.

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

• Account
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var billing_entity : BusinessEntityResponse | None

var model_config

var notification_configs : list[adcp.types.projections._NotificationConfigResponse] | None

Inherited members

• Account:
  • model_dump
  • model_dump_json
  • model_summary

class AccountScope (*args, **kwds)

Expand source code

class AccountScope(StrEnum):
    operator = 'operator'
    brand = 'brand'
    operator_brand = 'operator_brand'
    agent = 'agent'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var agent

var brand

var operator

var operator_brand

class AccountSetupRequiredDetails (**data: Any)

Expand source code

class AccountSetupRequiredDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    setup_url: Annotated[
        AnyUrl | None, Field(description='URL where account setup can be completed')
    ] = None
    setup_steps: Annotated[
        list[str] | None, Field(description='Steps remaining before the account is ready')
    ] = 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

Class variables

var model_config

var setup_steps : list[str] | None

var setup_url : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AccountWithAuthorization (**data: Any)

Expand source code

class AccountWithAuthorization(Account):
    authorization: Annotated[
        account_authorization.AccountAuthorization | None,
        Field(
            description="Optional. The caller's scope grant against this account. Vendor agents of any type (media-buy, signals, governance, creative, brand) that support scope introspection SHOULD populate this so callers can preempt SCOPE_INSUFFICIENT / FIELD_NOT_PERMITTED errors rather than discovering scope by trial and error. Media-buy sales agents claiming the `attestation_verifier` standard scope MUST populate it. Absence means the vendor agent does not advertise introspectable scope for this account — callers MUST NOT infer access from absence, and fall back to error-driven discovery via the RBAC error codes."
        ),
    ] = 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

• Account
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var authorization : AccountAuthorization | None

var model_config

Inherited members

• Account:
  • model_dump
  • model_dump_json
  • model_summary

class AcquireRightsRequest (**data: Any)

Expand source code

class AcquireRightsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque intent authorization for this rights commitment. Required when governance applies to the resolved account.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    rights_id: Annotated[
        str, Field(description='Rights offering identifier from get_rights response')
    ]
    pricing_option_id: Annotated[
        str, Field(description='Selected pricing option from the rights offering')
    ]
    buyer: Annotated[brand_ref.BrandReference, Field(description="The buyer's brand identity")]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account context for this acquisition. Used by the brand agent to resolve any governance agent previously bound for this brand+operator pair via sync_governance. When both an inline governance_context token and a bound governance agent are present, the token is verified against that resolved relationship. An agent advertising adcp.governance_enforcement for acquire_rights MUST resolve an account and returns ACCOUNT_REQUIRED when neither the request nor an existing resource supplies one; it MUST NOT infer that a missing token means ungoverned. Legacy non-claiming agents may continue to treat omission of both fields as ungoverned during 3.x. Pass a natural key (brand, operator, optional sandbox) or a seller-assigned account_id from list_accounts.'
        ),
    ] = None
    campaign: Annotated[Campaign, Field(description='Campaign details for rights clearance')]
    revocation_webhook: Annotated[
        push_notification_config_1.PushNotificationConfig,
        Field(
            description='Webhook for rights revocation notifications. If the rights holder needs to revoke rights (talent scandal, contract violation, etc.), they POST a revocation-notification to this URL. The buyer is responsible for stopping creative delivery upon receipt.'
        ),
    ]
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Webhook for async status updates if the acquisition requires approval. The rights agent sends a webhook notification when the status transitions to acquired or rejected.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated key for safe retries. Resubmitting with the same key returns the original response rather than creating a duplicate acquisition. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 account : AccountReference1 | AccountReference2 | None

var buyer : BrandReference

var campaign : Campaign

var context : ContextObject | None

var ext : ExtensionObject | None

var governance_context : str | None

var idempotency_key : str

var model_config

var pricing_option_id : str

var push_notification_config : PushNotificationConfig | None

var revocation_webhook : PushNotificationConfig

var rights_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 AcquireRightsAcquiredResponse (**data: Any)

Expand source code

class AcquireRightsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    rights_id: str
    rights_status: Literal['acquired'] = 'acquired'
    brand_id: str
    terms: rights_terms_1.RightsTerms
    generation_credentials: list[generation_credential_1.GenerationCredential]
    restrictions: list[str] | None = None
    disclosure: Disclosure | None = None
    approval_webhook: push_notification_config_1.PushNotificationConfig | None = None
    usage_reporting_url: AnyUrl | None = None
    rights_constraint: Any
    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.

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 approval_webhook : PushNotificationConfig | None

var brand_id : str

var context : ContextObject | None

var disclosure : Disclosure | None

var ext : ExtensionObject | None

var generation_credentials : list[GenerationCredential]

var model_config

var restrictions : list[str] | None

var rights_constraint : Any

var rights_id : str

var rights_status : Literal['acquired']

var terms : RightsTerms

var usage_reporting_url : pydantic.networks.AnyUrl | None

class AcquireRightsResponse1 (**data: Any)

Expand source code

class AcquireRightsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    rights_id: str
    rights_status: Literal['acquired'] = 'acquired'
    brand_id: str
    terms: rights_terms_1.RightsTerms
    generation_credentials: list[generation_credential_1.GenerationCredential]
    restrictions: list[str] | None = None
    disclosure: Disclosure | None = None
    approval_webhook: push_notification_config_1.PushNotificationConfig | None = None
    usage_reporting_url: AnyUrl | None = None
    rights_constraint: Any
    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.

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 approval_webhook : PushNotificationConfig | None

var brand_id : str

var context : ContextObject | None

var disclosure : Disclosure | None

var ext : ExtensionObject | None

var generation_credentials : list[GenerationCredential]

var model_config

var restrictions : list[str] | None

var rights_constraint : Any

var rights_id : str

var rights_status : Literal['acquired']

var terms : RightsTerms

var usage_reporting_url : pydantic.networks.AnyUrl | 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 AcquireRightsPendingResponse (**data: Any)

Expand source code

class AcquireRightsResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    rights_id: str
    rights_status: Literal['pending_approval'] = 'pending_approval'
    brand_id: str
    detail: str | None = None
    estimated_response_time: str | None = 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.

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 brand_id : str

var context : ContextObject | None

var detail : str | None

var estimated_response_time : str | None

var ext : ExtensionObject | None

var model_config

var rights_id : str

var rights_status : Literal['pending_approval']

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 AcquireRightsRejectedResponse (**data: Any)

Expand source code

class AcquireRightsResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    rights_id: str
    rights_status: Literal['rejected'] = 'rejected'
    brand_id: str
    reason: str
    suggestions: list[str] | None = 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.

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 brand_id : str

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var reason : str

var rights_id : str

var rights_status : Literal['rejected']

var suggestions : list[str] | 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 AcquireRightsErrorResponse (**data: Any)

Expand source code

class AcquireRightsResponse4(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 ActionNotAllowedDetails (**data: Any)

Expand source code

class ActionNotAllowedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    attempted_action: Annotated[
        media_buy_available_action_id.MediaBuyAvailableActionId,
        Field(
            description='The action the request mapped to, per the normative action-to-field mapping in update_media_buy task-reference.'
        ),
    ]
    reason: Annotated[
        action_not_allowed_reason.ActionNotAllowedReason,
        Field(
            description='Why the action was rejected. Buyer SDKs branch on this to choose a recovery path.'
        ),
    ]
    currently_available_actions: Annotated[
        list[media_buy_available_action.MediaBuyAvailableAction] | None,
        Field(
            description="Echo of the buy's resolved `available_actions[]` at rejection time. Buyer SDKs render this to the caller as the recovery option set."
        ),
    ] = None
    decline_reason: Annotated[
        seller_policy_decline_reason.SellerPolicyDeclineReason | None,
        Field(
            description='Coarse seller-policy dimension behind a buy-specific denial. Sellers SHOULD populate this for `reason: not_supported_on_buy` when they have a structured reason and disclosure does not expose private thresholds or enforcement controls. It SHOULD be omitted for structural reasons such as `wrong_status`, `not_supported_on_product`, `mode_mismatch`, and `condition_unresolved`. When present, it MUST be consistent with the enclosing error.recovery classification.'
        ),
    ] = 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

Class variables

var attempted_action : MediaBuyValidAction | Literal['update_media_buy_frequency_cap']

var currently_available_actions : list[MediaBuyAvailableAction] | None

var decline_reason : SellerPolicyDeclineReason | None

var model_config

var reason : ActionNotAllowedReason

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ActionNotAllowedReason (*args, **kwds)

Expand source code

class ActionNotAllowedReason(StrEnum):
    wrong_status = 'wrong_status'
    not_supported_on_product = 'not_supported_on_product'
    not_supported_on_buy = 'not_supported_on_buy'
    mode_mismatch = 'mode_mismatch'
    condition_unresolved = 'condition_unresolved'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var condition_unresolved

var mode_mismatch

var not_supported_on_buy

var not_supported_on_product

var wrong_status

class ActivateSignalRequest (**data: Any)

Expand source code

class ActivateSignalRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    action: Annotated[
        Action | None,
        Field(
            description="Whether to activate or deactivate the signal. Deactivating removes the segment from downstream platforms, required when campaigns end to comply with data governance policies (GDPR, CCPA). Defaults to 'activate' when omitted."
        ),
    ] = Action.activate
    signal_agent_segment_id: Annotated[
        str,
        Field(
            description='Opaque activation handle returned in the signal_agent_segment_id field of each get_signals response entry. Pass this string verbatim — do not pass the signal_id object.'
        ),
    ]
    destinations: Annotated[
        list[destination.Destination],
        Field(
            description='Target destination(s) for activation. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ]
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="The pricing option selected from the signal's pricing_options in the get_signals response. Required when the signal has pricing options. Records the buyer's pricing commitment at activation time; pass this same value in report_usage for billing verification."
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque authorization context returned by an approved check_governance decision for this signal activation. Required when the account has a registered governance agent; signal agents MUST reject governed activations that omit a valid context. Conditions and denied decisions never produce this value.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for this activation. Associates with a commercial relationship established via sync_accounts.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate activations on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 account : AccountReference1 | AccountReference2 | None

var action : Action | None

var context : ContextObject | None

var destinations : list[Destination1 | Destination2]

var ext : ExtensionObject | None

var governance_context : str | None

var idempotency_key : str

var model_config

var pricing_option_id : str | None

var signal_agent_segment_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 ActivateSignalResponse1 (**data: Any)

Expand source code

class ActivateSignalResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    deployments: list[deployment_1.Deployment]
    sandbox: bool | None = 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.

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 context : ContextObject | None

var deployments : list[Deployment1 | Deployment2]

var ext : ExtensionObject | None

var model_config

var sandbox : bool | None

class ActivateSignalSuccessResponse (**data: Any)

Expand source code

class ActivateSignalResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    deployments: list[deployment_1.Deployment]
    sandbox: bool | None = 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.

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 context : ContextObject | None

var deployments : list[Deployment1 | Deployment2]

var ext : ExtensionObject | None

var model_config

var sandbox : bool | 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 ActivateSignalErrorResponse (**data: Any)

Expand source code

class ActivateSignalResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 SegmentIdActivationKey (**data: Any)

Expand source code

class ActivationKey1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Literal['segment_id'], Field(description='Segment ID based targeting')] = 'segment_id'
    segment_id: Annotated[
        str,
        Field(description='The platform-specific segment identifier to use in campaign targeting'),
    ]

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

Class variables

var model_config

var segment_id : str

var type : Literal['segment_id']

class PropertyIdActivationKey (**data: Any)

Expand source code

class ActivationKey1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Literal['segment_id'], Field(description='Segment ID based targeting')] = 'segment_id'
    segment_id: Annotated[
        str,
        Field(description='The platform-specific segment identifier to use in campaign targeting'),
    ]

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

Class variables

var model_config

var segment_id : str

var type : Literal['segment_id']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class KeyValueActivationKey (**data: Any)

Expand source code

class ActivationKey2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Literal['key_value'], Field(description='Key-value pair based targeting')] = 'key_value'
    key: Annotated[str, Field(description='The targeting parameter key')]
    value: Annotated[str, Field(description='The targeting parameter value')]

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

Class variables

var key : str

var model_config

var type : Literal['key_value']

var value : str

class PropertyTagActivationKey (**data: Any)

Expand source code

class ActivationKey2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Literal['key_value'], Field(description='Key-value pair based targeting')] = 'key_value'
    key: Annotated[str, Field(description='The targeting parameter key')]
    value: Annotated[str, Field(description='The targeting parameter value')]

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

Class variables

var key : str

var model_config

var type : Literal['key_value']

var value : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

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

• adcp.types._forward_compat._VersionedManifestReadbackModel
• GetAccountFinancialsRequest
• Balance
• Credit
• GetAccountFinancialsResponse1
• GetAccountFinancialsResponse2
• Invoice
• LastTopUp
• Spend
• ListAccountChangesRequest
• ListAccountChangesResponse
• ListAccountsRequest
• ListAccountsResponse
• ReportUsageRequest
• ReportUsageResponse
• SyncAccountsRequest
• Account
• CreditLimit
• Setup
• SyncAccountsResponse1
• SyncAccountsResponse2
• SyncGovernanceRequest
• SyncGovernanceResponse
• AcquireRightsRequest
• AcquireRightsResponse1
• AcquireRightsResponse2
• AcquireRightsResponse3
• AcquireRightsResponse4
• Disclosure
• CreativeApprovalRequest
• CreativeApprovalResponse1
• CreativeApprovalResponse2
• CreativeApprovalResponse3
• CreativeApprovalResponse4
• GetBrandIdentityRequest
• Asset
• Colors
• File
• FontRole2
• Fonts
• GetBrandIdentityResponse1
• GetBrandIdentityResponse2
• House
• Logo
• Rights
• Tone
• VoiceSynthesis
• GetRightsRequest
• Excluded
• ExclusivityStatus
• GetRightsResponse1
• GetRightsResponse2
• PreviewAsset
• Right
• SearchBrandsRequest
• SearchBrandsResponse
• UpdateRightsRequest
• UpdateRightsResponse1
• UpdateRightsResponse2
• VerifyBrandClaimRequest
• VerifyBrandClaimErrorResponse
• VerifyBrandClaimSuccessResponse
• VerifyBrandClaimsRequestBulk
• VerifyBrandClaimsErrorResponse
• VerifyBrandClaimsResponseBulk
• CreateCollectionListRequest
• CreateCollectionListResponse
• DeleteCollectionListRequest
• DeleteCollectionListResponse
• GetCollectionListRequest
• GetCollectionListResponse
• ListCollectionListsRequest
• ListCollectionListsResponse
• UpdateCollectionListRequest
• UpdateCollectionListResponse
• ComplyTestControllerRequest
• ComplyTestControllerResponse
• CalibrateContentRequest
• CalibrateContentResponse1
• CalibrateContentResponse2
• Feature
• CreateContentStandardsRequest
• CreateContentStandardsResponse
• GetContentStandardsRequest
• GetContentStandardsResponse1
• GetContentStandardsResponse2
• GetMediaBuyArtifactsRequest
• Artifact
• BrandContext
• CollectionInfo
• GetMediaBuyArtifactsResponse1
• GetMediaBuyArtifactsResponse2
• ListContentStandardsRequest
• ListContentStandardsResponse
• UpdateContentStandardsRequest
• UpdateContentStandardsResponse
• ValidateContentDeliveryRequest
• Feature
• Result
• Summary
• ValidateContentDeliveryResponse1
• ValidateContentDeliveryResponse2
• TasksGetRequest
• TasksGetResponse
• TasksListRequest
• TasksListResponse
• GetCreativeDeliveryRequest
• GetCreativeDeliveryResponse
• GetCreativeFeaturesRequest
• GetCreativeFeaturesResponse1
• GetCreativeFeaturesResponse2
• GetCreativeFeaturesResponse3
• ListCreativeFormatsRequestCreativeAgent
• ListCreativeFormatsResponseCreativeAgent
• ListCreativesRequest
• ListCreativesResponse
• ListTransformersRequestCreativeAgent
• ListTransformersResponseCreativeAgent
• PreviewCreativeRequest
• Input
• Input2
• Preview
• Preview2
• Preview3
• PreviewCreativeResponse1
• PreviewCreativeResponse2
• PreviewCreativeResponse3
• PreviewCreativeResponse4
• Response
• Result
• SyncCreativesRequest
• Creative
• SyncCreativesResponse1
• SyncCreativesResponse2
• SyncCreativesResponse3
• ValidateInputResponse
• VersionUnsupportedDetails
• CheckGovernanceRequest2
• CheckGovernanceResponse
• GetPlanAuditLogsRequest
• GetPlanAuditLogsResponse
• ReportPlanAdjustmentRequest
• ReportPlanAdjustmentResponse
• ReportPlanOutcomeRequest
• ReportPlanOutcomeResponse
• SyncPlansRequest
• SyncPlansResponse
• AcceptProposalRequest
• BuildCreativeRequest
• BuildCreativeResponse1
• BuildCreativeResponse2
• BuildCreativeResponse3
• BuildCreativeResponse4
• BuildCreativeResponse5
• BuildCreativeResponse6
• CatalogItemRef
• Creative
• Estimate
• Eval
• Input
• Input2
• PerLeaf
• Preview
• Preview2
• Preview3
• Preview4
• Variant
• BuyProductsRequest
• ControlMediaBuyRequest
• CreateMediaBuyRequest
• CreateMediaBuyResponse1
• CreateMediaBuyResponse2
• CreateMediaBuyResponse3
• DeclineProposalsRequest
• GetMediaBuyDeliveryRequest
• GetMediaBuyDeliveryResponse
• GetMediaBuysRequest
• GetMediaBuysResponse
• GetProductsRejected
• GetProductsRequest
• GetProductsResponse
• GetReportingStatusRequest
• GetReportingStatusResponse
• ListCreativeFormatsRequest
• ListCreativeFormatsResponse
• ListProductsRequest
• LogEventRequest
• LogEventResponse1
• LogEventResponse2
• PartialFailure
• PackageRequest
• ProvidePerformanceFeedbackRequest
• ProvidePerformanceFeedbackResponse1
• ProvidePerformanceFeedbackResponse2
• RefineProposalsRequest
• RequestProposalsRequest
• SyncAudiencesRequest
• Audience
• MatchBreakdown
• Source
• SyncAudiencesResponse1
• SyncAudiencesResponse2
• SyncAudiencesResponse3
• SyncCatalogsRequest
• Catalog
• ItemIssue
• SyncCatalogsResponse1
• SyncCatalogsResponse2
• SyncCatalogsResponse3
• SyncEventSourcesRequest
• EventSource
• Setup
• SyncEventSourcesResponse1
• SyncEventSourcesResponse2
• SyncReportingReceiptsRequest
• SyncReportingReceiptsResponse
• SyncReportingStatusRequest
• SyncReportingStatusResponse
• UpdateMediaBuyRequest
• UpdateMediaBuyResponse1
• UpdateMediaBuyResponse2
• UpdateMediaBuyResponse3
• CreatePropertyListRequest
• CreatePropertyListResponse
• DeletePropertyListRequest
• DeletePropertyListResponse
• GetPropertyListRequest
• GetPropertyListResponse
• ListPropertyListsRequest
• ListPropertyListsResponse
• UpdatePropertyListRequest
• UpdatePropertyListResponse
• ValidatePropertyDeliveryRequest
• ValidatePropertyDeliveryResponse
• GetAdcpCapabilitiesRequest
• GetAdcpCapabilitiesResponse
• GetPrincipalRequest
• GetPrincipalResponse
• GetTaskStatusRequest
• GetTaskStatusResponse
• ListTasksRequest
• ListTasksResponse
• SyncAgentNotificationConfigsRequest
• SyncAgentNotificationConfigsResponse
• SyncPrincipalRequest
• SyncPrincipalResponse
• ActivateSignalRequest
• ActivateSignalResponse1
• ActivateSignalResponse2
• GetSignalsRequest
• GetSignalsResponse
• SiGetOfferingRequest
• SiGetOfferingResponse
• SiInitiateSessionRequest
• SiInitiateSessionResponse
• SiSendMessageRequest
• SiSendMessageResponse
• SiTerminateSessionRequest
• SiTerminateSessionResponse
• ContextMatchRequest
• ContextMatchResponseRouterPublisher
• IdentityMatchRequest
• IdentityMatchResponseRouterPublisher
• ContextMatchResponseProviderRouter
• IdentityMatchResponseProviderRouter

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 AdvertiserIndustry (*args, **kwds)

Expand source code

class AdvertiserIndustry(StrEnum):
    automotive = 'automotive'
    automotive_electric_vehicles = 'automotive.electric_vehicles'
    automotive_parts_accessories = 'automotive.parts_accessories'
    automotive_luxury = 'automotive.luxury'
    beauty_cosmetics = 'beauty_cosmetics'
    beauty_cosmetics_skincare = 'beauty_cosmetics.skincare'
    beauty_cosmetics_fragrance = 'beauty_cosmetics.fragrance'
    beauty_cosmetics_haircare = 'beauty_cosmetics.haircare'
    cannabis = 'cannabis'
    cpg = 'cpg'
    cpg_personal_care = 'cpg.personal_care'
    cpg_household = 'cpg.household'
    dating = 'dating'
    education = 'education'
    education_higher_education = 'education.higher_education'
    education_online_learning = 'education.online_learning'
    education_k12 = 'education.k12'
    energy_utilities = 'energy_utilities'
    energy_utilities_renewable = 'energy_utilities.renewable'
    fashion_apparel = 'fashion_apparel'
    fashion_apparel_luxury = 'fashion_apparel.luxury'
    fashion_apparel_sportswear = 'fashion_apparel.sportswear'
    finance = 'finance'
    finance_banking = 'finance.banking'
    finance_insurance = 'finance.insurance'
    finance_investment = 'finance.investment'
    finance_cryptocurrency = 'finance.cryptocurrency'
    food_beverage = 'food_beverage'
    food_beverage_alcohol = 'food_beverage.alcohol'
    food_beverage_restaurants = 'food_beverage.restaurants'
    food_beverage_packaged_goods = 'food_beverage.packaged_goods'
    gambling_betting = 'gambling_betting'
    gambling_betting_sports_betting = 'gambling_betting.sports_betting'
    gambling_betting_casino = 'gambling_betting.casino'
    gaming = 'gaming'
    gaming_mobile = 'gaming.mobile'
    gaming_console_pc = 'gaming.console_pc'
    gaming_esports = 'gaming.esports'
    government_nonprofit = 'government_nonprofit'
    government_nonprofit_political = 'government_nonprofit.political'
    government_nonprofit_charity = 'government_nonprofit.charity'
    healthcare = 'healthcare'
    healthcare_pharmaceutical = 'healthcare.pharmaceutical'
    healthcare_medical_devices = 'healthcare.medical_devices'
    healthcare_wellness = 'healthcare.wellness'
    home_garden = 'home_garden'
    home_garden_furniture = 'home_garden.furniture'
    home_garden_home_improvement = 'home_garden.home_improvement'
    media_entertainment = 'media_entertainment'
    media_entertainment_podcasts = 'media_entertainment.podcasts'
    media_entertainment_music = 'media_entertainment.music'
    media_entertainment_film_tv = 'media_entertainment.film_tv'
    media_entertainment_publishing = 'media_entertainment.publishing'
    media_entertainment_live_events = 'media_entertainment.live_events'
    pets = 'pets'
    professional_services = 'professional_services'
    professional_services_legal = 'professional_services.legal'
    professional_services_consulting = 'professional_services.consulting'
    real_estate = 'real_estate'
    real_estate_residential = 'real_estate.residential'
    real_estate_commercial = 'real_estate.commercial'
    recruitment_hr = 'recruitment_hr'
    retail = 'retail'
    retail_ecommerce = 'retail.ecommerce'
    retail_department_stores = 'retail.department_stores'
    sports_fitness = 'sports_fitness'
    sports_fitness_equipment = 'sports_fitness.equipment'
    sports_fitness_teams_leagues = 'sports_fitness.teams_leagues'
    technology = 'technology'
    technology_software = 'technology.software'
    technology_hardware = 'technology.hardware'
    technology_ai_ml = 'technology.ai_ml'
    telecom = 'telecom'
    telecom_mobile_carriers = 'telecom.mobile_carriers'
    telecom_internet_providers = 'telecom.internet_providers'
    transportation_logistics = 'transportation_logistics'
    travel_hospitality = 'travel_hospitality'
    travel_hospitality_airlines = 'travel_hospitality.airlines'
    travel_hospitality_hotels = 'travel_hospitality.hotels'
    travel_hospitality_cruise = 'travel_hospitality.cruise'
    travel_hospitality_tourism = 'travel_hospitality.tourism'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var automotive

var automotive_electric_vehicles

var automotive_luxury

var automotive_parts_accessories

var beauty_cosmetics

var beauty_cosmetics_fragrance

var beauty_cosmetics_haircare

var beauty_cosmetics_skincare

var cannabis

var cpg

var cpg_household

var cpg_personal_care

var dating

var education

var education_higher_education

var education_k12

var education_online_learning

var energy_utilities

var energy_utilities_renewable

var fashion_apparel

var fashion_apparel_luxury

var fashion_apparel_sportswear

var finance

var finance_banking

var finance_cryptocurrency

var finance_insurance

var finance_investment

var food_beverage

var food_beverage_alcohol

var food_beverage_packaged_goods

var food_beverage_restaurants

var gambling_betting

var gambling_betting_casino

var gambling_betting_sports_betting

var gaming

var gaming_console_pc

var gaming_esports

var gaming_mobile

var government_nonprofit

var government_nonprofit_charity

var government_nonprofit_political

var healthcare

var healthcare_medical_devices

var healthcare_pharmaceutical

var healthcare_wellness

var home_garden

var home_garden_furniture

var home_garden_home_improvement

var media_entertainment

var media_entertainment_film_tv

var media_entertainment_live_events

var media_entertainment_music

var media_entertainment_podcasts

var media_entertainment_publishing

var pets

var professional_services

var professional_services_consulting

var professional_services_legal

var real_estate

var real_estate_commercial

var real_estate_residential

var recruitment_hr

var retail

var retail_department_stores

var retail_ecommerce

var sports_fitness

var sports_fitness_equipment

var sports_fitness_teams_leagues

var technology

var technology_ai_ml

var technology_hardware

var technology_software

var telecom

var telecom_internet_providers

var telecom_mobile_carriers

var transportation_logistics

var travel_hospitality

var travel_hospitality_airlines

var travel_hospitality_cruise

var travel_hospitality_hotels

var travel_hospitality_tourism

class AgentConfig (**data: Any)

Expand source code

class AgentConfig(BaseModel):
    """Agent configuration."""

    id: str
    agent_uri: str
    protocol: Protocol
    auth_token: str | None = None
    requires_auth: bool = False
    auth_header: str = "x-adcp-auth"  # Header name for authentication
    auth_type: str = "token"  # "token" for direct value, "bearer" for "Bearer {token}"
    timeout: float = 30.0  # Request timeout in seconds
    mcp_transport: str = (
        "streamable_http"  # "streamable_http" (default, modern) or "sse" (legacy fallback)
    )
    debug: bool = False  # Enable debug mode to capture request/response details
    extra_headers: dict[str, str] = Field(default_factory=dict)
    """Additional HTTP headers sent on every request to this agent.

    This is a **transport-layer escape hatch**, not an AdCP protocol
    extension point — protocol-defined fields belong in the request
    envelope or ``RequestContext.metadata``. Use this for vendor or
    deployment-specific routing headers (e.g. tenant routing on a
    multi-tenant server).

    Reserved: the configured ``auth_header`` (default ``x-adcp-auth``)
    and the standard ``Authorization`` header — set credentials via
    ``auth_token``/``auth_header`` instead. Header names are rejected
    if they contain CR/LF or other control characters.

    Persisted plaintext at ``~/.adcp/config.json`` when saved via the
    CLI — do not store credentials here.
    """

    @field_validator("agent_uri")
    @classmethod
    def validate_agent_uri(cls, v: str) -> str:
        """Validate agent URI format."""
        if not v:
            raise ValueError("agent_uri cannot be empty")

        if not v.startswith(("http://", "https://")):
            raise ValueError(
                f"agent_uri must start with http:// or https://, got: {v}\n"
                "Example: https://agent.example.com"
            )

        parsed = urlparse(v)
        if parsed.username or parsed.password:
            raise ValueError(
                "agent_uri must not include credentials; use auth_token/auth_header instead"
            )

        return v

    @field_validator("timeout")
    @classmethod
    def validate_timeout(cls, v: float) -> float:
        """Validate timeout is reasonable."""
        if v <= 0:
            raise ValueError(f"timeout must be positive, got: {v}")

        if v > 300:  # 5 minutes
            raise ValueError(
                f"timeout is very large ({v}s). Consider a value under 300 seconds.\n"
                "Large timeouts can cause long hangs if agent is unresponsive."
            )

        return v

    @field_validator("mcp_transport")
    @classmethod
    def validate_mcp_transport(cls, v: str) -> str:
        """Validate MCP transport type."""
        valid_transports = ["streamable_http", "sse"]
        if v not in valid_transports:
            raise ValueError(
                f"mcp_transport must be one of {valid_transports}, got: {v}\n"
                "Use 'streamable_http' for modern agents (recommended)"
            )
        return v

    @field_validator("auth_type")
    @classmethod
    def validate_auth_type(cls, v: str) -> str:
        """Validate auth type."""
        valid_types = ["token", "bearer"]
        if v not in valid_types:
            raise ValueError(
                f"auth_type must be one of {valid_types}, got: {v}\n"
                "Use 'bearer' for OAuth2/standard Authorization header"
            )
        return v

    @model_validator(mode="after")
    def _validate_security_constraints(self) -> AgentConfig:
        non_loopback_http = self.agent_uri.startswith("http://") and not is_loopback_http_uri(
            self.agent_uri
        )
        if self.auth_token and non_loopback_http:
            raise ValueError(
                "auth_token requires an https:// agent_uri for non-loopback hosts; "
                "plain HTTP is only allowed for localhost/loopback development"
            )

        if self.extra_headers and non_loopback_http:
            raise ValueError(
                "extra_headers require an https:// agent_uri for non-loopback hosts; "
                "plain HTTP is only allowed for localhost/loopback development"
            )

        if not self.extra_headers:
            return self
        reserved = {self.auth_header.lower(), "authorization"}
        for key, value in self.extra_headers.items():
            if not key:
                raise ValueError("extra_headers contains an empty header name")
            if any(c in key for c in ("\r", "\n", "\x00")) or any(ord(c) < 0x20 for c in key):
                raise ValueError(f"extra_headers key contains control character: {key!r}")
            if any(c in value for c in ("\r", "\n", "\x00")):
                raise ValueError(f"extra_headers value for {key!r} contains CR/LF/NUL")
            if key.lower() in reserved:
                raise ValueError(
                    f"extra_headers may not override reserved auth header "
                    f"{key!r} (collides with auth_header={self.auth_header!r} "
                    f"or 'Authorization'); set credentials via auth_token + "
                    f"auth_header instead"
                )
        return self

Agent configuration.

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_uri : str

var auth_header : str

var auth_token : str | None

var auth_type : str

var debug : bool

var extra_headers : dict[str, str]

Additional HTTP headers sent on every request to this agent.

This is a transport-layer escape hatch, not an AdCP protocol extension point — protocol-defined fields belong in the request envelope or RequestContext.metadata. Use this for vendor or deployment-specific routing headers (e.g. tenant routing on a multi-tenant server).

Reserved: the configured auth_header (default x-adcp-auth) and the standard Authorization header — set credentials via auth_token/auth_header instead. Header names are rejected if they contain CR/LF or other control characters.

Persisted plaintext at ~/.adcp/config.json when saved via the CLI — do not store credentials here.

var id : str

var mcp_transport : str

var model_config

var protocol : Protocol

var requires_auth : bool

var timeout : float

Static methods

def validate_agent_uri(v: str) ‑> str

Validate agent URI format.

def validate_auth_type(v: str) ‑> str

Validate auth type.

def validate_mcp_transport(v: str) ‑> str

Validate MCP transport type.

def validate_timeout(v: float) ‑> float

Validate timeout is reasonable.

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.

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

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.

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

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.

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

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 AgentPermissionDeniedDetails (**data: Any)

Expand source code

class AgentPermissionDeniedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['agent'],
        Field(
            description='Discriminator that this `PERMISSION_DENIED` was triggered by a per-buyer-agent provisioning gate (as opposed to a generic credential-shaped failure). Registered subset of `enums/error-scope.json` — sellers MUST set this field exactly to `"agent"` for this shape, and MUST omit `scope` entirely when responding on the unauthenticated/unestablished-identity path required by the cross-tenant oracle clamp. The `AGENT_SUSPENDED` / `AGENT_BLOCKED` codes (per-agent commercial status) do NOT carry an explicit `scope` field — the code itself is the discriminator on those paths, mirroring `BILLING_NOT_PERMITTED_FOR_AGENT`.'
        ),
    ] = 'agent'
    reason: Annotated[
        Literal['sandbox_only'],
        Field(
            description='Registered per-agent provisioning gate that fired. `"sandbox_only"` — the agent is provisioned for sandbox traffic only and the request was against a non-sandbox account. New `reason` values MUST be added here (the enum is closed by `additionalProperties: false`) so cross-language SDKs can dispatch without parsing prose.'
        ),
    ] = 'sandbox_only'

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

Class variables

var model_config

var reason : Literal['sandbox_only']

var scope : Literal['agent']

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.

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

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 AggregatedTotals (**data: Any)

Expand source code

class AggregatedTotals(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    impressions: Annotated[
        StrictFloat, Field(description='Total impressions delivered across all media buys', ge=0.0)
    ]
    spend: Annotated[
        StrictFloat, Field(description='Total amount spent across all media buys', ge=0.0)
    ]
    clicks: Annotated[
        StrictFloat | None,
        Field(description='Total clicks across all media buys (if applicable)', ge=0.0),
    ] = None
    completed_views: Annotated[
        StrictFloat | None,
        Field(
            description='Total audio/video completions across all media buys (if applicable)',
            ge=0.0,
        ),
    ] = None
    views: Annotated[
        StrictFloat | None,
        Field(description='Total views across all media buys (if applicable)', ge=0.0),
    ] = None
    conversions: Annotated[
        StrictFloat | None,
        Field(description='Total conversions across all media buys (if applicable)', ge=0.0),
    ] = None
    conversion_value: Annotated[
        StrictFloat | None,
        Field(description='Total conversion value across all media buys (if applicable)', ge=0.0),
    ] = None
    commissionable_value: Annotated[
        StrictFloat | None,
        Field(
            description='Total settled conversion value eligible for revenue-share commission across all media buys (if applicable)',
            ge=0.0,
        ),
    ] = None
    roas: Annotated[
        StrictFloat | None,
        Field(
            description='Aggregate return on ad spend across all media buys (total conversion_value / total spend)',
            ge=0.0,
        ),
    ] = None
    new_to_brand_rate: Annotated[
        StrictFloat | None,
        Field(
            description='Fraction of total conversions across all media buys from first-time brand buyers (weighted by conversion volume, not a simple average of per-buy rates)',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    cost_per_acquisition: Annotated[
        StrictFloat | None,
        Field(
            description='Aggregate cost per conversion across all media buys (total spend / total conversions)',
            ge=0.0,
        ),
    ] = None
    completion_rate: Annotated[
        StrictFloat | None,
        Field(
            description='Aggregate completion rate across all media buys (weighted by impressions, not a simple average of per-buy rates). Null indicates the metric is not applicable to the aggregated buys (e.g. all non-video inventory).',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    reach: Annotated[
        StrictFloat | None,
        Field(
            description='Reach across all media buys. Only present when all media buys share the same reach_unit. Omitted when reach units are heterogeneous — use per-buy reach values instead. The optional reach_aggregation field declares whether this value is deduplicated across buys or is a sum of constituent reach values.',
            ge=0.0,
        ),
    ] = None
    reach_aggregation: Annotated[
        reach_aggregation_1.ReachAggregation | None,
        Field(
            description='How reach was combined across the media buys in this aggregate. When omitted, legacy reach semantics are unknown and consumers MUST NOT use reach as the denominator for frequency.'
        ),
    ] = None
    reach_unit: Annotated[
        reach_unit_1.ReachUnit | None,
        Field(
            description='Unit of measurement for reach. Only present when all aggregated media buys use the same reach_unit.'
        ),
    ] = None
    frequency: Annotated[
        StrictFloat | None,
        Field(
            description='Average frequency per reach unit across all media buys (impressions / reach). In new payloads, only present when reach is present and reach_aggregation is deduplicated. MUST be omitted when reach_aggregation is sum_of_constituent_reach. Legacy payloads that omit reach_aggregation remain schema-valid, but consumers MUST NOT treat their reach as a safe frequency denominator.',
            ge=0.0,
        ),
    ] = None
    media_buy_count: Annotated[
        SchemaInt, Field(description='Number of media buys included in the response', ge=0)
    ]
    metric_aggregates: Annotated[
        list[delivery_metric_aggregate.DeliveryMetricAggregate] | None,
        Field(
            description="Cross-buy delivery aggregates partitioned by qualifier. Row-symmetric with `package.committed_metrics` and `by_package[].missing_metrics` — same atomic unit `(scope, metric_id, qualifier)` — so reconciliation collapses to a row-level join on the tuple. Granularity rule: one row per `(metric_id, full-qualifier-set)`, reported at the finest available granularity; buyers re-aggregate up if they want a coarser view. Used only for metrics with non-empty qualifier sets — unqualified metrics (`impressions`, `spend`, `media_buy_count`, etc.) remain at the top of `aggregated_totals`. **Mutual exclusion MUST**: for any `metric_id` appearing in `metric_aggregates`, the corresponding top-level scalar in `aggregated_totals` MUST be omitted (not zeroed) — avoids duplicate sources of truth. The qualifier vocabulary on this delivery surface is closed today (`additionalProperties: false`, same content as `committed_metrics.qualifier`) but is expected to **diverge from contract qualifier in future minors** as transparency disclosures buyers don't commit to ship delivery-only (e.g., `tracker_firing` pending #3832 resolution). Each row carries a `value` plus inlined per-metric component fields (e.g., `measurable_impressions` and `viewable_impressions` for `viewable_rate`; `spend` and `conversions` for `cost_per_acquisition`). Per-buy `totals` keeps its flat shape — each buy is single-qualifier by definition; only the aggregate spans qualifiers. **Qualifier-set drift across reports**: when a campaign gains a new qualifier mid-flight (e.g., adds `tracker_firing` partitioning in week 2), prior periods' rows remain valid at their original granularity; buyers SHOULD NOT retroactively repartition.",
            examples=[
                [
                    {
                        'scope': 'standard',
                        'metric_id': 'viewable_rate',
                        'qualifier': {'viewability_standard': 'mrc'},
                        'value': 0.7286,
                        'measurable_impressions': 700000,
                        'viewable_impressions': 510000,
                    },
                    {
                        'scope': 'standard',
                        'metric_id': 'viewable_rate',
                        'qualifier': {'viewability_standard': 'groupm'},
                        'value': 0.55,
                        'measurable_impressions': 180000,
                        'viewable_impressions': 99000,
                    },
                    {
                        'scope': 'vendor',
                        'vendor': {'domain': 'attentionvendor.example'},
                        'metric_id': 'attention_units',
                        'qualifier': {},
                        'value': 4.2,
                        'measurable_impressions': 800000,
                    },
                ]
            ],
        ),
    ] = 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

Class variables

var clicks : float | None

var commissionable_value : float | None

var completed_views : float | None

var completion_rate : float | None

var conversion_value : float | None

var conversions : float | None

var cost_per_acquisition : float | None

var frequency : float | None

var impressions : float

var media_buy_count : int

var metric_aggregates : list[DeliveryMetricAggregate1 | DeliveryMetricAggregate2] | None

var model_config

var new_to_brand_rate : float | None

var reach : float | None

var reach_aggregation : ReachAggregation | None

var reach_unit : ReachUnit | None

var roas : float | None

var spend : float

var views : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AiTool (**data: Any)

Expand source code

class AiTool(AdCPBaseModel):
    name: Annotated[
        str,
        Field(
            description="Name of the AI tool or model (e.g., 'DALL-E 3', 'Stable Diffusion XL', 'Gemini')"
        ),
    ]
    version: Annotated[
        str | None,
        Field(
            description="Version identifier for the AI tool or model (e.g., '25.1', '0125', '2.1'). For generative models, use the model version rather than the API version."
        ),
    ] = None
    provider: Annotated[
        str | None,
        Field(
            description="Organization that provides the AI tool (e.g., 'OpenAI', 'Stability AI', 'Google')"
        ),
    ] = 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

Class variables

var model_config

var name : str

var provider : str | None

var version : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Artifact (**data: Any)

Expand source code

class Artifact(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    property_rid: Annotated[
        str,
        Field(
            description='Stable property identifier from the property catalog. Globally unique across the ecosystem.'
        ),
    ]
    artifact_id: Annotated[
        str,
        Field(
            description="Identifier for this artifact within the property. The property owner defines the scheme (e.g., 'article_12345', 'episode_42_segment_3', 'post_abc123')."
        ),
    ]
    variant_id: Annotated[
        str | None,
        Field(
            description="Identifies a specific variant of this artifact. Use for A/B tests, translations, or temporal versions. Examples: 'en', 'es-MX', 'v2', 'headline_test_b'. The combination of artifact_id + variant_id must be unique."
        ),
    ] = None
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format reference. Use `format_kind` for canonical artifact media classification.',
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(description='Optional canonical media/creative kind associated with this artifact.'),
    ] = None
    url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional URL for this artifact (web page, podcast feed, video page). Not all artifacts have URLs (e.g., Instagram content, podcast segments, TV scenes).'
        ),
    ] = None
    published_time: Annotated[
        AwareDatetime | None, Field(description='When the artifact was published (ISO 8601 format)')
    ] = None
    last_update_time: Annotated[
        AwareDatetime | None,
        Field(description='When the artifact was last modified (ISO 8601 format)'),
    ] = None
    assets: Annotated[
        list[Assets],
        Field(
            description='Artifact assets in document flow order - text blocks, images, video, audio',
            max_length=200,
        ),
    ]
    metadata: Annotated[
        Metadata | None, Field(description='Rich metadata extracted from the artifact')
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this artifact. Serves as the default provenance for all assets within this artifact — individual assets can override with their own provenance.'
        ),
    ] = None
    identifiers: Annotated[
        Identifiers | None, Field(description='Platform-specific identifiers for this artifact')
    ] = 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

Class variables

var artifact_id : str

var assets : list[Assets1 | Assets2 | Assets3 | Assets4]

var format_id : FormatReferenceStructuredObject | None

var format_kind : str | None

var identifiers : Identifiers | None

var last_update_time : pydantic.types.AwareDatetime | None

var metadata : Metadata | None

var model_config

var property_rid : str

var provenance : Provenance | None

var published_time : pydantic.types.AwareDatetime | None

var url : pydantic.networks.AnyUrl | None

var variant_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ArtifactWebhookPayload (**data: Any)

Expand source code

class ArtifactWebhookPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Sender-generated key stable across retries of the same webhook event. Sales agents MUST generate a cryptographically random value (UUID v4 recommended) per distinct emission of a batch and reuse the same key on every retry. Recipients MUST dedupe by this key, scoped to the authenticated sender identity (HMAC secret or Bearer credential) — keys from different sales agents are independent. Distinct from `batch_id`, which identifies the logical batch: `idempotency_key` identifies this specific emission event, so a re-emission of the same `batch_id` (e.g., after a correction) is a different event and MUST carry a fresh `idempotency_key`.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    media_buy_id: Annotated[
        str, Field(description='Media buy identifier these artifacts belong to')
    ]
    batch_id: Annotated[
        str,
        Field(
            description='Unique identifier for this batch of artifacts. Use for deduplication and acknowledgment.'
        ),
    ]
    timestamp: Annotated[
        AwareDatetime, Field(description='When this batch was generated (ISO 8601)')
    ]
    artifacts: Annotated[
        list[Artifact], Field(description='Content artifacts from delivered impressions')
    ]
    pagination: Annotated[
        Pagination | None, Field(description='Pagination info when batching large artifact sets')
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var artifacts : list[Artifact]

var batch_id : str

var ext : ExtensionObject | None

var idempotency_key : str

var media_buy_id : str

var model_config

var pagination : Pagination | None

var timestamp : pydantic.types.AwareDatetime

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Asset (**data: Any)

Expand source code

class Asset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_id: Annotated[str, Field(description='Unique identifier')]
    asset_type: Annotated[AssetContentType, Field(description='Type of asset content')]
    url: Annotated[AnyUrl, Field(description='URL to CDN-hosted asset file')]
    tags: Annotated[
        list[str] | None,
        Field(description="Tags for discovery (e.g., 'hero', 'lifestyle', 'product', 'holiday')"),
    ] = None
    name: Annotated[
        LocalizedScalar | None,
        Field(description='Human-readable name, either a legacy plain string or localized values.'),
    ] = None
    description: Annotated[
        LocalizedScalar | None,
        Field(
            description='Asset description or usage notes, either a legacy plain string or localized values.'
        ),
    ] = None
    width: Annotated[SchemaInt | None, Field(description='Image/video width in pixels')] = None
    height: Annotated[SchemaInt | None, Field(description='Image/video height in pixels')] = None
    duration_seconds: Annotated[
        StrictFloat | None, Field(description='Video/audio duration in seconds')
    ] = None
    file_size_bytes: Annotated[SchemaInt | None, Field(description='File size in bytes')] = None
    format: Annotated[str | None, Field(description="File format (e.g., 'jpg', 'mp4', 'mp3')")] = (
        None
    )
    metadata: Annotated[
        dict[str, Any] | None, Field(description='Additional asset-specific metadata')
    ] = 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

Class variables

var asset_id : str

var asset_type : AssetContentType

var description : LocalizedScalar | None

var duration_seconds : float | None

var file_size_bytes : int | None

var format : str | None

var height : int | None

var metadata : dict[str, typing.Any] | None

var model_config

var name : LocalizedScalar | None

var tags : list[str] | None

var url : pydantic.networks.AnyUrl

var width : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AssetContentType (*args, **kwds)

Expand source code

class AssetContentType(StrEnum):
    image = 'image'
    video = 'video'
    audio = 'audio'
    text = 'text'
    markdown = 'markdown'
    html = 'html'
    css = 'css'
    javascript = 'javascript'
    zip = 'zip'
    vast = 'vast'
    daast = 'daast'
    url = 'url'
    webhook = 'webhook'
    brief = 'brief'
    catalog = 'catalog'
    published_post = 'published_post'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audio

var brief

var catalog

var css

var daast

var html

var image

var javascript

var markdown

var published_post

var text

var url

var vast

var video

var webhook

var zip

class AssetType (*args, **kwds)

Expand source code

class AssetContentType(StrEnum):
    image = 'image'
    video = 'video'
    audio = 'audio'
    text = 'text'
    markdown = 'markdown'
    html = 'html'
    css = 'css'
    javascript = 'javascript'
    zip = 'zip'
    vast = 'vast'
    daast = 'daast'
    url = 'url'
    webhook = 'webhook'
    brief = 'brief'
    catalog = 'catalog'
    published_post = 'published_post'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audio

var brief

var catalog

var css

var daast

var html

var image

var javascript

var markdown

var published_post

var text

var url

var vast

var video

var webhook

var zip

class CanonicalAssetSource (*args, **kwds)

Expand source code

class AssetSource(StrEnum):
    buyer_uploaded = 'buyer_uploaded'
    publisher_host_recorded = 'publisher_host_recorded'
    seller_pre_rendered_from_brief = 'seller_pre_rendered_from_brief'
    seller_human_designed = 'seller_human_designed'
    agent_synthesized = 'agent_synthesized'
    publisher_owned_reference = 'publisher_owned_reference'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var agent_synthesized

var buyer_uploaded

var publisher_host_recorded

var publisher_owned_reference

var seller_human_designed

var seller_pre_rendered_from_brief

class ImageFormatAsset (**data: Any)

Expand source code

class Assets(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['image'] = 'image'
    requirements: image_asset_requirements.ImageAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['image']

var item_type : Literal['individual']

var model_config

var requirements : ImageAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class AudioFormatAsset (**data: Any)

Expand source code

class Assets10(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['audio'] = 'audio'
    requirements: audio_asset_requirements.AudioAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['audio']

var item_type : Literal['individual']

var model_config

var requirements : AudioAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class TextFormatAsset (**data: Any)

Expand source code

class Assets11(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['text'] = 'text'
    requirements: text_asset_requirements.TextAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['text']

var item_type : Literal['individual']

var model_config

var requirements : TextAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class MarkdownFormatAsset (**data: Any)

Expand source code

class Assets12(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['markdown'] = 'markdown'
    requirements: markdown_asset_requirements.MarkdownAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['markdown']

var item_type : Literal['individual']

var model_config

var requirements : MarkdownAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class HtmlFormatAsset (**data: Any)

Expand source code

class Assets13(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['html'] = 'html'
    requirements: html_asset_requirements.HtmlAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['html']

var item_type : Literal['individual']

var model_config

var requirements : HtmlAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class CssFormatAsset (**data: Any)

Expand source code

class Assets14(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['css'] = 'css'
    requirements: css_asset_requirements.CssAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['css']

var item_type : Literal['individual']

var model_config

var requirements : CssAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class JavascriptFormatAsset (**data: Any)

Expand source code

class Assets15(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['javascript'] = 'javascript'
    requirements: javascript_asset_requirements.JavascriptAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['javascript']

var item_type : Literal['individual']

var model_config

var requirements : JavascriptAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class VastFormatAsset (**data: Any)

Expand source code

class Assets17(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['vast'] = 'vast'
    requirements: vast_asset_requirements.VastAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['vast']

var item_type : Literal['individual']

var model_config

var requirements : VastAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class DaastFormatAsset (**data: Any)

Expand source code

class Assets18(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['daast'] = 'daast'
    requirements: daast_asset_requirements.DaastAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['daast']

var item_type : Literal['individual']

var model_config

var requirements : DaastAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class UrlFormatAsset (**data: Any)

Expand source code

class Assets19(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['url'] = 'url'
    requirements: url_asset_requirements.UrlAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['url']

var item_type : Literal['individual']

var model_config

var requirements : UrlAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class WebhookFormatAsset (**data: Any)

Expand source code

class Assets20(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['webhook'] = 'webhook'
    requirements: webhook_asset_requirements.WebhookAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['webhook']

var item_type : Literal['individual']

var model_config

var requirements : WebhookAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class BriefFormatAsset (**data: Any)

Expand source code

class Assets21(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['brief'] = 'brief'

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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['brief']

var item_type : Literal['individual']

var model_config

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class CatalogFormatAsset (**data: Any)

Expand source code

class Assets22(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['catalog'] = 'catalog'
    requirements: catalog_requirements.CatalogRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['catalog']

var item_type : Literal['individual']

var model_config

var requirements : CatalogRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class RepeatableAssetGroup (**data: Any)

Expand source code

class Assets29(AdCPBaseModel):
    item_type: Annotated[
        Literal['repeatable_group'],
        Field(description='Discriminator indicating this is a repeatable asset group'),
    ] = 'repeatable_group'
    asset_group_id: Annotated[
        str, Field(description="Identifier for this asset group (e.g., 'product', 'slide', 'card')")
    ]
    required: Annotated[
        StrictBool,
        Field(
            description='Whether this asset group is required. If true, at least min_count repetitions must be provided.'
        ),
    ]
    min_count: Annotated[
        SchemaInt,
        Field(
            description='Minimum number of repetitions required (if group is required) or allowed (if optional)',
            ge=0,
        ),
    ]
    max_count: Annotated[
        SchemaInt, Field(description='Maximum number of repetitions allowed', ge=1)
    ]
    selection_mode: Annotated[
        SelectionMode | None,
        Field(
            description="How the platform uses repetitions of this group. 'sequential' means all items display in order (carousels, playlists). 'optimize' means the platform selects the best-performing combination from alternatives (asset group optimization like Meta Advantage+ or Google Pmax)."
        ),
    ] = SelectionMode.sequential
    assets: Annotated[
        list[Assets30], Field(description='Assets within each repetition of this group')
    ]

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

Class variables

var asset_group_id : str

var assets : list[Assets31 | Assets32 | Assets33 | Assets34 | Assets35 | Assets36 | Assets37 | Assets38 | Assets40 | Assets41 | Assets42 | Assets43 | UnknownGroupAsset]

var item_type : Literal['repeatable_group']

var max_count : int

var min_count : int

var model_config

var required : bool

var selection_mode : SelectionMode | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ImageFormatGroupAsset (**data: Any)

Expand source code

class Assets31(BaseGroupAsset):
    asset_type: Literal['image'] = 'image'
    requirements: image_asset_requirements.ImageAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['image']

var model_config

var requirements : ImageAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class VideoFormatGroupAsset (**data: Any)

Expand source code

class Assets32(BaseGroupAsset):
    asset_type: Literal['video'] = 'video'
    requirements: video_asset_requirements.VideoAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['video']

var model_config

var requirements : VideoAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class AudioFormatGroupAsset (**data: Any)

Expand source code

class Assets33(BaseGroupAsset):
    asset_type: Literal['audio'] = 'audio'
    requirements: audio_asset_requirements.AudioAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['audio']

var model_config

var requirements : AudioAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class TextFormatGroupAsset (**data: Any)

Expand source code

class Assets34(BaseGroupAsset):
    asset_type: Literal['text'] = 'text'
    requirements: text_asset_requirements.TextAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['text']

var model_config

var requirements : TextAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class MarkdownFormatGroupAsset (**data: Any)

Expand source code

class Assets35(BaseGroupAsset):
    asset_type: Literal['markdown'] = 'markdown'
    requirements: markdown_asset_requirements.MarkdownAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['markdown']

var model_config

var requirements : MarkdownAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class HtmlFormatGroupAsset (**data: Any)

Expand source code

class Assets36(BaseGroupAsset):
    asset_type: Literal['html'] = 'html'
    requirements: html_asset_requirements.HtmlAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['html']

var model_config

var requirements : HtmlAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class CssFormatGroupAsset (**data: Any)

Expand source code

class Assets37(BaseGroupAsset):
    asset_type: Literal['css'] = 'css'
    requirements: css_asset_requirements.CssAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['css']

var model_config

var requirements : CssAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class JavascriptFormatGroupAsset (**data: Any)

Expand source code

class Assets38(BaseGroupAsset):
    asset_type: Literal['javascript'] = 'javascript'
    requirements: javascript_asset_requirements.JavascriptAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['javascript']

var model_config

var requirements : JavascriptAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class VastFormatGroupAsset (**data: Any)

Expand source code

class Assets40(BaseGroupAsset):
    asset_type: Literal['vast'] = 'vast'
    requirements: vast_asset_requirements.VastAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['vast']

var model_config

var requirements : VastAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class DaastFormatGroupAsset (**data: Any)

Expand source code

class Assets41(BaseGroupAsset):
    asset_type: Literal['daast'] = 'daast'
    requirements: daast_asset_requirements.DaastAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['daast']

var model_config

var requirements : DaastAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class UrlFormatGroupAsset (**data: Any)

Expand source code

class Assets42(BaseGroupAsset):
    asset_type: Literal['url'] = 'url'
    requirements: url_asset_requirements.UrlAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['url']

var model_config

var requirements : UrlAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class WebhookFormatGroupAsset (**data: Any)

Expand source code

class Assets43(BaseGroupAsset):
    asset_type: Literal['webhook'] = 'webhook'
    requirements: webhook_asset_requirements.WebhookAssetRequirements | None = 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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['webhook']

var model_config

var requirements : WebhookAssetRequirements | None

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class VideoFormatAsset (**data: Any)

Expand source code

class Assets9(BaseIndividualAsset):
    item_type: Literal['individual'] = 'individual'
    asset_type: Literal['video'] = 'video'
    requirements: video_asset_requirements.VideoAssetRequirements | None = 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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['video']

var item_type : Literal['individual']

var model_config

var requirements : VideoAssetRequirements | None

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class AssignedPackage (**data: Any)

Expand source code

class AssignedPackage(IndicatorBearingResourceState):
    model_config = ConfigDict(
        extra='allow',
    )
    indicator_types_evaluated: Annotated[
        list[IndicatorTypesEvaluatedEnum] | None,
        Field(
            description='Indicator types covered by this snapshot. Required whenever indicators is present. Types omitted from this list remain unknown even when indicators is empty. Every returned indicator.type MUST appear in this list.',
            min_length=1,
        ),
    ] = None
    indicators: Annotated[
        list[Indicator] | None,
        Field(
            description='Current seller assertions for the indicator types and publisher/placement coverage named by the sibling evaluation fields. Omitted means unknown or not evaluated. A present empty array means evaluated with no current assertion for indicator_types_evaluated in the evaluated scope.'
        ),
    ] = None
    package_id: Annotated[str, Field(description='Package identifier')]
    media_buy_id: Annotated[
        str | None,
        Field(
            description='Media buy containing this package. A seller advertising list_creatives in media_buy.relationship_notifications.projection_tasks MUST include this field on every assignment row, including rows where indicators is omitted as unknown, so buyers can key and reread the relationship unambiguously when package IDs are reused across media buys.'
        ),
    ] = None
    assigned_date: Annotated[AwareDatetime, Field(description='When this assignment was created')]
    approval_status: Annotated[
        creative_approval_status.CreativeApprovalStatus | None,
        Field(
            description='Aggregate approval state for this creative in this package assignment. This mirrors the same relationship in get_media_buys. Sellers advertising list_creatives as an indicator projection task MUST include it; partially_approved requires approval_scopes.'
        ),
    ] = None
    rejection_reason: Annotated[
        str | None,
        Field(
            description='Human-readable explanation when approval_status is rejected. Mirrors get_media_buys for the same relationship.'
        ),
    ] = None
    approval_scopes: Annotated[
        list[creative_approval_scope.ScopedCreativeApproval] | None,
        Field(
            description='Complete, disjoint publisher/placement approval partition when approval_status is partially_approved. A normalized scope appears once. For one publisher, use either one publisher-wide row or placement-specific rows, never both. Omit when one approval_status applies uniformly to the whole assignment. The same scoped outcomes are mirrored on get_media_buys.',
            min_length=2,
        ),
    ] = None
    indicators_as_of: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller last completed the evaluation represented by indicators for this relationship. Required whenever indicators is present, including an empty array.'
        ),
    ] = None
    indicators_evaluated_scope: Annotated[
        list[indicator_scope.IndicatorScope] | None,
        Field(
            description='Optional publisher or placement scopes covered by this evaluation. Omit when indicators covers the whole package–creative assignment. When present, scopes not listed remain unknown; every returned indicator.scope entry MUST be contained by this set.',
            min_length=1,
        ),
    ] = 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

• IndicatorBearingResourceState
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var approval_scopes : list[ScopedCreativeApproval] | None

var approval_status : CreativeApprovalStatus | None

var assigned_date : pydantic.types.AwareDatetime

var indicator_types_evaluated : list[IndicatorTypesEvaluatedEnum] | None

var indicators : list[Indicator] | None

var indicators_as_of : pydantic.types.AwareDatetime | None

var indicators_evaluated_scope : list[IndicatorScope] | None

var media_buy_id : str | None

var model_config

var package_id : str

var rejection_reason : str | None

Inherited members

• IndicatorBearingResourceState:
  • model_dump
  • model_dump_json
  • model_summary

class Assignments (**data: Any)

Expand source code

class Assignments(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    assignment_count: Annotated[
        SchemaInt, Field(description='Total number of active package assignments', ge=0)
    ]
    returned_assignment_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of rows present in assigned_packages for this response.',
            ge=0,
            le=200,
        ),
    ] = None
    matching_assignment_count: Annotated[
        SchemaInt | None,
        Field(
            description='Total active assignments matching filters.indicator_types. MUST be present exactly when assignment_projection was matching. May exceed returned_assignment_count.',
            ge=0,
        ),
    ] = None
    assignments_truncated: Annotated[
        StrictBool | None,
        Field(
            description='True exactly when more qualifying assignments exist than were returned under assignment_limit. Qualifying means assignment_count for the all projection and matching_assignment_count for the matching projection. Buyers needing complete state repair through get_media_buys.'
        ),
    ] = None
    assigned_packages: Annotated[
        list[AssignedPackage] | None,
        Field(
            description='Bounded package assignment projection. Under assignment_projection: matching, contains only assignments carrying a requested indicator type; otherwise contains active assignments up to assignment_limit. The response ceiling is enforced via verifier_constraints rather than maxItems, so payloads from 3.1 sellers remain schema-valid.'
        ),
    ] = 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

Class variables

var assigned_packages : list[AssignedPackage] | None

var assignment_count : int

var assignments_truncated : bool | None

var matching_assignment_count : int | None

var model_config

var returned_assignment_count : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SyncAudiencesAudience (**data: Any)

Expand source code

class Audience(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    audience_id: Annotated[
        str,
        Field(
            description="Buyer's identifier for this audience. Used to reference the audience in targeting overlays."
        ),
    ]
    name: Annotated[str | None, Field(description='Human-readable name for this audience')] = None
    description: Annotated[
        str | None,
        Field(
            description="Human-readable description of this audience's composition or purpose (e.g., 'High-value customers who purchased in the last 90 days')."
        ),
    ] = None
    audience_type: Annotated[
        AudienceType | None,
        Field(
            description="Intended use for this audience. 'crm': target these users. 'suppression': exclude these users from delivery. 'lookalike_seed': use as a seed for the seller's lookalike modeling. Sellers may handle audiences differently based on type (e.g., suppression lists bypass minimum size requirements on some platforms)."
        ),
    ] = None
    tags: Annotated[
        list[Tag] | None,
        Field(
            description="Buyer-defined tags for organizing and filtering audiences (e.g., 'holiday_2026', 'high_ltv'). Tags are stored by the seller and returned in discovery-only calls."
        ),
    ] = None
    add: Annotated[
        list[audience_member.AudienceMember] | None,
        Field(
            description='Members to add to this audience. Hashed before sending — normalize emails to lowercase+trim, phones to E.164.',
            min_length=1,
        ),
    ] = None
    remove: Annotated[
        list[audience_member.AudienceMember] | None,
        Field(
            description='Members to remove from this audience. If the same identifier appears in both add and remove in a single request, remove takes precedence.',
            min_length=1,
        ),
    ] = None
    source: Annotated[
        audience_source.AudienceSource | None,
        Field(
            description='External source reference: the seller ingests membership from a shared dataset or vendor-distributed segment instead of inline member deltas. Mutually exclusive with add/remove — an audience is either buyer-pushed or externally sourced, and transport is fixed at creation: a cross-transport upsert (member deltas against a sourced audience, or source against a pushed one) is rejected with CONFLICT (error.field: audience_id); convert by delete-and-recreate. Only send source kinds whose activation pattern the seller declared via audience_activation (undeclared kinds are rejected with UNSUPPORTED_FEATURE). Experimental — see the media_buy.audience_activation feature.'
        ),
    ] = None
    delete: Annotated[
        StrictBool | None,
        Field(
            description='When true, delete this audience from the account entirely. All other fields on this audience object are ignored. Use this to delete a specific audience without affecting others.'
        ),
    ] = None
    consent_basis: Annotated[
        consent_basis_1.ConsentBasis | None,
        Field(
            description='GDPR lawful basis for processing this audience list. Informational — not validated by the protocol, but required by some sellers operating in regulated markets (e.g. EU). When omitted, the buyer asserts they have a lawful basis appropriate to their jurisdiction.'
        ),
    ] = 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

Class variables

var add : list[AudienceMember] | None

var audience_id : str

var audience_type : AudienceType | None

var consent_basis : ConsentBasis | None

var delete : bool | None

var description : str | None

var model_config

var name : str | None

var remove : list[AudienceMember] | None

var source : AudienceSource1 | AudienceSource2 | None

var tags : list[Tag] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AudienceSource (*args, **kwds)

Expand source code

class AudienceSource(StrEnum):
    synced = 'synced'
    platform = 'platform'
    third_party = 'third_party'
    lookalike = 'lookalike'
    retargeting = 'retargeting'
    unknown = 'unknown'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var lookalike

var platform

var retargeting

var synced

var third_party

var unknown

class AudienceTooSmallDetails (**data: Any)

Expand source code

class AudienceTooSmallDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    minimum_size: Annotated[
        StrictFloat | None, Field(description='Minimum audience size required')
    ] = None
    current_size: Annotated[StrictFloat | None, Field(description='Current audience size')] = 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

Class variables

var current_size : float | None

var minimum_size : float | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AudioContent (**data: Any)

Expand source code

class AudioAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['audio'],
        Field(
            description='Discriminator identifying this as an audio asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'audio'
    url: Annotated[AnyUrl, Field(description='URL to the audio asset')]
    duration_ms: Annotated[
        SchemaInt | None, Field(description='Audio duration in milliseconds', ge=0)
    ] = None
    file_size_bytes: Annotated[SchemaInt | None, Field(description='File size in bytes', ge=1)] = (
        None
    )
    container_format: Annotated[
        str | None,
        Field(description='Audio container/file format (mp3, m4a, aac, wav, ogg, flac, etc.)'),
    ] = None
    codec: Annotated[
        str | None,
        Field(
            description='Audio codec used (aac, aac_lc, he_aac, pcm, mp3, vorbis, opus, flac, ac3, eac3, etc.)'
        ),
    ] = None
    sampling_rate_hz: Annotated[
        SchemaInt | None, Field(description='Sampling rate in Hz (e.g., 44100, 48000, 96000)')
    ] = None
    channels: Annotated[
        audio_channel_layout.AudioChannelLayout | None, Field(description='Channel configuration')
    ] = None
    bit_depth: Annotated[BitDepth | None, Field(description='Bit depth')] = None
    bitrate_kbps: Annotated[
        SchemaInt | None, Field(description='Bitrate in kilobits per second', ge=1)
    ] = None
    loudness_lufs: Annotated[
        StrictFloat | None, Field(description='Integrated loudness in LUFS')
    ] = None
    true_peak_dbfs: Annotated[StrictFloat | None, Field(description='True peak level in dBFS')] = (
        None
    )
    transcript_url: Annotated[
        AnyUrl | None, Field(description='URL to text transcript of the audio content')
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var asset_type : Literal['audio']

var bit_depth : BitDepth | None

var bitrate_kbps : int | None

var channels : AudioChannelLayout | None

var codec : str | None

var container_format : str | None

var duration_ms : int | None

var file_size_bytes : int | None

var loudness_lufs : float | None

var model_config

var provenance : Provenance | None

var sampling_rate_hz : int | None

var transcript_url : pydantic.networks.AnyUrl | None

var true_peak_dbfs : float | None

var url : pydantic.networks.AnyUrl

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.

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

Class variables

var credentials : str

var model_config

var schemes : list[typing.Literal['Bearer']]

class PushNotificationAuthentication (**data: Any)

Expand source code

class Authentication(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    schemes: Annotated[
        list[auth_scheme.AuthenticationScheme],
        Field(
            description="Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for legacy shared-secret signing. Both are deprecated; new integrations SHOULD omit `authentication` and use the RFC 9421 webhook profile.",
            max_length=1,
            min_length=1,
        ),
    ]
    credentials: Annotated[
        str,
        Field(
            description='Credentials for the legacy scheme. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.',
            min_length=32,
        ),
    ]

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

Class variables

var credentials : str

var model_config

var schemes : list[AuthenticationScheme]

class NotificationAuthentication (**data: Any)

Expand source code

class Authentication(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    schemes: Annotated[list[auth_scheme.AuthenticationScheme], Field(max_length=1, min_length=1)]
    credentials: Annotated[
        str | None,
        Field(
            description='Credentials for the legacy scheme. Bearer: token. HMAC-SHA256: shared secret. Minimum 32 characters. Exchanged out-of-band during onboarding. Write-only.',
            min_length=32,
        ),
    ] = 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

• adcp.types.projections._NotificationAuthenticationResponse

Class variables

var credentials : str | None

var model_config

var schemes : list[AuthenticationScheme]

class ReportingWebhookAuthentication (**data: Any)

Expand source code

class Authentication(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    schemes: Annotated[
        list[auth_scheme.AuthenticationScheme],
        Field(
            description="Array of authentication schemes. ['Bearer'] for simple token auth, ['HMAC-SHA256'] for legacy shared-secret signing. Both are deprecated; new integrations SHOULD use the RFC 9421 webhook signing profile instead.",
            max_length=1,
            min_length=1,
        ),
    ]
    credentials: Annotated[
        str,
        Field(
            description='Credentials for the legacy scheme. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.',
            min_length=32,
        ),
    ]

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

Class variables

var credentials : str

var model_config

var schemes : list[AuthenticationScheme]

class GovernanceAuthentication (**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.

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

Class variables

var credentials : str

var model_config

var schemes : list[typing.Literal['Bearer']]

class CreateMediaBuyAuthentication (**data: Any)

Expand source code

class Authentication(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    schemes: Annotated[
        list[auth_scheme.AuthenticationScheme],
        Field(
            description="Array of authentication schemes. ['Bearer'] for simple token auth, ['HMAC-SHA256'] for legacy shared-secret signing. Both are deprecated; new integrations SHOULD use the RFC 9421 webhook signing profile instead.",
            max_length=1,
            min_length=1,
        ),
    ]
    credentials: Annotated[
        str,
        Field(
            description='Credentials for the legacy scheme. For Bearer: token sent in Authorization header. For HMAC-SHA256: shared secret used to generate signature. Minimum 32 characters. Exchanged out-of-band during onboarding.',
            min_length=32,
        ),
    ]

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

Class variables

var credentials : str

var model_config

var schemes : list[AuthenticationScheme]

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 Scheme (*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 ReportingAuthoritativeParty (*args, **kwds)

Expand source code

class AuthoritativeParty(StrEnum):
    seller = 'seller'
    consumer = 'consumer'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var consumer

var seller

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.

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

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 AuthorizedAgents (**data: Any)

Expand source code

class AuthorizedAgents1(AuthorizedAgentBaseFields):
    model_config = ConfigDict(
        extra='allow',
    )
    authorization_type: Annotated[
        Literal['property_ids'],
        Field(description='Discriminator indicating authorization by specific property IDs'),
    ] = 'property_ids'
    property_ids: Annotated[
        list[property_id.PropertyId],
        Field(
            description='Property IDs this agent is authorized for. Resolved against the top-level properties array in this file',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description="Optional collection constraints. When present, authorization only applies to inventory associated with these collections. A selector without collection_ids grants for all collections declared in that selector's publisher_domain adagents.json (the bulk-grant form for owner-sold carriage).",
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        StrictBool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = 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

• AuthorizedAgentBaseFields
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AuthorizedAgents15
• AuthorizedAgents22
• AuthorizedAgents29
• AuthorizedAgents36
• AuthorizedAgents43
• AuthorizedAgents8

Class variables

var authorization_type : Literal['property_ids']

var collections : list[CollectionSelector] | None

var countries : list[Country] | None

var delegation_type : DelegationType | None

var effective_from : pydantic.types.AwareDatetime | None

var effective_until : pydantic.types.AwareDatetime | None

var exclusive : bool | None

var model_config

var placement_ids : list[str] | None

var placement_tags : list[str] | None

var property_ids : list[PropertyId]

class AuthorizedAgentsByPropertyId (**data: Any)

Expand source code

class AuthorizedAgents1(AuthorizedAgentBaseFields):
    model_config = ConfigDict(
        extra='allow',
    )
    authorization_type: Annotated[
        Literal['property_ids'],
        Field(description='Discriminator indicating authorization by specific property IDs'),
    ] = 'property_ids'
    property_ids: Annotated[
        list[property_id.PropertyId],
        Field(
            description='Property IDs this agent is authorized for. Resolved against the top-level properties array in this file',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description="Optional collection constraints. When present, authorization only applies to inventory associated with these collections. A selector without collection_ids grants for all collections declared in that selector's publisher_domain adagents.json (the bulk-grant form for owner-sold carriage).",
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        StrictBool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = 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

• AuthorizedAgentBaseFields
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AuthorizedAgents15
• AuthorizedAgents22
• AuthorizedAgents29
• AuthorizedAgents36
• AuthorizedAgents43
• AuthorizedAgents8

Class variables

var authorization_type : Literal['property_ids']

var collections : list[CollectionSelector] | None

var countries : list[Country] | None

var delegation_type : DelegationType | None

var effective_from : pydantic.types.AwareDatetime | None

var effective_until : pydantic.types.AwareDatetime | None

var exclusive : bool | None

var model_config

var placement_ids : list[str] | None

var placement_tags : list[str] | None

var property_ids : list[PropertyId]

Inherited members

• AuthorizedAgentBaseFields:
  • model_dump
  • model_dump_json
  • model_summary

class AuthorizedAgentsByPropertyTag (**data: Any)

Expand source code

class AuthorizedAgents2(AuthorizedAgentBaseFields):
    model_config = ConfigDict(
        extra='allow',
    )
    authorization_type: Annotated[
        Literal['property_tags'],
        Field(description='Discriminator indicating authorization by property tags'),
    ] = 'property_tags'
    property_tags: Annotated[
        list[property_tag.PropertyTag],
        Field(
            description='Tags identifying which properties this agent is authorized for. Resolved against the top-level properties array in this file using tag matching',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description="Optional collection constraints. When present, authorization only applies to inventory associated with these collections. A selector without collection_ids grants for all collections declared in that selector's publisher_domain adagents.json (the bulk-grant form for owner-sold carriage).",
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        StrictBool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = 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

• AuthorizedAgentBaseFields
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AuthorizedAgents16
• AuthorizedAgents23
• AuthorizedAgents30
• AuthorizedAgents37
• AuthorizedAgents44
• AuthorizedAgents9

Class variables

var authorization_type : Literal['property_tags']

var collections : list[CollectionSelector] | None

var countries : list[Country] | None

var delegation_type : DelegationType | None

var effective_from : pydantic.types.AwareDatetime | None

var effective_until : pydantic.types.AwareDatetime | None

var exclusive : bool | None

var model_config

var placement_ids : list[str] | None

var placement_tags : list[str] | None

var property_tags : list[PropertyTag]

Inherited members

• AuthorizedAgentBaseFields:
  • model_dump
  • model_dump_json
  • model_summary

class AuthorizedAgentsByInlineProperties (**data: Any)

Expand source code

class AuthorizedAgents3(AuthorizedAgentBaseFields):
    model_config = ConfigDict(
        extra='allow',
    )
    authorization_type: Annotated[
        Literal['inline_properties'],
        Field(
            description='Discriminator indicating authorization by inline property definitions. Companion field is `properties` (not `inline_properties`) — the only authorization_type whose companion field name does not mirror the discriminator value.'
        ),
    ] = 'inline_properties'
    properties: Annotated[
        list[property.Property],
        Field(
            description='Specific properties this agent is authorized for, defined inline on the agent entry (alternative to property_ids/property_tags). Note: this is the companion field for `authorization_type: "inline_properties"` — the field is named `properties`, not `inline_properties`.',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description="Optional collection constraints. When present, authorization only applies to inventory associated with these collections. A selector without collection_ids grants for all collections declared in that selector's publisher_domain adagents.json (the bulk-grant form for owner-sold carriage).",
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        StrictBool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = 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

• AuthorizedAgentBaseFields
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AuthorizedAgents10
• AuthorizedAgents17
• AuthorizedAgents24
• AuthorizedAgents31
• AuthorizedAgents38
• AuthorizedAgents45

Class variables

var authorization_type : Literal['inline_properties']

var collections : list[CollectionSelector] | None

var countries : list[Country] | None

var delegation_type : DelegationType | None

var effective_from : pydantic.types.AwareDatetime | None

var effective_until : pydantic.types.AwareDatetime | None

var exclusive : bool | None

var model_config

var placement_ids : list[str] | None

var placement_tags : list[str] | None

var properties : list[Property]

Inherited members

• AuthorizedAgentBaseFields:
  • model_dump
  • model_dump_json
  • model_summary

class AuthorizedAgentsByPublisherProperties (**data: Any)

Expand source code

class AuthorizedAgents4(AuthorizedAgentBaseFields):
    model_config = ConfigDict(
        extra='allow',
    )
    authorization_type: Annotated[
        Literal['publisher_properties'],
        Field(
            description='Discriminator indicating authorization for properties from other publisher domains'
        ),
    ] = 'publisher_properties'
    publisher_properties: Annotated[
        list[publisher_property_selector.PublisherPropertySelector],
        Field(
            description='Properties from other publisher domains this agent is authorized for. Each entry specifies a publisher domain and which of their properties this agent can sell',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description="Optional collection constraints. When present, authorization only applies to inventory associated with these collections. A selector without collection_ids grants for all collections declared in that selector's publisher_domain adagents.json (the bulk-grant form for owner-sold carriage).",
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        StrictBool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = 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

• AuthorizedAgentBaseFields
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AuthorizedAgents11
• AuthorizedAgents18
• AuthorizedAgents25
• AuthorizedAgents32
• AuthorizedAgents39
• AuthorizedAgents46

Class variables

var authorization_type : Literal['publisher_properties']

var collections : list[CollectionSelector] | None

var countries : list[Country] | None

var delegation_type : DelegationType | None

var effective_from : pydantic.types.AwareDatetime | None

var effective_until : pydantic.types.AwareDatetime | None

var exclusive : bool | None

var model_config

var placement_ids : list[str] | None

var placement_tags : list[str] | None

var publisher_properties : list[PublisherPropertySelector1 | PublisherPropertySelector2 | PublisherPropertySelector3]

Inherited members

• AuthorizedAgentBaseFields:
  • model_dump
  • model_dump_json
  • model_summary

class AuthorizedAgentsBySignalId (**data: Any)

Expand source code

class AuthorizedAgents5(AuthorizedAgentBaseFields):
    model_config = ConfigDict(
        extra='allow',
    )
    authorization_type: Annotated[
        Literal['signal_ids'],
        Field(description='Discriminator indicating authorization by specific signal IDs'),
    ] = 'signal_ids'
    signal_ids: Annotated[
        list[SignalId],
        Field(
            description='Signal IDs this agent is authorized to resell. Resolved against the top-level signals array in this file',
            min_length=1,
        ),
    ]

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

• AuthorizedAgentBaseFields
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AuthorizedAgents12
• AuthorizedAgents19
• AuthorizedAgents26
• AuthorizedAgents33
• AuthorizedAgents40
• AuthorizedAgents47

Class variables

var authorization_type : Literal['signal_ids']

var model_config

var signal_ids : list[SignalId]

Inherited members

• AuthorizedAgentBaseFields:
  • model_dump
  • model_dump_json
  • model_summary

class AuthorizedAgentsBySignalTag (**data: Any)

Expand source code

class AuthorizedAgents6(AuthorizedAgentBaseFields):
    model_config = ConfigDict(
        extra='allow',
    )
    authorization_type: Annotated[
        Literal['signal_tags'],
        Field(description='Discriminator indicating authorization by signal tags'),
    ] = 'signal_tags'
    signal_tags: Annotated[
        list[SignalTag],
        Field(
            description='Signal tags this agent is authorized for. Agent can resell all signals with these tags',
            min_length=1,
        ),
    ]

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

• AuthorizedAgentBaseFields
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• AuthorizedAgents13
• AuthorizedAgents20
• AuthorizedAgents27
• AuthorizedAgents34
• AuthorizedAgents41
• AuthorizedAgents48

Class variables

var authorization_type : Literal['signal_tags']

var model_config

var signal_tags : list[SignalTag]

Inherited members

• AuthorizedAgentBaseFields:
  • model_dump
  • model_dump_json
  • model_summary

class AvailableMetric (*args, **kwds)

Expand source code

class AvailableMetric(StrEnum):
    impressions = 'impressions'
    spend = 'spend'
    clicks = 'clicks'
    ctr = 'ctr'
    views = 'views'
    completed_views = 'completed_views'
    completion_rate = 'completion_rate'
    conversions = 'conversions'
    conversion_value = 'conversion_value'
    commissionable_value = 'commissionable_value'
    roas = 'roas'
    cost_per_acquisition = 'cost_per_acquisition'
    new_to_brand_rate = 'new_to_brand_rate'
    leads = 'leads'
    reach = 'reach'
    frequency = 'frequency'
    grps = 'grps'
    engagements = 'engagements'
    engagement_rate = 'engagement_rate'
    follows = 'follows'
    saves = 'saves'
    profile_visits = 'profile_visits'
    viewability = 'viewability'
    viewable_rate = 'viewable_rate'
    viewable_impressions = 'viewable_impressions'
    measurable_impressions = 'measurable_impressions'
    viewed_seconds = 'viewed_seconds'
    viewed_seconds_percentiles = 'viewed_seconds_percentiles'
    viewed_seconds_histogram = 'viewed_seconds_histogram'
    quartile_data = 'quartile_data'
    quartile_25 = 'quartile_25'
    quartile_50 = 'quartile_50'
    quartile_75 = 'quartile_75'
    quartile_100 = 'quartile_100'
    time_based_views = 'time_based_views'
    dooh_metrics = 'dooh_metrics'
    ooh_metrics = 'ooh_metrics'
    cost_per_click = 'cost_per_click'
    cost_per_completed_view = 'cost_per_completed_view'
    cpm = 'cpm'
    downloads = 'downloads'
    units_sold = 'units_sold'
    new_to_brand_units = 'new_to_brand_units'
    plays = 'plays'
    incremental_sales_lift = 'incremental_sales_lift'
    brand_lift = 'brand_lift'
    foot_traffic = 'foot_traffic'
    conversion_lift = 'conversion_lift'
    brand_search_lift = 'brand_search_lift'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var brand_lift

var brand_search_lift

var clicks

var commissionable_value

var completed_views

var completion_rate

var conversion_lift

var conversion_value

var conversions

var cost_per_acquisition

var cost_per_click

var cost_per_completed_view

var cpm

var ctr

var dooh_metrics

var downloads

var engagement_rate

var engagements

var follows

var foot_traffic

var frequency

var grps

var impressions

var incremental_sales_lift

var leads

var measurable_impressions

var new_to_brand_rate

var new_to_brand_units

var ooh_metrics

var plays

var profile_visits

var quartile_100

var quartile_25

var quartile_50

var quartile_75

var quartile_data

var reach

var roas

var saves

var spend

var time_based_views

var units_sold

var viewability

var viewable_impressions

var viewable_rate

var viewed_seconds

var viewed_seconds_histogram

var viewed_seconds_percentiles

var views

class AvailablePackage (**data: Any)

Expand source code

class AvailablePackage(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    package_id: Annotated[str, Field(description='Unique identifier for the package')]
    media_buy_id: Annotated[str, Field(description='Media buy that this package belongs to')]
    seller_agent: Annotated[
        seller_agent_ref.SellerAgentReference,
        Field(
            description="The seller agent that owns this package. `agent_url` MUST match one of `authorized_agents[].url` in the publisher's adagents.json authoritative for every property this package may serve. Providers SHOULD validate at sync time and reject mismatches with `seller_not_authorized`. Cached alongside the package and used for offer attribution, per-seller observability, and dispute resolution — not for request-time filtering."
        ),
    ]
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format identifiers eligible for this package. Use canonical `format_options`.',
        ),
    ] = None
    format_options: Annotated[
        list[package_format_snapshot.PackageFormatSnapshot] | None,
        Field(
            description='Immutable seller-resolved PackageFormatSnapshots eligible for this package. A sender projects this field only when the Trusted Match transport profile supports the highest AdCP release version of every field in every snapshot. It MUST NOT strip an unsupported selector or digest field from a snapshot; for an older or version-unknown provider, omit the entire contract-bearing snapshot and do not claim production-path evidence from a legacy projection.',
            min_length=1,
        ),
    ] = None
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description="The buyer's catalogs attached to this package, with selectors (ids, gtins, tags, category, query) scoping which items are in play. References synced catalogs by catalog_id. The provider resolves items from its cached copy."
        ),
    ] = 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

Class variables

var catalogs : list[Catalog] | None

var format_ids : list[FormatReferenceStructuredObject] | None

var format_options : list[PackageFormatSnapshot18 | PackageFormatSnapshot19 | PackageFormatSnapshot20 | PackageFormatSnapshot21 | PackageFormatSnapshot22 | PackageFormatSnapshot23 | PackageFormatSnapshot24 | PackageFormatSnapshot25 | PackageFormatSnapshot26 | PackageFormatSnapshot27 | PackageFormatSnapshot28 | PackageFormatSnapshot29 | PackageFormatSnapshot30 | PackageFormatSnapshot31 | PackageFormatSnapshot32 | PackageFormatSnapshot33] | None

var media_buy_id : str

var model_config

var package_id : str

var seller_agent : SellerAgentReference

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BillingNotPermittedForAgentDetails (**data: Any)

Expand source code

class BillingNotPermittedForAgentDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    rejected_billing: Annotated[
        billing_party.BillingParty,
        Field(
            description='The `billing` value the seller rejected — echoed verbatim from the request for caller-side reconciliation.'
        ),
    ]
    suggested_billing: Annotated[
        billing_party.BillingParty | None,
        Field(
            description="A single billing value the calling buyer agent MAY retry with autonomously. Typically `operator` for passthrough-only agents. Sellers MAY omit this field when no retryable value exists for this agent's commercial relationship — in that case the rejection is terminal-pending-onboarding and the buyer MUST complete offline payments-relationship onboarding before any value other than the original request will succeed. Sellers MUST NOT populate this field with the full subset of values the agent may use; the field surfaces at most one canonical retry."
        ),
    ] = 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

Class variables

var model_config

var rejected_billing : BillingParty

var suggested_billing : BillingParty | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BillingNotSupportedDetails (**data: Any)

Expand source code

class BillingNotSupportedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    scope: Annotated[
        Scope | None,
        Field(
            description='Which gate fired. `"capability"` — the seller\'s `supported_billing` capability does not include the requested value (advice: choose from `supported_billing` and retry). `"account"` — the seller\'s capability accepts the value generally but not for the specific operator on this account (advice: try the next-most-permissive value the capability allows). Registered subset of the shared discriminator vocabulary in `enums/error-scope.json` — the per-agent scope is reserved for `BILLING_NOT_PERMITTED_FOR_AGENT` (which carries no explicit `scope` field) and for `PERMISSION_DENIED` with `error-details/agent-permission-denied.json`. Sellers MUST omit this field when the response is being returned to a caller whose agent identity has not been established (signed-request derivation or credential-to-agent mapping); see the uniform-response requirement in error-handling.mdx Billing and Account Setup.'
        ),
    ] = None
    supported_billing: Annotated[
        list[billing_party.BillingParty] | None,
        Field(
            description='Echoed copy of the seller\'s `supported_billing` capability for the caller\'s convenience — saves a `get_adcp_capabilities` round-trip when `scope` is `"capability"`. Sellers MAY omit this field; callers MUST treat absence as "call `get_adcp_capabilities`" rather than "any value is permitted."',
            min_length=1,
        ),
    ] = 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

Class variables

var model_config

var scope : Scope | None

var supported_billing : list[BillingParty] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BrandIdentity (**data: Any)

Expand source code

class Brand(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    id: Annotated[
        BrandId, Field(description='Brand identifier within the house. House chooses this ID.')
    ]
    url: Annotated[
        AnyUrl | None, Field(description='Primary brand URL for context and asset discovery')
    ] = None
    identity_relying_parties: Annotated[
        list[IdentityRelyingParty] | None,
        Field(
            description='Verified-identity relying parties scoped to this brand/property, for attestation provenance in TMP Identity Match. Use when a brand or property runs its own relying_party_id (per-property pseudonyms); entity-wide relying parties live on the house object. See specs/tmp-verified-identity-attestation.md.'
        ),
    ] = None
    names: Annotated[
        list[LocalizedName],
        Field(
            description='Localized brand names. Multiple entries per language allowed for aliases.',
            min_length=1,
        ),
    ]
    keller_type: KellerType | None = None
    parent_brand: Annotated[
        BrandId | None, Field(description='Parent brand ID for sub-brands and endorsed brands')
    ] = None
    description: Annotated[str | None, Field(description='Brand description')] = None
    industries: Annotated[
        list[str] | None,
        Field(
            description="Brand industries (e.g., ['automotive'] or ['pharmaceutical', 'cpg'] for a consumer health company). Describes what the company does — not what regulatory regimes apply (use policy_categories for that).",
            min_length=1,
        ),
    ] = None
    target_audience: Annotated[str | None, Field(description='Primary target audience')] = None
    logos: Annotated[list[Logo] | None, Field(description='Brand logo assets')] = None
    colors: Colors | None = None
    fonts: Fonts | None = None
    tone: Annotated[
        str | Tone | None, Field(description='Brand voice and messaging tone guidelines')
    ] = None
    tagline: Annotated[
        str | Tagline | None,
        Field(
            description='Brand tagline or slogan. Accepts a plain string or a localized array matching the names pattern.'
        ),
    ] = None
    assets: Annotated[list[Asset] | None, Field(description='Brand asset library')] = None
    properties: Annotated[
        list[Property] | None,
        Field(
            description='Digital properties associated with this brand — owned, managed, or represented'
        ),
    ] = None
    product_catalog: ProductCatalog | None = None
    privacy_policy_url: Annotated[
        AnyUrl | None, Field(description="URL to the brand's privacy policy")
    ] = None
    data_subject_contestation: DataSubjectContestation | None = None
    disclaimers: Annotated[
        list[Disclaimer] | None, Field(description='Legal disclaimers for creatives')
    ] = None
    trademarks: Annotated[
        list[Trademark] | None,
        Field(
            description="Brand-level registered trademarks. Use for marks the brand owns or controls (e.g., a sub-brand's own marks distinct from the corporate parent). House-level trademarks live on the house object; resolution between the two is union — both lists are valid claims."
        ),
    ] = None
    voice_synthesis: Annotated[
        VoiceSynthesis | None,
        Field(description='TTS voice synthesis configuration for AI-generated audio'),
    ] = None
    avatar: Annotated[Avatar | None, Field(description='Visual avatar configuration')] = None
    visual_guidelines: Annotated[
        VisualGuidelines | None,
        Field(description='Structured visual rules for generative creative systems'),
    ] = None
    agents: Annotated[
        Agents | None,
        Field(
            description='Agents authorized to act on behalf of this brand. Consumers resolving an agent by URL use the matching brand-level entry; do not infer a type-wide override of unrelated house-level entries when multiple same-type entries exist.'
        ),
    ] = None
    brand_agent: Annotated[
        BrandAgent | None,
        Field(
            deprecated=True,
            description="Deprecated: use agents array with type 'brand' instead. Brand agent that provides dynamic brand data via MCP.",
        ),
    ] = None
    rights_agent: Annotated[
        RightsAgent | None,
        Field(
            deprecated=True,
            description="Deprecated: use agents array with type 'rights' instead. Rights licensing agent for this brand.",
        ),
    ] = None
    contact: Annotated[Contact1 | None, Field(description='Brand-level contact information')] = None
    collections: Annotated[
        list[Collection] | None,
        Field(
            description="Collections this person or brand is associated with. Enables bidirectional linking: a collection's talent references brand.json via brand_url, and brand.json links back to collections."
        ),
    ] = 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

• BrandDiscovery5

Class variables

var agents : Agents | None

var assets : list[Asset] | None

var avatar : Avatar | None

var brand_agent : BrandAgent | None

var collections : list[Collection] | None

var colors : Colors | None

var contact : Contact1 | None

var data_subject_contestation : DataSubjectContestation | None

var description : str | None

var disclaimers : list[Disclaimer] | None

var fonts : Fonts | None

var id : BrandId

var identity_relying_parties : list[IdentityRelyingParty] | None

var industries : list[str] | None

var keller_type : KellerType | None

var logos : list[Logo] | None

var model_config

var names : list[LocalizedName]

var parent_brand : BrandId | None

var privacy_policy_url : pydantic.networks.AnyUrl | None

var product_catalog : ProductCatalog | None

var properties : list[Property] | None

var rights_agent : RightsAgent | None

var tagline : str | Tagline | None

var target_audience : str | None

var tone : str | Tone | None

var trademarks : list[Trademark] | None

var url : pydantic.networks.AnyUrl | None

var visual_guidelines : VisualGuidelines | None

var voice_synthesis : VoiceSynthesis | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BrandReference (**data: Any)

Expand source code

class BrandReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    domain: Annotated[
        str,
        Field(
            description="Domain where /.well-known/brand.json is hosted, or the brand's operating domain",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    brand_id: Annotated[
        brand_id_1.BrandId | None,
        Field(
            description='Brand identifier within the house portfolio. Optional for single-brand domains.'
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Canonical set of ISO 3166-1 alpha-2 countries for this advertiser identity. Omit for a global/default identity. Array order is not meaningful; producers MUST sort codes lexicographically before computing keys or signatures. This qualifies account identity and is not delivery targeting.',
            min_length=1,
        ),
    ] = None
    industries: Annotated[
        list[str] | None,
        Field(
            description="Inline override for the brand's industries. Useful when the caller cannot modify the brand's canonical brand.json but needs to declare industries for governance (e.g., Annex III vertical detection). brand.json remains the canonical source; when omitted here, governance agents SHOULD resolve from brand.json."
        ),
    ] = None
    data_subject_contestation: Annotated[
        DataSubjectContestation | None,
        Field(
            description="Inline override for the brand's contestation contact point. Useful when the operator does not control brand.json but needs to discharge Art 22(3) for this plan. brand.json is canonical; when omitted, governance agents resolve brand → house → missing."
        ),
    ] = None
    brand_kit_override: Annotated[
        BrandKitOverride | None,
        Field(
            description="Inline override for brand-kit fields normally resolved from `/.well-known/brand.json` on `domain` (logo, colors, voice, tagline). Use when brand.json is missing, stale, or inappropriate for this specific call — e.g., a campaign-scoped tagline, a co-branded creative, a freshly-rebranded color palette the brand.json hasn't shipped yet. Same inline-override pattern as `industries` and `data_subject_contestation` above: brand.json is canonical, the override is per-call. Adopters needing to override fields outside this subset (`voice_attributes`, `prohibited_terms`, etc.) MUST publish a different brand.json and reference it via a different `domain` — the inline override is intentionally narrow to a small high-traffic subset.\n\n**Merge semantics (normative).** The merge is **field-level**, not whole-object replacement. Each field within `brand_kit_override` (`logo`, `colors`, `voice`, `tagline`) is evaluated independently — when a field is present on the override the override value applies; when a field is absent the brand.json value applies (or is absent if brand.json doesn't carry one either). For composite fields (`colors.primary`, `colors.secondary`, `colors.accent`), the merge is one level deeper: each color slot is evaluated independently — a producer can override `colors.primary` while still inheriting `colors.secondary` from brand.json. SDKs MUST NOT treat a present `brand_kit_override.colors` as wiping the brand.json `colors` block entirely; only the per-slot fields present in the override take precedence. Without this rule, a partial-override semantics would diverge across SDKs and produce inconsistent rendering for the same payload."
        ),
    ] = 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

Class variables

var brand_id : BrandId | None

var brand_kit_override : BrandKitOverride | None

var countries : list[Country] | None

var data_subject_contestation : DataSubjectContestation | None

var domain : str

var industries : list[str] | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BrandSource (*args, **kwds)

Expand source code

class BrandSource(Enum):
    brand_json = "brand_json"
    community = "community"
    enriched = "enriched"

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

• attribute access::

>>> Color.RED
<Color.RED: 1>

• value lookup:

>>> Color(1)
<Color.RED: 1>

• name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

• enum.Enum

Class variables

var brand_json

var community

var enriched

class BriefAsset (**data: Any)

Expand source code

class BriefAsset(CreativeBrief):
    asset_type: Annotated[
        Literal['brief'],
        Field(
            description='Discriminator identifying this as a brief asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'brief'

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

• CreativeBrief
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['brief']

var model_config

Inherited members

• CreativeBrief:
  • model_dump
  • model_dump_json
  • model_summary

class BudgetTooLowDetails (**data: Any)

Expand source code

class BudgetTooLowDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    minimum_budget: Annotated[
        StrictFloat | None, Field(description="Seller's minimum budget for this product")
    ] = None
    currency: Annotated[str | None, Field(description='ISO 4217 currency code')] = 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

Class variables

var currency : str | None

var minimum_budget : float | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class LegacyBuildCreativeRequest (**data: Any)

Expand source code

class BuildCreativeRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque intent authorization when this creative execution incurs vendor cost.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    message: Annotated[
        str | None,
        Field(
            description='Natural language instructions for the transformation or generation. For pure generation, this is the creative brief. For transformation, this provides guidance on how to adapt the creative. For refinement, this describes the desired changes.'
        ),
    ] = None
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest | None,
        Field(
            description='Creative manifest to transform or generate from. On the canonical 3.2 path it carries `format_kind`, optional `format_option_ref`, and the required input assets. For transformation (for example resizing or reformatting), this is the complete creative to adapt. When creative_id is provided, the agent resolves the creative from its library and this field is ignored.'
        ),
    ] = None
    creative_representation_set: Annotated[
        creative_representation_set_1.CreativeRepresentationSet | None,
        Field(
            description="Complete creative revision containing equivalent trafficking representations, of which exactly one is selected for this seller-bound output. This mode is accepted only by the destination sales agent and requires representation_destination plus representation_selection_strategy. The target capability selects the seller's build route; representation_destination supplies the binding inventory contract. The resolver verifies revision_content_digest against the complete set, retains every representation unchanged, selects exactly one compatible representation, and returns a manifest carrying representation_selection. If macro_values is present, selection happens first and binding affects only the derived output; the retained representation set and its revision binding never change. When none is compatible, the request fails with CREATIVE_REPRESENTATION_UNRESOLVED and one representation_rejections entry per candidate."
        ),
    ] = None
    representation_destination: Annotated[
        representation_destination_1.RepresentationDestination | None,
        Field(
            description='Seller-owned product and effective format context for representation resolution. Required only with creative_representation_set and meaningful only when this endpoint is the destination sales agent.'
        ),
    ] = None
    representation_selection_strategy: Annotated[
        representation_selection_strategy_1.RepresentationSelectionStrategy | None,
        Field(
            description='Deterministic strategy to apply after compatibility filtering. Required with creative_representation_set and MUST be advertised by creative.representation_resolution.strategies.'
        ),
    ] = None
    creative_id: Annotated[
        str | None,
        Field(
            description="Reference to a creative in the agent's library. The creative agent resolves this to a manifest from its library. Use this instead of creative_manifest when retrieving an existing creative for tag generation or format adaptation."
        ),
    ] = None
    concept_id: Annotated[
        str | None,
        Field(
            description='Creative concept containing the creative. Creative agents SHOULD assign globally unique creative_id values; when they cannot guarantee uniqueness, concept_id is REQUIRED to disambiguate.'
        ),
    ] = None
    media_buy_id: Annotated[
        str | None,
        Field(
            description='Media buy identifier for tag generation context. When the creative agent is also the ad server, this provides the trafficking context needed to generate placement-specific tags (e.g., CM360 placement ID). Not needed when tags are generated at the creative level (most creative platforms).'
        ),
    ] = None
    package_id: Annotated[
        str | None,
        Field(
            description='Package identifier within the media buy. Used with media_buy_id when the creative agent needs line-item-level context for tag generation. Omit to get a tag not scoped to a specific package.'
        ),
    ] = None
    target_format_id: Annotated[
        format_id.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format selector. Use `target_capability_id` with a value advertised in `get_adcp_capabilities.creative.supported_formats[].capability_id`.',
        ),
    ] = None
    target_format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format selectors. Use `target_capability_ids` with values advertised in `get_adcp_capabilities.creative.supported_formats[].capability_id`.',
            max_length=50,
            min_length=1,
        ),
    ] = None
    target_capability_id: Annotated[
        str | None,
        Field(
            description='Canonical 3.2 single-output selector. Matches exactly one `get_adcp_capabilities.creative.supported_formats[].capability_id` advertised by this creative agent. The matched entry supplies the canonical `format` declaration used to validate inputs and the returned manifest. Mutually exclusive with `target_capability_ids` and the deprecated target_format_id fields.',
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ] = None
    target_capability_ids: Annotated[
        list[TargetCapabilityId] | None,
        Field(
            description='Canonical 3.2 multi-output selector. Each value matches a `get_adcp_capabilities.creative.supported_formats[].capability_id`. The creative agent produces one canonical manifest per capability in request order. Mutually exclusive with `target_capability_id` and the deprecated target_format_id fields.',
            max_length=50,
            min_length=1,
        ),
    ] = None
    transformer_id: Annotated[
        str | None,
        Field(
            description="Selects an account-scoped transformer (discovered via list_transformers) to perform the build. One transformer per call. When present, the build uses this transformer and target_capability_id/target_capability_ids select which of its outputs to produce — they MUST be a subset of the transformer's output_capability_ids. Deprecated target_format_id fields use the legacy output_format_ids compatibility path. Render configuration goes in `config`."
        ),
    ] = None
    config: Annotated[
        dict[str, Any] | None,
        Field(
            description='Typed render configuration for the selected transformer, keyed by each param\'s `field` (from the transformer\'s params[] in list_transformers). Example: { "voice": "isaac", "speaking_rate": 1.1, "mastering_preset": "podcast" }. The agent MUST validate `config` against the transformer\'s live params for this account and reject unrecognized keys and out-of-range / non-enumerated values with a field-attributed error (e.g. `config.voice`) rather than silently ignoring them — config drives a paid render. Genuinely vendor-specific or experimental knobs not declared as params belong in `ext`, not here. (The schema leaves this object open because legal keys are dynamic per transformer; strict validation is a normative agent obligation.) When `refine_from_build_variant_id` is set, `config` is applied as a DELTA over the parent leaf\'s config.'
        ),
    ] = None
    refine_from_build_variant_id: Annotated[
        str | None,
        Field(
            description='Refine a previously produced variant and return new lineage-linked variants. The transformer and target capability are inherited from the parent leaf. A refinement request MUST omit transformer_id, target_capability_id(s), and deprecated target_format_id(s); changing transformer or output format is a new transformation build, not refinement. Requires creative.supports_refinement.'
        ),
    ] = None
    mode: Annotated[
        Mode | None,
        Field(
            description="`execute` (default) produces and bills the creative(s). `estimate` is a DRY RUN: the agent produces nothing and bills nothing, and returns a BuildCreativeEstimate with a projected cost band (cost_low/cost_high) computed against THIS request's actual inputs (script length, brief, catalog size, max_creatives × max_variants) — the band the buyer cannot derive itself, since per_unit gives the rate but not the unit count. Requires the agent to advertise `creative.supports_spend_controls`; otherwise rejected with `UNSUPPORTED_FEATURE`."
        ),
    ] = Mode.execute
    max_spend: Annotated[
        MaxSpend | None,
        Field(
            description='Hard per-call spend ceiling. The agent produces leaves until the NEXT leaf would push the run\'s aggregate vendor_cost over `amount`, then STOPS and returns the partial BuildCreativeVariantSuccess produced so far with `budget_status: "capped"` (every returned leaf is real, trafficable, and billed — nothing produced is discarded; the leaf shortfall is `leaves_returned` < `leaves_total`). If even the first leaf would exceed the cap, the call fails with BUDGET_CAP_REACHED. `currency` MUST match the rate card\'s currency (the agent does not FX-convert) or the request is rejected with INVALID_REQUEST (error.field `max_spend.currency`). Requires `creative.supports_spend_controls`. Caps a SINGLE call — to bound a refinement loop, track aggregate vendor_cost across calls and stop issuing them (buyer responsibility in this revision). max_spend bounds only build-time vendor_cost: CPM-priced builds (estimate basis `cpm_deferred`) have build-time vendor_cost 0 and accrue at serve time, so max_spend never engages for them — bound a CPM fan-out with max_creatives instead.'
        ),
    ] = None
    max_creatives: Annotated[
        SchemaInt | None,
        Field(
            description='Caps how many DISTINCT creatives to produce along the catalog/item fan-out axis — one creative per catalog item. Use it to sample a large catalog (e.g. send 150 job openings, set max_creatives: 5 to preview five). Distinct from item_limit, which caps how many catalog items a SINGLE creative consumes (DCO-style). Omitted with a catalog input means one creative per item up to the catalog/format bound; omitted without a catalog collapses to a single creative. Large fan-outs may return asynchronously. Mutually exclusive with `refine_from_build_variant_id` (refinement targets one prior creative, not a catalog fan-out). Supported only when the agent advertises `creative.multiplicity.supports_catalog_fanout`; values above `max_creatives_limit` are clamped. Pair with `max_spend` to bound the bill of a large fan-out.',
            ge=1,
        ),
    ] = None
    signal_conditions: Annotated[
        list[SignalCondition] | None,
        Field(
            description="Advisory keep-all PRODUCTION axis: produce one distinct creative group per signal condition, each kept and trafficked with its own signal targeting (e.g. a rain creative AND a sun creative). Sibling to max_creatives (catalog axis), NOT a variant_axis value (which is choose-among). Each item reuses SignalTargeting (value_type-discriminated binary/categorical/numeric over signal_ref) so the produced group's signal_condition resolves condition identity through the SAME schema the sales-side package targeting uses, plus an optional signal_agent_segment_id carrying the RESOLVED-segment identity (vs signal_ref's definition identity) — echo a provider-exposed handle verbatim; it is the primary trafficking-compatibility key, with categorical signal_ref+value as the weaker fallback. Per #5280 this is an ADVISORY context pointer — it informs production and MUST NOT hard-block at the build_creative layer; trafficking-compatibility (a sun creative MUST NOT serve into rain-targeted packages) is enforced reject-at-trafficking on the sales side (SIGNAL_TARGETING_INCOMPATIBLE), not here. Triggers the BuildCreativeVariantSuccess shape. Supported only when the agent advertises creative.multiplicity.supports_signal_fanout; condition counts above max_signal_conditions_limit are CLAMPED (not rejected), consistent with max_creatives. Composes with max_creatives (catalog × conditions cross-product) and max_variants (variants per group).",
            min_length=1,
        ),
    ] = None
    max_variants: Annotated[
        SchemaInt | None,
        Field(
            description='Caps how many ALTERNATIVES to produce per creative (different voices, themes, best-of-N, etc.). Default 1 preserves single-output behavior. Each variant is a real, independently-billed build (you pay for all produced); the buyer keeps one or many. When variant_axis.values[] is provided, its length is authoritative over max_variants. Resolutions/quality tiers are NOT variants — request them as additional target formats.',
            ge=1,
        ),
    ] = 1
    variant_axis: Annotated[
        VariantAxis | None,
        Field(
            description='Declares the dimension along which variants differ. When `values` is provided, the agent produces exactly one variant per value (e.g. an A/B of two voices). When only `dimension` is provided, the agent chooses up to max_variants variants along that dimension (e.g. best-of-N, themes).'
        ),
    ] = None
    keep_mode: Annotated[
        KeepMode | None,
        Field(
            description='Advisory hint for how the buyer intends to use the variants. `keep_one` (best-of-N) and `keep_some` signal the agent to set `recommended`/`rank` on returned variants. Advisory only — it does not change what is returned or billed; every produced variant is returned and charged. Keeping is a client act of trafficking the chosen build_variant_id(s).'
        ),
    ] = KeepMode.keep_all
    selection_strategy: Annotated[
        creative_selection_strategy.CreativeSelectionStrategy | None,
        Field(
            description='Governs HOW the agent samples when max_creatives < items_total (folds #5262). audience_relevance draws its ranking input from the SAME signal_ref pointers in signal_conditions / package targeting — NOT a parallel signals[] array. proximity takes a location input (geo shape TBD — WG open). inventory_priority is seller-side catalog metadata (margin/overstock/promo; no buyer input). random is the status-quo default. Per-creative selection ordering surfaces on the existing rank / recommended fields of creatives[].variants[], not a new selection_rank. Advisory; absent => agent default (random).'
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account reference for pricing and billing. When present, the creative agent applies account-specific pricing from the rate card, records the build against the account for billing, and can enforce account-level quotas or entitlements. Required by creative agents that charge for their services.'
        ),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand reference for creative generation. Resolved to full brand identity (colors, logos, tone) at execution time.'
        ),
    ] = None
    quality: Annotated[
        creative_quality.CreativeQuality | None,
        Field(
            description="Quality tier for generation. 'draft' produces fast, lower-fidelity output for iteration and review. 'production' produces full-quality output for final delivery. If omitted, the creative agent uses its own default. For non-generative transforms (e.g., format resizing), creative agents MAY ignore this field."
        ),
    ] = None
    evaluator: Annotated[
        evaluator_spec.EvaluatorSpec | None,
        Field(
            description="Optional advisory evaluator (buyer-attached pointer, #5280) declaring how produced variants should be evaluated and ranked — the rank-side of the get_creative_features feature oracle. Experimental (x-status: experimental): the whole evaluator surface is new and unfrozen, and requires creative.supports_evaluator, which sellers MUST pair with `creative.evaluator` in experimental_features. Drives the producing agent's gate-then-rank pipeline over its best_of_n exploration: per leaf, evaluate (the chosen form) → optionally GATE (`evaluator.feature_requirement[]`, drop fails — internal pruning of which leaves the agent recommends, never an AdCP-layer block of an already-produced billable leaf) → RANK survivors (`evaluator.rank_by`, an explicit {feature_id, direction} ordering). Feature discovery uses get_adcp_capabilities governance.creative_features for rank_by, feature_requirement, and eval.features[]; evaluator_id is a pre-provisioned/account-arranged preset, not an ID discovered from that catalog. Populates a per-leaf `eval` block of creative-feature values (creative-feature-result[]) when supports_evaluator. When the evaluator names an external agent (`evaluator.feature_agent.agent_url` or the agent-form `agent_url`), that agent MUST appear in the seller's `creative_policy.accepted_verifiers[]` (the same allowlist #5280 established for provenance verify_agent); an off-list agent is rejected with `EVALUATOR_AGENT_NOT_ACCEPTED`. The outbound evaluator call authenticates on the transport (request signing/JWKS, mTLS, or a pre-provisioned static credential); credentials and caller-supplied trust material MUST NOT appear in evaluator, context, ext, or creative payload fields, and credential- or trust-material keys should be rejected with `CREDENTIAL_IN_ARGS`. With no `feature_requirement`, evaluation is advisory only and does not change what is produced or billed; an unreachable/unknown on-list agent degrades to seller-default ranking (advisory errors[] note), not a failure. Requires creative.supports_evaluator; otherwise ignored."
        ),
    ] = None
    item_limit: Annotated[
        SchemaInt | None,
        Field(
            description="Maximum number of catalog items a SINGLE creative consumes when generating (DCO-style — e.g. how many items fill one carousel/feed creative). When a catalog asset contains more items than this limit, the creative agent selects the top items based on relevance or catalog ordering. When item_limit exceeds the format's max_items, the creative agent SHOULD use the lesser of the two. Ignored when the manifest contains no catalog assets. Distinct from `max_creatives`, which fans OUT across catalog items to produce one distinct creative per item.",
            ge=1,
        ),
    ] = None
    include_preview: Annotated[
        StrictBool | None,
        Field(
            description="When true, requests the creative agent to include preview renders in the response alongside the manifest. Agents that support this return a 'preview' object in the response using the same structure as preview_creative. Agents that do not support inline preview simply omit the field. This avoids a separate preview_creative round trip for platforms that generate previews as a byproduct of building."
        ),
    ] = None
    preview_inputs: Annotated[
        list[PreviewInput] | None,
        Field(
            description='Input sets for preview generation when include_preview is true. Supported with a single target_capability_id; multi-capability requests generate one default preview per output. Deprecated target-format selectors retain equivalent compatibility behavior.',
            min_length=1,
        ),
    ] = None
    preview_quality: Annotated[
        creative_quality.CreativeQuality | None,
        Field(
            description="Render quality for inline preview when include_preview is true. 'draft' produces fast, lower-fidelity renderings. 'production' produces full-quality renderings. Independent of the build quality parameter — you can build at draft quality and preview at production quality, or vice versa. If omitted, the creative agent uses its own default. Ignored when include_preview is false or omitted."
        ),
    ] = None
    preview_output_format: Annotated[
        preview_output_format_1.PreviewOutputFormat | None,
        Field(
            description="Output format for preview renders when include_preview is true. 'url' returns preview_url (iframe-embeddable URL), 'html' returns preview_html (raw HTML). Ignored when include_preview is false or omitted."
        ),
    ] = preview_output_format_1.PreviewOutputFormat.url
    macro_values: Annotated[
        dict[str, str] | None,
        Field(
            description="Raw concrete values offered for build-time binding, keyed by AdCP universal semantic (for example CLICK_URL or CACHEBUSTER). With declarations, a value binds only a verified-universal `resolve_value` occurrence performed_by `creative_agent`, using that declaration's exact context and encoding; callers MUST NOT pre-encode it. The selected `creative.supported_formats[]` route's macro_resolution_capabilities is the binding build/preview capability set; seller-wide and product sets apply only on the sales execution path. Values never short-circuit `translate_to_native`: translation emits its target declaration and the complete target capability chain remains required. For creative_representation_set, selection happens before binding and the complete representation set remains byte-identical. Without declarations, the 3.x legacy path remains: creative agents may translate recognized AdCP tokens using the existing `translateUniversalMacros` contract, preserve omitted placeholders for the sales agent, and ignore unknown keys. Existing unmapped/frozen-consent diagnostics remain required."
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate creative generation on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on build_creative. Meaningful only when the request enters the async lifecycle and returns a Submitted envelope. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change response timing semantics: agents MUST NOT route a request through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; requests that can be completed inline still return the synchronous success shape.'
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var brand : BrandReference | None

var concept_id : str | None

var config : dict[str, typing.Any] | None

var context : ContextObject | None

var creative_id : str | None

var creative_manifest : CreativeManifest | None

var creative_representation_set : CreativeRepresentationSet | None

var evaluator : EvaluatorSpec1 | EvaluatorSpec2 | EvaluatorSpec3 | None

var ext : ExtensionObject | None

var governance_context : str | None

var idempotency_key : str

var include_preview : bool | None

var item_limit : int | None

var keep_mode : KeepMode | None

var macro_values : dict[str, str] | None

var max_creatives : int | None

var max_spend : MaxSpend | None

var max_variants : int | None

var media_buy_id : str | None

var message : str | None

var mode : Mode | None

var model_config

var package_id : str | None

var preview_inputs : list[PreviewInput] | None

var preview_output_format : PreviewOutputFormat | None

var preview_quality : CreativeQuality | None

var push_notification_config : PushNotificationConfig | None

var quality : CreativeQuality | None

var refine_from_build_variant_id : str | None

var representation_destination : RepresentationDestination | None

var representation_selection_strategy : RepresentationSelectionStrategy | None

var selection_strategy : CreativeSelectionStrategy | None

var signal_conditions : list[SignalCondition5 | SignalCondition6 | SignalCondition7] | None

var target_capability_id : str | None

var target_capability_ids : list[TargetCapabilityId] | None

var target_format_id : FormatReferenceStructuredObject | None

var target_format_ids : list[FormatReferenceStructuredObject] | None

var transformer_id : str | None

var variant_axis : VariantAxis | 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 LegacyBuildCreativeResponse1 (**data: Any)

Expand source code

class BuildCreativeResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    creative_manifest: creative_manifest_1.CreativeManifest
    build_variant_id: str | None = None
    recipe_hash: str | None = None
    sandbox: bool | None = None
    expires_at: AwareDatetime | None = None
    preview: Preview | None = None
    preview_error: error_1.Error | None = None
    pricing_option_id: str | None = None
    vendor_cost: Annotated[float, Field(ge=0)] | None = None
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')] | None = None
    consumption: creative_consumption_1.CreativeConsumption | None = 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.

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 build_variant_id : str | None

var consumption : CreativeConsumption | None

var context : ContextObject | None

var creative_manifest : adcp.types._forward_compat._ReadbackCreativeManifest

var currency : str | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var model_config

var preview : Preview | None

var preview_error : Error | None

var pricing_option_id : str | None

var recipe_hash : str | None

var sandbox : bool | None

var vendor_cost : float | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class LegacyBuildCreativeSuccessResponse (**data: Any)

Expand source code

class BuildCreativeResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    creative_manifest: creative_manifest_1.CreativeManifest
    build_variant_id: str | None = None
    recipe_hash: str | None = None
    sandbox: bool | None = None
    expires_at: AwareDatetime | None = None
    preview: Preview | None = None
    preview_error: error_1.Error | None = None
    pricing_option_id: str | None = None
    vendor_cost: Annotated[float, Field(ge=0)] | None = None
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')] | None = None
    consumption: creative_consumption_1.CreativeConsumption | None = 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.

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 build_variant_id : str | None

var consumption : CreativeConsumption | None

var context : ContextObject | None

var creative_manifest : adcp.types._forward_compat._ReadbackCreativeManifest

var currency : str | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var model_config

var preview : Preview | None

var preview_error : Error | None

var pricing_option_id : str | None

var recipe_hash : str | None

var sandbox : bool | None

var vendor_cost : float | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 LegacyBuildCreativeErrorResponse (**data: Any)

Expand source code

class BuildCreativeResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

class LegacyBuildCreativeResponse2 (**data: Any)

Expand source code

class BuildCreativeResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 LegacyBuildCreativeResponse3 (**data: Any)

Expand source code

class BuildCreativeResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    creative_manifests: Annotated[list[creative_manifest_1.CreativeManifest], Field(min_length=1)]
    sandbox: bool | None = None
    expires_at: AwareDatetime | None = None
    preview: Preview3 | None = None
    preview_error: error_1.Error | None = None
    pricing_option_id: str | None = None
    vendor_cost: Annotated[float, Field(ge=0)] | None = None
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')] | None = None
    consumption: creative_consumption_1.CreativeConsumption | None = 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.

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 consumption : CreativeConsumption | None

var context : ContextObject | None

var creative_manifests : list[adcp.types._forward_compat._ReadbackCreativeManifest]

var currency : str | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var model_config

var preview : Preview3 | None

var preview_error : Error | None

var pricing_option_id : str | None

var sandbox : bool | None

var vendor_cost : float | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 LegacyBuildCreativeResponse4 (**data: Any)

Expand source code

class BuildCreativeResponse4(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    creatives: Annotated[list[Creative], Field(min_length=1)]
    items_total: Annotated[int, Field(ge=0)] | None = None
    items_returned: Annotated[int, Field(ge=0)] | None = None
    leaves_total: Annotated[int, Field(ge=0)] | None = None
    leaves_returned: Annotated[int, Field(ge=0)] | None = None
    vendor_cost: Annotated[float, Field(ge=0)] | None = None
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')] | None = None
    keep_mode_applied: Literal['keep_all', 'keep_one', 'keep_some'] | None = None
    selection_strategy_applied: creative_selection_strategy_1.CreativeSelectionStrategy | None = None
    budget_status: Literal['complete', 'capped'] | None = None
    errors: list[error_1.Error] | None = None
    sandbox: bool | None = None
    expires_at: AwareDatetime | None = 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.

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 budget_status : Literal['complete', 'capped'] | None

var context : ContextObject | None

var creatives : list[adcp.types._forward_compat._BuildReadbackCreative]

var currency : str | None

var errors : list[Error] | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var items_returned : int | None

var items_total : int | None

var keep_mode_applied : Literal['keep_all', 'keep_one', 'keep_some'] | None

var leaves_returned : int | None

var leaves_total : int | None

var model_config

var sandbox : bool | None

var selection_strategy_applied : CreativeSelectionStrategy | None

var vendor_cost : float | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 LegacyBuildCreativeResponse5 (**data: Any)

Expand source code

class BuildCreativeResponse5(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    mode: Literal['estimate'] = 'estimate'
    estimate: Estimate
    expires_at: AwareDatetime | None = 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.

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 context : ContextObject | None

var estimate : Estimate

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var mode : Literal['estimate']

var model_config

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 LegacyBuildCreativeResponse6 (**data: Any)

Expand source code

class BuildCreativeResponse6(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

class LegacyBuildCreativeSubmittedResponse (**data: Any)

Expand source code

class BuildCreativeResponse6(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

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 BusinessEntity (**data: Any)

Expand source code

class BusinessEntity(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    legal_name: Annotated[
        str, Field(description='Registered legal name of the business entity', max_length=200)
    ]
    vat_id: Annotated[
        str | None,
        Field(
            description='VAT identification number (e.g., DE123456789 for Germany, FR12345678901 for France). Required for B2B invoicing in the EU. Must be normalized: no spaces, dots, or dashes.',
            pattern='^[A-Z]{2}[A-Z0-9]{2,13}$',
        ),
    ] = None
    tax_id: Annotated[
        str | None,
        Field(
            description='Tax identification number for jurisdictions that do not use VAT (e.g., US EIN)',
            max_length=30,
        ),
    ] = None
    registration_number: Annotated[
        str | None,
        Field(
            description='Company registration number (e.g., HRB 12345 for German Handelsregister)',
            max_length=50,
        ),
    ] = None
    address: Annotated[
        Address | None, Field(description='Postal address for invoicing and legal correspondence')
    ] = None
    contacts: Annotated[
        list[Contact] | None,
        Field(
            description='Contacts for billing, legal, and operational matters. Contains personal data subject to GDPR and equivalent regulations. Implementations MUST use this data only for invoicing and account management.',
            max_length=10,
        ),
    ] = None
    bank: Annotated[
        Bank | None,
        Field(
            description='Bank account details for payment processing. Write-only: included in requests to provide payment coordinates, but MUST NOT be echoed in responses. Sellers store these details and confirm receipt without returning them.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

• BusinessEntityResponse

Class variables

var address : Address | None

var bank : Bank | None

var contacts : list[Contact] | None

var ext : ExtensionObject | None

var legal_name : str

var model_config

var registration_number : str | None

var tax_id : str | None

var vat_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BusinessEntityResponse (**data: Any)

Expand source code

class BusinessEntityResponse(BusinessEntity):
    """Response projection of :class:`BusinessEntity` with bank details stripped.

    Per AdCP 3.0.x ``core/business-entity.json``: ``bank.*`` fields carry
    ``writeOnly: true`` and MUST NOT appear in responses. Sellers store
    bank coordinates and confirm receipt without echoing them.

    This subclass enforces the contract two ways:

    * Construction: passing ``bank=...`` raises ``ValidationError``.
    * Serialization: the field is excluded from ``model_dump()`` output
      even if some path mutated it post-construction (defense in depth
      against ``model_copy()``, idempotency replay caches, etc.).
    """

    bank: Any = Field(default=None, exclude=True)

    @field_validator("bank", mode="before")
    @classmethod
    def _reject_bank(cls, v: Any) -> None:
        if v is not None:
            raise ValueError(
                "BusinessEntityResponse must not carry bank details — bank is "
                "write-only per AdCP spec. Drop the field before constructing "
                "a response, or use to_account_response() to strip it."
            )
        return None

Response projection of :class:BusinessEntity with bank details stripped.

Per AdCP 3.0.x core/business-entity.json: bank.* fields carry writeOnly: true and MUST NOT appear in responses. Sellers store bank coordinates and confirm receipt without echoing them.

This subclass enforces the contract two ways:

• Construction: passing bank=... raises ValidationError.
• Serialization: the field is excluded from model_dump() output even if some path mutated it post-construction (defense in depth against model_copy(), idempotency replay caches, etc.).

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

• BusinessEntity
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var bank : Any

var model_config

Inherited members

• BusinessEntity:
  • model_dump
  • model_dump_json
  • model_summary

class BuyProductsRequest (**data: Any)

Expand source code

class BuyProductsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str, Field(max_length=255, min_length=16, pattern='^[A-Za-z0-9_.:-]{16,255}$')
    ]
    name: Annotated[
        str | None,
        Field(
            description='Human-readable name for this media buy, shared by buyer and seller for trafficking UI display and operational communication. When supplied, the seller MUST persist it and echo it unchanged on the commitment success response and subsequent get_media_buys reads. The name is operational metadata outside accepted_proposal and is not covered by terms_digest. This display label is not an identifier or financial reference.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    account: Annotated[
        canonical_account_ref.CanonicalAccountReference,
        Field(
            description='Execution account. A natural-key account is the single brand source and MUST NOT be combined with top-level brand.'
        ),
    ]
    brand: Annotated[
        brand_key.BrandKey | None,
        Field(
            description='Brand source required when account is ID-only. Omit when account already contains brand and operator.'
        ),
    ] = None
    advertiser_industry: Annotated[
        advertiser_industry_1.AdvertiserIndustry | None,
        Field(
            description='Industry classification for this campaign. Sellers may infer it from the resolved brand manifest when omitted.'
        ),
    ] = None
    feed_version: Annotated[
        str,
        Field(
            description='list_products feed_version containing the published offers being accepted. Sellers reject stale or mismatched versions rather than silently applying changed terms.',
            min_length=1,
        ),
    ]
    pricing_version: Annotated[
        str | None,
        Field(
            description='list_products pricing_version containing the accepted rate. Buyers MUST include this whenever list_products returned one; omission means the seller does not version pricing separately.',
            min_length=1,
        ),
    ] = None
    purchases: Annotated[list[product_purchase_input.ProductPurchaseInput], Field(min_length=1)]
    total_budget: TotalBudget | None = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Optional hard aggregate daily spend ceiling in total_budget.currency or the media buy's derived currency. It bounds the shared daily spend pool without allocating or reserving amounts for purchases.",
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Optional max-impression cap using one counter across purchases. Buyers send it only when aggregate_frequency_capping is advertised. Every selected product must declare compatible media_buy_support; otherwise the purchase is rejected atomically with UNSUPPORTED_FEATURE before any mutation, never clamped.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='Optional IANA timezone override shared by every aggregate and purchase daily cap. Requires buyer_timezone_override support; otherwise rejected with UNSUPPORTED_FEATURE. When omitted, budget_capping.timezone_basis selects Account.timezone or fixed_timezone.',
            min_length=1,
        ),
    ] = None
    budget_allocation: canonical_budget_allocation.CanonicalBudgetAllocation | None = None
    start_time: start_timing.StartTiming
    end_time: AwareDatetime
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Aggregate media-buy pacing. In seller-optimized allocation, a seller declaring media_buy.features.seller_optimized_budget MUST accept omission and `even`; it MAY reject `asap` or `front_loaded` with UNSUPPORTED_FEATURE (error.field `pacing`) before any provider mutation and MUST NOT silently coerce them to `even`. Fixed-allocation semantics are unchanged.'
        ),
    ] = None
    bidding: bidding_policy.BiddingPolicy | None = None
    paused: StrictBool | None = False
    purchase_order_ref: Annotated[str | None, Field(max_length=255, min_length=1)] = None
    agency_estimate_number: Annotated[str | None, Field(max_length=100)] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(description='Authorized per-buy billing entity override.'),
    ] = None
    governance_context: Annotated[str | None, Field(max_length=4096, min_length=1)] = None
    push_notification_config: push_notification_config_1.PushNotificationConfig | None = None
    reporting_webhook: Annotated[
        reporting_webhook_1.ReportingWebhook | None,
        Field(
            description='Optional reporting delivery configuration established atomically with the MediaBuy. This is execution metadata and is not part of the immutable product pricing terms.'
        ),
    ] = None
    opportunity: Annotated[
        Opportunity | None,
        Field(
            description='Optional planning-cycle closure for a direct product purchase. Success infers closed with accepted_with_seller when status is omitted; an explicit status MUST carry that same closure.'
        ),
    ] = 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 account : CanonicalAccountReference1 | CanonicalAccountReference2

var advertiser_industry : AdvertiserIndustry | None

var agency_estimate_number : str | None

var bidding : BiddingPolicy | None

var brand : BrandKey | None

var budget_allocation : CanonicalBudgetAllocation1 | CanonicalBudgetAllocation2 | None

var budget_cap_timezone : str | None

var context : ContextObject | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime

var ext : ExtensionObject | None

var feed_version : str

var frequency_cap : MediaBuyFrequencyCap | None

var governance_context : str | None

var idempotency_key : str

var invoice_recipient : BusinessEntity | None

var model_config

var name : str | None

var opportunity : Opportunity | None

var pacing : Pacing | None

var paused : bool | None

var pricing_version : str | None

var purchase_order_ref : str | None

var purchases : list[ProductPurchaseInput]

var push_notification_config : PushNotificationConfig | None

var reporting_webhook : ReportingWebhook | None

var start_time : Literal['asap'] | pydantic.types.AwareDatetime

var total_budget : TotalBudget | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 BuyingMode (*args, **kwds)

Expand source code

class BuyingMode(StrEnum):
    brief = 'brief'
    wholesale = 'wholesale'
    refine = 'refine'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var brief

var refine

var wholesale

class ByPackageItem (**data: Any)

Expand source code

class ByPackageItem(DeliveryMetrics):
    package_id: Annotated[str, Field(description="Seller's package identifier")]
    pacing_index: Annotated[
        StrictFloat | None,
        Field(
            description='Package delivery pace relative to its package-level pacing plan (1.0 = on track, <1.0 = behind, >1.0 = ahead). In seller-optimized mode this is a subordinate diagnostic and may be absent when no package pacing preference exists.',
            ge=0.0,
        ),
    ] = None
    pricing_model: Annotated[
        pricing_model_1.PricingModel,
        Field(
            description='The pricing model used for this package (e.g., cpm, cpcv, cpp). Indicates how the package is billed and which metrics are most relevant for optimization.'
        ),
    ]
    rate: Annotated[
        StrictFloat,
        Field(
            description='The pricing rate for this package. For fixed-rate pricing, this is the agreed currency-denominated unit rate (e.g., CPM rate of 12.50 means $12.50 per 1,000 impressions). For auction-based pricing, this is the effective rate based on actual delivery. For revenue_share, this is the decimal commission rate (e.g., 0.04 means 4%) and is not itself currency-denominated.',
            ge=0.0,
        ),
    ]
    currency: Annotated[
        str,
        Field(
            description="ISO 4217 currency code for this package's spend and currency-denominated pricing rate. The rate for revenue_share is a dimensionless commission fraction, but attributed monetary values still use this currency. When the enclosing media_buy_deliveries[].currency is present, this value MUST equal it. For AdCP-authored buys both values MUST equal the media-buy currency. A different package currency is permitted only for a legacy or externally created mixed-currency buy whose row currency, daily_breakdown, and row/window monetary totals are omitted. AdCP does not perform currency conversion.",
            pattern='^[A-Z]{3}$',
        ),
    ]
    delivery_status: Annotated[
        delivery_status_1.DeliveryStatus | None,
        Field(
            description="System-reported operational state of this package. Reflects actual delivery state independent of buyer pause control. 'not_delivering' means zero impressions were recorded for the entire reporting_period while the package was in-flight. Sellers SHOULD only report 'not_delivering' once the package's data is_final for the period — a provisional (is_final: false) zero may still be measurement catching up, not genuine non-delivery."
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(description='Whether this package is currently paused by the buyer'),
    ] = None
    is_final: Annotated[
        StrictBool | None,
        Field(
            description="Whether this delivery data is final for the reporting period. When false, the data may be updated as measurement matures (e.g., broadcast C7 window accumulating DVR playback) or as processing completes (e.g., IVT filtering, deduplication). When true, the seller considers this data closed — no further updates for this period — and is willing to invoice on it subject to the buy's `measurement_terms.billing_measurement`. Absent means the seller does not distinguish provisional from final data."
        ),
    ] = None
    finalized_at: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp at which this package's data became final. Present only when `is_final: true`. Anchors reconciliation and (when later defined) dispute-window clocks against the buy's `measurement_terms.billing_measurement.measurement_window`."
        ),
    ] = None
    measurement_window: Annotated[
        str | None,
        Field(
            description="Which measurement window this data represents, referencing a window_id from the product's reporting_capabilities.measurement_windows. For broadcast: 'live', 'c3', 'c7'. When absent, the data is not windowed (standard digital reporting). When present with is_final: false, a later report for the same period will provide a wider window or more complete data.",
            examples=['live', 'c3', 'c7'],
            max_length=50,
        ),
    ] = None
    supersedes_window: Annotated[
        str | None,
        Field(
            description="Which measurement window this data replaces. Present on window_update notifications to indicate progression (e.g., 'live' when reporting C3 data that supersedes live-only numbers). Absent on the first report for a period. Buyers should replace stored data for the superseded window with this report's data.",
            examples=['live', 'c3'],
            max_length=50,
        ),
    ] = None
    missing_metrics: Annotated[
        list[missing_metric.MissingMetric] | None,
        Field(
            description="Metrics that the binding reporting contract declared but that are NOT populated in this report. Reconciliation source: when `package.committed_metrics` is present, `missing_metrics` is computed against entries where `committed_at < reporting_period.end` — independent of subsequent product mutations and respecting the commitment timestamp on each entry (a metric committed mid-flight is only flagged missing in reports for periods after its commitment). When `package.committed_metrics` is absent, fall back to the product's current `reporting_capabilities.available_metrics` (no timestamp filter). Empty array (or absent) indicates clean delivery against the contract. Non-empty signals an accountability breach — the seller committed to the metric but did not produce the value here. Sellers MUST exclude metrics that are not yet measurable for the current `measurement_window` (e.g., post-IVT counts during the live window) — those will appear (or not) when a wider window supersedes this report via `supersedes_window`. Each entry uses an explicit `scope` discriminator: `standard` for entries from the closed `available-metric.json` enum, `vendor` for vendor-defined metrics anchored on a BrandRef. Symmetric with `committed_metrics`. When the request narrowed the payload via requested_metrics, sellers MUST NOT list a committed metric here solely because the buyer excluded it — missing_metrics reports delivery gaps, not request narrowing.",
            examples=[
                [],
                [{'scope': 'standard', 'metric_id': 'completed_views'}],
                [
                    {'scope': 'standard', 'metric_id': 'completed_views'},
                    {
                        'scope': 'vendor',
                        'vendor': {'domain': 'attentionvendor.example'},
                        'metric_id': 'attention_units',
                    },
                ],
            ],
        ),
    ] = None
    metric_values: Annotated[
        list[package_delivery_metric_value.PackageDeliveryMetricValue] | None,
        Field(
            description='Qualified standard delivery values for this package. Each entry is the delivered counterpart to a standard-scope package.committed_metrics or by_package[].missing_metrics row, using the same atomic key (scope, metric_id, qualifier). Sellers report one row per full qualifier set at package grain; when a metric appears here, its flat scalar counterpart on the package MUST be omitted to avoid two sources of truth. Vendor-scope values continue to use vendor_metric_values. Buyers reconcile rows directly and perform any compatible cross-package aggregation themselves.'
        ),
    ] = None
    by_catalog_item: Annotated[
        list[catalog_item_delivery_metrics.CatalogItemDeliveryMetrics] | None,
        Field(
            description='Delivery by catalog item within this package. Available for catalog-driven packages when the seller supports item-level reporting.'
        ),
    ] = None
    by_catalog_item_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_catalog_item was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_catalog_item is present and the request included reporting_dimensions.catalog_item (false means the list is complete). When the breakdown was returned automatically without a request key, the flag is RECOMMENDED but not required — automatic rows carry no completeness contract.'
        ),
    ] = None
    by_catalog_item_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_catalog_item rows. Sellers MUST return this field whenever by_catalog_item is present and the request included reporting_dimensions.catalog_item. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric. When the breakdown was returned automatically without a request key, the field is RECOMMENDED but not required — automatic rows carry no completeness contract."
        ),
    ] = None
    by_catalog_item_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_catalog_item ordering. Sellers MUST return this field whenever by_catalog_item is present and the request included reporting_dimensions.catalog_item, alongside by_catalog_item_sorted_by. When the breakdown was returned automatically without a request key, the field is RECOMMENDED but not required — automatic rows carry no completeness contract.'
        ),
    ] = None
    by_creative: Annotated[
        list[creative_delivery_metrics.CreativeDeliveryMetrics] | None,
        Field(
            description='Metrics broken down by creative within this package. Available when the seller supports creative-level reporting.'
        ),
    ] = None
    by_format: Annotated[
        list[ByFormatItem] | None,
        Field(
            description="Delivery by canonical creative format kind within this package. Negotiated on the GET path when the buyer requests reporting_dimensions.format and the product declares supports_format_breakdown; reporting webhook configuration does not negotiate or guarantee this breakdown. Each row aggregates every served creative of that format kind. Sellers MUST aggregate all delivery using adopter-defined shapes into one format_kind 'custom' row. When by_format_truncated is false, additive metrics such as impressions and spend across the rows SHOULD reconcile to the corresponding package totals, subject to the measurement and attribution semantics of each metric. Buyers MUST NOT expect row-level correspondence between by_format and by_creative because the two breakdowns are independently produced at different grains."
        ),
    ] = None
    by_format_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_format was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_format is present (false means the list is complete).'
        ),
    ] = None
    by_format_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_format rows. Sellers MUST return this field whenever by_format is present. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric."
        ),
    ] = None
    by_format_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_format ordering. Sellers MUST return this field whenever by_format is present.'
        ),
    ] = None
    by_creative_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_creative was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_creative is present and the request included reporting_dimensions.creative (false means the list is complete). When the breakdown was returned automatically without a request key, the flag is RECOMMENDED but not required — automatic rows carry no completeness contract.'
        ),
    ] = None
    by_creative_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_creative rows. Sellers MUST return this field whenever by_creative is present and the request included reporting_dimensions.creative. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric. When the breakdown was returned automatically without a request key, the field is RECOMMENDED but not required — automatic rows carry no completeness contract."
        ),
    ] = None
    by_creative_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_creative ordering. Sellers MUST return this field whenever by_creative is present and the request included reporting_dimensions.creative, alongside by_creative_sorted_by. When the breakdown was returned automatically without a request key, the field is RECOMMENDED but not required — automatic rows carry no completeness contract.'
        ),
    ] = None
    by_keyword: Annotated[
        list[keyword_delivery_metrics.KeywordDeliveryMetrics] | None,
        Field(
            description='Metrics broken down by keyword within this package. One row per (keyword, match_type) pair — the same keyword with different match types appears as separate rows. Keyword-grain only: rows reflect aggregate performance of each targeted keyword, not individual search queries. Rows may not sum to package totals when a single impression is attributed to the triggering keyword only. Available for search and retail media packages when the seller supports keyword-level reporting.'
        ),
    ] = None
    by_keyword_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_keyword was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_keyword is present and the request included reporting_dimensions.keyword (false means the list is complete). When the breakdown was returned automatically without a request key, the flag is RECOMMENDED but not required — automatic rows carry no completeness contract.'
        ),
    ] = None
    by_keyword_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_keyword rows. Sellers MUST return this field whenever by_keyword is present and the request included reporting_dimensions.keyword. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric. When the breakdown was returned automatically without a request key, the field is RECOMMENDED but not required — automatic rows carry no completeness contract."
        ),
    ] = None
    by_keyword_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_keyword ordering. Sellers MUST return this field whenever by_keyword is present and the request included reporting_dimensions.keyword, alongside by_keyword_sorted_by. When the breakdown was returned automatically without a request key, the field is RECOMMENDED but not required — automatic rows carry no completeness contract.'
        ),
    ] = None
    by_geo: Annotated[
        list[geo_delivery_metrics.GeoDeliveryMetrics] | None,
        Field(
            description="Delivery by geographic area within this package. Available when the buyer requests geo breakdown via reporting_dimensions and the seller supports it. Each dimension's rows are independent slices that should sum to the package total."
        ),
    ] = None
    by_geo_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_geo was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_geo is present (false means the list is complete).'
        ),
    ] = None
    by_geo_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_geo rows. Sellers MUST return this field whenever by_geo is present. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric."
        ),
    ] = None
    by_geo_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_geo ordering. Sellers MUST return this field whenever by_geo is present.'
        ),
    ] = None
    by_device_type: Annotated[
        list[ByDeviceTypeItem] | None,
        Field(
            description='Delivery by device form factor within this package. Available when the buyer requests device_type breakdown via reporting_dimensions and the seller supports it.'
        ),
    ] = None
    by_device_type_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_device_type was truncated. Sellers MUST return this flag whenever by_device_type is present (false means the list is complete).'
        ),
    ] = None
    by_device_type_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_device_type rows. Sellers MUST return this field whenever by_device_type is present. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric."
        ),
    ] = None
    by_device_type_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_device_type ordering. Sellers MUST return this field whenever by_device_type is present.'
        ),
    ] = None
    by_device_type_pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(
            description="Cursor to retrieve the remaining by_device_type rows when by_device_type_truncated is true. Sellers MUST return this field whenever by_device_type_truncated is true; omit when false or when by_device_type is absent. Pass the cursor back in the corresponding request's reporting_dimensions.device_type_1.cursor to fetch the next page; other reporting_dimensions.device_type request fields (limit, sort_by, sort_direction) MUST be repeated unchanged across paged requests."
        ),
    ] = None
    by_device_platform: Annotated[
        list[ByDevicePlatformItem] | None,
        Field(
            description='Delivery by operating system within this package. Available when the buyer requests device_platform breakdown via reporting_dimensions and the seller supports it. Useful for CTV campaigns where tvOS vs Roku OS vs Fire OS matters.'
        ),
    ] = None
    by_device_platform_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_device_platform was truncated. Sellers MUST return this flag whenever by_device_platform is present (false means the list is complete).'
        ),
    ] = None
    by_device_platform_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_device_platform rows. Sellers MUST return this field whenever by_device_platform is present. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric."
        ),
    ] = None
    by_device_platform_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_device_platform ordering. Sellers MUST return this field whenever by_device_platform is present.'
        ),
    ] = None
    by_device_platform_pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(
            description="Cursor to retrieve the remaining by_device_platform rows when by_device_platform_truncated is true. Sellers MUST return this field whenever by_device_platform_truncated is true; omit when false or when by_device_platform is absent. Pass the cursor back in the corresponding request's reporting_dimensions.device_platform_1.cursor to fetch the next page; other reporting_dimensions.device_platform request fields (limit, sort_by, sort_direction) MUST be repeated unchanged across paged requests."
        ),
    ] = None
    by_audience: Annotated[
        list[ByAudienceItem] | None,
        Field(
            description="Delivery by audience segment within this package. Available when the buyer requests audience breakdown via reporting_dimensions and the seller supports it. Only 'synced' audiences are directly targetable via the targeting overlay; other sources are informational."
        ),
    ] = None
    by_audience_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_audience was truncated. Sellers MUST return this flag whenever by_audience is present (false means the list is complete).'
        ),
    ] = None
    by_audience_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_audience rows. Sellers MUST return this field whenever by_audience is present. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric."
        ),
    ] = None
    by_audience_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_audience ordering. Sellers MUST return this field whenever by_audience is present.'
        ),
    ] = None
    by_audience_pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(
            description="Cursor to retrieve the remaining by_audience rows when by_audience_truncated is true. Sellers MUST return this field whenever by_audience_truncated is true; omit when false or when by_audience is absent. Pass the cursor back in the corresponding request's reporting_dimensions.audience.cursor to fetch the next page; other reporting_dimensions.audience request fields (limit, sort_by, sort_direction) MUST be repeated unchanged across paged requests."
        ),
    ] = None
    by_demographic: Annotated[
        list[ByDemographicItem] | None,
        Field(
            description='Delivery by demographic within this package. Available when the buyer requests demographic breakdown and the product declares supports_demographic_breakdown. A free-form measurement code does not prove alignment with buyer targeting. When age is present it is the authoritative machine-comparable interval; for requested age_ranges, sellers MUST echo the exact requested interval and MUST NOT substitute a wider or narrower native bucket.'
        ),
    ] = None
    by_demographic_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether non-suppressed by_demographic rows were truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_demographic is present. False means every non-suppressed row is present; inspect by_demographic_suppressed separately before reconciling rows to package totals.'
        ),
    ] = None
    by_demographic_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_demographic rows. Sellers MUST return this field whenever by_demographic is present. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric."
        ),
    ] = None
    by_demographic_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_demographic ordering. Sellers MUST return this field whenever by_demographic is present.'
        ),
    ] = None
    by_demographic_suppressed: Annotated[
        StrictBool | None,
        Field(
            description='Whether one or more otherwise reportable demographic rows were omitted due to privacy, policy, or measurement thresholds. Sellers MUST return this flag whenever by_demographic is present. False means no rows were threshold-suppressed.'
        ),
    ] = None
    by_placement: Annotated[
        list[placement_delivery_metrics.PlacementDeliveryMetrics] | None,
        Field(
            description='Delivery by placement within this package. placement_id remains required for 3.1 compatibility. New 3.2 sellers also emit placement_identity, whose discriminator separates publisher-catalog identity from sales-agent-defined inline identity.'
        ),
    ] = None
    by_placement_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_placement was truncated. Sellers MUST return this flag whenever by_placement is present (false means the list is complete).'
        ),
    ] = None
    by_placement_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="The metric actually used to order by_placement rows. Sellers MUST return this field whenever by_placement is present. When the seller cannot sort by the requested sort_by metric it falls back to 'spend'; this echo makes the fallback visible instead of silently returning rows the buyer will misread as ordered by the requested metric."
        ),
    ] = None
    by_placement_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_placement ordering. Sellers MUST return this field whenever by_placement is present.'
        ),
    ] = None
    by_placement_pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(
            description="Cursor to retrieve the remaining by_placement rows when by_placement_truncated is true. Sellers MUST return this field whenever by_placement_truncated is true; omit when false or when by_placement is absent. Pass the cursor back in the corresponding request's reporting_dimensions.placement.cursor to fetch the next page; other reporting_dimensions.placement request fields (limit, sort_by, sort_direction) MUST be repeated unchanged across paged requests."
        ),
    ] = None
    by_property: Annotated[
        list[property_delivery_metrics.PropertyDeliveryMetrics] | None,
        Field(
            description='Delivery by publisher property within this package. Each row identifies the actual surface with an operational identifier and adds property_ref when it resolves to a canonical publisher catalog entry. Rows are independent of by_collection.'
        ),
    ] = None
    by_property_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether non-suppressed by_property rows were truncated. Sellers MUST return this flag whenever by_property is present. False means every non-suppressed row is present; inspect by_property_suppressed before reconciling rows to package totals.'
        ),
    ] = None
    by_property_suppressed: Annotated[
        StrictBool | None,
        Field(
            description='Whether one or more otherwise reportable by_property rows were omitted from this response due to privacy, policy, or measurement thresholds. Sellers MUST return this flag whenever by_property is present. False means no rows were threshold-suppressed. Both suppression and truncation may be true.'
        ),
    ] = None
    by_property_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description='The metric actually used to order by_property rows. Sellers MUST return this field whenever by_property is present.'
        ),
    ] = None
    by_property_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_property rows. Sellers MUST return this field whenever by_property is present.'
        ),
    ] = None
    by_collection: Annotated[
        list[collection_delivery_metrics.CollectionDeliveryMetrics] | None,
        Field(
            description='Delivery by publisher-scoped collection within this package. This is a marginal breakdown and does not by itself prove which property carried a collection.'
        ),
    ] = None
    by_collection_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_collection was truncated. Sellers MUST return this flag whenever by_collection is present.'
        ),
    ] = None
    by_collection_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description='The metric actually used to order by_collection rows. Sellers MUST return this field whenever by_collection is present.'
        ),
    ] = None
    by_collection_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_collection rows. Sellers MUST return this field whenever by_collection is present.'
        ),
    ] = None
    by_installment: Annotated[
        list[installment_delivery_metrics.InstallmentDeliveryMetrics] | None,
        Field(description='Delivery by canonically identified installment within this package.'),
    ] = None
    by_installment_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_installment was truncated. Sellers MUST return this flag whenever by_installment is present.'
        ),
    ] = None
    by_installment_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description='The metric actually used to order by_installment rows. Sellers MUST return this field whenever by_installment is present.'
        ),
    ] = None
    by_installment_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_installment rows. Sellers MUST return this field whenever by_installment is present.'
        ),
    ] = None
    by_collection_property: Annotated[
        list[collection_property_delivery_metrics.CollectionPropertyDeliveryMetrics] | None,
        Field(
            description='Delivery at the collection × property intersection. A row is affirmative delivery evidence that the referenced collection ran on the referenced property; it is not merely a carriage or catalog assertion.'
        ),
    ] = None
    by_collection_property_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether non-suppressed by_collection_property rows were truncated. Sellers MUST return this flag whenever by_collection_property is present.'
        ),
    ] = None
    by_collection_property_suppressed: Annotated[
        StrictBool | None,
        Field(
            description='Whether one or more otherwise reportable by_collection_property rows were omitted from this response due to privacy, policy, or measurement thresholds. Sellers MUST return this flag whenever by_collection_property is present. False means no rows were threshold-suppressed. Both suppression and truncation may be true.'
        ),
    ] = None
    by_collection_property_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description='The metric actually used to order by_collection_property rows. Sellers MUST return this field whenever by_collection_property is present.'
        ),
    ] = None
    by_collection_property_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_collection_property rows. Sellers MUST return this field whenever by_collection_property is present.'
        ),
    ] = None
    by_installment_property: Annotated[
        list[installment_property_delivery_metrics.InstallmentPropertyDeliveryMetrics] | None,
        Field(
            description='Delivery at the installment × property intersection. A row is affirmative delivery evidence that the referenced airing, episode, issue, or programming block ran on the referenced property; it is not inferred from collection carriage or independent marginals.'
        ),
    ] = None
    by_installment_property_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether non-suppressed by_installment_property rows were truncated. Sellers MUST return this flag whenever by_installment_property is present.'
        ),
    ] = None
    by_installment_property_suppressed: Annotated[
        StrictBool | None,
        Field(
            description='Whether one or more otherwise reportable by_installment_property rows were omitted from this response due to privacy, policy, or measurement thresholds. Sellers MUST return this flag whenever by_installment_property is present. False means no rows were threshold-suppressed. Both suppression and truncation may be true.'
        ),
    ] = None
    by_installment_property_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description='The metric actually used to order by_installment_property rows. Sellers MUST return this field whenever by_installment_property is present.'
        ),
    ] = None
    by_installment_property_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_installment_property rows. Sellers MUST return this field whenever by_installment_property is present.'
        ),
    ] = None
    by_placement_property: Annotated[
        list[placement_property_delivery_metrics.PlacementPropertyDeliveryMetrics] | None,
        Field(
            description='Delivery at the placement × property intersection. This proves which actual property carried a placement that may span more than one property.'
        ),
    ] = None
    by_placement_property_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether non-suppressed by_placement_property rows were truncated. Sellers MUST return this flag whenever by_placement_property is present.'
        ),
    ] = None
    by_placement_property_suppressed: Annotated[
        StrictBool | None,
        Field(
            description='Whether one or more otherwise reportable by_placement_property rows were omitted from this response due to privacy, policy, or measurement thresholds. Sellers MUST return this flag whenever by_placement_property is present. False means no rows were threshold-suppressed. Both suppression and truncation may be true.'
        ),
    ] = None
    by_placement_property_sorted_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description='The metric actually used to order by_placement_property rows. Sellers MUST return this field whenever by_placement_property is present.'
        ),
    ] = None
    by_placement_property_sort_direction: Annotated[
        sort_direction.SortDirection | None,
        Field(
            description='The direction actually applied to by_placement_property rows. Sellers MUST return this field whenever by_placement_property is present.'
        ),
    ] = None
    by_spot: Annotated[
        list[BySpotItem] | None,
        Field(
            description='Spot-level as-run airing records for broadcast TV, radio, or other scheduled inventory. Available when the buyer requests spot breakdown and the product declares supports_spot_breakdown. Sellers MUST order rows by aired_at ascending. The same spot_id is reused when a later package measurement_window adds or revises metrics. Network and station are optional so station-direct radio and network-level TV records use the same channel-neutral shape. Sellers SHOULD populate creative_id whenever they can associate a specific airing with a creative, particularly when the package could serve more than one creative during any part of the reporting period, including a mid-period replacement. Sellers that cannot make that association MUST omit creative_id rather than emit a default or placeholder. Buyers MUST NOT aggregate by_spot rows by creative_id and expect the result to equal by_creative impressions for the same creative: the two dimensions are independently produced at different granularities and are subject to different metric-maturation and attribution semantics within the package measurement_window. by_creative is the authoritative creative-performance aggregate; creative_id on a by_spot row identifies which creative aired, not an independent metric roll-up source.'
        ),
    ] = None
    by_spot_truncated: Annotated[
        StrictBool | None,
        Field(
            description='Whether by_spot is incomplete because of the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_spot is present (false means the as-run log is complete for the requested reporting period).'
        ),
    ] = None
    daily_breakdown: Annotated[
        list[DailyBreakdownItem] | None,
        Field(
            description='Day-by-day delivery for this package. Only present when include_package_daily_breakdown is true in the request. Enables per-package pacing analysis and line-item monitoring.'
        ),
    ] = None
    spend: Any

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

• DeliveryMetrics
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var by_audience : list[ByAudienceItem] | None

var by_audience_pagination : PaginationResponse | None

var by_audience_sort_direction : SortDirection | None

var by_audience_sorted_by : SortMetric | None

var by_audience_truncated : bool | None

var by_catalog_item : list[CatalogItemDeliveryMetrics] | None

var by_catalog_item_sort_direction : SortDirection | None

var by_catalog_item_sorted_by : SortMetric | None

var by_catalog_item_truncated : bool | None

var by_collection : list[CollectionDeliveryMetrics] | None

var by_collection_property : list[CollectionPropertyDeliveryMetrics] | None

var by_collection_property_sort_direction : SortDirection | None

var by_collection_property_sorted_by : SortMetric | None

var by_collection_property_suppressed : bool | None

var by_collection_property_truncated : bool | None

var by_collection_sort_direction : SortDirection | None

var by_collection_sorted_by : SortMetric | None

var by_collection_truncated : bool | None

var by_creative : list[CreativeDeliveryMetrics] | None

var by_creative_sort_direction : SortDirection | None

var by_creative_sorted_by : SortMetric | None

var by_creative_truncated : bool | None

var by_demographic : list[ByDemographicItem] | None

var by_demographic_sort_direction : SortDirection | None

var by_demographic_sorted_by : SortMetric | None

var by_demographic_suppressed : bool | None

var by_demographic_truncated : bool | None

var by_device_platform : list[ByDevicePlatformItem] | None

var by_device_platform_pagination : PaginationResponse | None

var by_device_platform_sort_direction : SortDirection | None

var by_device_platform_sorted_by : SortMetric | None

var by_device_platform_truncated : bool | None

var by_device_type : list[ByDeviceTypeItem] | None

var by_device_type_pagination : PaginationResponse | None

var by_device_type_sort_direction : SortDirection | None

var by_device_type_sorted_by : SortMetric | None

var by_device_type_truncated : bool | None

var by_format : list[ByFormatItem] | None

var by_format_sort_direction : SortDirection | None

var by_format_sorted_by : SortMetric | None

var by_format_truncated : bool | None

var by_geo : list[GeoDeliveryMetrics] | None

var by_geo_sort_direction : SortDirection | None

var by_geo_sorted_by : SortMetric | None

var by_geo_truncated : bool | None

var by_installment : list[InstallmentDeliveryMetrics] | None

var by_installment_property : list[InstallmentPropertyDeliveryMetrics] | None

var by_installment_property_sort_direction : SortDirection | None

var by_installment_property_sorted_by : SortMetric | None

var by_installment_property_suppressed : bool | None

var by_installment_property_truncated : bool | None

var by_installment_sort_direction : SortDirection | None

var by_installment_sorted_by : SortMetric | None

var by_installment_truncated : bool | None

var by_keyword : list[KeywordDeliveryMetrics] | None

var by_keyword_sort_direction : SortDirection | None

var by_keyword_sorted_by : SortMetric | None

var by_keyword_truncated : bool | None

var by_placement : list[PlacementDeliveryMetrics] | None

var by_placement_pagination : PaginationResponse | None

var by_placement_property : list[PlacementPropertyDeliveryMetrics] | None

var by_placement_property_sort_direction : SortDirection | None

var by_placement_property_sorted_by : SortMetric | None

var by_placement_property_suppressed : bool | None

var by_placement_property_truncated : bool | None

var by_placement_sort_direction : SortDirection | None

var by_placement_sorted_by : SortMetric | None

var by_placement_truncated : bool | None

var by_property : list[PropertyDeliveryMetrics] | None

var by_property_sort_direction : SortDirection | None

var by_property_sorted_by : SortMetric | None

var by_property_suppressed : bool | None

var by_property_truncated : bool | None

var by_spot : list[BySpotItem] | None

var by_spot_truncated : bool | None

var currency : str

var daily_breakdown : list[DailyBreakdownItem] | None

var delivery_status : DeliveryStatus | None

var finalized_at : pydantic.types.AwareDatetime | None

var is_final : bool | None

var measurement_window : str | None

var metric_values : list[PackageDeliveryMetricValue] | None

var missing_metrics : list[MissingMetric1 | MissingMetric2] | None

var model_config

var pacing_index : float | None

var package_id : str

var paused : bool | None

var pricing_model : PricingModel

var rate : float

var spend : Any

var supersedes_window : str | None

Inherited members

• DeliveryMetrics:
  • model_dump
  • model_dump_json
  • model_summary

class CalibrateContentRequest (**data: Any)

Expand source code

class CalibrateContentRequest(AdcpRequest, AdcpVersionEnvelope):
    standards_id: Annotated[str, Field(description='Standards configuration to calibrate against')]
    artifact: Annotated[artifact_1.Artifact, Field(description='Artifact to evaluate')]
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 artifact : Artifact

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var standards_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 CalibrateContentResponse1 (**data: Any)

Expand source code

class CalibrateContentResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    verdict: binary_verdict_1.BinaryVerdict
    confidence: Annotated[float, Field(ge=0, le=1)] | None = None
    explanation: str | None = None
    features: list[Feature] | None = 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.

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 confidence : float | None

var context : ContextObject | None

var explanation : str | None

var ext : ExtensionObject | None

var features : list[Feature] | None

var model_config

var verdict : BinaryVerdict

class CalibrateContentSuccessResponse (**data: Any)

Expand source code

class CalibrateContentResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    verdict: binary_verdict_1.BinaryVerdict
    confidence: Annotated[float, Field(ge=0, le=1)] | None = None
    explanation: str | None = None
    features: list[Feature] | None = 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.

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 confidence : float | None

var context : ContextObject | None

var explanation : str | None

var ext : ExtensionObject | None

var features : list[Feature] | None

var model_config

var verdict : BinaryVerdict

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 CalibrateContentErrorResponse (**data: Any)

Expand source code

class CalibrateContentResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: list[error_1.Error]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 CanonicalFormatAgentPlacement (**data: Any)

Expand source code

class CanonicalFormatAgentPlacementAiSurfaceSponsoredPlacement(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    experimental: Annotated[
        Any | None,
        Field(
            description="Marked experimental at 3.1 GA: the canonical's tracking model (mention-level impression + attribution, postback shape, cross-surface dedup) is intentionally underspecified for 3.1. Adopters claiming `agent_placement` ship private tracking integrations; buyer agents MUST treat attribution as adapter-defined until the 3.2 tracking-macro spec lands. Promotion to non-experimental gated on the 3.2 tracking-contract spec."
        ),
    ] = True
    v1_translatable: Annotated[
        Any | None,
        Field(
            description="Inherently new in v2 — AI-surface sponsored mentions weren't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural."
        ),
    ] = False
    slots: Annotated[
        Any | None,
        Field(
            description="agent_placement has minimal buyer-shipped slots — the surface composes the rendered output from brand context (resolved via the manifest's top-level `brand` BrandRef) plus optional offering_ref and landing_page_url assets. None of these assets are rendered verbatim by the buyer; the agent chooses how to use them."
        ),
    ] = [
        {'asset_group_id': 'offering_ref', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    output_modality: Annotated[
        OutputModality | None,
        Field(
            description='How the surface presents the mention. `text` = inline text (chat, search snippet). `audio` = TTS-synthesized voice. `card` = structured card with optional image + text.'
        ),
    ] = None
    max_mention_length_chars: Annotated[
        SchemaInt | None,
        Field(
            description='For text output: maximum length of the surface-composed mention text.',
            ge=1,
        ),
    ] = None
    max_mention_duration_ms: Annotated[
        SchemaInt | None,
        Field(
            description='For audio output: maximum duration of the spoken mention in milliseconds.',
            ge=1,
        ),
    ] = None
    supports_offering_reference: Annotated[
        StrictBool | None,
        Field(
            description='Whether the product accepts an offering reference (specific product/service to promote within the mention) in addition to brand context.'
        ),
    ] = None
    supports_landing_page_url: Annotated[
        StrictBool | None,
        Field(
            description='Whether the surface attaches a landing page URL to the mention (citation, learn-more link).'
        ),
    ] = None
    tone_constraints: Annotated[
        list[str] | None,
        Field(
            description="**Advisory only.** Buyer-declared brand-voice preferences the surface SHOULD honor (e.g., ['formal', 'no_superlatives']). LLM/agentic surfaces have no protocol-level mechanism to verify enforcement — adopters that need hard guarantees should rely on brand.json voice declarations and post-mention review rather than this field. Future revisions may tie this to a structured tone vocabulary; for now treat as free-text guidance."
        ),
    ] = None
    disclosure_required: Annotated[
        StrictBool | None,
        Field(
            description='Whether the surface must include an explicit sponsorship disclosure label.'
        ),
    ] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var disclosure_required : bool | None

var experimental : typing.Any | None

var max_mention_duration_ms : int | None

var max_mention_length_chars : int | None

var model_config

var output_modality : OutputModality | None

var slots : typing.Any | None

var supports_landing_page_url : bool | None

var supports_offering_reference : bool | None

var tone_constraints : list[str] | None

var v1_translatable : typing.Any | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatBase (**data: Any)

Expand source code

class CanonicalFormatBase(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    experimental: Annotated[
        StrictBool | None,
        Field(
            description='When true, this canonical or seller narrowing may not work as declared. Adopters SHOULD preflight it with validate_input or in a sandbox and SHOULD NOT route production budget without testing; experimental status never makes the deprecated v1 path preferable. Drivers include unsettled spec shape, an adopter runtime gap, and custom shapes awaiting promotion. This replaces the earlier status plus runtime_status axes. Sellers SHOULD set experimental whenever a canonical or declaration is not production-ready.'
        ),
    ] = False
    deprecated: Annotated[
        StrictBool | None,
        Field(
            description="When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with `migration_target_version` to indicate when the canonical is expected to be removed. Distinct from `experimental`: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path."
        ),
    ] = False
    v1_translatable: Annotated[
        StrictBool | None,
        Field(
            description="Whether this canonical has any v1 named-format equivalent. `true` (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via `v1-canonical-mapping.json` is meaningful. `false` — the canonical is inherently new in v2 and has no v1 form; v1's `list_creative_formats` couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.\n\nLets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit `canonical` field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares `canonical_formats_only: true` on the product declaration). SDKs encountering `v1_translatable: false` on a canonical SHOULD NOT emit `FORMAT_PROJECTION_FAILED` (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The six inherently-v2 canonicals in 3.2 are `image_carousel`, `sponsored_placement`, `responsive_creative`, `agent_placement`, `seller_rendered_stateful_display`, and `coordinated_placements`."
        ),
    ] = True
    since_version: Annotated[
        str | None,
        Field(
            description="AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.",
            pattern='^[1-9]\\d*\\.(0|[1-9]\\d*)$',
        ),
    ] = None
    migration_target_version: Annotated[
        str | None,
        Field(
            description="AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when `deprecated: true`) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').",
            pattern='^[1-9]\\d*\\.(0|[1-9]\\d*)$',
        ),
    ] = None
    composition_model: Annotated[
        CompositionModel | None,
        Field(
            description='Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).'
        ),
    ] = None
    provenance_required: Annotated[
        StrictBool | None,
        Field(
            description='When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.'
        ),
    ] = None
    platform_extensions: Annotated[
        list[platform_extension_ref.PlatformExtensionReference] | None,
        Field(
            description='Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled `extensions` map in get_products responses or fetched directly.\n\n**Collision precedence (normative).** When two or more `platform_extensions[]` entries on the same declaration extend the same target (e.g., both extend `tracking`) with overlapping field names, **array order is authoritative — later entries override earlier ones on a per-field basis** (last-in-array-wins). SDKs MUST surface the overlap via the `errors[]` array on the `get_products` response with a structured code (`FORMAT_DECLARATION_DIVERGENT` is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with `error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }`). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.'
        ),
    ] = None
    synthesis_nondeterministic: Annotated[
        StrictBool | None,
        Field(
            description="When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive `validate_input` is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, `build_creative` returns task_failed with a synthesis_failed reason. Distinct from `composition_model` (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that `validate_input` can predict output properties from input properties.\n\n**Compatibility with `asset_source` / `item_production_model`**: `synthesis_nondeterministic: true` MAY pair with any of `seller_pre_rendered_from_brief`, `seller_human_designed`, or `agent_synthesized` (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with `buyer_uploaded` (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with `publisher_host_recorded` (the publisher's host produces a deterministic-from-script output even if the human voice varies). When `synthesis_nondeterministic: true` is set with an incompatible source, validators SHOULD reject with a structured error."
        ),
    ] = False
    slots: Annotated[
        list[Slot] | None,
        Field(
            description="Programmatic declaration of which canonical asset_group_id slots a manifest targeting this format must (or may) populate. Lets SDK codegen and validators enumerate expected slots without parsing the format's prose description. Each entry references an asset_group_id from the canonical vocabulary registry, paired with an `asset_type` so the validator knows which asset schema to apply. Format-level narrowing parameters that apply across all slots (e.g., flat `headline_max_chars` on responsive_creative) may also live on the format declaration; per-slot constraints (a specific slot's `max_chars` or `max_size_kb`) live on the slot entry."
        ),
    ] = None
    required_connections: Annotated[
        list[downstream_connection_requirement.DownstreamConnectionRequirement] | None,
        Field(
            description='Downstream platform connections or grants required to use this format declaration. These are in addition to the single AdCP caller credential. Use this when a platform product requires multiple downstream grants, such as an advertiser account connection plus a publisher identity or post authorization for published-post references.'
        ),
    ] = None
    reference_mutability: Annotated[
        ReferenceMutability | None,
        Field(
            description='Policy for formats whose `slots` accept a `published_post` reference. `immutable_snapshot`: seller snapshots the referenced post at approval and later source changes do not change the served creative. `mutable_requires_reapproval`: the source post may change and material changes require review before continued serving. `mutable_auto_recheck`: the source post may change and the seller continuously or periodically rechecks authorization/policy without requiring buyer resubmission. Omit when the format has no `published_post` slot.'
        ),
    ] = None
    production_window_business_days: Annotated[
        SchemaInt | None,
        Field(
            description='Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).',
            ge=0,
        ),
    ] = 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

• CanonicalFormatAgentPlacementAiSurfaceSponsoredPlacement
• CanonicalFormatDaastAudio
• CanonicalFormatHostedAudio
• CanonicalFormatVastAudio
• CanonicalFormatCoordinatedPlacements
• Params
• Params10
• Params11
• Params12
• Params13
• Params2
• Params3
• Params4
• Params5
• Params6
• Params7
• Params8
• Params9
• CanonicalFormatDisplayTag
• CanonicalFormatHtml5Banner
• CanonicalFormatImage
• CanonicalFormatImageCarousel
• CanonicalFormatNativeInFeed
• CanonicalFormatResponsiveCreative
• CanonicalFormatSellerRenderedStatefulDisplay
• CanonicalFormatSponsoredPlacementRetailMediaCatalogDriven
• CanonicalFormatHostedVideo
• CanonicalFormatVastVideo

Class variables

var composition_model : adcp.types.domains.formats.canonical._base.CompositionModel | None

var deprecated : bool | None

var experimental : bool | None

var migration_target_version : str | None

var model_config

var platform_extensions : list[PlatformExtensionReference] | None

var production_window_business_days : int | None

var provenance_required : bool | None

var reference_mutability : adcp.types.domains.formats.canonical._base.ReferenceMutability | None

var required_connections : list[DownstreamConnectionRequirement] | None

var since_version : str | None

var slots : list[adcp.types.domains.formats.canonical._base.Slot] | None

var synthesis_nondeterministic : bool | None

var v1_translatable : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatDaastAudio (**data: Any)

Expand source code

class CanonicalFormatDaastAudio(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    slots: Annotated[
        Any | None,
        Field(
            description="Default slots for audio_daast canonical. Buyer ships a DAAST tag (URL or inline XML, 1.0 or 1.1) plus an optional clickthrough URL. Tracking events are inherent to DAAST and don't require explicit slots."
        ),
    ] = [
        {'asset_group_id': 'daast_tag', 'asset_type': 'daast', 'required': True},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    daast_version: Annotated[
        daast_version_1.DaastVersion | None,
        Field(
            deprecated=True,
            description='Deprecated one-element alias for `daast_versions`. Producers use either the singular legacy alias or the plural 3.2 field, never both.',
        ),
    ] = None
    daast_versions: Annotated[
        daast_tracker_constraints.DaastVersions | None,
        Field(
            description="Accepted DAAST versions for this format option. A tracker execution selector's daast_versions must be a nonempty subset of this set."
        ),
    ] = None
    duration_ms_range: Annotated[
        list[DurationMsRangeItem] | None,
        Field(
            description='[min, max] duration in milliseconds. **Precedence**: `duration_ms_exact` takes precedence when both ship. SDKs SHOULD lint a warning when both fields ship.',
            max_length=2,
            min_length=2,
        ),
    ] = None
    duration_ms_exact: Annotated[
        SchemaInt | None,
        Field(
            description='When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship.',
            ge=1,
        ),
    ] = None
    linear_required: StrictBool | None = None
    max_wrapper_depth: Annotated[SchemaInt | None, Field(ge=0)] = None
    ssl_required: StrictBool | None = None
    companion_image_required: StrictBool | None = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var companion_image_required : bool | None

var daast_version : DaastVersion | None

var daast_versions : DaastVersions | None

var duration_ms_exact : int | None

var duration_ms_range : list[DurationMsRangeItem] | None

var linear_required : bool | None

var max_wrapper_depth : int | None

var model_config

var slots : typing.Any | None

var ssl_required : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatDisplayTag (**data: Any)

Expand source code

class CanonicalFormatDisplayTag(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    slots: Annotated[
        Any | None,
        Field(
            description='Backward-compatible URL-delivery slots. `tag_url` MUST use `url_type: ad_request`. A format option accepting `inline_markup` or `paired_redirect` overrides this list with a required slot whose `asset_type` is `display_tag`; the display-tag asset keeps paired redirect URLs atomic.'
        ),
    ] = [
        {'asset_group_id': 'tag_url', 'asset_type': 'url', 'required': True},
        {'asset_group_id': 'backup_image', 'asset_type': 'image', 'required': False},
    ]
    width: Annotated[
        SchemaInt | None,
        Field(
            description='Required tag rendering width in pixels — use for fixed-size slots. For multi-size flexible slots use `sizes[]`; for responsive use `min_width`/`max_width`/`min_height`/`max_height`. Exactly one of `(width, height)`, `sizes[]`, or `min/max_width` + `min/max_height` ranges MUST be set.',
            ge=1,
        ),
    ] = None
    height: Annotated[
        SchemaInt | None,
        Field(
            description='Required tag rendering height in pixels. See `width` for size-mode mutual exclusion.',
            ge=1,
        ),
    ] = None
    sizes: Annotated[
        list[Size] | None,
        Field(
            description="List of accepted (width, height) pairs for a multi-size flexible slot. The buyer's third-party tag must render at one of the listed sizes; the seller picks which size to request at impression time. Mutually exclusive with `(width, height)` and with responsive ranges.",
            min_length=1,
        ),
    ] = None
    min_width: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum accepted width for responsive third-party tags. Pair with `max_width`. Mutually exclusive with `(width, height)` and `sizes[]`.',
            ge=1,
        ),
    ] = None
    max_width: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted width for responsive third-party tags. Pair with `min_width`.',
            ge=1,
        ),
    ] = None
    min_height: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum accepted height for responsive third-party tags. Pair with `max_height`.',
            ge=1,
        ),
    ] = None
    max_height: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted height for responsive third-party tags. Pair with `min_height`.',
            ge=1,
        ),
    ] = None
    supported_tag_types: Annotated[
        list[SupportedTagType] | None,
        Field(
            deprecated=True,
            description='Deprecated ambiguous mechanism list. Use `supported_delivery_types`; markup subtype lives on the `display_tag` asset.',
        ),
    ] = None
    supported_delivery_types: Annotated[
        list[SupportedDeliveryType] | None,
        Field(
            description='Closed set of delivery types this format option can traffic. `paired_redirect` means one atomic ad-request/click-through pair (Internal Redirect semantics), never independently matchable URL slots.',
            min_length=1,
        ),
    ] = None
    ssl_required: Annotated[
        StrictBool | None, Field(description='Whether the tag URL must be HTTPS.')
    ] = None
    max_redirect_depth: Annotated[
        SchemaInt | None, Field(description='Maximum redirect chain depth permitted.', ge=0)
    ] = None
    max_response_time_ms: Annotated[
        SchemaInt | None,
        Field(description='Maximum tag-server response time in milliseconds.', ge=1),
    ] = None
    backup_image_required: Annotated[
        StrictBool | None,
        Field(
            description='Whether a backup image must accompany the tag for environments that cannot render the third-party tag.'
        ),
    ] = None
    backup_image_max_size_kb: Annotated[SchemaInt | None, Field(ge=1)] = None
    om_sdk_required: Annotated[
        StrictBool | None,
        Field(
            description="Whether the buyer's tag must integrate IAB Open Measurement SDK for viewability."
        ),
    ] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var backup_image_max_size_kb : int | None

var backup_image_required : bool | None

var height : int | None

var max_height : int | None

var max_redirect_depth : int | None

var max_response_time_ms : int | None

var max_width : int | None

var min_height : int | None

var min_width : int | None

var model_config

var om_sdk_required : bool | None

var sizes : list[Size] | None

var slots : typing.Any | None

var ssl_required : bool | None

var supported_delivery_types : list[SupportedDeliveryType] | None

var supported_tag_types : list[SupportedTagType] | None

var width : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatHostedAudio (**data: Any)

Expand source code

class CanonicalFormatHostedAudio(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    slots: Annotated[
        Any | None,
        Field(
            description="Default slots for buyer-uploaded audio. Host-read products override with a `script` (asset_type: text) or `creative_brief` (asset_type: brief) slot in place of `audio_main`, plus `asset_source: 'publisher_host_recorded'` and `buyer_asset_acceptance: 'rejected'`. TTS-from-script products override similarly with `asset_source: 'seller_pre_rendered_from_brief'`."
        ),
    ] = [
        {'asset_group_id': 'audio_main', 'asset_type': 'audio', 'required': True},
        {'asset_group_id': 'companion_image', 'asset_type': 'image', 'required': False},
        {'asset_group_id': 'brand_name', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    duration_ms_range: Annotated[
        list[DurationMsRange | None] | None,
        Field(
            description='[min, max] duration in milliseconds. Either endpoint MAY be null to express an unbounded side: [null, 60000] means up to 60s; [15000, null] means at least 15s. [null, null] is invalid because at least one endpoint must be bounded. **Precedence**: when both `duration_ms_exact` and `duration_ms_range` ship on the same product, `duration_ms_exact` takes precedence — buyers MUST validate against the exact value and ignore the range. SDKs SHOULD lint a warning when both fields ship; producers SHOULD pick one.',
            max_length=2,
            min_length=2,
        ),
    ] = None
    duration_ms_exact: Annotated[
        SchemaInt | None,
        Field(
            description='When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship.',
            ge=1,
        ),
    ] = None
    audio_codecs: list[AudioCodec] | None = None
    audio_sample_rates: list[AudioSampleRate] | None = None
    audio_channels: list[AudioChannel] | None = None
    min_bitrate_kbps: Annotated[SchemaInt | None, Field(ge=1)] = None
    max_bitrate_kbps: Annotated[SchemaInt | None, Field(ge=1)] = None
    max_file_size_mb: Annotated[
        StrictFloat | None,
        Field(
            description='Maximum hosted audio file size in decimal megabytes. Agents that proxy or cache media SHOULD advertise their effective transport ceiling here.',
            gt=0.0,
        ),
    ] = None
    loudness_lufs: Annotated[
        StrictFloat | None,
        Field(
            description='Required integrated loudness in LUFS (typical: -16 for streaming/podcast, -23 for broadcast). Negative values.'
        ),
    ] = None
    loudness_tolerance_db: Annotated[
        StrictFloat | None,
        Field(description='Permitted deviation from loudness_lufs in dB.', ge=0.0),
    ] = None
    true_peak_dbfs: Annotated[
        StrictFloat | None, Field(description='Maximum true-peak level in dBFS (typical: -2).')
    ] = None
    asset_source: Annotated[
        AssetSource | None,
        Field(
            description="Where the rendered audio bytes come from. Single shared enum across canonicals (see `image.json#asset_source` for the full semantics). `publisher_host_recorded`: the publisher's host records the audio (podcast host-read pattern); buyer must use the publisher's build_creative capability. `publisher_owned_reference` is valid only when the product accepts a reference asset whose publisher-owned source resolves to playable audio. `publisher_host_recorded` remains the normal audio-specific host-read value."
        ),
    ] = AssetSource.buyer_uploaded
    buyer_asset_acceptance: Annotated[
        BuyerAssetAcceptance | None,
        Field(
            description="Whether the product accepts buyer-uploaded audio. When `rejected`, the buyer cannot ship an audio asset directly — they must use build_creative (or sync_creatives with brief inputs) so the seller produces the audio. Combined with `asset_source`, lets a product declare 'I produce audio from briefs and refuse buyer uploads' (asset_source=`seller_pre_rendered_from_brief`, buyer_asset_acceptance=`rejected`)."
        ),
    ] = BuyerAssetAcceptance.accepted
    companion_image_required: StrictBool | None = None
    companion_image_aspect_ratio: str | None = None
    companion_image_max_file_size_kb: Annotated[SchemaInt | None, Field(ge=1)] = None
    brand_name_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_source : AssetSource | None

var audio_channels : list[AudioChannel] | None

var audio_codecs : list[AudioCodec] | None

var audio_sample_rates : list[AudioSampleRate] | None

var brand_name_max_chars : int | None

var buyer_asset_acceptance : BuyerAssetAcceptance | None

var companion_image_aspect_ratio : str | None

var companion_image_max_file_size_kb : int | None

var companion_image_required : bool | None

var duration_ms_exact : int | None

var duration_ms_range : list[DurationMsRange | None] | None

var loudness_lufs : float | None

var loudness_tolerance_db : float | None

var max_bitrate_kbps : int | None

var max_file_size_mb : float | None

var min_bitrate_kbps : int | None

var model_config

var slots : typing.Any | None

var true_peak_dbfs : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatHostedVideo (**data: Any)

Expand source code

class CanonicalFormatHostedVideo(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    slots: Annotated[
        Any | None,
        Field(
            description='Default slots for video_hosted canonical. Buyer ships a video asset (file or hosted URL); optional headline, primary text (long-form caption), CTA (typically constrained via `cta_values`), brand_name (typical for vertical short-form), companion_banner (typical for horizontal instream), and clickthrough URL. Products MAY override or extend the default — e.g., remove `companion_banner` for short-form vertical, narrow `cta` to a value enum, mark `landing_page_url` as required.'
        ),
    ] = [
        {'asset_group_id': 'video_main', 'asset_type': 'video', 'required': True},
        {'asset_group_id': 'headline', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'primary_text', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'cta', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'brand_name', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'companion_banner', 'asset_type': 'image', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    orientation: Annotated[
        Orientation | None,
        Field(
            description='Video orientation. Vertical = 9:16 (Reels, Stories, Shorts). Horizontal = 16:9 (instream, CTV). Square = 1:1 (in-feed).'
        ),
    ] = None
    aspect_ratio: Annotated[
        str | None,
        Field(
            description='Aspect ratio. Inferred from orientation if omitted.',
            pattern='^[0-9]+(\\.[0-9]+)?:[0-9]+(\\.[0-9]+)?$',
        ),
    ] = None
    min_width: Annotated[SchemaInt | None, Field(ge=1)] = None
    min_height: Annotated[SchemaInt | None, Field(ge=1)] = None
    max_width: Annotated[SchemaInt | None, Field(ge=1)] = None
    max_height: Annotated[SchemaInt | None, Field(ge=1)] = None
    duration_ms_range: Annotated[
        list[DurationMsRange | None] | None,
        Field(
            description='[min, max] duration in milliseconds. Either endpoint MAY be null to express an unbounded side: [null, 60000] means up to 60s; [15000, null] means at least 15s. [null, null] is invalid because at least one endpoint must be bounded. **Precedence**: when both `duration_ms_exact` and `duration_ms_range` ship on the same product, `duration_ms_exact` takes precedence — buyers MUST validate against the exact value and ignore the range. SDKs SHOULD lint a warning when both fields ship; producers SHOULD pick one.',
            max_length=2,
            min_length=2,
        ),
    ] = None
    duration_ms_exact: Annotated[
        SchemaInt | None,
        Field(
            description='When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship (see `duration_ms_range` description).',
            ge=1,
        ),
    ] = None
    video_codecs: list[VideoCodec] | None = None
    audio_codecs: list[AudioCodec] | None = None
    containers: list[Container] | None = None
    min_bitrate_kbps: Annotated[SchemaInt | None, Field(ge=1)] = None
    max_bitrate_kbps: Annotated[SchemaInt | None, Field(ge=1)] = None
    max_file_size_mb: Annotated[
        SchemaInt | None,
        Field(description='Maximum file size, where 1 MB is exactly 1,000,000 bytes.', ge=1),
    ] = None
    frame_rates: list[StrictFloat] | None = None
    captions: Captions | None = None
    om_sdk_required: StrictBool | None = None
    headline_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    primary_text_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    brand_name_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    cta_values: list[str] | None = None
    companion_banner_widths: Annotated[
        list[CompanionBannerWidth] | None,
        Field(description='Permitted companion banner widths (instream video).'),
    ] = None
    companion_banner_heights: list[CompanionBannerHeight] | None = None
    asset_source: Annotated[
        AssetSource | None,
        Field(
            description='Where the rendered asset bytes come from. Single shared enum across canonicals. See `image.json#asset_source` for the full semantics. `publisher_host_recorded` is audio-specific and has no defined behavior on video. `publisher_owned_reference` is valid when the product accepts an existing post reference via a `published_post` slot instead of uploaded video bytes. Adopters MUST select a value appropriate to the canonical.'
        ),
    ] = AssetSource.buyer_uploaded
    buyer_asset_acceptance: Annotated[
        BuyerAssetAcceptance | None,
        Field(
            description='Whether the product accepts buyer-uploaded video. When `rejected`, the buyer cannot ship a video asset directly — they must use build_creative, sync_creatives with brief inputs, or sync_creatives with an accepted reference asset so the seller produces or resolves the video.'
        ),
    ] = BuyerAssetAcceptance.accepted
    ctv_ad_experience: Annotated[
        ctv_ad_experience_1.CtvAdExperience | None,
        Field(
            description='CTV experience this option serves. On `video_hosted` only `screensaver` is valid (ambient looping video the platform plays on idle). Other experiences route per the matrix in docs/creative/ctv-experiences.mdx; linear CTV video declares no experience.'
        ),
    ] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var aspect_ratio : str | None

var asset_source : AssetSource | None

var audio_codecs : list[AudioCodec] | None

var brand_name_max_chars : int | None

var buyer_asset_acceptance : BuyerAssetAcceptance | None

var captions : Captions | None

var companion_banner_heights : list[CompanionBannerHeight] | None

var companion_banner_widths : list[CompanionBannerWidth] | None

var containers : list[Container] | None

var cta_values : list[str] | None

var ctv_ad_experience : CtvAdExperience | None

var duration_ms_exact : int | None

var duration_ms_range : list[DurationMsRange | None] | None

var frame_rates : list[float] | None

var headline_max_chars : int | None

var max_bitrate_kbps : int | None

var max_file_size_mb : int | None

var max_height : int | None

var max_width : int | None

var min_bitrate_kbps : int | None

var min_height : int | None

var min_width : int | None

var model_config

var om_sdk_required : bool | None

var orientation : Orientation | None

var primary_text_max_chars : int | None

var slots : typing.Any | None

var video_codecs : list[VideoCodec] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatHtml5Banner (**data: Any)

Expand source code

class CanonicalFormatHtml5Banner(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    slots: Annotated[
        Any | None,
        Field(
            description="Default slots for html5 canonical. Buyer ships a zip bundle plus optional backup image (required when `backup_image_required: true`) and clickthrough URL. The zip's entry point is typically `index.html`; click handling uses the `clickTag` (or `clickTAG`) macro substituted by the seller at serve time."
        ),
    ] = [
        {'asset_group_id': 'html5_bundle', 'asset_type': 'zip', 'required': True},
        {'asset_group_id': 'backup_image', 'asset_type': 'image', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    width: Annotated[
        SchemaInt | None,
        Field(
            description='Required banner width in pixels — use for fixed-size slots. For multi-size flexible slots use `sizes[]`; for responsive use `min_width`/`max_width`/`min_height`/`max_height`. Exactly one of `(width, height)`, `sizes[]`, or `min/max_width` + `min/max_height` ranges MUST be set.',
            ge=1,
        ),
    ] = None
    height: Annotated[
        SchemaInt | None,
        Field(
            description='Required banner height in pixels. See `width` for size-mode mutual exclusion.',
            ge=1,
        ),
    ] = None
    sizes: Annotated[
        list[Size] | None,
        Field(
            description='List of accepted (width, height) pairs for a multi-size flexible slot (publisher banner that accepts 300×250 OR 728×90 OR 970×250). Mirrors OpenRTB `banner.format[]`. Mutually exclusive with `(width, height)` and with responsive ranges.',
            min_length=1,
        ),
    ] = None
    min_width: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum accepted width for responsive HTML5 banners that adapt within a range. Pair with `max_width`. Mutually exclusive with `(width, height)` and `sizes[]`.',
            ge=1,
        ),
    ] = None
    max_width: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted width for responsive HTML5 banners. Pair with `min_width`.',
            ge=1,
        ),
    ] = None
    min_height: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum accepted height for responsive HTML5 banners. Pair with `max_height`.',
            ge=1,
        ),
    ] = None
    max_height: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted height for responsive HTML5 banners. Pair with `min_height`.',
            ge=1,
        ),
    ] = None
    max_initial_load_kb: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum initial-load file size (zip + above-the-fold assets) in kilobytes. IAB display standards: 200 KB for fixed sizes, 100 KB for mobile.',
            ge=1,
        ),
    ] = None
    max_polite_load_kb: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum polite-load file size after host-initiated subload, in kilobytes. IAB display standards: 500 KB for fixed sizes.',
            ge=1,
        ),
    ] = None
    host_initiated_subload: Annotated[
        StrictBool | None,
        Field(
            description='Whether the host page must initiate the polite-load phase. IAB-compliant banners require true.'
        ),
    ] = None
    max_animation_duration_ms: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum total animation duration in milliseconds. IAB standard: 30000 (30 seconds).',
            ge=0,
        ),
    ] = None
    max_cpu_load_percent: Annotated[
        SchemaInt | None,
        Field(description='Maximum CPU load percentage during render.', ge=1, le=100),
    ] = None
    mraid_required: Annotated[
        StrictBool | None,
        Field(description='Whether MRAID compatibility is required (mobile in-app).'),
    ] = None
    mraid_version: Annotated[
        MraidVersion | None,
        Field(description='Required MRAID version when mraid_required is true.'),
    ] = None
    om_sdk_required: Annotated[
        StrictBool | None,
        Field(description='Whether IAB Open Measurement SDK integration is required.'),
    ] = None
    clicktag_macro: Annotated[
        ClicktagMacro | None, Field(description='Name of the click-tag macro the bundle must use.')
    ] = None
    backup_image_required: Annotated[
        StrictBool | None,
        Field(
            description='Whether a backup image must accompany the zip for non-HTML5 environments.'
        ),
    ] = None
    backup_image_max_size_kb: Annotated[
        SchemaInt | None, Field(description='Maximum backup image file size in kilobytes.', ge=1)
    ] = None
    ssl_required: StrictBool | None = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var backup_image_max_size_kb : int | None

var backup_image_required : bool | None

var clicktag_macro : ClicktagMacro | None

var height : int | None

var host_initiated_subload : bool | None

var max_animation_duration_ms : int | None

var max_cpu_load_percent : int | None

var max_height : int | None

var max_initial_load_kb : int | None

var max_polite_load_kb : int | None

var max_width : int | None

var min_height : int | None

var min_width : int | None

var model_config

var mraid_required : bool | None

var mraid_version : MraidVersion | None

var om_sdk_required : bool | None

var sizes : list[Size] | None

var slots : typing.Any | None

var ssl_required : bool | None

var width : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatImage (**data: Any)

Expand source code

class CanonicalFormatImage(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    motion_level: MotionLevel | None = None
    slots: Annotated[
        Any | None,
        Field(
            description="Default slots for image canonical. Buyer ships an image asset (file or hosted URL) plus optional headline, body text, primary text (long-form caption), CTA (typically constrained to an enum via `cta_values`), and clickthrough URL. Products MAY override the default — make `headline` required, narrow `cta` to a value enum, or remove slots the surface doesn't consume."
        ),
    ] = [
        {'asset_group_id': 'image_main', 'asset_type': 'image', 'required': True},
        {'asset_group_id': 'headline', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'body_text', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'primary_text', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'cta', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    width: Annotated[
        SchemaInt | None,
        Field(
            description="Logical render width in pixels — use for fixed-size slots (e.g., a 300×250 IAB MREC). When `pixel_ratios` is absent, the required image asset width is the same value (1x). When `pixel_ratios` is present, an accepted asset's intrinsic width is `width × pixel_ratio`. For multi-size flexible slots, use `sizes[]`; for responsive slots, use the min/max fields. The three size modes are mutually exclusive.",
            ge=1,
        ),
    ] = None
    height: Annotated[
        SchemaInt | None,
        Field(
            description='Logical render height in pixels. Intrinsic asset height is `height × pixel_ratio`, where the ratio defaults to 1 when `pixel_ratios` is absent. See `width` for size-mode mutual exclusion.',
            ge=1,
        ),
    ] = None
    sizes: Annotated[
        list[Size] | None,
        Field(
            description='List of accepted logical (width, height) render pairs for a multi-size flexible slot. The buyer ships an asset matching one logical size multiplied by one accepted `pixel_ratios` entry (or by 1 when `pixel_ratios` is absent). SDKs MUST treat size and density as separate axes: a 600×500 intrinsic asset at 2x satisfies a logical 300×250 size; it does not create a logical 600×500 placement. Mirrors OpenRTB `banner.format[]` semantics. Mutually exclusive with `(width, height)` and with responsive ranges.',
            min_length=1,
        ),
    ] = None
    pixel_ratios: Annotated[
        list[PixelRatio] | None,
        Field(
            description='Accepted intrinsic-pixel densities for image assets, expressed as intrinsic pixels per logical render pixel (for example `[1, 2]` accepts both standard and Retina renditions). Absence means `[1]` for backward compatibility. This is an acceptance set, not a requirement to submit every rendition: one `image_main` asset satisfying any listed ratio is sufficient unless the effective `image_main` slot declares `required_pixel_ratios`. SDKs determine the effective ratio from `asset.pixel_ratio` when supplied, otherwise infer it from intrinsic asset dimensions divided by the matched logical size. Width and height ratios MUST agree.',
            min_length=1,
        ),
    ] = None
    min_width: Annotated[
        SchemaInt | None,
        Field(
            description="Minimum accepted width in pixels for responsive slots that adapt within a range (e.g., 'any width from 300 to 970'). Use with `max_width` (and optionally `min_height`/`max_height`). Mutually exclusive with `(width, height)` and `sizes[]`.",
            ge=1,
        ),
    ] = None
    max_width: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted width in pixels for responsive slots. Pair with `min_width`. See `min_width` for size-mode mutual exclusion.',
            ge=1,
        ),
    ] = None
    min_height: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum accepted height in pixels for responsive slots. Pair with `max_height`.',
            ge=1,
        ),
    ] = None
    max_height: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum accepted height in pixels for responsive slots. Pair with `min_height`.',
            ge=1,
        ),
    ] = None
    aspect_ratio: Annotated[
        str | None,
        Field(
            description="Optional aspect ratio constraint (e.g., '1.91:1', '1:1'). When provided alongside `width`/`height`, must agree. When used with `sizes[]` or responsive ranges, narrows accepted entries to those matching the aspect ratio.",
            pattern='^[0-9]+(\\.[0-9]+)?:[0-9]+(\\.[0-9]+)?$',
        ),
    ] = None
    max_file_size_kb: Annotated[
        SchemaInt | None, Field(description='Maximum file size in kilobytes.', ge=1)
    ] = None
    image_formats: Annotated[
        list[ImageFormat] | None, Field(description='Permitted image file formats.')
    ] = None
    ssl_required: Annotated[
        StrictBool | None,
        Field(description='Whether the image and its trackers must be served over HTTPS.'),
    ] = None
    headline_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    body_text_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    cta_values: Annotated[
        list[str] | None,
        Field(
            description="Permitted CTA values for this product (e.g., ['LEARN_MORE', 'SHOP_NOW'])."
        ),
    ] = None
    asset_source: Annotated[
        AssetSource | None,
        Field(
            description="Where the rendered asset bytes come from. Single shared enum across all canonicals (`image`, `video_hosted`, `audio_hosted` — replaces the earlier per-canonical `image_source` / `video_source` / `audio_source` fields). `buyer_uploaded` (default): buyer ships a pre-rendered asset. `publisher_host_recorded`: publisher's host records the asset (audio-specific; podcast host-read pattern). `seller_pre_rendered_from_brief`: buyer ships a brief plus structured copy; seller renders ONE asset at sync_creatives or build_creative time (generative-DSP pattern). `seller_human_designed`: seller's design team renders manually from a brief. `agent_synthesized`: AI synthesis pipeline; pair with `synthesis_nondeterministic: true` when the platform cannot guarantee in-spec output (Veo/Sora/Imagen-class). `publisher_owned_reference`: buyer references an existing post or publisher-owned object via a `published_post` slot; the seller resolves and serves the referenced content after authorization/review rather than receiving uploaded bytes.\n\nNot every value is meaningful on every canonical — `publisher_host_recorded` is audio-specific; on `image` or `video_hosted` it has no defined behavior. `publisher_owned_reference` is meaningful only when the product's `slots` declaration accepts a reference asset such as `published_post`. Adopters MUST select a value appropriate to the canonical's asset type. The `slots` declaration is the binding contract for what the buyer ships; `asset_source` is informational and lets buyers understand the production model when picking products."
        ),
    ] = AssetSource.buyer_uploaded
    buyer_asset_acceptance: Annotated[
        BuyerAssetAcceptance | None,
        Field(
            description="Whether the product accepts buyer-uploaded assets. When `rejected`, the buyer cannot ship pre-rendered bytes directly — they must use build_creative (or sync_creatives with brief inputs or reference assets) so the seller produces or resolves the asset. Combined with `asset_source`, lets a product declare 'I produce assets from briefs and refuse buyer uploads' (asset_source=`seller_pre_rendered_from_brief`, buyer_asset_acceptance=`rejected`) or 'I accept existing post references, not uploaded bytes' (asset_source=`publisher_owned_reference`, buyer_asset_acceptance=`rejected`)."
        ),
    ] = BuyerAssetAcceptance.accepted
    ctv_ad_experience: Annotated[
        ctv_ad_experience_1.CtvAdExperience | None,
        Field(
            description='CTV experience this option serves. On `image` only `pause` and `screensaver` are valid — the image-plus-copy contract the major pause-ad sellers ingest (seller composites the frame; typical canvas 1920×1080 or a transparent-region overlay). Other experiences route per the matrix in docs/creative/ctv-experiences.mdx.'
        ),
    ] = None
    activation_methods: Annotated[
        list[activation_method.CreativeActivationMethod] | None,
        Field(
            description='Viewer activation mechanisms this option offers (e.g. `qr_code` on a pause frame). Activations are engagement events, not impressions.'
        ),
    ] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var activation_methods : list[CreativeActivationMethod] | None

var aspect_ratio : str | None

var asset_source : AssetSource | None

var body_text_max_chars : int | None

var buyer_asset_acceptance : BuyerAssetAcceptance | None

var cta_values : list[str] | None

var ctv_ad_experience : CtvAdExperience | None

var headline_max_chars : int | None

var height : int | None

var image_formats : list[ImageFormat] | None

var max_file_size_kb : int | None

var max_height : int | None

var max_width : int | None

var min_height : int | None

var min_width : int | None

var model_config

var motion_level : MotionLevel | None

var pixel_ratios : list[PixelRatio] | None

var sizes : list[Size] | None

var slots : typing.Any | None

var ssl_required : bool | None

var width : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatImageCarousel (**data: Any)

Expand source code

class CanonicalFormatImageCarousel(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    v1_translatable: Annotated[
        Any | None,
        Field(
            description="Inherently new in v2 — multi-card carousels (Meta carousel, Pinterest pin collections, Snap collection ads) weren't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural."
        ),
    ] = False
    slots: Annotated[
        Any | None,
        Field(
            description="Default slots for image_carousel. The `cards` slot's value in the manifest is an array of [card-asset](/schemas/core/assets/card-asset.json) objects; `min` / `max` constrain card count."
        ),
    ] = [
        {'asset_group_id': 'cards', 'asset_type': 'card', 'required': True, 'min': 2, 'max': 10},
        {'asset_group_id': 'primary_text', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    card_aspect_ratio: Annotated[
        str | None,
        Field(
            description="Aspect ratio shared across all cards (e.g., '1:1', '1.91:1', '4:5').",
            pattern='^[0-9]+(\\.[0-9]+)?:[0-9]+(\\.[0-9]+)?$',
        ),
    ] = None
    min_cards: Annotated[
        SchemaInt | None, Field(description='Minimum card count (typical: 2 or 3).', ge=2)
    ] = None
    max_cards: Annotated[
        SchemaInt | None,
        Field(description='Maximum card count (typical: 6, 10, or 35 depending on platform).'),
    ] = None
    allowed_card_media_asset_types: Annotated[
        list[AllowedCardMediaAssetType] | None,
        Field(
            description='Asset types each card\'s `media` field may carry. Default: [\'image\']. Polymorphic carousels (Meta) allow [\'image\', \'video\']. Renamed from `allowed_card_asset_types` to disambiguate that this constrains the card\'s media payload, not the card-asset itself (which is always asset_type: "card").'
        ),
    ] = None
    allowed_card_asset_types: Annotated[
        list[AllowedCardMediaAssetType] | None,
        Field(
            deprecated=True,
            description='DEPRECATED — alias for `allowed_card_media_asset_types`. Kept for back-compat; prefer the new field name. Removed in 5.0.',
        ),
    ] = None
    card_image_max_file_size_kb: Annotated[SchemaInt | None, Field(ge=1)] = None
    card_video_max_file_size_kb: Annotated[SchemaInt | None, Field(ge=1)] = None
    card_video_max_duration_ms: Annotated[SchemaInt | None, Field(ge=1)] = None
    primary_text_max_chars: Annotated[
        SchemaInt | None,
        Field(description='Maximum length of the carousel-level primary text.', ge=1),
    ] = None
    card_headline_max_chars: Annotated[
        SchemaInt | None,
        Field(
            description='Per-card headline character limit. Governs the `headline` field on each card-asset in the `cards` slot.',
            ge=1,
        ),
    ] = None
    card_description_max_chars: Annotated[
        SchemaInt | None,
        Field(
            description='Per-card description character limit. Governs the `description` field on each card-asset in the `cards` slot. Distinct from `card_headline_max_chars`: description is longer body copy (typically 100-500 chars); headline is the short label (typically 25-40 chars).',
            ge=1,
        ),
    ] = None
    ssl_required: StrictBool | None = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var allowed_card_asset_types : list[AllowedCardMediaAssetType] | None

var allowed_card_media_asset_types : list[AllowedCardMediaAssetType] | None

var card_aspect_ratio : str | None

var card_description_max_chars : int | None

var card_headline_max_chars : int | None

var card_image_max_file_size_kb : int | None

var card_video_max_duration_ms : int | None

var card_video_max_file_size_kb : int | None

var max_cards : int | None

var min_cards : int | None

var model_config

var primary_text_max_chars : int | None

var slots : typing.Any | None

var ssl_required : bool | None

var v1_translatable : typing.Any | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatKind (*args, **kwds)

Expand source code

class CanonicalFormatKind(StrEnum):
    image = 'image'
    html5 = 'html5'
    display_tag = 'display_tag'
    image_carousel = 'image_carousel'
    video_hosted = 'video_hosted'
    video_vast = 'video_vast'
    audio_hosted = 'audio_hosted'
    audio_vast = 'audio_vast'
    audio_daast = 'audio_daast'
    sponsored_placement = 'sponsored_placement'
    native_in_feed = 'native_in_feed'
    responsive_creative = 'responsive_creative'
    agent_placement = 'agent_placement'
    seller_rendered_stateful_display = 'seller_rendered_stateful_display'
    coordinated_placements = 'coordinated_placements'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var agent_placement

var audio_daast

var audio_hosted

var audio_vast

var coordinated_placements

var custom

var display_tag

var html5

var image

var image_carousel

var native_in_feed

var responsive_creative

var seller_rendered_stateful_display

var sponsored_placement

var video_hosted

var video_vast

class CanonicalFormatNativeInFeed (**data: Any)

Expand source code

class CanonicalFormatNativeInFeed(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    experimental: Annotated[
        Any | None,
        Field(
            description='Stable at 3.1 GA. Shape mirrors IAB OpenRTB Native 1.2 — the renderer contract is well-established across in-feed native and content-recommendation adopters.'
        ),
    ] = False
    v1_translatable: Annotated[
        Any | None,
        Field(
            description='Translates to v1 named native formats (e.g., `native_standard`, `native_content`) via the projection registry. Sellers with existing v1 named native formats SHOULD point `v1_format_ref[]` at them.'
        ),
    ] = True
    slots: Annotated[
        Any | None,
        Field(
            description="Default slot shape for native_in_feed. Mirrors IAB OpenRTB Native 1.2 asset types, including the Native video asset: `video` carries a VAST document (the Native 1.2 `vasttag` field) for video-bearing native units such as CTV menu heroes with focus-triggered playback. Products MAY override (`slots_override` on the projection ref) to narrow per-slot limits (`max_chars` on title/body) or remove unused slots (a content-recommendation slot that doesn't display an icon)."
        ),
    ] = [
        {'asset_group_id': 'title', 'asset_type': 'text', 'required': True},
        {'asset_group_id': 'body_text', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'main_image', 'asset_type': 'image', 'required': False},
        {'asset_group_id': 'icon', 'asset_type': 'image', 'required': False},
        {'asset_group_id': 'cta', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'advertiser_name', 'asset_type': 'text', 'required': True},
        {'asset_group_id': 'sponsored_label', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': True},
        {'asset_group_id': 'display_url', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'rating', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'price', 'asset_type': 'text', 'required': False},
        {'asset_group_id': 'video', 'asset_type': 'vast', 'required': False},
        {'asset_group_id': 'impression_tracker', 'asset_type': 'pixel_tracker', 'required': False},
        {'asset_group_id': 'viewability_tracker', 'asset_type': 'pixel_tracker', 'required': False},
        {'asset_group_id': 'click_tracker', 'asset_type': 'pixel_tracker', 'required': False},
    ]
    ctv_ad_experience: Annotated[
        ctv_ad_experience_1.CtvAdExperience | None,
        Field(
            description='CTV experience this option serves. On native_in_feed `menu` and `overlay` are valid. `menu`: smart-TV home/menu surfaces where the platform assembles buyer assets (background/main image, logo/icon, copy, optional focus-triggered video); `menu_placement` selects the tile vs headline-banner variant, and catalog-derived sponsored tiles route to `sponsored_placement` instead. `overlay`: seller-composited in-stream overlays supplied as an asset bundle (video, logo, imagery, copy, activation copy) — the contract overlay sellers that do not ingest VAST tags use; VAST-ingesting sellers publish a `video_vast` sibling option instead. The wire name stays `native_in_feed` for 3.x even though neither surface is literally in-feed.'
        ),
    ] = None
    menu_placement: Annotated[
        MenuPlacement | None,
        Field(
            description='Menu surface variant, mapping to OpenRTB Native `plcmttype` 1 (tile/feed) and 3 (headline banner). Valid only with `ctv_ad_experience: "menu"`.'
        ),
    ] = None
    focus_behavior: Annotated[
        FocusBehavior | None,
        Field(
            description='What happens when the viewer\'s remote focus lands on the unit. `autoplay_*` requires a `video` asset; playback method maps to AdCOM playbackmethod on OpenRTB bridges. Valid only with `ctv_ad_experience: "menu"`.'
        ),
    ] = None
    motion_level: Annotated[
        motion_level_1.CreativeMotionLevel | None,
        Field(description='Accepted motion class for the rendered unit (AdCOM attrs 21-23).'),
    ] = None
    activation_methods: Annotated[
        list[activation_method.CreativeActivationMethod] | None,
        Field(
            description='Viewer activation mechanisms this option offers (QR, deep link, send-to-device). Activations are engagement events, not impressions.'
        ),
    ] = None
    title_max_chars: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum character length for the title slot. IAB native typical: 25 (short) to 90 (long). Buyer agents SHOULD validate ship-time title length against this.',
            ge=1,
        ),
    ] = None
    body_text_max_chars: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum character length for the body_text slot. IAB native typical: 90 (mainline) to 140 (extended).',
            ge=1,
        ),
    ] = None
    cta_max_chars: Annotated[
        SchemaInt | None,
        Field(description='Maximum character length for the cta slot. Typical: 15–25.', ge=1),
    ] = None
    cta_values: Annotated[
        list[str] | None,
        Field(
            description="Permitted CTA values for this product (e.g., ['LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', 'DOWNLOAD']). When set, narrows the cta slot to a closed enum."
        ),
    ] = None
    main_image_sizes: Annotated[
        list[MainImageSize] | None,
        Field(
            description='Accepted logical (width, height) pairs for the main_image slot. Common IAB native sizes: 1200×627 (1.91:1), 1080×1080 (1:1), 1080×1350 (4:5). When the effective main_image slot declares `pixel_ratios`, intrinsic asset dimensions are the matched logical pair multiplied by the selected ratio; absence remains 1x.',
            min_length=1,
        ),
    ] = None
    icon_size: Annotated[
        IconSize | None,
        Field(
            description='Required logical (width, height) for the icon slot when present (typical: 80×80 or 100×100). When the effective icon slot declares `pixel_ratios`, intrinsic dimensions are multiplied by the selected ratio; absence remains 1x.'
        ),
    ] = None
    max_image_file_size_kb: Annotated[
        SchemaInt | None,
        Field(description='Maximum file size in kilobytes for main_image and icon.', ge=1),
    ] = None
    image_formats: Annotated[
        list[ImageFormat] | None, Field(description='Permitted image file formats.')
    ] = None
    ssl_required: Annotated[
        StrictBool | None,
        Field(
            description='Whether trackers, landing pages, and image URLs must be served over HTTPS.'
        ),
    ] = None
    asset_source: Annotated[
        AssetSource | None,
        Field(
            description="Where the rendered native assets come from. `publisher_host_recorded` is omitted (audio-specific and not meaningful for native). Other values mirror the shared production-source axis used on `image` / `video_hosted`. `buyer_uploaded` (default): buyer ships pre-rendered title/image/body. `seller_pre_rendered_from_brief`: buyer ships a brief, seller renders the native bundle. `agent_synthesized`: AI synthesis pipeline produces title + image + body from a brief; pair with `synthesis_nondeterministic: true` for generative pipelines that can't guarantee in-spec output. `publisher_owned_reference`: buyer ships an existing published post reference; the seller resolves the post into the native presentation after authorization/review."
        ),
    ] = AssetSource.buyer_uploaded
    buyer_asset_acceptance: Annotated[
        BuyerAssetAcceptance | None,
        Field(
            description='Whether the product accepts buyer-uploaded native assets. When `rejected`, the buyer cannot ship pre-rendered title/image/body — they must use `build_creative`, `sync_creatives` with brief inputs, or an accepted `published_post` reference so the seller produces or resolves the native bundle.'
        ),
    ] = BuyerAssetAcceptance.accepted

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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var activation_methods : list[CreativeActivationMethod] | None

var asset_source : AssetSource | None

var body_text_max_chars : int | None

var buyer_asset_acceptance : BuyerAssetAcceptance | None

var cta_max_chars : int | None

var cta_values : list[str] | None

var ctv_ad_experience : CtvAdExperience | None

var experimental : typing.Any | None

var focus_behavior : FocusBehavior | None

var icon_size : IconSize | None

var image_formats : list[ImageFormat] | None

var main_image_sizes : list[MainImageSize] | None

var max_image_file_size_kb : int | None

var menu_placement : MenuPlacement | None

var model_config

var motion_level : CreativeMotionLevel | None

var slots : typing.Any | None

var ssl_required : bool | None

var title_max_chars : int | None

var v1_translatable : typing.Any | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatResponsiveCreative (**data: Any)

Expand source code

class CanonicalFormatResponsiveCreative(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    experimental: Annotated[
        Any | None,
        Field(
            description="Marked experimental at 3.1 GA: composition is algorithmic (the surface picks combinations and reports per-asset breakdowns), and there's no clean v1-translatable equivalent. Buyers ship asset pools rather than rendered creatives; the surface's per-impression composition cannot be predicted by `validate_input`. Adopters SHOULD validate behavior per surface (Google PMax vs Meta Advantage+ creative differ meaningfully)."
        ),
    ] = True
    v1_translatable: Annotated[
        Any | None,
        Field(
            description="Inherently new in v2 — algorithmic asset-pool composition (Google PMax / Meta Advantage+ creative) wasn't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural."
        ),
    ] = False
    slots: Any | None = [
        {
            'asset_group_id': 'headlines',
            'asset_type': 'text',
            'required': True,
            'min': 3,
            'max': 15,
        },
        {
            'asset_group_id': 'long_headlines',
            'asset_type': 'text',
            'required': False,
            'min': 1,
            'max': 5,
        },
        {
            'asset_group_id': 'descriptions',
            'asset_type': 'text',
            'required': True,
            'min': 2,
            'max': 5,
        },
        {
            'asset_group_id': 'images_landscape',
            'asset_type': 'image',
            'required': False,
            'min': 1,
            'max': 20,
        },
        {
            'asset_group_id': 'images_square',
            'asset_type': 'image',
            'required': False,
            'min': 1,
            'max': 20,
        },
        {
            'asset_group_id': 'images_vertical',
            'asset_type': 'image',
            'required': False,
            'min': 1,
            'max': 20,
        },
        {'asset_group_id': 'video', 'asset_type': 'video', 'required': False, 'min': 0, 'max': 5},
        {
            'asset_group_id': 'logo',
            'asset_type': 'image',
            'required': True,
            'min': 1,
            'max': 5,
            'logo_slots': [
                'logo_card_light',
                'logo_card_dark',
                'marketplace_listing',
                'ad_end_card',
            ],
            'required_logo_slots': ['logo_card_light', 'logo_card_dark'],
        },
        {
            'asset_group_id': 'landing_page_url',
            'asset_type': 'url',
            'required': True,
            'min': 1,
            'max': 1,
        },
    ]
    headlines_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    headlines_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    headline_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    long_headlines_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    long_headlines_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    long_headline_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    descriptions_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    descriptions_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    description_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    images_landscape_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    images_landscape_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    images_landscape_aspect_ratio: str | None = None
    images_square_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    images_square_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    images_vertical_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    images_vertical_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    videos_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    videos_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    video_min_duration_ms: Annotated[SchemaInt | None, Field(ge=1)] = None
    video_max_duration_ms: Annotated[SchemaInt | None, Field(ge=1)] = None
    logo_min: Annotated[SchemaInt | None, Field(ge=0)] = None
    logo_max: Annotated[SchemaInt | None, Field(ge=0)] = None
    logo_aspect_ratios: list[str] | None = None
    business_name_max_chars: Annotated[SchemaInt | None, Field(ge=1)] = None
    asset_image_max_file_size_kb: Annotated[SchemaInt | None, Field(ge=1)] = None
    supports_catalog_input: Annotated[
        StrictBool | None,
        Field(
            description='Whether the product can additionally consume a catalog reference (e.g., PMax with product feed).'
        ),
    ] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_image_max_file_size_kb : int | None

var business_name_max_chars : int | None

var description_max_chars : int | None

var descriptions_max : int | None

var descriptions_min : int | None

var experimental : typing.Any | None

var headline_max_chars : int | None

var headlines_max : int | None

var headlines_min : int | None

var images_landscape_aspect_ratio : str | None

var images_landscape_max : int | None

var images_landscape_min : int | None

var images_square_max : int | None

var images_square_min : int | None

var images_vertical_max : int | None

var images_vertical_min : int | None

var logo_aspect_ratios : list[str] | None

var logo_max : int | None

var logo_min : int | None

var long_headline_max_chars : int | None

var long_headlines_max : int | None

var long_headlines_min : int | None

var model_config

var slots : typing.Any | None

var supports_catalog_input : bool | None

var v1_translatable : typing.Any | None

var video_max_duration_ms : int | None

var video_min_duration_ms : int | None

var videos_max : int | None

var videos_min : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatSponsoredPlacement (**data: Any)

Expand source code

class CanonicalFormatSponsoredPlacementRetailMediaCatalogDriven(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    experimental: Annotated[
        Any | None,
        Field(
            description='Marked experimental at 3.1 GA: the canonical covers 4 meaningfully different retail-media adapter contracts (Amazon SP, Criteo SP / CitrusAd SP, Pinterest Collection, generative-per-SKU). Adopter contracts vary; buyers MUST validate per-adapter behavior before routing budget. Promotion to non-experimental gated on the #4592 adapter-contract docs work.'
        ),
    ] = True
    v1_translatable: Annotated[
        Any | None,
        Field(
            description="Inherently new in v2 — retail-media catalog placements weren't expressible as v1 named formats. SDKs MUST NOT emit `FORMAT_PROJECTION_FAILED` for products using this canonical; the v1-unreachability is structural, not a registry-coverage gap."
        ),
    ] = False
    slots: Any | None = [
        {'asset_group_id': 'source_catalog', 'required': True, 'asset_type': 'catalog'},
        {'asset_group_id': 'hero_asset', 'required': False, 'asset_type': 'image'},
        {'asset_group_id': 'landing_page_url', 'required': False, 'asset_type': 'url'},
    ]
    supported_catalog_types: Annotated[
        list[catalog_type.CatalogType] | None,
        Field(description='Catalog types this product accepts.'),
    ] = None
    min_items: Annotated[
        SchemaInt | None, Field(description='Minimum catalog item count buyer must supply.', ge=1)
    ] = None
    max_items: Annotated[
        SchemaInt | None, Field(description='Maximum items considered for placement.')
    ] = None
    fanout_mode: Annotated[
        FanoutMode | None,
        Field(
            description='How items map to delivery: per_item = one ad per catalog item; multi_item_in_creative = composed multi-item ad (Pinterest Collection, Snap Collection); single_item = one ad showing one item.'
        ),
    ] = None
    required_catalog_fields: Annotated[
        list[str] | None,
        Field(
            description="Catalog item fields the seller requires (e.g., ['title', 'image_url', 'price'])."
        ),
    ] = None
    supported_id_types: Annotated[
        list[SupportedIdType] | None,
        Field(description='Catalog identifier types the placement renders against.'),
    ] = None
    hero_asset_supported: Annotated[
        StrictBool | None,
        Field(
            description='Whether the buyer can supply a hero/banner asset alongside the catalog (Pinterest Collection pattern).'
        ),
    ] = None
    item_production_model: Annotated[
        ItemProductionModel | None,
        Field(
            description='How each per-item creative is produced. Covers the same production-source axis as `asset_source` on `image` / `video_hosted` / `audio_hosted` but with a 4-value subset — drops `publisher_host_recorded` because it\'s audio-specific and doesn\'t apply to retail-media catalog placements. SDK codegen MAY share a base enum and narrow per-canonical, or emit two distinct enums; either way the wire values overlap exactly for the 4 retained values. `buyer_uploaded` (default, current Amazon/Criteo/CitrusAd pattern): the buyer\'s catalog already contains rendered assets per item; the seller composes the placement using those assets. ("Uploaded" reads slightly off for catalog-keyed items where the buyer didn\'t actively upload bytes — the catalog ingestion already supplied them — but the semantic is the same: rendered bytes are buyer-supplied, not seller-produced.) `seller_pre_rendered_from_brief`: the buyer ships a brief plus the catalog reference; the seller renders one creative per catalog item from the brief at sync_creatives time. `seller_human_designed`: seller\'s design team produces per-item renders manually. `agent_synthesized`: AI synthesis pipeline produces per-item renders; pair with `synthesis_nondeterministic: true` for Veo/Sora-class generative video applied per item. Captures the multi-output generative pattern (1 brief × N catalog items → N rendered creatives) under the existing canonical without requiring a separate canonical. Distinct from `fanout_mode`, which describes how items map to delivery slots after rendering.'
        ),
    ] = ItemProductionModel.buyer_uploaded
    ctv_ad_experience: Annotated[
        ctv_ad_experience_1.CtvAdExperience | None,
        Field(
            description='CTV experience this option serves. On `sponsored_placement`: `menu` (sponsored app/content tiles and rows whose assets derive from a catalog listing — Fire-TV-tile pattern), `squeezeback`, and `in_scene` (seller-composited brand integrations produced from the catalog/brief rather than a buyer wire creative). Asset-bundle menu heroes route to `native_in_feed`.'
        ),
    ] = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var ctv_ad_experience : CtvAdExperience | None

var experimental : typing.Any | None

var fanout_mode : FanoutMode | None

var hero_asset_supported : bool | None

var item_production_model : ItemProductionModel | None

var max_items : int | None

var min_items : int | None

var model_config

var required_catalog_fields : list[str] | None

var slots : typing.Any | None

var supported_catalog_types : list[CatalogType] | None

var supported_id_types : list[SupportedIdType] | None

var v1_translatable : typing.Any | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalFormatVastVideo (**data: Any)

Expand source code

class CanonicalFormatVastVideo(CanonicalFormatBase):
    model_config = ConfigDict(
        extra='allow',
    )
    slots: Annotated[
        Any | None,
        Field(
            description="Default slots for video_vast canonical. Buyer ships a VAST tag (URL or inline XML, VAST 2.x-4.x) plus an optional clickthrough URL (which falls back to the VAST `ClickThrough` element when omitted). Tracking events are inherent to VAST and don't require explicit slots."
        ),
    ] = [
        {'asset_group_id': 'vast_tag', 'asset_type': 'vast', 'required': True},
        {'asset_group_id': 'landing_page_url', 'asset_type': 'url', 'required': False},
    ]
    orientation: Orientation | None = None
    aspect_ratio: Annotated[
        str | None, Field(pattern='^[0-9]+(\\.[0-9]+)?:[0-9]+(\\.[0-9]+)?$')
    ] = None
    vast_versions: Annotated[
        list[vast_version_1.VastVersion] | None,
        Field(
            description='VAST versions accepted by this product format option. The asset still declares exactly one `vast_version`; compatibility requires membership in this set and the seller-wide execution set.',
            min_length=1,
        ),
    ] = None
    vast_version: Annotated[
        vast_version_1.VastVersion | None,
        Field(
            deprecated=True,
            description='Deprecated one-element alias for `vast_versions`. Producers use either the singular legacy alias or the plural 3.2 field, never both.',
        ),
    ] = None
    media_file_requirements: Annotated[
        vast_media_file_requirements.VastMediafileRequirements | None,
        Field(
            description='Technical acceptance constraints for alternative VAST MediaFile renditions. Each applicable resolved InLine linear creative needs at least one MediaFile satisfying all declared constraints.'
        ),
    ] = None
    vpaid_enabled: Annotated[
        StrictBool | None,
        Field(
            description='Whether VPAID interactivity is supported. When true, the VAST tag may carry VPAID JS/Flash payloads.'
        ),
    ] = None
    vpaid_version: VpaidVersion | None = None
    simid_supported: Annotated[
        StrictBool | None,
        Field(
            description='Whether the seller accepts IAB SIMID through `<InteractiveCreativeFile apiFramework="SIMID">` on a Linear VAST creative. SIMID is not a generic VAST extension and cannot be serialized under NonLinearAds; every `ctv_ad_experience` profile therefore forbids `true`.'
        ),
    ] = None
    duration_ms_range: Annotated[
        list[DurationMsRangeItem] | None,
        Field(
            description='[min, max] duration in milliseconds. **Precedence**: `duration_ms_exact` takes precedence when both ship. SDKs SHOULD lint a warning when both fields ship.',
            max_length=2,
            min_length=2,
        ),
    ] = None
    duration_ms_exact: Annotated[
        SchemaInt | None,
        Field(
            description='When set, duration must equal exactly this value. Takes precedence over `duration_ms_range` when both ship.',
            ge=1,
        ),
    ] = None
    min_width: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum placement/player width in pixels. MediaFile rendition dimensions are declared in `media_file_requirements`.',
            ge=1,
        ),
    ] = None
    max_width: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum placement/player width in pixels. MediaFile rendition dimensions are declared in `media_file_requirements`.',
            ge=1,
        ),
    ] = None
    min_height: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum placement/player height in pixels. MediaFile rendition dimensions are declared in `media_file_requirements`.',
            ge=1,
        ),
    ] = None
    max_height: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum placement/player height in pixels. MediaFile rendition dimensions are declared in `media_file_requirements`.',
            ge=1,
        ),
    ] = None
    creative_type: Annotated[
        CreativeType | None,
        Field(
            description='Required VAST creative class: `linear` (in-stream Linear), `nonlinear` (NonLinearAds overlay-class), or `either`. Supersedes `linear_required`; when both are present `creative_type` wins, and validators treat `linear_required: true` with no `creative_type` as `linear`.'
        ),
    ] = None
    ctv_ad_experience: Annotated[
        ctv_ad_experience_1.CtvAdExperience | None,
        Field(
            description='CTV experience this option is eligible to serve. On video_vast only `pause`, `screensaver`, `overlay`, `squeezeback`, and `in_scene` are valid (`menu` routes to native_in_feed or sponsored_placement), and `creative_type` MUST be `nonlinear`. Because VAST places `<InteractiveCreativeFile>` only under Linear `<MediaFiles>`, `simid_supported` MUST NOT be true on any of these NonLinear profiles. Per-experience floors: `overlay` and `squeezeback` require a 10s minimum duration; `in_scene` requires a 3s minimum brand-exposure duration and forbids interactivity (`vpaid_enabled` MUST NOT be true); `pause` has no duration floor and ends on viewer or device action.'
        ),
    ] = None
    motion_level: Annotated[
        motion_level_1.CreativeMotionLevel | None,
        Field(description='Accepted motion class for the rendered creative (AdCOM attrs 21-23).'),
    ] = None
    activation_methods: Annotated[
        list[activation_method.CreativeActivationMethod] | None,
        Field(
            description='Viewer activation mechanisms this option offers. Activations are engagement events, not impressions.'
        ),
    ] = None
    linear_required: Annotated[
        StrictBool | None,
        Field(
            description='Whether the VAST creative must be linear (non-skippable in-stream). Superseded by `creative_type`; retained for pre-3.2 declarations.'
        ),
    ] = None
    skippable_after_ms: Annotated[
        SchemaInt | None,
        Field(
            description='When skippable, the buyer-side skip threshold in milliseconds (e.g., 5000 for 5-second skippable pre-roll).',
            ge=0,
        ),
    ] = None
    max_wrapper_depth: Annotated[
        SchemaInt | None, Field(description='Maximum VAST wrapper redirect depth permitted.', ge=0)
    ] = None
    ssl_required: StrictBool | None = 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

• adcp.types.domains.formats.canonical._base.CanonicalFormatBase
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var activation_methods : list[CreativeActivationMethod] | None

var aspect_ratio : str | None

var creative_type : CreativeType | None

var ctv_ad_experience : CtvAdExperience | None

var duration_ms_exact : int | None

var duration_ms_range : list[DurationMsRangeItem] | None

var linear_required : bool | None

var max_height : int | None

var max_width : int | None

var max_wrapper_depth : int | None

var media_file_requirements : VastMediafileRequirements | None

var min_height : int | None

var min_width : int | None

var model_config

var motion_level : CreativeMotionLevel | None

var orientation : Orientation | None

var simid_supported : bool | None

var skippable_after_ms : int | None

var slots : typing.Any | None

var ssl_required : bool | None

var vast_version : VastVersion | None

var vast_versions : list[VastVersion] | None

var vpaid_enabled : bool | None

var vpaid_version : VpaidVersion | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalMediaBuyActionMode (*args, **kwds)

Expand source code

class CanonicalMediaBuyActionMode(StrEnum):
    self_serve = 'self_serve'
    conditional_self_serve = 'conditional_self_serve'
    seller_managed = 'seller_managed'
    requires_approval = 'requires_approval'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var conditional_self_serve

var requires_approval

var self_serve

var seller_managed

class CanonicalMediaBuyActionName (*args, **kwds)

Expand source code

class CanonicalMediaBuyActionName(StrEnum):
    pause = 'pause'
    resume = 'resume'
    cancel = 'cancel'
    extend_flight = 'extend_flight'
    shorten_flight = 'shorten_flight'
    update_flight_dates = 'update_flight_dates'
    increase_budget = 'increase_budget'
    decrease_budget = 'decrease_budget'
    reallocate_budget = 'reallocate_budget'
    update_budget_allocation = 'update_budget_allocation'
    update_targeting = 'update_targeting'
    update_pacing = 'update_pacing'
    update_bidding = 'update_bidding'
    update_frequency_caps = 'update_frequency_caps'
    update_media_buy_frequency_cap = 'update_media_buy_frequency_cap'
    update_catalog_assignments = 'update_catalog_assignments'
    update_keywords = 'update_keywords'
    update_optimization_goals = 'update_optimization_goals'
    update_impression_goal = 'update_impression_goal'
    update_spend_target = 'update_spend_target'
    update_reporting_webhook = 'update_reporting_webhook'
    replace_creative = 'replace_creative'
    update_creative_assignments = 'update_creative_assignments'
    remove_creative = 'remove_creative'
    add_packages = 'add_packages'
    remove_packages = 'remove_packages'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var add_packages

var cancel

var decrease_budget

var extend_flight

var increase_budget

var pause

var reallocate_budget

var remove_creative

var remove_packages

var replace_creative

var resume

var shorten_flight

var update_bidding

var update_budget_allocation

var update_catalog_assignments

var update_creative_assignments

var update_flight_dates

var update_frequency_caps

var update_impression_goal

var update_keywords

var update_media_buy_frequency_cap

var update_optimization_goals

var update_pacing

var update_reporting_webhook

var update_spend_target

var update_targeting

class CanonicalProductAction (**data: Any)

Expand source code

class CanonicalProductAction(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    action: canonical_media_buy_action.CanonicalMediaBuyActionName
    modes: Annotated[
        list[canonical_media_buy_action_mode.CanonicalMediaBuyActionMode], Field(min_length=1)
    ]
    allowed_statuses: Annotated[
        list[media_buy_status.MediaBuyStatus] | None, Field(min_length=1)
    ] = None
    sla: sla_window.SlaWindow | None = None
    constraints: Annotated[
        change_term_constraints.MediaBuyChangeTermConstraints | None,
        Field(
            description='Advisory machine-readable bounds for product selection; proposal change terms restate binding bounds.'
        ),
    ] = None
    terms_ref: Annotated[
        str | None,
        Field(
            description='Optional advisory pointer to published commercial terms. It is not a proposal change-term identity.'
        ),
    ] = 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

Class variables

var action : CanonicalMediaBuyActionName

var allowed_statuses : list[MediaBuyStatus] | None

var constraints : MediaBuyChangeTermConstraints1 | MediaBuyChangeTermConstraints2 | MediaBuyChangeTermConstraints3 | MediaBuyChangeTermConstraints4 | None

var model_config

var modes : list[CanonicalMediaBuyActionMode]

var sla : SlaWindow | None

var terms_ref : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalProjectionReference (**data: Any)

Expand source code

class CanonicalProjectionReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    kind: Annotated[
        str,
        Field(
            description='The v2 canonical-format-kind this v1 format projects to (`image`, `html5`, `display_tag`, `image_carousel`, `video_hosted`, `video_vast`, `audio_hosted`, `audio_vast`, `audio_daast`, `sponsored_placement`, `native_in_feed`, `responsive_creative`, `agent_placement`, `seller_rendered_stateful_display`, `coordinated_placements`, or `custom`).'
        ),
    ]
    asset_source: Annotated[
        AssetSource | None,
        Field(
            description="Where the rendered asset bytes come from on the projected v2 declaration. Default (when omitted) is `buyer_uploaded` — the canonical's default. Set explicitly when the v1 named format doesn't follow that default. Required for generative entries (`agent_synthesized` or `seller_pre_rendered_from_brief`) because their asset shape doesn't carry image/video/audio bytes, and for published-post reference entries (`publisher_owned_reference`) because their asset shape carries a post reference rather than uploaded bytes. Projection without this hint produces a lossy v2 declaration that claims buyer-uploaded bytes."
        ),
    ] = None
    slots_override: Annotated[
        list[canonical_projection_slot_override.CanonicalProjectionSlotOverride] | None,
        Field(
            description="When the v1 named format's slot shape differs from the canonical's default slots, this carries the override that the projected v2 declaration's `params.slots[]` should use. REPLACES (does not merge with) the canonical's default slots — projection-time semantics. The slot vocabulary follows `asset-group-vocabulary.json`. Asset IDs in the v1 format's `assets[*]` MUST resolve (directly or via the vocabulary's aliases) to the `asset_group_id` values declared here.",
            min_length=1,
        ),
    ] = 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

Class variables

var asset_source : AssetSource | None

var kind : str

var model_config

var slots_override : list[CanonicalProjectionSlotOverride] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalSlotOverride (**data: Any)

Expand source code

class CanonicalProjectionSlotOverride(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_group_id: Annotated[
        str,
        Field(
            description='Asset group identifier from `asset-group-vocabulary.json` (e.g., `generation_prompt`, `creative_brief`, `image_main`, `video_main`).'
        ),
    ]
    asset_type: Annotated[
        str,
        Field(
            description='Asset type — `image`, `video`, `audio`, `text`, `html`, `javascript`, `url`, `zip`, `brief`, `catalog`, `published_post`, or another canonical slot asset type.'
        ),
    ]
    required: Annotated[
        StrictBool | None,
        Field(description='Whether the slot is required in the projected declaration.'),
    ] = False
    max_chars: Annotated[
        SchemaInt | None, Field(description='Max character count for text slots.', ge=1)
    ] = None
    consumed_for_production: Annotated[
        StrictBool | None,
        Field(
            description="When false, slot is for moderation/review only and is NOT consumed by the seller's renderer (e.g., a brand-safety brief that informs review but doesn't appear in the rendered ad)."
        ),
    ] = True

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

Class variables

var asset_group_id : str

var asset_type : str

var consumed_for_production : bool | None

var max_chars : int | None

var model_config

var required : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CardAsset (**data: Any)

Expand source code

class CardAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['card'],
        Field(
            description='Discriminator identifying this as a card asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'card'
    media: Annotated[
        asset_union.ImageAsset | asset_union.VideoAsset,
        Field(
            description="The card's primary visual asset. Either an `image` or `video` asset, matching the parent format's `allowed_card_media_asset_types` parameter.",
            discriminator='asset_type',
        ),
    ]
    headline: Annotated[
        str | None,
        Field(
            description='Optional per-card short text label (typically 25-40 chars). Length governed by `card_headline_max_chars` on the format declaration. Meta carousel headline, Pinterest pin title, Snap Collection sticker text, TikTok caption-short.'
        ),
    ] = None
    description: Annotated[
        str | None,
        Field(
            description='Optional per-card longer text (typically 100-500 chars). Distinct from `headline`: `description` is body copy, `headline` is the label. Length governed by `card_description_max_chars` on the format declaration. Meta carousel description, Pinterest pin description, AI-surface result body text, TikTok long caption.'
        ),
    ] = None
    cta: Annotated[
        str | None,
        Field(
            description="Optional per-card call-to-action label (e.g., 'SHOP_NOW', 'LEARN_MORE'). When the parent format declares `cta_values` (allowed CTA labels), the per-card `cta` MUST be one of those values. Lets a Meta or TikTok carousel show different CTAs per card."
        ),
    ] = None
    landing_page_url: Annotated[
        asset_union.UrlAsset | None,
        Field(
            description='Optional per-card click-through URL. URL asset with `url_type: "clickthrough"`.'
        ),
    ] = None
    platform_extensions: Annotated[
        list[asset_union.PlatformExtensionRef] | None,
        Field(
            description='Per-card platform-specific extensions (URI+digest references). Same hosting model as format-level platform_extensions. Use this for Meta carousel-card attributes, Pinterest pin overrides, etc. — NEVER inline non-canonical keys on the card object directly.'
        ),
    ] = None
    provenance: Annotated[
        asset_union.Provenance | None,
        Field(
            description='Provenance metadata for this card, overrides manifest-level provenance.'
        ),
    ] = 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

Class variables

var asset_type : Literal['card']

var cta : str | None

var description : str | None

var headline : str | None

var landing_page_url : UrlAsset | None

var media : ImageAsset | VideoAsset

var model_config

var platform_extensions : list[PlatformExtensionRef] | None

var provenance : Provenance | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Catalog (**data: Any)

Expand source code

class Catalog(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catalog_id: Annotated[
        str | None,
        Field(
            description="Buyer's identifier for this catalog. Required when syncing via sync_catalogs. When used in creatives, references a previously synced catalog on the account."
        ),
    ] = None
    name: Annotated[
        str | None,
        Field(
            description="Human-readable name for this catalog (e.g., 'Summer Products 2025', 'Amsterdam Store Locations')."
        ),
    ] = None
    type: Annotated[
        catalog_type.CatalogType,
        Field(
            description="Catalog type. Structural types: 'offering' (AdCP Offering objects), 'product' (ecommerce entries), 'inventory' (stock per location), 'store' (physical locations), 'promotion' (deals and pricing). Vertical types: 'hotel', 'flight', 'job', 'vehicle', 'real_estate', 'education', 'destination', 'app' — each with an industry-specific item schema."
        ),
    ]
    url: Annotated[
        AnyUrl | None,
        Field(
            description="URL to an external catalog feed. The platform fetches and resolves items from this URL. For offering-type catalogs, the feed contains an array of Offering objects. For other types, the feed format is determined by feed_format. When omitted with type 'product', the platform uses its synced copy of the brand's product catalog."
        ),
    ] = None
    feed_format: Annotated[
        feed_format_1.FeedFormat | None,
        Field(
            description='Format of the external feed at url. Required when url points to a non-AdCP feed (e.g., Google Merchant Center XML, Meta Product Catalog). Omit for offering-type catalogs where the feed is native AdCP JSON.'
        ),
    ] = None
    update_frequency: Annotated[
        update_frequency_1.UpdateFrequency | None,
        Field(
            description='How often the platform should re-fetch the feed from url. Only applicable when url is provided. Platforms may use this as a hint for polling schedules.'
        ),
    ] = None
    items: Annotated[
        list[dict[str, Any]] | None,
        Field(
            description="Inline catalog data. The item schema depends on the catalog type: Offering objects for 'offering', StoreItem for 'store', HotelItem for 'hotel', FlightItem for 'flight', JobItem for 'job', VehicleItem for 'vehicle', RealEstateItem for 'real_estate', EducationItem for 'education', DestinationItem for 'destination', AppItem for 'app', or freeform objects for 'product', 'inventory', and 'promotion'. Mutually exclusive with url — provide one or the other, not both. Implementations should validate items against the type-specific schema.",
            min_length=1,
        ),
    ] = None
    ids: Annotated[
        list[str] | None,
        Field(
            description='Filter catalog to exact canonical item keys. The key field is offering_id for offering, store_id for store, hotel_id for hotel, flight_id for flight, job_id for job, vehicle_id for vehicle, listing_id for real_estate, program_id for education, destination_id for destination, and app_id for app. Product, inventory, and promotion catalogs use the stable normalized source identifier retained during ingestion (for example a retailer SKU). The same canonical key is used by catalog availability item_id.',
            min_length=1,
        ),
    ] = None
    gtins: Annotated[
        list[Gtin] | None,
        Field(
            description="Filter product-type catalogs by GTIN identifiers for cross-retailer catalog matching. Accepts standard GTIN formats (GTIN-8, UPC-A/GTIN-12, EAN-13/GTIN-13, GTIN-14). Only applicable when type is 'product'.",
            min_length=1,
        ),
    ] = None
    tags: Annotated[
        list[str] | None,
        Field(
            description='Filter catalog to items with these tags. Tags are matched using OR logic — items matching any tag are included.',
            min_length=1,
        ),
    ] = None
    category: Annotated[
        str | None,
        Field(
            description="Filter catalog to items in this category (e.g., 'beverages/soft-drinks', 'chef-positions')."
        ),
    ] = None
    query: Annotated[
        str | None,
        Field(
            description="Natural language filter for catalog items (e.g., 'all pasta sauces under $5', 'amsterdam vacancies')."
        ),
    ] = None
    conversion_events: Annotated[
        list[event_type.EventType] | None,
        Field(
            description="Event types that represent conversions for items in this catalog. Declares what events the platform should attribute to catalog items — e.g., a job catalog converts via submit_application, a product catalog via purchase. The event's content_ids field carries the item IDs that connect back to catalog items. Use content_id_type to declare what identifier type content_ids values represent.",
            min_length=1,
        ),
    ] = None
    content_id_type: Annotated[
        content_id_type_1.ContentIdType | None,
        Field(
            description="Identifier type that the event's content_ids field should be matched against for items in this catalog. For example, 'gtin' means content_ids values are Global Trade Item Numbers, 'sku' means retailer SKUs. Omit when using a custom identifier scheme not listed in the enum."
        ),
    ] = None
    feed_field_mappings: Annotated[
        list[catalog_field_mapping.CatalogFieldMapping] | None,
        Field(
            description='Declarative normalization rules for external feeds. Maps non-standard feed field names, date formats, price encodings, and image URLs to the AdCP catalog item schema. Applied during sync_catalogs ingestion. Supports field renames, named transforms (date, divide, boolean, split), static literal injection, and assignment of image URLs to typed asset pools.',
            min_length=1,
        ),
    ] = 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

• CatalogAsset

Class variables

var catalog_id : str | None

var category : str | None

var content_id_type : ContentIdType | None

var conversion_events : list[EventType] | None

var feed_field_mappings : list[CatalogFieldMapping] | None

var feed_format : FeedFormat | None

var gtins : list[Gtin] | None

var ids : list[str] | None

var items : list[dict[str, typing.Any]] | None

var model_config

var name : str | None

var query : str | None

var tags : list[str] | None

var type : CatalogType

var update_frequency : UpdateFrequency | None

var url : pydantic.networks.AnyUrl | None

class SyncCatalogResult (**data: Any)

Expand source code

class Catalog(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    catalog_id: str
    catalog_generation: Annotated[str, StringConstraints(min_length=1, max_length=255)] | None = None
    action: catalog_action_1.CatalogAction
    platform_id: str | None = None
    item_count: Annotated[int, Field(ge=0)] | None = None
    items_approved: Annotated[int, Field(ge=0)] | None = None
    items_pending: Annotated[int, Field(ge=0)] | None = None
    items_rejected: Annotated[int, Field(ge=0)] | None = None
    item_issues: list[ItemIssue] | None = None
    last_synced_at: AwareDatetime | None = None
    next_fetch_at: AwareDatetime | None = None
    changes: list[str] | None = None
    errors: list[error_1.Error] | None = None
    warnings: list[str] | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var action : CatalogAction

var catalog_generation : str | None

var catalog_id : str

var changes : list[str] | None

var errors : list[Error] | None

var item_count : int | None

var item_issues : list[ItemIssue] | None

var items_approved : int | None

var items_pending : int | None

var items_rejected : int | None

var last_synced_at : pydantic.types.AwareDatetime | None

var model_config

var next_fetch_at : pydantic.types.AwareDatetime | None

var platform_id : str | None

var warnings : list[str] | None

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class CatalogAction (*args, **kwds)

Expand source code

class CatalogAction(StrEnum):
    created = 'created'
    updated = 'updated'
    unchanged = 'unchanged'
    failed = 'failed'
    deleted = 'deleted'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var created

var deleted

var failed

var unchanged

var updated

class CatalogAsset (**data: Any)

Expand source code

class CatalogAsset(Catalog):
    asset_type: Annotated[
        Literal['catalog'],
        Field(
            description='Discriminator identifying this as a catalog asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'catalog'

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

• Catalog
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : Literal['catalog']

var model_config

Inherited members

• Catalog:
  • model_dump
  • model_dump_json
  • model_summary

class CatalogFieldBinding1 (**data: Any)

Expand source code

class CatalogFieldBinding1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    kind: Literal['catalog_group'] = 'catalog_group'
    format_group_id: Annotated[
        str,
        Field(description="The asset_group_id of a repeatable_group in the format's assets array."),
    ]
    catalog_item: Annotated[
        Literal[True],
        Field(
            description="Each repetition of the format's repeatable_group maps to one item from the catalog."
        ),
    ]
    per_item_bindings: Annotated[
        list[PerItemBindings] | None,
        Field(
            description='Scalar and asset pool bindings that apply within each repetition of the group. Nested catalog_group bindings are not permitted.',
            min_length=1,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var catalog_item : Literal[True]

var ext : ExtensionObject | None

var format_group_id : str

var kind : Literal['catalog_group']

var model_config

var per_item_bindings : list[ScalarBinding | AssetPoolBinding] | None

class CatalogGroupBinding (**data: Any)

Expand source code

class CatalogFieldBinding1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    kind: Literal['catalog_group'] = 'catalog_group'
    format_group_id: Annotated[
        str,
        Field(description="The asset_group_id of a repeatable_group in the format's assets array."),
    ]
    catalog_item: Annotated[
        Literal[True],
        Field(
            description="Each repetition of the format's repeatable_group maps to one item from the catalog."
        ),
    ]
    per_item_bindings: Annotated[
        list[PerItemBindings] | None,
        Field(
            description='Scalar and asset pool bindings that apply within each repetition of the group. Nested catalog_group bindings are not permitted.',
            min_length=1,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var catalog_item : Literal[True]

var ext : ExtensionObject | None

var format_group_id : str

var kind : Literal['catalog_group']

var model_config

var per_item_bindings : list[ScalarBinding | AssetPoolBinding] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CatalogFieldMapping (**data: Any)

Expand source code

class CatalogFieldMapping(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    feed_field: Annotated[
        str | None,
        Field(
            description='Field name in the external feed record. Omit when injecting a static literal value (use the value property instead).'
        ),
    ] = None
    catalog_field: Annotated[
        str | None,
        Field(
            description="Target field on the catalog item schema, using dot notation for nested fields (e.g., 'name', 'price.amount', 'location.city'). Mutually exclusive with asset_group_id."
        ),
    ] = None
    asset_group_id: Annotated[
        str | None,
        Field(
            description="Places the feed field value (a URL) into a typed asset pool on the catalog item's assets array. The value is wrapped as an image or video asset in a group with this ID. Use standard group IDs: 'images_landscape', 'images_vertical', 'images_square', 'logo', 'video'. Mutually exclusive with catalog_field."
        ),
    ] = None
    value: Annotated[
        Any | None,
        Field(
            description='Static literal value to inject into catalog_field for every item, regardless of what the feed contains. Mutually exclusive with feed_field. Useful for fields the feed omits (e.g., currency when price is always USD, or a constant category value).'
        ),
    ] = None
    transform: Annotated[
        Transform | None,
        Field(
            description='Named transform to apply to the feed field value before writing to the catalog schema. See transform-specific parameters (format, timezone, by, separator).'
        ),
    ] = None
    format: Annotated[
        str | None,
        Field(
            description="For transform 'date': the input date format string (e.g., 'YYYYMMDD', 'MM/DD/YYYY', 'DD-MM-YYYY'). Output is always ISO 8601 (e.g., '2025-03-01'). Uses Unicode date pattern tokens."
        ),
    ] = None
    timezone: Annotated[
        str | None,
        Field(
            description="For transform 'date': the timezone of the input value. IANA timezone identifier (e.g., 'UTC', 'America/New_York', 'Europe/Amsterdam'). Defaults to UTC when omitted."
        ),
    ] = None
    by: Annotated[
        StrictFloat | None,
        Field(
            description="For transform 'divide': the divisor to apply (e.g., 100 to convert integer cents to decimal dollars).",
            gt=0.0,
        ),
    ] = None
    separator: Annotated[
        str | None,
        Field(
            description="For transform 'split': the separator character or string to split on. Defaults to ','."
        ),
    ] = ','
    default: Annotated[
        Any | None,
        Field(
            description='Fallback value to use when feed_field is absent, null, or empty. Applied after any transform would have been applied. Allows optional feed fields to have a guaranteed baseline value.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var asset_group_id : str | None

var by : float | None

var catalog_field : str | None

var default : typing.Any | None

var ext : ExtensionObject | None

var feed_field : str | None

var format : str | None

var model_config

var separator : str | None

var timezone : str | None

var transform : Transform | None

var value : typing.Any | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ByCatalogItemItem (**data: Any)

Expand source code

class CatalogItemDeliveryMetrics(DeliveryMetrics):
    content_id: Annotated[
        str, Field(description='Catalog item identifier (e.g., SKU, GTIN, job_id, offering_id)')
    ]
    content_id_type: Annotated[
        content_id_type_1.ContentIdType | None,
        Field(description='Identifier type for this content_id'),
    ] = None
    impressions: Any
    spend: Any

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

• DeliveryMetrics
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var content_id : str

var content_id_type : ContentIdType | None

var impressions : Any

var model_config

var spend : Any

Inherited members

• DeliveryMetrics:
  • model_dump
  • model_dump_json
  • model_summary

class CatalogItemStatus (*args, **kwds)

Expand source code

class CatalogItemStatus(StrEnum):
    approved = 'approved'
    pending = 'pending'
    rejected = 'rejected'
    warning = 'warning'
    withdrawn = 'withdrawn'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var approved

var pending

var rejected

var warning

var withdrawn

class CatalogRequirements (**data: Any)

Expand source code

class CatalogRequirements(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catalog_type: Annotated[
        catalog_type_1.CatalogType,
        Field(description='The catalog type this requirement applies to'),
    ]
    required: Annotated[
        StrictBool | None,
        Field(
            description='Whether this catalog type must be present. When true, creatives using this format must reference a synced catalog of this type.'
        ),
    ] = True
    min_items: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum number of items the catalog must contain for this format to render properly (e.g., a carousel might require at least 3 products)',
            ge=1,
        ),
    ] = None
    max_items: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of items the format can render. Items beyond this limit are ignored. Useful for fixed-slot layouts (e.g., a 3-product card) or feed-size constraints.',
            ge=1,
        ),
    ] = None
    required_fields: Annotated[
        list[str] | None,
        Field(
            description="Fields that must be present and non-empty on every item in the catalog. Field names are catalog-type-specific (e.g., 'title', 'price', 'image_url' for product catalogs; 'store_id', 'quantity' for inventory feeds).",
            min_length=1,
        ),
    ] = None
    feed_formats: Annotated[
        list[feed_format.FeedFormat] | None,
        Field(
            description='Accepted feed formats for this catalog type. When specified, the synced catalog must use one of these formats. When omitted, any format is accepted.',
            min_length=1,
        ),
    ] = None
    offering_asset_constraints: Annotated[
        list[offering_asset_constraint.OfferingAssetConstraint] | None,
        Field(
            description="Per-item creative asset requirements. Declares what asset groups (headlines, images, videos) each catalog item must provide in its assets array, along with count bounds and per-asset technical constraints. Applicable to 'offering' and all vertical catalog types (hotel, flight, job, etc.) whose items carry typed assets.",
            min_length=1,
        ),
    ] = None
    field_bindings: Annotated[
        list[catalog_field_binding.CatalogFieldBinding] | None,
        Field(
            description='Explicit mappings from format template slots to catalog item fields or typed asset pools. Optional — creative agents can infer mappings without them, but bindings make the relationship self-describing and enable validation. Covers scalar fields (asset_id → catalog_field), asset pools (asset_id → asset_group_id on the catalog item), and repeatable groups that iterate over catalog items.',
            min_length=1,
        ),
    ] = 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

Class variables

var catalog_type : CatalogType

var feed_formats : list[FeedFormat] | None

var field_bindings : list[ScalarBinding | AssetPoolBinding | CatalogFieldBinding1] | None

var max_items : int | None

var min_items : int | None

var model_config

var offering_asset_constraints : list[OfferingAssetConstraint] | None

var required : bool | None

var required_fields : list[str] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CatalogType (*args, **kwds)

Expand source code

class CatalogType(StrEnum):
    offering = 'offering'
    product = 'product'
    inventory = 'inventory'
    store = 'store'
    promotion = 'promotion'
    hotel = 'hotel'
    flight = 'flight'
    job = 'job'
    vehicle = 'vehicle'
    real_estate = 'real_estate'
    education = 'education'
    destination = 'destination'
    app = 'app'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var app

var destination

var education

var flight

var hotel

var inventory

var job

var offering

var product

var promotion

var real_estate

var store

var vehicle

class CheckGovernanceRequest (**data: Any)

Expand source code

class CheckGovernanceRequest(AdcpRequest, CheckGovernanceRequest3):
    'Universal governance check for campaign actions. The governance agent infers the check type from the fields present: tool+payload = intent check (proposed, orchestrator-side); planned_delivery or delivery_metrics with governance_context = execution or lifecycle check (committed, service-side). Proposal acceptance supplies the immutable proposal separately so governance can inspect its typed commercial terms while payload remains the exact downstream arguments. MediaBuy controls use buyer-proposed and seller-computed positive-delta ceilings. The first check is addressed by plan_id. Subsequent service-side checks use the opaque governance_context as the authoritative plan binding.'

Universal governance check for campaign actions. The governance agent infers the check type from the fields present: tool+payload = intent check (proposed, orchestrator-side); planned_delivery or delivery_metrics with governance_context = execution or lifecycle check (committed, service-side). Proposal acceptance supplies the immutable proposal separately so governance can inspect its typed commercial terms while payload remains the exact downstream arguments. MediaBuy controls use buyer-proposed and seller-computed positive-delta ceilings. The first check is addressed by plan_id. Subsequent service-side checks use the opaque governance_context as the authoritative plan binding.

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
• CheckGovernanceRequest3
• CheckGovernanceRequest1
• CheckGovernanceRequest2
• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

Inherited members

• AdcpRequest:
  • get_account
  • get_adcp_major_version
  • get_adcp_version
  • get_context
  • get_idempotency_key
  • get_push_notification_config
• CheckGovernanceRequest3:
  • model_dump
  • model_dump_json
  • model_summary

class CheckGovernanceResponse (**data: Any)

Expand source code

class CheckGovernanceResponse(AdcpResponse, AdcpVersionEnvelope):
    @model_validator(mode='before')
    @classmethod
    def _status_to_verdict(cls, data: Any) -> Any:
        if isinstance(data, dict) and 'verdict' not in data and 'status' in data:
            data = dict(data)
            data['verdict'] = data['status']
        return data

    model_config = ConfigDict(
        extra='allow',
    )
    check_id: Annotated[
        str,
        Field(
            description='Unique identifier for this governance check record. Use in report_plan_outcome to link outcomes to the check that authorized them.'
        ),
    ]
    verdict: Annotated[
        governance_decision.GovernanceDecision,
        Field(
            description='Governance verdict: approved | denied | conditions. Renamed from `status` in 3.1 to free the top-level `status` key for the envelope task-status (TaskStatus) under MCP flat-on-the-wire serialization. The enum values are unchanged; only the property name moved.'
        ),
    ]
    check_type: Annotated[
        CheckType | None,
        Field(
            description='Check shape that produced the verdict. Required for the cross-role governance_enforcement contract. Its presence selects the modern verdict-specific response rules; its absence selects the deprecated legacy 3.x compatibility shape. Intent checks may return conditions; execution checks are binary approved or denied.'
        ),
    ] = None
    plan_id: Annotated[
        str | None,
        Field(
            description='Plan identifier echoed on an initial plan-addressed check. Optional on continuation checks addressed by governance_context; services do not need this value and MUST treat the token binding as authoritative.'
        ),
    ] = None
    explanation: Annotated[
        str, Field(description='Human-readable explanation of the governance decision.')
    ]
    findings: Annotated[
        list[Finding] | None,
        Field(
            description="Specific issues found during the governance check. Present when verdict is 'denied' or 'conditions'. MAY also be present on 'approved' for informational findings (e.g., budget approaching limit)."
        ),
    ] = None
    conditions: Annotated[
        list[Condition] | None,
        Field(
            description="Intent-phase counterproposal. Present only when verdict is 'conditions'. It does not authorize execution and MUST NOT be returned for execution or lifecycle checks. Each field path is rooted at the complete check_governance request arguments, so both payload.* and proposed_commitment.* can be addressed. After applying conditions, the caller MUST re-call check_governance with the adjusted parameters and receive approved before proceeding."
        ),
    ] = None
    consultation_context: Annotated[
        str | None,
        Field(
            description='Opaque negotiation handle present only with modern conditions responses. It carries no authorization and MUST NOT be sent to a downstream service. The governance agent MUST bind it server-side to the authenticated principal, caller, plan, tool, purchase type, and target audience, and reject a re-check if any binding changes. The buyer returns it only on the adjusted intent re-check.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]+$',
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description="When this approval expires. In the cross-role shape, present only when verdict is 'approved'. Deprecated legacy conditions responses may also carry it for 3.x compatibility. The caller must act before this time or re-call check_governance. A lapsed approval is no approval."
        ),
    ] = None
    next_check: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller should next call check_governance with delivery metrics. Present when the governance agent expects ongoing delivery reporting.'
        ),
    ] = None
    delivery_statement: Annotated[
        DeliveryStatement | None,
        Field(
            description='Canonical seller-attributed delivery statement retained by governance. Present on delivery execution checks. The buyer binds any later observation to this exact statement through report_plan_outcome.'
        ),
    ] = None
    categories_evaluated: Annotated[
        list[str] | None,
        Field(
            description="Governance categories evaluated during this check. Each value is an **agent-internal** label (e.g., `budget_authority`, `regulatory_compliance`, or any internal-reviewer key the agent's policy model defines) — not a protocol-level enum. Since one governance agent per account composes all specialist review behind its single endpoint, `categories_evaluated` is how that internal decomposition surfaces to auditors. Consumers MUST treat values as opaque labels for display and audit, not as a machine-level contract."
        ),
    ] = None
    policies_evaluated: Annotated[
        list[str] | None,
        Field(
            description="Policy IDs evaluated during this check. Includes registry policy IDs (resolved via the policy registry) and any inline `policy_id`s declared in the plan's `custom_policies`."
        ),
    ] = None
    mode: Annotated[
        governance_mode.GovernanceMode | None,
        Field(
            description='Governance enforcement mode active when this check was evaluated. Allows counterparties, regulators, and auditors to distinguish whether a finding blocked execution (enforce) or was logged silently (audit).'
        ),
    ] = None
    runtime_attestation_evaluations: Annotated[
        list[RuntimeAttestationEvaluation] | None,
        Field(
            description="Evaluator-of-record results for request runtime_attestations[], in the same order and with exactly one result per presentation. Each result is the shared AttestationEvaluation and MUST bind to this response's check_id through action_binding.action_type = https://adcontextprotocol.org/actions/governance-check and action_binding.action_id = check_id. The signed governance_context MUST bind the same reference_digest/outcome pairs; large evidence stays in the audit log rather than the token.",
            max_length=10,
            min_length=1,
        ),
    ] = None
    runtime_attestation_binding_digest: Annotated[
        str | None,
        Field(
            description='SHA-256 of RFC 8785 JCS({ evaluations: runtime_attestation_evaluations, findings: attestation_bound_findings }), where attestation_bound_findings is the response findings[] subset carrying attestation_reference_digest, preserved in response order. Required whenever runtime_attestation_evaluations is present. The governance_context JWS carries this exact value as runtime_attestation_binding_digest; get_plan_audit_logs retains ordered {reference, evaluation} pairs so auditors can first recompute every reference_digest and then prove which evaluations and findings the signed decision relied on.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque authorization context for this governed action. Present only when verdict is approved; denied and conditions responses MUST NOT carry it. The buyer attaches it to the protocol envelope when sending the governed request. The service persists and forwards it on subsequent execution and lifecycle checks without requiring plan_id.\n\nGovernance agents MUST emit a compact JWS per the AdCP JWS profile. Verifiers validate the standard authorization claims but MUST NOT interpret embedded governance state for business logic. The issuing governance agent uses the token to recover its internal plan and decision state.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = 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.

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
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var categories_evaluated : list[str] | None

var check_id : str

var check_type : CheckType | None

var conditions : list[Condition] | None

var consultation_context : str | None

var context : ContextObject | None

var delivery_statement : DeliveryStatement | None

var expires_at : pydantic.types.AwareDatetime | None

var explanation : str

var ext : ExtensionObject | None

var findings : list[Finding] | None

var governance_context : str | None

var mode : GovernanceMode | None

var model_config

var next_check : pydantic.types.AwareDatetime | None

var plan_id : str | None

var policies_evaluated : list[str] | None

var runtime_attestation_binding_digest : str | None

var runtime_attestation_evaluations : list[RuntimeAttestationEvaluation] | None

var verdict : GovernanceDecision

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 CoBrandingRequirement (*args, **kwds)

Expand source code

class CoBrandingRequirement(StrEnum):
    required = 'required'
    optional = 'optional'
    none = 'none'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var none

var optional

var required

class CoBranding (*args, **kwds)

Expand source code

class CoBrandingRequirement(StrEnum):
    required = 'required'
    optional = 'optional'
    none = 'none'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var none

var optional

var required

class CollectionList (**data: Any)

Expand source code

class CollectionList(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list_id: Annotated[str, Field(description='Unique identifier for this collection list')]
    name: Annotated[str, Field(description='Human-readable name for the list')]
    description: Annotated[str | None, Field(description="Description of the list's purpose")] = (
        None
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns this list. Returned as account_id form (seller-assigned identifier).'
        ),
    ] = None
    base_collections: Annotated[
        list[base_collection_source.BaseCollectionSource] | None,
        Field(
            description="Array of collection sources to evaluate. Each entry is a discriminated union: distribution_ids (platform-independent identifiers), publisher_collections (publisher_domain + collection_ids), or publisher_genres (publisher_domain + genres). If omitted, queries the agent's entire collection database."
        ),
    ] = None
    filters: Annotated[
        collection_list_filters.CollectionListFilters | None,
        Field(description='Dynamic filters applied when resolving the list'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand reference used to automatically apply appropriate rules. Resolved to full brand identity at execution time.'
        ),
    ] = None
    webhook_url: Annotated[
        AnyUrl | None,
        Field(description='URL to receive notifications when the resolved list changes'),
    ] = None
    cache_duration_hours: Annotated[
        SchemaInt | None,
        Field(
            description='Recommended cache duration for resolved list. Consumers should re-fetch after this period. Defaults to 168 (one week) because collection metadata changes less frequently than property metadata.',
            ge=1,
        ),
    ] = 168
    created_at: Annotated[AwareDatetime | None, Field(description='When the list was created')] = (
        None
    )
    updated_at: Annotated[
        AwareDatetime | None, Field(description='When the list was last modified')
    ] = None
    collection_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of collections in the resolved list (at time of last resolution)'
        ),
    ] = 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

Class variables

var account : AccountReference1 | AccountReference2 | None

var base_collections : list[BaseCollectionSource1 | BaseCollectionSource2 | BaseCollectionSource3] | None

var brand : BrandReference | None

var cache_duration_hours : int | None

var collection_count : int | None

var created_at : pydantic.types.AwareDatetime | None

var description : str | None

var filters : CollectionListFilters | None

var list_id : str

var model_config

var name : str

var updated_at : pydantic.types.AwareDatetime | None

var webhook_url : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CollectionListChangedWebhook (**data: Any)

Expand source code

class CollectionListChangedWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Sender-generated key stable across retries of the same webhook event. Governance agents MUST generate a cryptographically random value (UUID v4 recommended) per distinct list-change event and reuse the same key on every retry. Recipients MUST dedupe by this key, scoped to the authenticated sender identity (HMAC secret or Bearer credential) — keys from different governance agents are independent.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    event: Annotated[Literal['collection_list_changed'], Field(description='The event type')] = 'collection_list_changed'
    list_id: Annotated[str, Field(description='ID of the collection list that changed')]
    list_name: Annotated[str | None, Field(description='Name of the collection list')] = None
    change_summary: Annotated[
        ChangeSummary | None, Field(description='Summary of changes to the resolved list')
    ] = None
    resolved_at: Annotated[AwareDatetime, Field(description='When the list was re-resolved')]
    cache_valid_until: Annotated[
        AwareDatetime | None,
        Field(description='When the consumer should refresh from the governance agent'),
    ] = None
    signature: Annotated[
        str,
        Field(
            description='HMAC-SHA256 webhook signature over {unix_timestamp}.{raw_http_body_bytes} using the secret exchanged out-of-band when the seller registered with the governance agent. Recipients MUST verify against the X-ADCP-Signature and X-ADCP-Timestamp headers using timing-safe comparison and MUST reject requests where |now - timestamp| > 300 seconds. The body copy of this field is a convenience only — the headers are authoritative. See docs/building/implementation/security#webhook-security.'
        ),
    ]
    ext: ext_1.ExtensionObject | None = 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

Class variables

var cache_valid_until : pydantic.types.AwareDatetime | None

var change_summary : ChangeSummary | None

var event : Literal['collection_list_changed']

var ext : ExtensionObject | None

var idempotency_key : str

var list_id : str

var list_name : str | None

var model_config

var resolved_at : pydantic.types.AwareDatetime

var signature : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CollectionListFilters (**data: Any)

Expand source code

class CollectionListFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    content_ratings_exclude: Annotated[
        list[content_rating.ContentRating] | None,
        Field(
            description="Exclude collections with any of these content ratings (OR logic). This is a metadata filter on the collection's declared content_rating field — it does not evaluate episode content.",
            min_length=1,
        ),
    ] = None
    content_ratings_include: Annotated[
        list[content_rating.ContentRating] | None,
        Field(
            description='Include only collections with any of these content ratings (OR logic). Collections without a declared content_rating are excluded.',
            min_length=1,
        ),
    ] = None
    genres_exclude: Annotated[
        list[str] | None,
        Field(
            description='Exclude collections tagged with any of these genres (OR logic). Values are interpreted against genre_taxonomy when present.',
            min_length=1,
        ),
    ] = None
    genres_include: Annotated[
        list[str] | None,
        Field(
            description='Include only collections with any of these genres (OR logic). Collections without genre metadata are excluded. Values are interpreted against genre_taxonomy when present.',
            min_length=1,
        ),
    ] = None
    genre_taxonomy: Annotated[
        genre_taxonomy_1.GenreTaxonomy | None,
        Field(
            description='Taxonomy for genre filter values. When present, genres_include and genres_exclude values are interpreted as taxonomy IDs.'
        ),
    ] = None
    kinds: Annotated[
        list[collection_kind.CollectionKind] | None,
        Field(description='Filter to these collection kinds', min_length=1),
    ] = None
    exclude_distribution_ids: Annotated[
        list[ExcludeDistributionId] | None,
        Field(
            description='Always exclude collections with these distribution identifiers',
            min_length=1,
        ),
    ] = None
    production_quality: Annotated[
        list[production_quality_1.ProductionQuality] | None,
        Field(description='Filter by production quality tier', min_length=1),
    ] = 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

Class variables

var content_ratings_exclude : list[ContentRating] | None

var content_ratings_include : list[ContentRating] | None

var exclude_distribution_ids : list[ExcludeDistributionId] | None

var genre_taxonomy : GenreTaxonomy | None

var genres_exclude : list[str] | None

var genres_include : list[str] | None

var kinds : list[CollectionKind] | None

var model_config

var production_quality : list[ProductionQuality] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Colors (**data: Any)

Expand source code

class Colors(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    primary: Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')] | Annotated[list[Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')]], Field(min_length=1)] | None = None
    secondary: Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')] | Annotated[list[Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')]], Field(min_length=1)] | None = None
    accent: Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')] | Annotated[list[Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')]], Field(min_length=1)] | None = None
    background: Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')] | Annotated[list[Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')]], Field(min_length=1)] | None = None
    text: Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')] | Annotated[list[Annotated[str, StringConstraints(pattern='^#[0-9A-Fa-f]{6}$')]], Field(min_length=1)] | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var accent : str | list[str] | None

var background : str | list[str] | None

var model_config

var primary : str | list[str] | None

var secondary : str | list[str] | None

var text : str | list[str] | None

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class CommercialTerms (**data: Any)

Expand source code

class CommercialTerms(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_feed_version: Annotated[
        str | None,
        Field(
            description='Wholesale product feed version against which direct published offers were accepted. Omitted when the seller authored terms outside a wholesale snapshot.',
            min_length=1,
        ),
    ] = None
    source_pricing_version: Annotated[
        str | None,
        Field(
            description='Pricing-layer version against which published rates were accepted.',
            min_length=1,
        ),
    ] = None
    brand: brand_key.BrandKey
    advertiser_industry: advertiser_industry_1.AdvertiserIndustry | None = None
    purchases: Annotated[
        list[product_purchase.ProductPurchase],
        Field(
            description='Exact canonical product, pricing, format, catalog, budget, targeting, bidding, optimization, resolved flight, measurement, and performance terms in the commercial envelope.',
            min_length=1,
        ),
    ]
    start_time: start_timing.StartTiming
    end_time: AwareDatetime
    total_budget: TotalBudget | None = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Hard aggregate daily spend ceiling accepted as part of these terms. It bounds total spend without creating purchase allocations.',
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Hard MediaBuy-level cap accepted as part of these terms. One counter aggregates exposures across every purchase; purchase targeting caps remain independently binding.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='Shared IANA calendar-day boundary for aggregate and purchase daily caps in these terms.',
            min_length=1,
        ),
    ] = None
    budget_allocation: canonical_budget_allocation.CanonicalBudgetAllocation | None = None
    pacing: pacing_1.Pacing | None = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description="Media-buy bidding policy. A proposal answering criteria.outcome_target.cost_per states here the cost the seller can plan to, which the buyer adopts on acceptance: the requested strength, and an amount greater than or equal to the ask (the ask when the seller can forecast goal volume under it within the buyer's budget, otherwise the lowest such amount), denominated in the purchases' pricing currency, which equals cost_per.currency. It is an execution control, not an expected price; when the planned spend at that amount is below total_budget, forecast points carry metrics.spend. See outcome-target.json for goal binding."
        ),
    ] = None
    invoice_recipient: business_entity.BusinessEntity | None = None
    purchase_order_ref: Annotated[str | None, Field(max_length=255, min_length=1)] = None
    agency_estimate_number: Annotated[str | None, Field(max_length=100)] = None
    reporting_commitments: Annotated[
        list[ReportingCommitment] | None,
        Field(
            description='Binding reporting contract keyed by position in purchases. Amendments preserve prior entries and add metrics with effective_at; seller-assigned package IDs live in the execution binding, outside this digest.',
            min_length=1,
        ),
    ] = None
    cancellation_terms: CancellationTerms | None = None
    change_terms: Annotated[
        list[change_term.MediaBuyChangeTerm] | None,
        Field(
            description='Binding buyer change rights included in the commercial envelope and therefore covered by terms_digest. Entries are uniquely keyed by action. When this field is present, an omitted action is not a negotiated change right. Omission of the entire field means legacy-unspecified rights, not a prohibition.',
            min_length=1,
        ),
    ] = None

    @model_validator(mode='after')
    def _validate_change_term_set(self) -> CommercialTerms:
        if self.change_terms is None:
            return self
        actions = [term.action.value for term in self.change_terms]
        term_ids = [term.term_id for term in self.change_terms]
        if len(set(actions)) != len(actions):
            raise ValueError('change_terms must be uniquely keyed by action')
        if len(set(term_ids)) != len(term_ids):
            raise ValueError('change_terms term_id values must be unique')
        currencies = set()
        for purchase in self.purchases:
            if purchase.pricing is None:
                raise ValueError('accepted commercial-term purchases require resolved pricing')
            currencies.add(purchase.pricing.currency)
        for term in self.change_terms:
            if term.constraints is None:
                continue
            constraint = term.constraints
            if constraint.kind == 'budget':
                money_fields = (
                    constraint.max_delta_amount,
                    constraint.min_result_amount,
                    constraint.max_result_amount,
                )
                if any(money is not None and money.currency not in currencies for money in money_fields):
                    raise ValueError('change-term monetary constraint currency must match purchases')
                if (
                    constraint.min_result_amount is not None
                    and constraint.max_result_amount is not None
                    and constraint.min_result_amount.amount > constraint.max_result_amount.amount
                ):
                    raise ValueError('change-term minimum result exceeds maximum result')
            elif constraint.kind == 'flight':
                if (
                    constraint.earliest_result is not None
                    and constraint.latest_result is not None
                    and constraint.earliest_result > constraint.latest_result
                ):
                    raise ValueError('change-term earliest result exceeds latest result')
            elif constraint.kind == 'effective_timing' and (
                constraint.earliest_effective_at is not None
                and constraint.latest_effective_at is not None
                and constraint.earliest_effective_at > constraint.latest_effective_at
            ):
                raise ValueError('change-term earliest effective time exceeds latest time')
        return self

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

Class variables

var advertiser_industry : AdvertiserIndustry | None

var agency_estimate_number : str | None

var bidding : BiddingPolicy | None

var brand : BrandKey

var budget_allocation : CanonicalBudgetAllocation1 | CanonicalBudgetAllocation2 | None

var budget_cap_timezone : str | None

var cancellation_terms : CancellationTerms | None

var change_terms : list[MediaBuyChangeTerm] | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime

var frequency_cap : MediaBuyFrequencyCap | None

var invoice_recipient : BusinessEntity | None

var model_config

var pacing : Pacing | None

var purchase_order_ref : str | None

var purchases : list[ProductPurchase]

var reporting_commitments : list[ReportingCommitment] | None

var source_feed_version : str | None

var source_pricing_version : str | None

var start_time : Literal['asap'] | pydantic.types.AwareDatetime

var total_budget : TotalBudget | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CompatibilityPurchaseCoordinatorInput (**data: Any)

Expand source code

class CompatibilityPurchaseCoordinatorInput(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        UUID,
        Field(
            description='Replay identity for this logical coordinator operation. Exact retries resume the durable operation record instead of redeeming the continuation again.'
        ),
    ]
    continuation_token: Annotated[
        str,
        Field(
            description='Opaque token returned by products_available.purchase_continuation.',
            min_length=16,
        ),
    ]
    account: Annotated[
        account_ref.AccountReference,
        Field(
            description='Account identity that must match the account bound into the continuation token.'
        ),
    ]
    selected_product_ids: Annotated[
        list[SelectedProductId],
        Field(
            description='Non-empty subset of the product IDs bound into the continuation.',
            min_length=1,
            json_schema_extra={'uniqueItems': True},
        ),
    ]
    accepted_losses: Annotated[
        list[AcceptedLoss],
        Field(
            description='Exact loss set returned with the continuation. Missing, extra, or stale consent fails before mutation.',
            min_length=2,
            json_schema_extra={
                'uniqueItems': True,
                'allOf': [
                    {'contains': {'const': 'feed_version_not_atomic'}},
                    {'contains': {'const': 'pricing_version_not_atomic'}},
                ],
            },
        ),
    ]
    legacy_create_request: Annotated[
        dict[str, Any],
        Field(
            description='Proposed create_media_buy payload. Before mutation the coordinator validates this object against create-media-buy-request.json from source_adcp_version, requires explicit-package mode, and requires its package product IDs to equal selected_product_ids.',
            min_length=1,
        ),
    ]


    @field_validator('selected_product_ids')
    @classmethod
    def _selected_product_ids_are_unique(
        cls, values: list[SelectedProductId]
    ) -> list[SelectedProductId]:
        if len(values) != len(set(values)):
            raise ValueError('selected_product_ids must contain unique items')
        return values

    @field_validator('accepted_losses')
    @classmethod
    def _accepted_losses_match_schema(
        cls, values: list[AcceptedLoss]
    ) -> list[AcceptedLoss]:
        value_set = set(values)
        if len(values) != len(value_set):
            raise ValueError('accepted_losses must contain unique items')
        required = {
            AcceptedLoss.feed_version_not_atomic,
            AcceptedLoss.pricing_version_not_atomic,
        }
        if not required.issubset(value_set):
            raise ValueError('accepted_losses must include the required compatibility losses')
        return values

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

Class variables

var accepted_losses : list[AcceptedLoss]

var account : AccountReference1 | AccountReference2

var continuation_token : str

var idempotency_key : uuid.UUID

var legacy_create_request : dict[str, typing.Any]

var model_config

var selected_product_ids : list[SelectedProductId]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ComplyTestControllerRequest (**data: Any)

Expand source code

class ComplyTestControllerRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    scenario: Annotated[
        str,
        Field(
            description="Test scenario to execute. 'list_scenarios' discovers supported scenarios. 'force_*' and 'simulate_*' trigger state transitions. 'reporting_core_lifecycle_probe' installs a caller/account-scoped Core fixture whose first elapsed obligation is visible before any report, advances its virtual clock into delayed or action_required, and can publish deterministic zero-row or non-empty revisions, restate a provisional revision, restate one the caller already received, or cross the consumer-status deadline and consumer-mismatch escalation boundaries, without waiting for wall-clock boundaries. Other scenarios provide deterministic sandbox probes for their documented lifecycle checks. Runners and sellers MUST accept unknown scenario strings - new scenarios may be added in additive releases."
        ),
    ]
    params: Annotated[
        Params | None,
        Field(
            description='Scenario-specific parameters. Required for all scenarios except list_scenarios.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    account: Annotated[
        Account | None,
        Field(
            description="Sandbox account assertion. The runner MUST set sandbox: true on every comply_test_controller request. The seller MUST refuse the request (returning a structured error) if the targeted account is not a sandbox account in the seller's persisted records. This field is a caller-side declaration of intent — it does not grant sandbox status; sellers verify against their own account state. The (Sandbox) verification tier is defined by this gate: real production endpoints accept sandbox-flagged traffic and process it without real-world side effects, no separate test-mode endpoint required. See spec issue #3755 and the (Sandbox) framing in #4379."
        ),
    ] = 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 account : Account | None

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var params : Params | None

var scenario : 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 ComplyTestControllerResponse (**data: Any)

Expand source code

class ComplyTestControllerResponse(AdcpResponse, ResponseArmDispatchMixin, AdcpVersionEnvelope, ProtocolEnvelope):
    """Constructible compatibility base for generated response arms."""

    @classmethod
    def _response_arm_models(cls) -> tuple[type[ComplyTestControllerResponse], ...]:
        return (
            ComplyTestControllerResponse1,
            ComplyTestControllerResponse2,
            ComplyTestControllerResponse3,
            ComplyTestControllerResponse4,
            ComplyTestControllerResponse5,
            ComplyTestControllerResponse6,
            ComplyTestControllerResponse7,
            ComplyTestControllerResponse8,
        )

Constructible compatibility base for generated response arms.

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
• ResponseArmDispatchMixin
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• ComplyTestControllerResponse1
• ComplyTestControllerResponse2
• ComplyTestControllerResponse3
• ComplyTestControllerResponse4
• ComplyTestControllerResponse5
• ComplyTestControllerResponse6
• ComplyTestControllerResponse7
• ComplyTestControllerResponse8

Class variables

var model_config

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• ResponseArmDispatchMixin:
  • model_validate
  • model_validate_json
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class ComplyTestControllerResponse1 (**data: Any)

Expand source code

class ComplyTestControllerResponse1(ComplyTestControllerResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Literal[True]
    scenarios: Annotated[
        list[str],
        Field(
            description='Scenarios this seller has implemented. Runners and sellers MUST accept unknown scenario strings (open-for-extension) — new scenarios may be added in additive releases. Adopters who advertise `catalog_item_availability_probe` support deterministic cross-principal reference, eligibility-gate, expiry-clock, and catalog-generation tests for the catalog availability storyboard. Adopters who advertise `compact_product_lifecycle_probe` support deterministic synchronous list/request/finalize/decline/accept/control/readback behavior for a prepared product and strict post-deadline expiry of a committed proposal. Adopters who advertise `compact_direct_buy_lifecycle_probe` support deterministic synchronous list/buy/control/readback behavior for a prepared product. Adopters who advertise `reporting_core_lifecycle_probe` support deterministic obligation-before-report, clock-health, zero-row reporting, provisional-restatement, and post-received restatement-grace tests without wall-clock waits. `reliable_reporting_core_integrity_probe`, `reliable_reporting_managed_delivery_probe`, and `reliable_reporting_reconciled_billing_probe` seed the source-calendar/checkpoint, managed-resource, and receipt/adjustment workflows used by the Reliable Reporting tier storyboards. Adopters who advertise `force_creative_purge` opt in to deterministic creative purge coverage for account-level lifecycle webhooks. Adopters who advertise `force_media_buy_purge` opt in to deterministic deletion-independent idempotency replay coverage. Adopters who advertise `seed_measurement_catalog` opt in to deterministic measurement-catalog fixtures used by vendor_metric precondition storyboards. Adopters who advertise `query_upstream_traffic` opt in to the upstream-traffic conformance contract; storyboards that declare `check: upstream_traffic` grade not_applicable against adopters who do not advertise it. Adopters who advertise `query_provenance_audit_observations` opt in to sandbox-only audit-observation assertions for accepted creatives. Adopters who advertise `force_upstream_unavailable` opt in to stale-cache conformance testing via the `stale_response_advisory` storyboard.'
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var scenarios : list[str]

var success : Literal[True]

class ComplyListScenariosResponse (**data: Any)

Expand source code

class ComplyTestControllerResponse1(ComplyTestControllerResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Literal[True]
    scenarios: Annotated[
        list[str],
        Field(
            description='Scenarios this seller has implemented. Runners and sellers MUST accept unknown scenario strings (open-for-extension) — new scenarios may be added in additive releases. Adopters who advertise `catalog_item_availability_probe` support deterministic cross-principal reference, eligibility-gate, expiry-clock, and catalog-generation tests for the catalog availability storyboard. Adopters who advertise `compact_product_lifecycle_probe` support deterministic synchronous list/request/finalize/decline/accept/control/readback behavior for a prepared product and strict post-deadline expiry of a committed proposal. Adopters who advertise `compact_direct_buy_lifecycle_probe` support deterministic synchronous list/buy/control/readback behavior for a prepared product. Adopters who advertise `reporting_core_lifecycle_probe` support deterministic obligation-before-report, clock-health, zero-row reporting, provisional-restatement, and post-received restatement-grace tests without wall-clock waits. `reliable_reporting_core_integrity_probe`, `reliable_reporting_managed_delivery_probe`, and `reliable_reporting_reconciled_billing_probe` seed the source-calendar/checkpoint, managed-resource, and receipt/adjustment workflows used by the Reliable Reporting tier storyboards. Adopters who advertise `force_creative_purge` opt in to deterministic creative purge coverage for account-level lifecycle webhooks. Adopters who advertise `force_media_buy_purge` opt in to deterministic deletion-independent idempotency replay coverage. Adopters who advertise `seed_measurement_catalog` opt in to deterministic measurement-catalog fixtures used by vendor_metric precondition storyboards. Adopters who advertise `query_upstream_traffic` opt in to the upstream-traffic conformance contract; storyboards that declare `check: upstream_traffic` grade not_applicable against adopters who do not advertise it. Adopters who advertise `query_provenance_audit_observations` opt in to sandbox-only audit-observation assertions for accepted creatives. Adopters who advertise `force_upstream_unavailable` opt in to stale-cache conformance testing via the `stale_response_advisory` storyboard.'
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var scenarios : list[str]

var success : Literal[True]

Inherited members

• ComplyTestControllerResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class ComplyStateTransitionResponse (**data: Any)

Expand source code

class ComplyTestControllerResponse2(ComplyTestControllerResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Literal[True]
    previous_state: Annotated[str, Field(description='State before this transition')]
    current_state: Annotated[str, Field(description='State after this transition')]
    message: Annotated[
        str | None, Field(description='Human-readable description of the transition')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var current_state : str

var ext : ExtensionObject | None

var message : str | None

var model_config

var previous_state : str

var success : Literal[True]

Inherited members

• ComplyTestControllerResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class ComplySimulationResponse (**data: Any)

Expand source code

class ComplyTestControllerResponse3(ComplyTestControllerResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Literal[True]
    simulated: Annotated[
        dict[str, Any],
        Field(description='Values injected or applied by this call. Shape depends on scenario.'),
    ]
    cumulative: Annotated[
        dict[str, Any] | None,
        Field(description='Running totals across all simulation calls (simulate_delivery only)'),
    ] = None
    message: str | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var cumulative : dict[str, typing.Any] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var simulated : dict[str, typing.Any]

var success : Literal[True]

Inherited members

• ComplyTestControllerResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class ComplyErrorResponse (**data: Any)

Expand source code

class ComplyTestControllerResponse4(ComplyTestControllerResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Literal[True]
    forced: Annotated[
        Forced,
        Field(
            description='Echo of the registered directive. The next matching operation call from this sandbox account will return the named arm.'
        ),
    ]
    message: Annotated[str | None, Field(description='Human-readable acknowledgement.')] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var forced : Forced

var message : str | None

var model_config

var success : Literal[True]

Inherited members

• ComplyTestControllerResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class CanonicalCompositionModel (*args, **kwds)

Expand source code

class CompositionModel(StrEnum):
    deterministic = 'deterministic'
    algorithmic = 'algorithmic'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var algorithmic

var deterministic

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.

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

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 ConflictDetails (**data: Any)

Expand source code

class ConflictDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    resource_id: Annotated[
        str | None, Field(description='Identifier of the conflicting resource')
    ] = None
    expected_version: Annotated[
        StrictFloat | str | None,
        Field(description='Version or ETag the client was operating against'),
    ] = None
    current_version: Annotated[
        StrictFloat | str | None, Field(description='Current version or ETag on the server')
    ] = 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

Class variables

var current_version : float | str | None

var expected_version : float | str | None

var model_config

var resource_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ConsentBasis (*args, **kwds)

Expand source code

class ConsentBasis(StrEnum):
    consent = 'consent'
    legitimate_interest = 'legitimate_interest'
    contract = 'contract'
    legal_obligation = 'legal_obligation'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var consent

var contract

var legal_obligation

var legitimate_interest

class ReportingConsumerStatusValue (*args, **kwds)

Expand source code

class ConsumerStatus(StrEnum):
    received = 'received'
    obligation_missing = 'obligation_missing'
    revision_missing = 'revision_missing'
    unreadable = 'unreadable'
    content_mismatch = 'content_mismatch'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var content_mismatch

var obligation_missing

var received

var revision_missing

var unreadable

class Contact (**data: Any)

Expand source code

class Contact(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    name: Annotated[
        str,
        Field(
            description="Name of the entity managing this file (e.g., 'Meta Advertising Operations', 'Clear Channel Digital')",
            max_length=255,
            min_length=1,
        ),
    ]
    email: Annotated[
        EmailStr | None,
        Field(
            description='Contact email for questions or issues with this authorization file',
            max_length=255,
            min_length=1,
        ),
    ] = None
    domain: Annotated[
        str | None,
        Field(
            description='Primary domain of the entity managing this file',
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    seller_id: Annotated[
        str | None,
        Field(
            description='Seller ID from IAB Tech Lab sellers.json (if applicable)',
            max_length=255,
            min_length=1,
        ),
    ] = None
    tag_id: Annotated[
        str | None,
        Field(
            description='TAG Certified Against Fraud ID for verification (if applicable)',
            max_length=100,
            min_length=1,
        ),
    ] = None
    privacy_policy_url: Annotated[
        AnyUrl | None,
        Field(
            description="URL to the entity's privacy policy. Used for consumer consent flows when interacting with this sales agent."
        ),
    ] = 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

Class variables

var domain : str | None

var email : pydantic.networks.EmailStr | None

var model_config

var name : str

var privacy_policy_url : pydantic.networks.AnyUrl | None

var seller_id : str | None

var tag_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ContentIdType (*args, **kwds)

Expand source code

class ContentIdType(StrEnum):
    sku = 'sku'
    gtin = 'gtin'
    offering_id = 'offering_id'
    job_id = 'job_id'
    hotel_id = 'hotel_id'
    flight_id = 'flight_id'
    vehicle_id = 'vehicle_id'
    listing_id = 'listing_id'
    store_id = 'store_id'
    program_id = 'program_id'
    destination_id = 'destination_id'
    app_id = 'app_id'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var app_id

var destination_id

var flight_id

var gtin

var hotel_id

var job_id

var listing_id

var offering_id

var program_id

var sku

var store_id

var vehicle_id

class ContentStandards (**data: Any)

Expand source code

class ContentStandards(AdCPBaseModel):
    standards_id: Annotated[
        str, Field(description='Unique identifier for this standards configuration')
    ]
    name: Annotated[
        str | None, Field(description='Human-readable name for this standards configuration')
    ] = None
    countries_all: Annotated[
        list[str] | None,
        Field(
            description='ISO 3166-1 alpha-2 country codes. Standards apply in ALL listed countries (AND logic).',
            min_length=1,
        ),
    ] = None
    channels_any: Annotated[
        list[channels.MediaChannel] | None,
        Field(
            description='Advertising channels. Standards apply to ANY of the listed channels (OR logic).',
            min_length=1,
        ),
    ] = None
    languages_any: Annotated[
        list[str] | None,
        Field(
            description="BCP 47 language tags (e.g., 'en', 'de', 'fr'). Standards apply to content in ANY of these languages (OR logic). Content in unlisted languages is not covered by these standards.",
            min_length=1,
        ),
    ] = None
    policies: Annotated[
        list[policy_entry.PolicyEntry] | None,
        Field(
            description='Bespoke policies for this content-standards configuration, using the same shape as registry entries. Each policy is addressable by policy_id; governance findings reference the policy_id that triggered them.',
            min_length=1,
        ),
    ] = None
    calibration_exemplars: Annotated[
        CalibrationExemplars | None,
        Field(
            description='Training/test set to calibrate policy interpretation. Provides concrete examples of pass/fail decisions.'
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for this content standards service. The buyer passes the selected pricing_option_id in report_usage for billing verification.',
            min_length=1,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var calibration_exemplars : CalibrationExemplars | None

var channels_any : list[MediaChannel] | None

var countries_all : list[str] | None

var ext : ExtensionObject | None

var languages_any : list[str] | None

var model_config

var name : str | None

var policies : list[PolicyEntry] | None

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var standards_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ContextMatchRequest (**data: Any)

Expand source code

class ContextMatchRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['context_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'context_match_request'
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any identity match request_id.'
        ),
    ]
    property_rid: Annotated[
        UUID,
        Field(
            description='Property catalog UUID (UUID v7). Globally unique, stable identifier assigned by the property catalog. The primary key for TMP matching and property list targeting.'
        ),
    ]
    property_id: Annotated[
        property_id_1.PropertyId | None,
        Field(
            description="Publisher's human-readable property slug (e.g., 'cnn_homepage'). Optional when property_rid is present. Useful for logging and debugging."
        ),
    ] = None
    property_type: Annotated[
        property_type_1.PropertyType, Field(description='Type of the publisher property')
    ]
    placement_id: Annotated[
        str,
        Field(
            description="Placement identifier from the publisher's placement registry in adagents.json. Identifies where on the property this ad opportunity exists. One placement per request."
        ),
    ]
    seller_agent_url: Annotated[
        AnyUrl,
        Field(
            description="API endpoint URL of the seller agent issuing this request. The provider uses this to resolve the active package set it has synced for this seller; when `package_ids` is omitted, evaluation occurs against that full set. If `seller_agent_url` does not match any seller the provider has synced packages for, the provider MUST return an empty offer set — it MUST NOT fall back to another seller's active set. The value identifies the asking seller, is identical for every user on a given placement, and carries no user identity, so it neither varies the request per user nor weakens the context/identity decorrelation boundary. Compared using the AdCP URL canonicalization rules, not byte-equality — see docs/reference/url-canonicalization. Consistent with `seller_agent_url` on the identity match request, `seller_agent.agent_url` on `AvailablePackage`, and `agent_url` in `adagents.json`."
        ),
    ]
    artifact: Annotated[
        artifact_1.Artifact | None,
        Field(
            description='Full content artifact adjacent to this ad opportunity. Same schema used for content standards evaluation. The publisher sends the artifact when they want the buyer to evaluate the full content. Contractual protections govern buyer use. TEE deployment upgrades contractual trust to cryptographic verification. Because the router fans out to multiple buyer agents, publishers MUST NOT include bearer tokens, service-account credentials, or signed URLs in this artifact. Routers MUST remove every asset `access` object and remove or replace every credential-bearing asset `url` before forwarding; only public asset URLs that recipients can resolve independently may remain.'
        ),
    ] = None
    artifact_refs: Annotated[
        list[ArtifactRef] | None,
        Field(
            description='Public content references adjacent to this ad opportunity. Each artifact identifies content via a public identifier the buyer can resolve independently — no private registry sync required.',
            max_length=20,
            min_length=1,
        ),
    ] = None
    geo: Annotated[
        Geo | None,
        Field(
            description='Coarse geographic location of the viewer. Publisher controls granularity — country is sufficient for regulatory compliance and volume filtering, region or metro helps with campaign targeting and valuation. Coarsened to prevent user identification: no postcode, no coordinates. All fields optional.'
        ),
    ] = None
    context_signals: Annotated[
        ContextSignals | None,
        Field(
            description="Pre-computed classifier outputs for the content environment. Use when the publisher wants to provide privacy-reduced context without sharing content or public references. Can supplement artifact_refs or replace them entirely. Ephemeral content that many users encounter (a trending query, a syndicated segment) is shared content; one user's turn or query is not. For non-public content attributable to a single user or session, only the field-specific privacy-reduced outputs permitted below may be sent. Raw content MUST NOT be included. The publisher is the classifier and privacy boundary."
        ),
    ] = None
    package_ids: Annotated[
        list[str] | None,
        Field(
            description='Restrict evaluation to specific packages. When omitted, the provider evaluates all eligible packages for this placement (the common case). MUST NOT vary by user — the same package_ids must be sent for every user on a given placement. User-dependent filtering leaks identity into the context path.',
            max_length=500,
            min_length=1,
        ),
    ] = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var artifact : Artifact | None

var artifact_refs : list[ArtifactRef] | None

var context_signals : ContextSignals | None

var field_schema : pydantic.networks.AnyUrl | None

var geo : Geo | None

var model_config

var package_ids : list[str] | None

var placement_id : str

var property_id : PropertyId | None

var property_rid : uuid.UUID

var property_type : PropertyType

var protocol_version : str | None

var request_id : str

var seller_agent_url : pydantic.networks.AnyUrl

var type : Literal['context_match_request']

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class ContextMatchResponse (**data: Any)

Expand source code

class ContextMatchResponseRouterPublisher(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['context_match_response'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'context_match_response'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the context match request.')
    ]
    offers: Annotated[
        list[offer.Offer],
        Field(
            description='Offers collected across the provider fan-out, one per activated package. An empty array means no packages matched. For simple activation, each offer has just package_id. For richer responses, offers include brand, price, summary, and creative manifest.'
        ),
    ]
    signals: Annotated[
        Signals | None,
        Field(
            description='Merged non-keyed response-level signals. Provider-local targeting pairs do not pass through this object; the router emits them only in signals_by_provider.'
        ),
    ] = None
    signals_by_provider: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[A-Za-z0-9_]+$', min_length=1, max_length=64)], SignalsByProvider]
        | None,
        Field(
            description="Router-authored map of provider targeting pairs, keyed by the publisher-assigned provider_id from provider registration. For every provider response containing a non-empty signals.targeting_kvs list, the router copies the complete list unchanged into that provider's bucket. The router derives the map key from its registration and MUST ignore or reject provider-supplied signals_by_provider data. A provider with no targeting pairs is omitted. Publishers resolve each (provider_id, key) tuple to a local ad-server destination and drop tuples that have no local mapping.",
            min_length=1,
        ),
    ] = 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

• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var offers : list[adcp.types._forward_compat._ReadbackOffer]

var request_id : str

var signals : Signals | None

var signals_by_provider : dict[str, SignalsByProvider] | None

var type : Literal['context_match_response']

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

Inherited members

• AdcpVersionEnvelope:
  • 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.

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

Class variables

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ControlMediaBuyRequest (**data: Any)

Expand source code

class ControlMediaBuyRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str, Field(max_length=255, min_length=16, pattern='^[A-Za-z0-9_.:-]{16,255}$')
    ]
    account: canonical_account_ref.CanonicalAccountReference
    media_buy_id: Annotated[str, Field(min_length=1)]
    revision: Annotated[
        SchemaInt,
        Field(
            description='Required optimistic-concurrency revision from the latest MediaBuy snapshot.',
            ge=1,
        ),
    ]
    name: Annotated[
        str | None,
        Field(
            description='Replace the human-readable MediaBuy name as revision-checked operational metadata. This display label is not an identifier, financial reference, or change to the accepted commercial terms.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    paused: StrictBool | None = None
    canceled: Annotated[
        Literal[True] | None,
        Field(
            description='Exercise an already-accepted unilateral cancellation right. A cancellation requiring seller agreement is requested by refining the accepted proposal.'
        ),
    ] = None
    cancellation_reason: Annotated[str | None, Field(max_length=500, min_length=1)] = None
    total_budget: TotalBudget | None = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Replace the hard aggregate daily cap; null removes it. Numeric changes apply immediately with current-cap-day spend counted and do not redistribute purchase caps.',
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Replace the shared MediaBuy frequency cap; null removes it. The change applies immediately without resetting counters: qualifying prior exposures still count in the resulting active window. Sellers MUST reject the complete mutation with UNSUPPORTED_FEATURE, before any change, if the cap is outside declared constraints or any active package cannot participate in the resulting shared counter, and MUST NOT clamp it. Requires update_media_buy_frequency_cap in available_actions.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='Replace the shared IANA cap-day timezone override; null restores the default selected by budget_capping.timezone_basis (Account.timezone or fixed_timezone). A timezone change begins at the next boundary under the previously effective timezone.',
            min_length=1,
        ),
    ] = None
    budget_allocation: canonical_budget_allocation.CanonicalBudgetAllocation | None = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Replace aggregate media-buy pacing. In seller-optimized allocation, a seller declaring media_buy.features.seller_optimized_budget MUST accept omission and `even`; it MAY reject `asap` or `front_loaded` with UNSUPPORTED_FEATURE (error.field `pacing`) before any provider mutation and MUST NOT silently coerce them to `even`. Fixed-allocation semantics are unchanged.'
        ),
    ] = None
    bidding: bidding_policy.BiddingPolicy | None = None
    packages: Annotated[
        list[package_control.PackageControl] | None,
        Field(
            description='Operational patches keyed by package_id. Each package_id MUST appear at most once; sellers reject duplicate IDs atomically.',
            min_length=1,
        ),
    ] = None
    reporting_webhook: reporting_webhook_1.ReportingWebhook | None = None
    governance_context: Annotated[str | None, Field(max_length=4096, min_length=1)] = None
    push_notification_config: push_notification_config_1.PushNotificationConfig | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> ControlMediaBuyRequest:
        # ``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 (('name',), ('paused',), ('canceled',), ('total_budget',), ('daily_budget_cap',), ('frequency_cap',), ('budget_cap_timezone',), ('budget_allocation',), ('pacing',), ('bidding',), ('packages',), ('reporting_webhook',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'ControlMediaBuyRequest requires at least one of these field groups: name | paused | canceled | total_budget | daily_budget_cap | frequency_cap | budget_cap_timezone | budget_allocation | pacing | bidding | packages | reporting_webhook'
        )

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 account : CanonicalAccountReference1 | CanonicalAccountReference2

var bidding : BiddingPolicy | None

var budget_allocation : CanonicalBudgetAllocation1 | CanonicalBudgetAllocation2 | None

var budget_cap_timezone : str | None

var canceled : Literal[True] | None

var cancellation_reason : str | None

var context : ContextObject | None

var daily_budget_cap : float | None

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var governance_context : str | None

var idempotency_key : str

var media_buy_id : str

var model_config

var name : str | None

var pacing : Pacing | None

var packages : list[PackageControl] | None

var paused : bool | None

var push_notification_config : PushNotificationConfig | None

var reporting_webhook : ReportingWebhook | None

var revision : int

var total_budget : TotalBudget | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 Country (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class Country(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{2}$'}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class ProductFilterCountry (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class Country(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{2}$'}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class CpaPricingOption (**data: Any)

Expand source code

class CpaPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['cpa'], Field(description='Cost per acquisition (conversion event)')
    ] = 'cpa'
    event_type: Annotated[
        event_type_1.EventType,
        Field(
            description='The conversion event type that triggers billing (e.g., purchase, lead, app_install)'
        ),
    ]
    custom_event_name: Annotated[
        str | None,
        Field(
            description="Name of the custom event when event_type is 'custom'. Required when event_type is 'custom', ignored otherwise."
        ),
    ] = None
    event_source_id: Annotated[
        str | None,
        Field(
            description='When present, only events from this specific event source count toward billing. Allows different CPA rates for different sources (e.g., online vs in-store purchases). Must match an event source configured via sync_event_sources.'
        ),
    ] = None
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat,
        Field(description='Fixed price per acquisition in the specified currency', gt=0.0),
    ]
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var custom_event_name : str | None

var eligible_adjustments : list[PriceAdjustmentKind] | None

var event_source_id : str | None

var event_type : EventType

var fixed_price : float

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var pricing_model : Literal['cpa']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CpcPricingOption (**data: Any)

Expand source code

class CpcPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpc'], Field(description='Cost per click')] = 'cpc'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per click. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['cpc']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CpcvPricingOption (**data: Any)

Expand source code

class CpcvPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['cpcv'], Field(description='Cost per completed view (100% completion)')
    ] = 'cpcv'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per completed view. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['cpcv']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CpmPricingOption (**data: Any)

Expand source code

class CpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')] = 'cpm'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['cpm']

var pricing_option_id : str

class CpmAuctionPricingOption (**data: Any)

Expand source code

class CpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')] = 'cpm'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['cpm']

var pricing_option_id : str

class CpmFixedRatePricingOption (**data: Any)

Expand source code

class CpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')] = 'cpm'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['cpm']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CppPricingOption (**data: Any)

Expand source code

class CppPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpp'], Field(description='Cost per Gross Rating Point')] = 'cpp'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per rating point. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    parameters: Annotated[
        Parameters, Field(description='CPP-specific parameters for demographic targeting')
    ]
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var min_spend_per_package : float | None

var model_config

var parameters : Parameters

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['cpp']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CpvPricingOption (**data: Any)

Expand source code

class CpvPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpv'], Field(description='Cost per view at threshold')] = 'cpv'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per view. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    parameters: Annotated[
        Parameters, Field(description='CPV-specific parameters defining the view threshold')
    ]
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var parameters : Parameters

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['cpv']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreateCollectionListRequest (**data: Any)

Expand source code

class CreateCollectionListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that will own the list. Pass a natural key (brand, operator, optional sandbox) or a seller-assigned account_id from list_accounts. When omitted, this task applies its task-local single-account shortcut: if exactly one account is accessible to the authenticated caller, the seller may assign the list to that account; otherwise it MUST return an account-required or ambiguous-account error. Omission MUST NOT mean an undocumented credential-local default account.'
        ),
    ] = None
    name: Annotated[str, Field(description='Human-readable name for the list')]
    description: Annotated[str | None, Field(description="Description of the list's purpose")] = (
        None
    )
    base_collections: Annotated[
        list[base_collection_source.BaseCollectionSource] | None,
        Field(
            description="Array of collection sources to evaluate. Each entry is a discriminated union: distribution_ids (platform-independent identifiers), publisher_collections (publisher_domain + collection_ids), or publisher_genres (publisher_domain + genres). If omitted, queries the agent's entire collection database.",
            min_length=1,
        ),
    ] = None
    filters: Annotated[
        collection_list_filters.CollectionListFilters | None,
        Field(description='Dynamic filters to apply when resolving the list'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand reference. When provided, the agent automatically applies appropriate rules based on brand characteristics (industry, target_audience, etc.). Resolved at execution time.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate collection list creation on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 account : AccountReference1 | AccountReference2 | None

var base_collections : list[BaseCollectionSource1 | BaseCollectionSource2 | BaseCollectionSource3] | None

var brand : BrandReference | None

var context : ContextObject | None

var description : str | None

var ext : ExtensionObject | None

var filters : CollectionListFilters | None

var idempotency_key : str

var model_config

var name : 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 CreateCollectionListResponse (**data: Any)

Expand source code

class CreateCollectionListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list: Annotated[
        collection_list.CollectionList, Field(description='The created collection list')
    ]
    auth_token: Annotated[
        str,
        Field(
            description='Token that authorizes sellers to fetch this list via get_collection_list. Only returned at creation time — buyers MUST store it in a secret manager. Scoped to this one list_id; MUST NOT be reused across lists. Governance agents MUST issue a distinct token per seller so per-relationship revocation is possible. Tokens MUST NOT be logged, appear in cache keys, or echo in error responses. delete_collection_list MUST revoke the token immediately; compromise-driven revocation MUST also signal cache invalidation to sellers (reduced cache_valid_until or a list-changed webhook). See Security considerations in docs/governance/collection/tasks/collection_lists.'
        ),
    ]
    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
    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.

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 auth_token : str

var context : ContextObject | None

var ext : ExtensionObject | None

var list : CollectionList

var model_config

var replayed : bool | 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 CreateContentStandardsRequest (**data: Any)

Expand source code

class CreateContentStandardsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    scope: Annotated[Scope, Field(description='Where this standards configuration applies')]
    registry_policy_ids: Annotated[
        list[str] | None,
        Field(
            description="Registry policy IDs to use as the evaluation basis for this content standard. When provided, the agent resolves policies from the registry and uses their policy text and exemplars as the evaluation criteria. The 'policy' field becomes optional when registry_policy_ids is provided."
        ),
    ] = None
    policies: Annotated[
        list[policy_entry.PolicyEntry] | None,
        Field(
            description='Bespoke policies for this content-standards configuration, using the same shape as registry entries. Each policy is addressable by policy_id and carries its own enforcement (must|should); governance findings reference the policy_id that triggered them. Inline bespoke policies can omit version/name/category (defaulted by the server). Combines with registry_policy_ids — registry policies and bespoke policies are both evaluated. Bespoke policy_ids MUST be flat (no colons/slashes) to avoid collision with namespaced registry ids.',
            min_length=1,
        ),
    ] = None
    calibration_exemplars: Annotated[
        CalibrationExemplars | None,
        Field(
            description='Training/test set to calibrate policy interpretation. Use URL references for pages to be fetched and analyzed, or full artifacts for pre-extracted content.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate content standards creation on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> CreateContentStandardsRequest:
        # ``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 (('policies',), ('registry_policy_ids',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'CreateContentStandardsRequest requires at least one of these field groups: policies | registry_policy_ids'
        )

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 calibration_exemplars : CalibrationExemplars | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var policies : list[PolicyEntry] | None

var registry_policy_ids : list[str] | None

var scope : Scope

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 CreateContentStandardsResponse (**data: Any)

Expand source code

class CreateContentStandardsResponse(AdcpResponse, ResponseArmDispatchMixin, AdcpVersionEnvelope, ProtocolEnvelope):
    """Constructible compatibility base for generated response arms."""

    @classmethod
    def _response_arm_models(cls) -> tuple[type[CreateContentStandardsResponse], ...]:
        return (
            CreateContentStandardsResponse1,
            CreateContentStandardsResponse2,
        )

Constructible compatibility base for generated response arms.

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
• ResponseArmDispatchMixin
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• CreateContentStandardsResponse1
• CreateContentStandardsResponse2

Class variables

var model_config

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• ResponseArmDispatchMixin:
  • model_validate
  • model_validate_json
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class CreateContentStandardsResponse1 (**data: Any)

Expand source code

class CreateContentStandardsResponse1(CreateContentStandardsResponse):
    standards_id: Annotated[
        str, Field(description='Unique identifier for the created standards configuration')
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var standards_id : str

class CreateContentStandardsSuccessResponse (**data: Any)

Expand source code

class CreateContentStandardsResponse1(CreateContentStandardsResponse):
    standards_id: Annotated[
        str, Field(description='Unique identifier for the created standards configuration')
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var standards_id : str

Inherited members

• CreateContentStandardsResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class CreateContentStandardsErrorResponse (**data: Any)

Expand source code

class CreateContentStandardsResponse2(CreateContentStandardsResponse):
    errors: list[error.Error]
    conflicting_standards_id: Annotated[
        str | None,
        Field(
            description='If the error is a scope conflict, the ID of the existing standards that conflict'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var conflicting_standards_id : str | None

var context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

Inherited members

• CreateContentStandardsResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class CreateMediaBuyRequest (**data: Any)

Expand source code

class CreateMediaBuyRequest(_LegacyCreateMediaBuyRequest, CanonicalBoundaryModel):
    """Canonical create request; packages are canonical package requests."""

    packages: list[PackageRequest] | None = None

Canonical create request; packages are canonical package requests.

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

• CreateMediaBuyRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var packages : list[PackageRequest] | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var plan_id : str | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class LegacyCreateMediaBuyRequest (**data: Any)

Expand source code

class CreateMediaBuyRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque intent authorization for this media-buy commitment. Required when governance applies to the resolved account.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. If a request with the same idempotency_key and account has already been processed, the seller returns the existing media buy rather than creating a duplicate. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    plan_id: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='DEPRECATED on seller-facing requests. New buyers send the approved governance_context on the protocol envelope; the seller forwards that opaque context and does not need the plan identifier. If both are present, the governance agent MUST reject a mismatch. Removed in 4.0.',
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference,
        Field(
            description='Account to bill for this media buy. Pass a natural key (brand, operator, optional sandbox) or a seller-assigned account_id from list_accounts.'
        ),
    ]
    proposal_id: Annotated[
        str | None,
        Field(
            description="ID of the exact committed proposal snapshot to execute. With total_budget, the publisher creates packages using the proposal's fixed percentages or seller-optimized constraints. Mutually exclusive: provide packages or proposal_id, not both. AdCP 3.2 request_proposals and ordinary refine_proposals revisions issue drafts; refine_proposals action finalize creates the executable committed hold. Sellers reject draft, declined, or previously executed snapshots, while exact retries with the original idempotency key replay historical success. Changed commercial terms are issued under a new proposal_id, so no separate proposal version is required."
        ),
    ] = None
    opportunity: Annotated[
        Opportunity | None,
        Field(
            description='Optional planning-cycle closure. Sellers infer successful proposal execution as closed with close_reason accepted_with_seller when status is omitted; when status is present it MUST be closed with that reason. If the proposal was issued under an opportunity_id, a supplied ID MUST match it.'
        ),
    ] = None
    total_budget: Annotated[
        TotalBudget | None,
        Field(
            description='Hard aggregate lifetime budget for the media buy. Required when executing a proposal and for seller-optimized explicit packages. Optional in fixed explicit-package mode; when present there, amount MUST equal the sum of package budgets. For a fixed proposal, the publisher applies allocation percentages to this amount. For a seller-optimized proposal or explicit buy, packages draw dynamically from this shared total.'
        ),
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Optional hard aggregate daily spend ceiling in the media-buy currency. It limits total spend without allocating package amounts. Package caps are subordinate and need not sum to it. Requires advertised media_buy budget-capping scope; otherwise rejected with UNSUPPORTED_FEATURE.',
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Optional max-impression cap using one counter across explicit packages. Requires advertised aggregate_frequency_capping and compatible media_buy_support on every product; otherwise sellers MUST reject with UNSUPPORTED_FEATURE before any mutation and MUST NOT silently drop, soften, or clamp the cap. Omit when executing proposal_id because accepted terms are authoritative.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='Optional shared IANA day boundary override for all caps. Requires buyer_timezone_override; otherwise rejected with UNSUPPORTED_FEATURE. When omitted, budget_capping.timezone_basis selects Account.timezone or the advertised fixed_timezone.',
            min_length=1,
        ),
    ] = None
    budget_allocation: Annotated[
        budget_allocation_1.BudgetAllocation | None,
        Field(
            description='How budget is allocated across explicit packages. Omission means fixed allocation (legacy-compatible). Buyer agents SHOULD send budget_allocation explicitly ({mode: "fixed"} or seller_optimized) rather than rely on omission, and when the principal\'s instruction does not determine whether the budget is one shared pool across packages or split per package, SHOULD ask the principal rather than guess. seller_optimized requires advertised media_buy.features.seller_optimized_budget; inside it, package budget caps, min_spend_target, and package pacing each require their own advertised sub-capability (seller_optimized_package_budgets, seller_optimized_min_spend_targets, seller_optimized_package_pacing), otherwise the request is rejected with UNSUPPORTED_FEATURE before any over-subscription validation. In proposal mode the committed proposal supplies this configuration and callers MUST omit it here.'
        ),
    ] = None
    packages: Annotated[
        Sequence[package_request.PackageRequest] | None,
        Field(
            description='Array of package configurations. Required when not using proposal_id. Mutually exclusive: provide packages or proposal_id, not both. Fixed allocation requires budget on every package. Seller-optimized allocation permits package budget to be omitted or to act as a hard cap. When executing a proposal, omit packages; the seller derives them from the committed proposal.',
            min_length=1,
        ),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference,
        Field(
            description='Brand reference for this media buy. Resolved to full brand identity at execution time from brand.json or the registry.'
        ),
    ]
    advertiser_industry: Annotated[
        advertiser_industry_1.AdvertiserIndustry | None,
        Field(
            description="Industry classification for this specific campaign. A brand may operate across multiple industries (brand.json industries field), but each media buy targets one. For example, a consumer health company running a wellness campaign sends 'healthcare.wellness', not 'cpg'. Sellers map this to platform-native codes (e.g., Spotify ADV categories, LinkedIn industry IDs). When omitted, sellers may infer from the brand manifest's industries field."
        ),
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description="Override the account's default billing entity for this specific buy. When provided, the seller invoices this entity instead. The seller MUST validate the invoice recipient is authorized for this account. When governance_agents are configured, the seller MUST include invoice_recipient in the check_governance request."
        ),
    ] = None
    io_acceptance: Annotated[
        IoAcceptance | None,
        Field(
            description="Acceptance of an insertion order from a committed proposal. Required when the proposal's insertion_order has requires_signature: true. References the io_id from the proposal's insertion_order."
        ),
    ] = None
    po_number: Annotated[str | None, Field(description='Purchase order number for tracking')] = None
    name: Annotated[
        str | None,
        Field(
            description='Human-readable name for this media buy, shared by buyer and seller for trafficking UI display and operational communication. When supplied, the seller MUST persist it and echo it unchanged on the create success response and subsequent get_media_buys reads. This display label is not an identifier or financial reference.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    agency_estimate_number: Annotated[
        str | None,
        Field(
            description="Agency estimate or authorization number. Primary financial reference for broadcast buys — links the order to the agency's media plan and billing system. Travels with the order and creative traffic identifiers through the transaction lifecycle.",
            max_length=100,
        ),
    ] = None
    start_time: start_timing.StartTiming
    end_time: Annotated[
        AwareDatetime, Field(description='Campaign end date/time in ISO 8601 format')
    ]
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description="Aggregate pacing strategy for the media-buy budget across the media-buy flight. This controls how much the buy spends over time. Package pacing is subordinate and influences which package receives the aggregate spend; package pacing MUST NOT cause aggregate delivery to exceed this strategy. Defaults to even when total_budget is present. When executing a proposal that carries pacing, omit this field or send the identical value; the seller MUST reject a conflicting override with TERMS_REJECTED. In a seller-optimized buy, a seller declaring media_buy.features.seller_optimized_budget MUST accept omission and `even`; it MAY reject `asap` or `front_loaded` with UNSUPPORTED_FEATURE (error.field `pacing`) before any provider mutation and MUST NOT silently coerce them to `even`. Pacing carried by the seller's own committed proposal is not subject to that rejection. Fixed-allocation semantics are unchanged."
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description="Complete media-buy bidding default inherited by packages that omit package.bidding. `{automatic:true}` records an explicit automatic policy. In seller-optimized mode, cost_per/roas bind to the primary budget_allocation_1.optimization_goals goal. In fixed mode, inherited cost_per is valid only when inheriting package primary-goal result units are compatible; inherited roas requires value-bearing primary goals. Every monetary field uses total_budget.currency or the single currency derived for the media buy, and every affected pricing option MUST declare that currency. Sellers MUST reject incompatible units, combinations, currency, or overrides before mutation with BIDDING_PLACEMENT_CONFLICT. Media-buy bidding combined with any inheriting package's legacy bid_price or legacy monetary optimization-goal target is ambiguous and MUST be rejected with AMBIGUOUS_BIDDING_POLICY."
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(
            description="Create the media buy in a paused delivery state. When true, and the buy would otherwise be active because creatives are assigned and the flight has started, the seller returns media_buy_status 'paused'. Setup blockers still take precedence: a buy with no creatives remains 'pending_creatives', and a future-dated buy remains 'pending_start' until its flight can start. Defaults to false."
        ),
    ] = False
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async task status notifications. Publisher will send webhooks when status changes (working, input-required, completed, failed, canceled). Buyers SHOULD supply `push_notification_config_1.operation_id` as the canonical correlation value; publishers echo that field back verbatim in webhook payloads and MUST NOT parse the URL to derive it.'
        ),
    ] = None
    reporting_webhook: Annotated[
        reporting_webhook_1.ReportingWebhook | None,
        Field(description='Optional webhook configuration for automated reporting delivery'),
    ] = None
    artifact_webhook: Annotated[
        ArtifactWebhook | None,
        Field(
            description='Optional webhook configuration for content artifact delivery. Used by governance agents to validate content adjacency. Seller pushes artifacts to this endpoint; orchestrator forwards to governance agent for validation.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> CreateMediaBuyRequest:
        # ``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 (('packages',), ('packages', 'total_budget', 'budget_allocation'), ('proposal_id', 'total_budget'),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'CreateMediaBuyRequest requires at least one of these field groups: packages | packages+total_budget+budget_allocation | proposal_id+total_budget'
        )

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

Subclasses

• CreateMediaBuyRequest

Class variables

var account : AccountReference1 | AccountReference2

var advertiser_industry : AdvertiserIndustry | None

var agency_estimate_number : str | None

var artifact_webhook : ArtifactWebhook | None

var bidding : BiddingPolicy | None

var brand : BrandReference

var budget_allocation : BudgetAllocation1 | BudgetAllocation2 | None

var budget_cap_timezone : str | None

var context : ContextObject | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var governance_context : str | None

var idempotency_key : str

var invoice_recipient : BusinessEntity | None

var io_acceptance : IoAcceptance | None

var model_config

var name : str | None

var opportunity : Opportunity | None

var pacing : Pacing | None

var packages : collections.abc.Sequence[PackageRequest] | None

var paused : bool | None

var po_number : str | None

var proposal_id : str | None

var push_notification_config : PushNotificationConfig | None

var reporting_webhook : ReportingWebhook | None

var start_time : Literal['asap'] | pydantic.types.AwareDatetime

var total_budget : TotalBudget | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var plan_id : str | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 LegacyCreateMediaBuySuccessResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    status: Literal['completed'] = 'completed'
    proposal_id: Annotated[str, StringConstraints(min_length=1)] | None = None
    media_buy_id: str
    name: Annotated[str, StringConstraints(pattern='\\S', min_length=1, max_length=255)] | None = None
    account: account_1.Account | None = None
    invoice_recipient: business_entity_1.BusinessEntity | None = None
    media_buy_status: media_buy_status_1.MediaBuyStatus | None = None
    confirmed_at: AwareDatetime | None
    creative_deadline: AwareDatetime | None = None
    revision: Annotated[int, Field(ge=1)]
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')] | None = None
    total_budget: Annotated[float, Field(ge=0)] | None = None
    daily_budget_cap: Annotated[float, Field(ge=0)] | None = None
    frequency_cap: media_buy_frequency_cap_1.MediaBuyFrequencyCap | None = None
    budget_cap_timezone: str | None = None
    budget_allocation: Any | None = None
    pacing: pacing_1.Pacing | None = None
    bidding: Any | None = None
    valid_actions: list[media_buy_valid_action_1.MediaBuyValidAction] | None = None
    available_actions: list[media_buy_available_action_1.MediaBuyAvailableAction] | None = None
    packages: list[package_1.Package]
    planned_delivery: planned_delivery_1.PlannedDelivery | None = None
    warnings: list[warning_1.Warning] | None = None
    sandbox: bool | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='before')
    @classmethod
    def _normalize_legacy_status(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        raw_status = unwrap_enum_value(data.get('status'))
        media_buy_status = unwrap_enum_value(data.get('media_buy_status'))
        if raw_status is None:
            data = dict(data)
            data['status'] = 'completed'
        elif raw_status == 'completed':
            data = dict(data)
            data['status'] = 'completed'
        elif media_buy_status is None and raw_status in MEDIA_BUY_LEGACY_STATUS_VALUES:
            data = dict(data)
            data['media_buy_status'] = raw_status
            data['status'] = 'completed'
        elif media_buy_status is not None and raw_status == media_buy_status:
            data = dict(data)
            data['status'] = 'completed'
        return data

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

Subclasses

• CreateMediaBuyResponse1

Class variables

var account : Account | None

var available_actions : list[MediaBuyAvailableAction] | None

var bidding : typing.Any | None

var budget_allocation : typing.Any | None

var budget_cap_timezone : str | None

var confirmed_at : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var creative_deadline : pydantic.types.AwareDatetime | None

var currency : str | None

var daily_budget_cap : float | None

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var invoice_recipient : BusinessEntity | None

var media_buy_id : str

var media_buy_status : MediaBuyStatus | None

var model_config

var name : str | None

var pacing : Pacing | None

var packages : list[Package]

var planned_delivery : PlannedDelivery | None

var proposal_id : str | None

var revision : int

var sandbox : bool | None

var status : Literal['completed']

var total_budget : float | None

var valid_actions : list[MediaBuyValidAction] | None

var warnings : list[Warning] | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class CreateMediaBuyResponse1 (**data: Any)

Expand source code

class CreateMediaBuyResponse1(_LegacyCreateMediaBuyResponse1, CanonicalBoundaryModel):
    """Canonical create response preserving the 3.x legacy-status normalizer."""

    packages: list[Package]  # type: ignore[assignment]

    @model_validator(mode="before")
    @classmethod
    def _normalize_legacy_status(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        raw_status = unwrap_enum_value(data.get("status"))
        media_buy_status = unwrap_enum_value(data.get("media_buy_status"))
        if raw_status is None or raw_status == "completed":
            return {**data, "status": "completed"}
        if media_buy_status is None and raw_status in MEDIA_BUY_LEGACY_STATUS_VALUES:
            return {**data, "media_buy_status": raw_status, "status": "completed"}
        if media_buy_status is not None and raw_status == media_buy_status:
            return {**data, "status": "completed"}
        return data

Canonical create response preserving the 3.x legacy-status normalizer.

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

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

Class variables

var model_config

var packages : list[Package]

class CreateMediaBuySuccessResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse1(_LegacyCreateMediaBuyResponse1, CanonicalBoundaryModel):
    """Canonical create response preserving the 3.x legacy-status normalizer."""

    packages: list[Package]  # type: ignore[assignment]

    @model_validator(mode="before")
    @classmethod
    def _normalize_legacy_status(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        raw_status = unwrap_enum_value(data.get("status"))
        media_buy_status = unwrap_enum_value(data.get("media_buy_status"))
        if raw_status is None or raw_status == "completed":
            return {**data, "status": "completed"}
        if media_buy_status is None and raw_status in MEDIA_BUY_LEGACY_STATUS_VALUES:
            return {**data, "media_buy_status": raw_status, "status": "completed"}
        if media_buy_status is not None and raw_status == media_buy_status:
            return {**data, "status": "completed"}
        return data

Canonical create response preserving the 3.x legacy-status normalizer.

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

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

Class variables

var model_config

var packages : list[Package]

Inherited members

• CreateMediaBuyResponse1:
  • adcp_major_version
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class LegacyCreateMediaBuyErrorResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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

Subclasses

• CreateMediaBuyResponse2

Class variables

var context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

class CreateMediaBuyErrorResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse2(_LegacyCreateMediaBuyResponse2, CanonicalBoundaryModel):
    """Canonical create-media-buy error arm."""

Canonical create-media-buy error arm.

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

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

Class variables

var model_config

Inherited members

• CreateMediaBuyResponse2:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class LegacyCreateMediaBuySubmittedResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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

Subclasses

• CreateMediaBuyResponse3

Class variables

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

class CreateMediaBuySubmittedResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse3(_LegacyCreateMediaBuyResponse3, CanonicalBoundaryModel):
    """Canonical create-media-buy submitted arm."""

Canonical create-media-buy submitted arm.

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

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

Class variables

var model_config

Inherited members

• CreateMediaBuyResponse3:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class CreatePropertyListRequest (**data: Any)

Expand source code

class CreatePropertyListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that will own the list. Pass a natural key (brand, operator, optional sandbox) or a seller-assigned account_id from list_accounts. When omitted, this task applies its task-local single-account shortcut: if exactly one account is accessible to the authenticated caller, the seller may assign the list to that account; otherwise it MUST return an account-required or ambiguous-account error. Omission MUST NOT mean an undocumented credential-local default account.'
        ),
    ] = None
    name: Annotated[str, Field(description='Human-readable name for the list')]
    description: Annotated[str | None, Field(description="Description of the list's purpose")] = (
        None
    )
    base_properties: Annotated[
        list[base_property_source.BasePropertySource] | None,
        Field(
            description="Array of property sources to evaluate. Each entry is a discriminated union: publisher_tags (publisher_domain + tags), publisher_ids (publisher_domain + property_ids), or identifiers (direct identifiers). If omitted, queries the agent's entire property database.",
            min_length=1,
        ),
    ] = None
    filters: Annotated[
        property_list_filters.PropertyListFilters | None,
        Field(description='Dynamic filters to apply when resolving the list'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand reference. When provided, the agent automatically applies appropriate rules based on brand characteristics (industry, target_audience, etc.). Resolved at execution time.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate property list creation on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 account : AccountReference1 | AccountReference2 | None

var base_properties : list[BasePropertySource1 | BasePropertySource2 | BasePropertySource3] | None

var brand : BrandReference | None

var context : ContextObject | None

var description : str | None

var ext : ExtensionObject | None

var filters : PropertyListFilters | None

var idempotency_key : str

var model_config

var name : 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 CreatePropertyListResponse (**data: Any)

Expand source code

class CreatePropertyListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list: Annotated[property_list.PropertyList, Field(description='The created property list')]
    auth_token: Annotated[
        str,
        Field(
            description='Token that can be shared with sellers to authorize fetching this list. Store this - it is only returned at creation time.'
        ),
    ]
    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
    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.

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 auth_token : str

var context : ContextObject | None

var ext : ExtensionObject | None

var list : PropertyList

var model_config

var replayed : bool | 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 Creative (**data: Any)

Expand source code

class Creative(_CanonicalListedCreative, CanonicalBoundaryModel):
    """Canonical listed creative; the format kind is required, not optional.

    A listed creative is a row a seller RETURNS, so the kind is required but
    never confined: a kind a newer seller emits is retained as-is, which is
    what ``core/canonical-format-kind.json`` requires of a consumer.
    """

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_id: _RemovedFormatId = Field(default=None, init=False)

    format_kind: str

Canonical listed creative; the format kind is required, not optional.

A listed creative is a row a seller RETURNS, so the kind is required but never confined: a kind a newer seller emits is retained as-is, which is what core/canonical-format-kind.json requires of a consumer.

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

• Creative
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var format_id : FormatReferenceStructuredObject | None

var format_kind : str

var model_config

class SyncCreativeResult (**data: Any)

Expand source code

class Creative(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    creative_id: str
    revision_id: creative_revision_id_1.CreativeRevisionId | None = None
    account: account_1.Account | None = None
    action: creative_action_1.CreativeAction
    status: creative_status_1.CreativeStatus | None = None
    platform_id: str | None = None
    localization: creative_localization_readback_1.CreativeLocalizationReadback | None = None
    changes: list[str] | None = None
    errors: list[error_1.Error] | None = None
    warnings: list[str] | None = None
    macro_resolution_results: list[macro_resolution_result_1.MacroResolutionResult] | None = None
    preview_url: AnyUrl | None = None
    expires_at: AwareDatetime | None = None
    assigned_to: list[str] | None = None
    assignment_errors: dict[Annotated[str, StringConstraints(pattern='^[a-zA-Z0-9_-]+$')], str] | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var account : Account | None

var action : CreativeAction

var assigned_to : list[str] | None

var assignment_errors : dict[str, str] | None

var changes : list[str] | None

var creative_id : str

var errors : list[Error] | None

var expires_at : pydantic.types.AwareDatetime | None

var localization : CreativeLocalizationReadback | None

var macro_resolution_results : list[MacroResolutionResult] | None

var model_config

var platform_id : str | None

var preview_url : pydantic.networks.AnyUrl | None

var revision_id : CreativeRevisionId | None

var status : CreativeStatus | None

var warnings : list[str] | None

class DeliveryCreative (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Creative identifier')]
    media_buy_id: Annotated[
        str | None,
        Field(
            description="Publisher's media buy identifier for this creative. Present when the request spanned multiple media buys, so the buyer can correlate each creative to its media buy."
        ),
    ] = None
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named format of this creative. New responses use `format_kind` and optional `format_option_ref`.',
        ),
    ] = None
    format_kind: Annotated[
        str | None, Field(description='Canonical format kind delivered for this creative.')
    ] = None
    format_option_ref: Annotated[
        format_option_ref_1.FormatOptionReference | None,
        Field(
            description='Portable reference to the product or publisher format option used for delivery, when disambiguation is required.'
        ),
    ] = None
    totals: Annotated[
        delivery_metrics.DeliveryMetrics | None,
        Field(description='Aggregate delivery metrics across all variants of this creative'),
    ] = None
    variant_count: Annotated[
        SchemaInt | None,
        Field(
            description='Total number of agent-unique variant_id rows for this creative. When max_variants was specified in the request, this may exceed the number of items in the variants array.',
            ge=0,
        ),
    ] = None
    variants: Annotated[
        list[creative_variant.CreativeVariant],
        Field(
            description='Variant-level delivery breakdown. Each agent-unique variant_id identifies one immutable served execution and each row includes metrics from exactly one source revision and, for localized delivery, exactly one locale variant. A distinct revision, locale, or rendered manifest receives a distinct variant_id; metrics MUST NOT cross those boundaries. For standard creatives, contains one row per source revision and locale represented in the reporting period. For asset group optimization, one per combination, source revision, and locale. For generative creative, one per generated execution, source revision, and locale. Empty when a creative has no variants yet.'
        ),
    ]

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

• DeliveryCreative

Class variables

var creative_id : str

var format_kind : str | None

var format_option_ref : FormatOptionReference1 | FormatOptionReference2 | None

var media_buy_id : str | None

var model_config

var totals : DeliveryMetrics | None

var variant_count : int | None

var variants : list[adcp.types._forward_compat._DeliveryVariant]

Instance variables

var format_id : FormatReferenceStructuredObject | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class ListCreativesCreative (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    revision_id: Annotated[
        creative_revision_id.CreativeRevisionId | None,
        Field(
            description='Current buyer-authored input revision for this creative. Present when the current effective content has revision identity and the seller advertises creative.supports_revisions; omitted after an accepted content-bearing legacy update without revision_id.'
        ),
    ] = None
    representation_selection: Annotated[
        representation_selection_1.RepresentationSelection | None,
        Field(
            description='Exact source-set and selected-output lineage retained when the current stored creative was resolved from a CreativeRepresentationSet.'
        ),
    ] = None
    account: Annotated[
        account_1.Account | None, Field(description='Account that owns this creative')
    ] = None
    name: Annotated[str, Field(description='Human-readable creative name')]
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format path. New listed creatives use `format_kind` and optional `format_option_ref`.',
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Canonical 3.2 path. The canonical format kind this creative targets. Mutually exclusive with deprecated `format_id`.'
        ),
    ] = None
    format_option_ref: Annotated[
        format_option_ref_1.FormatOptionReference | None,
        Field(
            description='Optional reference to the concrete canonical format option this creative targets. Required when `format_kind` alone is ambiguous in the enclosing product context.'
        ),
    ] = None
    status: Annotated[
        creative_status.CreativeStatus, Field(description='Current approval status of the creative')
    ]
    created_date: Annotated[AwareDatetime, Field(description='When the creative was created')]
    updated_date: Annotated[AwareDatetime, Field(description='When the creative was last modified')]
    assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z0-9_]+$')], asset_union.AssetVariant | Assets] | None,
        Field(
            description='Assets for this creative, keyed by asset_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema.'
        ),
    ] = None
    component_assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z][a-z0-9_]*$')], creative_assets.CreativeAssets] | None,
        Field(
            description='Preserved component-addressed asset maps for `coordinated_placements`, keyed by coordinated component ID.'
        ),
    ] = None
    localization: Annotated[
        creative_localization_readback.CreativeLocalizationReadback | None,
        Field(
            description='Authoritative exact materialized locale-variant state. Present for localized creatives when complete. The enclosing creative status is the single review lifecycle for all variants.'
        ),
    ] = None
    localization_unavailable: Annotated[
        LocalizationUnavailable | None,
        Field(
            description='Per-creative fail-closed state returned instead of localization when the seller knows the creative is localized but cannot construct complete exact readback. The creative remains in this page and counts toward query_summary.returned and pagination; buyers may continue using the base creative fields but MUST NOT infer locale eligibility.'
        ),
    ] = None
    tags: Annotated[
        list[str] | None, Field(description='User-defined tags for organization and searchability')
    ] = None
    rights: Annotated[
        list[rights_constraint.RightsConstraint] | None,
        Field(
            description="Exact rights constraints retained from the buyer's creative submission. Presence is presentation readback, not proof that the seller accepted or verified the rights.",
            min_length=1,
        ),
    ] = None
    rights_attestation_evaluations: Annotated[
        list[rights_attestation_evaluation.RightsAttestationEvaluation] | None,
        Field(
            description="Complete seller-produced verifier-of-record results for retained rights references. Buyers MUST ignore any evaluation they originally supplied and rely only on this seller readback for this seller's eligibility decision. This array has no independent item ceiling because rights is not capped; under a required policy every applicable retained constraint needs a corresponding current verified result.",
            min_length=1,
        ),
    ] = None
    concept_id: Annotated[
        str | None,
        Field(
            description='Creative concept this creative belongs to. Concepts group related creatives across sizes and formats.'
        ),
    ] = None
    concept_name: Annotated[str | None, Field(description='Human-readable concept name')] = None
    variables: Annotated[
        list[creative_variable.CreativeVariable] | None,
        Field(
            description='Dynamic content variables (DCO slots) for this creative. Included when include_variables=true.'
        ),
    ] = None
    assignments: Annotated[
        Assignments | None,
        Field(description='Current package assignments (included when include_assignments=true)'),
    ] = None
    snapshot: Annotated[
        Snapshot | None,
        Field(
            description='Lightweight delivery snapshot (included when include_snapshot=true). For detailed performance analytics, use get_creative_delivery.'
        ),
    ] = None
    snapshot_unavailable_reason: Annotated[
        snapshot_unavailable_reason_1.SnapshotUnavailableReason | None,
        Field(
            description='Machine-readable reason the snapshot is omitted. Present only when include_snapshot was true and snapshot data is unavailable for this creative.'
        ),
    ] = None
    items: Annotated[
        list[creative_item.CreativeItem] | None,
        Field(
            description='Items for multi-asset formats like carousels and native ads (included when include_items=true)'
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for using this creative (serving, delivery). Used by ad servers and library agents. Transformation agents expose build pricing on canonical transformer.pricing_options entries from list_transformers instead. Present when include_pricing=true and account provided. The buyer passes the applied pricing_option_id in report_usage.',
            min_length=1,
        ),
    ] = None
    purge: Annotated[
        Purge | None,
        Field(
            description="Tombstone block — present only when this record is a soft-purged creative surfaced via `include_purged: true`. The record's `status` field reflects the last status before purge (frozen — buyers MUST treat the creative as gone; assignments, snapshot, and serving operations no longer apply). Tombstones surface for the seller's webhook activity retention window (30 days from `purge.at`). Hard purges (`purge_kind: hard` on the webhook) do not surface on this read — the [`creative.purged`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) webhook is the only signal."
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook fires scoped to this creative — creative.status_changed, creative.purged, creative.assignment_changed, and assignment-level indicators.changed deliveries. Present only when include_webhook_activity is true. Account-anchored records include subscriber_id; the parent creative_id disambiguates the record. Retention: 30 days from completed_at. See snapshot-and-log.mdx § Webhook activity log pattern.',
            max_length=200,
        ),
    ] = None


    @model_validator(mode='after')
    def _validate_format_reference_xor(self) -> Creative:
        if (self.format_id is None) == (self.format_kind is None):
            raise ValueError('exactly one of format_id and format_kind is required')
        return self

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

• Creative

Class variables

var account : Account | None

var assets : dict[str, typing.Union[ImageAsset, VideoAsset, AudioAsset, VastAsset, DisplayTagAsset, TextAsset, UrlAsset, HtmlAsset, JavascriptAsset, ZipAsset, WebhookAsset, CssAsset, DaastAsset, MarkdownAsset, BriefAsset, CatalogAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VastTrackerAsset, DaastTrackerAsset, Assets]] | None

var assignments : Assignments | None

var component_assets : dict[str, CreativeAssets] | None

var concept_id : str | None

var concept_name : str | None

var created_date : pydantic.types.AwareDatetime

var creative_id : str

var format_id : FormatReferenceStructuredObject | None

var format_kind : str | None

var format_option_ref : FormatOptionReference1 | FormatOptionReference2 | None

var items : list[CreativeItem1 | CreativeItem2] | None

var localization : CreativeLocalizationReadback | None

var localization_unavailable : LocalizationUnavailable | None

var model_config

var name : str

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var purge : Purge | None

var representation_selection : RepresentationSelection | None

var revision_id : CreativeRevisionId | None

var rights : list[RightsConstraint] | None

var rights_attestation_evaluations : list[RightsAttestationEvaluation] | None

var snapshot : Snapshot | None

var snapshot_unavailable_reason : SnapshotUnavailableReason | None

var status : CreativeStatus

var tags : list[str] | None

var updated_date : pydantic.types.AwareDatetime

var variables : list[CreativeVariable] | None

var webhook_activity : list[WebhookActivityRecord] | None

class ListCreativesLegacyCreative (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    revision_id: Annotated[
        creative_revision_id.CreativeRevisionId | None,
        Field(
            description='Current buyer-authored input revision for this creative. Present when the current effective content has revision identity and the seller advertises creative.supports_revisions; omitted after an accepted content-bearing legacy update without revision_id.'
        ),
    ] = None
    representation_selection: Annotated[
        representation_selection_1.RepresentationSelection | None,
        Field(
            description='Exact source-set and selected-output lineage retained when the current stored creative was resolved from a CreativeRepresentationSet.'
        ),
    ] = None
    account: Annotated[
        account_1.Account | None, Field(description='Account that owns this creative')
    ] = None
    name: Annotated[str, Field(description='Human-readable creative name')]
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format path. New listed creatives use `format_kind` and optional `format_option_ref`.',
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Canonical 3.2 path. The canonical format kind this creative targets. Mutually exclusive with deprecated `format_id`.'
        ),
    ] = None
    format_option_ref: Annotated[
        format_option_ref_1.FormatOptionReference | None,
        Field(
            description='Optional reference to the concrete canonical format option this creative targets. Required when `format_kind` alone is ambiguous in the enclosing product context.'
        ),
    ] = None
    status: Annotated[
        creative_status.CreativeStatus, Field(description='Current approval status of the creative')
    ]
    created_date: Annotated[AwareDatetime, Field(description='When the creative was created')]
    updated_date: Annotated[AwareDatetime, Field(description='When the creative was last modified')]
    assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z0-9_]+$')], asset_union.AssetVariant | Assets] | None,
        Field(
            description='Assets for this creative, keyed by asset_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema.'
        ),
    ] = None
    component_assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z][a-z0-9_]*$')], creative_assets.CreativeAssets] | None,
        Field(
            description='Preserved component-addressed asset maps for `coordinated_placements`, keyed by coordinated component ID.'
        ),
    ] = None
    localization: Annotated[
        creative_localization_readback.CreativeLocalizationReadback | None,
        Field(
            description='Authoritative exact materialized locale-variant state. Present for localized creatives when complete. The enclosing creative status is the single review lifecycle for all variants.'
        ),
    ] = None
    localization_unavailable: Annotated[
        LocalizationUnavailable | None,
        Field(
            description='Per-creative fail-closed state returned instead of localization when the seller knows the creative is localized but cannot construct complete exact readback. The creative remains in this page and counts toward query_summary.returned and pagination; buyers may continue using the base creative fields but MUST NOT infer locale eligibility.'
        ),
    ] = None
    tags: Annotated[
        list[str] | None, Field(description='User-defined tags for organization and searchability')
    ] = None
    rights: Annotated[
        list[rights_constraint.RightsConstraint] | None,
        Field(
            description="Exact rights constraints retained from the buyer's creative submission. Presence is presentation readback, not proof that the seller accepted or verified the rights.",
            min_length=1,
        ),
    ] = None
    rights_attestation_evaluations: Annotated[
        list[rights_attestation_evaluation.RightsAttestationEvaluation] | None,
        Field(
            description="Complete seller-produced verifier-of-record results for retained rights references. Buyers MUST ignore any evaluation they originally supplied and rely only on this seller readback for this seller's eligibility decision. This array has no independent item ceiling because rights is not capped; under a required policy every applicable retained constraint needs a corresponding current verified result.",
            min_length=1,
        ),
    ] = None
    concept_id: Annotated[
        str | None,
        Field(
            description='Creative concept this creative belongs to. Concepts group related creatives across sizes and formats.'
        ),
    ] = None
    concept_name: Annotated[str | None, Field(description='Human-readable concept name')] = None
    variables: Annotated[
        list[creative_variable.CreativeVariable] | None,
        Field(
            description='Dynamic content variables (DCO slots) for this creative. Included when include_variables=true.'
        ),
    ] = None
    assignments: Annotated[
        Assignments | None,
        Field(description='Current package assignments (included when include_assignments=true)'),
    ] = None
    snapshot: Annotated[
        Snapshot | None,
        Field(
            description='Lightweight delivery snapshot (included when include_snapshot=true). For detailed performance analytics, use get_creative_delivery.'
        ),
    ] = None
    snapshot_unavailable_reason: Annotated[
        snapshot_unavailable_reason_1.SnapshotUnavailableReason | None,
        Field(
            description='Machine-readable reason the snapshot is omitted. Present only when include_snapshot was true and snapshot data is unavailable for this creative.'
        ),
    ] = None
    items: Annotated[
        list[creative_item.CreativeItem] | None,
        Field(
            description='Items for multi-asset formats like carousels and native ads (included when include_items=true)'
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for using this creative (serving, delivery). Used by ad servers and library agents. Transformation agents expose build pricing on canonical transformer.pricing_options entries from list_transformers instead. Present when include_pricing=true and account provided. The buyer passes the applied pricing_option_id in report_usage.',
            min_length=1,
        ),
    ] = None
    purge: Annotated[
        Purge | None,
        Field(
            description="Tombstone block — present only when this record is a soft-purged creative surfaced via `include_purged: true`. The record's `status` field reflects the last status before purge (frozen — buyers MUST treat the creative as gone; assignments, snapshot, and serving operations no longer apply). Tombstones surface for the seller's webhook activity retention window (30 days from `purge.at`). Hard purges (`purge_kind: hard` on the webhook) do not surface on this read — the [`creative.purged`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) webhook is the only signal."
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook fires scoped to this creative — creative.status_changed, creative.purged, creative.assignment_changed, and assignment-level indicators.changed deliveries. Present only when include_webhook_activity is true. Account-anchored records include subscriber_id; the parent creative_id disambiguates the record. Retention: 30 days from completed_at. See snapshot-and-log.mdx § Webhook activity log pattern.',
            max_length=200,
        ),
    ] = None


    @model_validator(mode='after')
    def _validate_format_reference_xor(self) -> Creative:
        if (self.format_id is None) == (self.format_kind is None):
            raise ValueError('exactly one of format_id and format_kind is required')
        return self

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

• Creative

Class variables

var account : Account | None

var assets : dict[str, typing.Union[ImageAsset, VideoAsset, AudioAsset, VastAsset, DisplayTagAsset, TextAsset, UrlAsset, HtmlAsset, JavascriptAsset, ZipAsset, WebhookAsset, CssAsset, DaastAsset, MarkdownAsset, BriefAsset, CatalogAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VastTrackerAsset, DaastTrackerAsset, Assets]] | None

var assignments : Assignments | None

var component_assets : dict[str, CreativeAssets] | None

var concept_id : str | None

var concept_name : str | None

var created_date : pydantic.types.AwareDatetime

var creative_id : str

var format_id : FormatReferenceStructuredObject | None

var format_kind : str | None

var format_option_ref : FormatOptionReference1 | FormatOptionReference2 | None

var items : list[CreativeItem1 | CreativeItem2] | None

var localization : CreativeLocalizationReadback | None

var localization_unavailable : LocalizationUnavailable | None

var model_config

var name : str

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var purge : Purge | None

var representation_selection : RepresentationSelection | None

var revision_id : CreativeRevisionId | None

var rights : list[RightsConstraint] | None

var rights_attestation_evaluations : list[RightsAttestationEvaluation] | None

var snapshot : Snapshot | None

var snapshot_unavailable_reason : SnapshotUnavailableReason | None

var status : CreativeStatus

var tags : list[str] | None

var updated_date : pydantic.types.AwareDatetime

var variables : list[CreativeVariable] | None

var webhook_activity : list[WebhookActivityRecord] | None

class ListCreativesCanonicalCreative (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    revision_id: Annotated[
        creative_revision_id.CreativeRevisionId | None,
        Field(
            description='Current buyer-authored input revision for this creative. Present when the current effective content has revision identity and the seller advertises creative.supports_revisions; omitted after an accepted content-bearing legacy update without revision_id.'
        ),
    ] = None
    representation_selection: Annotated[
        representation_selection_1.RepresentationSelection | None,
        Field(
            description='Exact source-set and selected-output lineage retained when the current stored creative was resolved from a CreativeRepresentationSet.'
        ),
    ] = None
    account: Annotated[
        account_1.Account | None, Field(description='Account that owns this creative')
    ] = None
    name: Annotated[str, Field(description='Human-readable creative name')]
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format path. New listed creatives use `format_kind` and optional `format_option_ref`.',
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Canonical 3.2 path. The canonical format kind this creative targets. Mutually exclusive with deprecated `format_id`.'
        ),
    ] = None
    format_option_ref: Annotated[
        format_option_ref_1.FormatOptionReference | None,
        Field(
            description='Optional reference to the concrete canonical format option this creative targets. Required when `format_kind` alone is ambiguous in the enclosing product context.'
        ),
    ] = None
    status: Annotated[
        creative_status.CreativeStatus, Field(description='Current approval status of the creative')
    ]
    created_date: Annotated[AwareDatetime, Field(description='When the creative was created')]
    updated_date: Annotated[AwareDatetime, Field(description='When the creative was last modified')]
    assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z0-9_]+$')], asset_union.AssetVariant | Assets] | None,
        Field(
            description='Assets for this creative, keyed by asset_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema.'
        ),
    ] = None
    component_assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z][a-z0-9_]*$')], creative_assets.CreativeAssets] | None,
        Field(
            description='Preserved component-addressed asset maps for `coordinated_placements`, keyed by coordinated component ID.'
        ),
    ] = None
    localization: Annotated[
        creative_localization_readback.CreativeLocalizationReadback | None,
        Field(
            description='Authoritative exact materialized locale-variant state. Present for localized creatives when complete. The enclosing creative status is the single review lifecycle for all variants.'
        ),
    ] = None
    localization_unavailable: Annotated[
        LocalizationUnavailable | None,
        Field(
            description='Per-creative fail-closed state returned instead of localization when the seller knows the creative is localized but cannot construct complete exact readback. The creative remains in this page and counts toward query_summary.returned and pagination; buyers may continue using the base creative fields but MUST NOT infer locale eligibility.'
        ),
    ] = None
    tags: Annotated[
        list[str] | None, Field(description='User-defined tags for organization and searchability')
    ] = None
    rights: Annotated[
        list[rights_constraint.RightsConstraint] | None,
        Field(
            description="Exact rights constraints retained from the buyer's creative submission. Presence is presentation readback, not proof that the seller accepted or verified the rights.",
            min_length=1,
        ),
    ] = None
    rights_attestation_evaluations: Annotated[
        list[rights_attestation_evaluation.RightsAttestationEvaluation] | None,
        Field(
            description="Complete seller-produced verifier-of-record results for retained rights references. Buyers MUST ignore any evaluation they originally supplied and rely only on this seller readback for this seller's eligibility decision. This array has no independent item ceiling because rights is not capped; under a required policy every applicable retained constraint needs a corresponding current verified result.",
            min_length=1,
        ),
    ] = None
    concept_id: Annotated[
        str | None,
        Field(
            description='Creative concept this creative belongs to. Concepts group related creatives across sizes and formats.'
        ),
    ] = None
    concept_name: Annotated[str | None, Field(description='Human-readable concept name')] = None
    variables: Annotated[
        list[creative_variable.CreativeVariable] | None,
        Field(
            description='Dynamic content variables (DCO slots) for this creative. Included when include_variables=true.'
        ),
    ] = None
    assignments: Annotated[
        Assignments | None,
        Field(description='Current package assignments (included when include_assignments=true)'),
    ] = None
    snapshot: Annotated[
        Snapshot | None,
        Field(
            description='Lightweight delivery snapshot (included when include_snapshot=true). For detailed performance analytics, use get_creative_delivery.'
        ),
    ] = None
    snapshot_unavailable_reason: Annotated[
        snapshot_unavailable_reason_1.SnapshotUnavailableReason | None,
        Field(
            description='Machine-readable reason the snapshot is omitted. Present only when include_snapshot was true and snapshot data is unavailable for this creative.'
        ),
    ] = None
    items: Annotated[
        list[creative_item.CreativeItem] | None,
        Field(
            description='Items for multi-asset formats like carousels and native ads (included when include_items=true)'
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for using this creative (serving, delivery). Used by ad servers and library agents. Transformation agents expose build pricing on canonical transformer.pricing_options entries from list_transformers instead. Present when include_pricing=true and account provided. The buyer passes the applied pricing_option_id in report_usage.',
            min_length=1,
        ),
    ] = None
    purge: Annotated[
        Purge | None,
        Field(
            description="Tombstone block — present only when this record is a soft-purged creative surfaced via `include_purged: true`. The record's `status` field reflects the last status before purge (frozen — buyers MUST treat the creative as gone; assignments, snapshot, and serving operations no longer apply). Tombstones surface for the seller's webhook activity retention window (30 days from `purge.at`). Hard purges (`purge_kind: hard` on the webhook) do not surface on this read — the [`creative.purged`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) webhook is the only signal."
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook fires scoped to this creative — creative.status_changed, creative.purged, creative.assignment_changed, and assignment-level indicators.changed deliveries. Present only when include_webhook_activity is true. Account-anchored records include subscriber_id; the parent creative_id disambiguates the record. Retention: 30 days from completed_at. See snapshot-and-log.mdx § Webhook activity log pattern.',
            max_length=200,
        ),
    ] = None


    @model_validator(mode='after')
    def _validate_format_reference_xor(self) -> Creative:
        if (self.format_id is None) == (self.format_kind is None):
            raise ValueError('exactly one of format_id and format_kind is required')
        return self

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

• Creative

Class variables

var account : Account | None

var assets : dict[str, typing.Union[ImageAsset, VideoAsset, AudioAsset, VastAsset, DisplayTagAsset, TextAsset, UrlAsset, HtmlAsset, JavascriptAsset, ZipAsset, WebhookAsset, CssAsset, DaastAsset, MarkdownAsset, BriefAsset, CatalogAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VastTrackerAsset, DaastTrackerAsset, Assets]] | None

var assignments : Assignments | None

var component_assets : dict[str, CreativeAssets] | None

var concept_id : str | None

var concept_name : str | None

var created_date : pydantic.types.AwareDatetime

var creative_id : str

var format_id : FormatReferenceStructuredObject | None

var format_kind : str | None

var format_option_ref : FormatOptionReference1 | FormatOptionReference2 | None

var items : list[CreativeItem1 | CreativeItem2] | None

var localization : CreativeLocalizationReadback | None

var localization_unavailable : LocalizationUnavailable | None

var model_config

var name : str

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var purge : Purge | None

var representation_selection : RepresentationSelection | None

var revision_id : CreativeRevisionId | None

var rights : list[RightsConstraint] | None

var rights_attestation_evaluations : list[RightsAttestationEvaluation] | None

var snapshot : Snapshot | None

var snapshot_unavailable_reason : SnapshotUnavailableReason | None

var status : CreativeStatus

var tags : list[str] | None

var updated_date : pydantic.types.AwareDatetime

var variables : list[CreativeVariable] | None

var webhook_activity : list[WebhookActivityRecord] | None

class ListCreativesCreativeItem (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    revision_id: Annotated[
        creative_revision_id.CreativeRevisionId | None,
        Field(
            description='Current buyer-authored input revision for this creative. Present when the current effective content has revision identity and the seller advertises creative.supports_revisions; omitted after an accepted content-bearing legacy update without revision_id.'
        ),
    ] = None
    representation_selection: Annotated[
        representation_selection_1.RepresentationSelection | None,
        Field(
            description='Exact source-set and selected-output lineage retained when the current stored creative was resolved from a CreativeRepresentationSet.'
        ),
    ] = None
    account: Annotated[
        account_1.Account | None, Field(description='Account that owns this creative')
    ] = None
    name: Annotated[str, Field(description='Human-readable creative name')]
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format path. New listed creatives use `format_kind` and optional `format_option_ref`.',
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Canonical 3.2 path. The canonical format kind this creative targets. Mutually exclusive with deprecated `format_id`.'
        ),
    ] = None
    format_option_ref: Annotated[
        format_option_ref_1.FormatOptionReference | None,
        Field(
            description='Optional reference to the concrete canonical format option this creative targets. Required when `format_kind` alone is ambiguous in the enclosing product context.'
        ),
    ] = None
    status: Annotated[
        creative_status.CreativeStatus, Field(description='Current approval status of the creative')
    ]
    created_date: Annotated[AwareDatetime, Field(description='When the creative was created')]
    updated_date: Annotated[AwareDatetime, Field(description='When the creative was last modified')]
    assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z0-9_]+$')], asset_union.AssetVariant | Assets] | None,
        Field(
            description='Assets for this creative, keyed by asset_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema.'
        ),
    ] = None
    component_assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z][a-z0-9_]*$')], creative_assets.CreativeAssets] | None,
        Field(
            description='Preserved component-addressed asset maps for `coordinated_placements`, keyed by coordinated component ID.'
        ),
    ] = None
    localization: Annotated[
        creative_localization_readback.CreativeLocalizationReadback | None,
        Field(
            description='Authoritative exact materialized locale-variant state. Present for localized creatives when complete. The enclosing creative status is the single review lifecycle for all variants.'
        ),
    ] = None
    localization_unavailable: Annotated[
        LocalizationUnavailable | None,
        Field(
            description='Per-creative fail-closed state returned instead of localization when the seller knows the creative is localized but cannot construct complete exact readback. The creative remains in this page and counts toward query_summary.returned and pagination; buyers may continue using the base creative fields but MUST NOT infer locale eligibility.'
        ),
    ] = None
    tags: Annotated[
        list[str] | None, Field(description='User-defined tags for organization and searchability')
    ] = None
    rights: Annotated[
        list[rights_constraint.RightsConstraint] | None,
        Field(
            description="Exact rights constraints retained from the buyer's creative submission. Presence is presentation readback, not proof that the seller accepted or verified the rights.",
            min_length=1,
        ),
    ] = None
    rights_attestation_evaluations: Annotated[
        list[rights_attestation_evaluation.RightsAttestationEvaluation] | None,
        Field(
            description="Complete seller-produced verifier-of-record results for retained rights references. Buyers MUST ignore any evaluation they originally supplied and rely only on this seller readback for this seller's eligibility decision. This array has no independent item ceiling because rights is not capped; under a required policy every applicable retained constraint needs a corresponding current verified result.",
            min_length=1,
        ),
    ] = None
    concept_id: Annotated[
        str | None,
        Field(
            description='Creative concept this creative belongs to. Concepts group related creatives across sizes and formats.'
        ),
    ] = None
    concept_name: Annotated[str | None, Field(description='Human-readable concept name')] = None
    variables: Annotated[
        list[creative_variable.CreativeVariable] | None,
        Field(
            description='Dynamic content variables (DCO slots) for this creative. Included when include_variables=true.'
        ),
    ] = None
    assignments: Annotated[
        Assignments | None,
        Field(description='Current package assignments (included when include_assignments=true)'),
    ] = None
    snapshot: Annotated[
        Snapshot | None,
        Field(
            description='Lightweight delivery snapshot (included when include_snapshot=true). For detailed performance analytics, use get_creative_delivery.'
        ),
    ] = None
    snapshot_unavailable_reason: Annotated[
        snapshot_unavailable_reason_1.SnapshotUnavailableReason | None,
        Field(
            description='Machine-readable reason the snapshot is omitted. Present only when include_snapshot was true and snapshot data is unavailable for this creative.'
        ),
    ] = None
    items: Annotated[
        list[creative_item.CreativeItem] | None,
        Field(
            description='Items for multi-asset formats like carousels and native ads (included when include_items=true)'
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for using this creative (serving, delivery). Used by ad servers and library agents. Transformation agents expose build pricing on canonical transformer.pricing_options entries from list_transformers instead. Present when include_pricing=true and account provided. The buyer passes the applied pricing_option_id in report_usage.',
            min_length=1,
        ),
    ] = None
    purge: Annotated[
        Purge | None,
        Field(
            description="Tombstone block — present only when this record is a soft-purged creative surfaced via `include_purged: true`. The record's `status` field reflects the last status before purge (frozen — buyers MUST treat the creative as gone; assignments, snapshot, and serving operations no longer apply). Tombstones surface for the seller's webhook activity retention window (30 days from `purge.at`). Hard purges (`purge_kind: hard` on the webhook) do not surface on this read — the [`creative.purged`](https://adcontextprotocol.org/schemas/v3/creative/creative-purged-webhook.json) webhook is the only signal."
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook fires scoped to this creative — creative.status_changed, creative.purged, creative.assignment_changed, and assignment-level indicators.changed deliveries. Present only when include_webhook_activity is true. Account-anchored records include subscriber_id; the parent creative_id disambiguates the record. Retention: 30 days from completed_at. See snapshot-and-log.mdx § Webhook activity log pattern.',
            max_length=200,
        ),
    ] = None


    @model_validator(mode='after')
    def _validate_format_reference_xor(self) -> Creative:
        if (self.format_id is None) == (self.format_kind is None):
            raise ValueError('exactly one of format_id and format_kind is required')
        return self

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

• Creative

Class variables

var account : Account | None

var assets : dict[str, typing.Union[ImageAsset, VideoAsset, AudioAsset, VastAsset, DisplayTagAsset, TextAsset, UrlAsset, HtmlAsset, JavascriptAsset, ZipAsset, WebhookAsset, CssAsset, DaastAsset, MarkdownAsset, BriefAsset, CatalogAsset, PublishedPostAsset, CardAsset, PixelTrackerAsset, VastTrackerAsset, DaastTrackerAsset, Assets]] | None

var assignments : Assignments | None

var component_assets : dict[str, CreativeAssets] | None

var concept_id : str | None

var concept_name : str | None

var created_date : pydantic.types.AwareDatetime

var creative_id : str

var format_id : FormatReferenceStructuredObject | None

var format_kind : str | None

var format_option_ref : FormatOptionReference1 | FormatOptionReference2 | None

var items : list[CreativeItem1 | CreativeItem2] | None

var localization : CreativeLocalizationReadback | None

var localization_unavailable : LocalizationUnavailable | None

var model_config

var name : str

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var purge : Purge | None

var representation_selection : RepresentationSelection | None

var revision_id : CreativeRevisionId | None

var rights : list[RightsConstraint] | None

var rights_attestation_evaluations : list[RightsAttestationEvaluation] | None

var snapshot : Snapshot | None

var snapshot_unavailable_reason : SnapshotUnavailableReason | None

var status : CreativeStatus

var tags : list[str] | None

var updated_date : pydantic.types.AwareDatetime

var variables : list[CreativeVariable] | None

var webhook_activity : list[WebhookActivityRecord] | None

class SyncCreativesCreative (**data: Any)

Expand source code

class Creative(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    creative_id: str
    revision_id: creative_revision_id_1.CreativeRevisionId | None = None
    account: account_1.Account | None = None
    action: creative_action_1.CreativeAction
    status: creative_status_1.CreativeStatus | None = None
    platform_id: str | None = None
    localization: creative_localization_readback_1.CreativeLocalizationReadback | None = None
    changes: list[str] | None = None
    errors: list[error_1.Error] | None = None
    warnings: list[str] | None = None
    macro_resolution_results: list[macro_resolution_result_1.MacroResolutionResult] | None = None
    preview_url: AnyUrl | None = None
    expires_at: AwareDatetime | None = None
    assigned_to: list[str] | None = None
    assignment_errors: dict[Annotated[str, StringConstraints(pattern='^[a-zA-Z0-9_-]+$')], str] | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var account : Account | None

var action : CreativeAction

var assigned_to : list[str] | None

var assignment_errors : dict[str, str] | None

var changes : list[str] | None

var creative_id : str

var errors : list[Error] | None

var expires_at : pydantic.types.AwareDatetime | None

var localization : CreativeLocalizationReadback | None

var macro_resolution_results : list[MacroResolutionResult] | None

var model_config

var platform_id : str | None

var preview_url : pydantic.networks.AnyUrl | None

var revision_id : CreativeRevisionId | None

var status : CreativeStatus | None

var warnings : list[str] | None

class BuildCreativeCreative (**data: Any)

Expand source code

class Creative(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    build_creative_id: str | None = None
    catalog_item_ref: CatalogItemRef | None = None
    signal_condition: signal_targeting_1.SignalTargeting | None = None
    variants: Annotated[list[Variant], Field(min_length=1)] | None = None
    errors: Annotated[list[error_1.Error], Field(min_length=1)] | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var build_creative_id : str | None

var catalog_item_ref : CatalogItemRef | None

var errors : list[Error] | None

var model_config

var signal_condition : SignalTargeting1 | SignalTargeting2 | SignalTargeting3 | None

var variants : list[Variant] | None

class CapabilitiesCreative (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    supports_compliance: Annotated[
        StrictBool | None,
        Field(
            description='When true, this creative agent can process briefs with compliance requirements (required_disclosures, prohibited_claims) and will validate that disclosures can be satisfied by the target format.'
        ),
    ] = None
    has_creative_library: Annotated[
        StrictBool | None,
        Field(
            description='When true, this agent hosts a creative library and supports list_creatives and creative_id references in build_creative. Creative agents with a library should also implement the accounts protocol (sync_accounts / list_accounts) so buyers can establish access.'
        ),
    ] = False
    supports_revisions: Annotated[
        StrictBool | None,
        Field(
            description='When true, this agent accepts buyer-assigned revision_id on sync_creatives, enforces immutable revision content, echoes accepted revision identity, returns it from list_creatives, and attributes delivered executions to it. Revision support does not imply revision history, rollback, or staged activation.'
        ),
    ] = False
    supports_generation: Annotated[
        StrictBool | None,
        Field(
            description='When true, this agent can generate creatives from natural language briefs via build_creative. The buyer provides a message with creative direction, and the agent produces a manifest with generated assets. When false, build_creative only supports transformation or library retrieval.'
        ),
    ] = False
    supports_transformation: Annotated[
        StrictBool | None,
        Field(
            description='When true, this agent can transform or resize existing canonical manifests via build_creative. The buyer supplies a creative_manifest and an advertised target_capability_id.'
        ),
    ] = False
    representation_resolution: Annotated[
        RepresentationResolution | None,
        Field(
            description='Explicit opt-in for deterministic seller-bound selection from `build_creative.creative_representation_set`. Only the destination sales agent may advertise and exercise this capability because resolution requires its current product, placement/publisher narrowings, and seller-wide execution ceilings. A standalone creative agent may help a buyer select locally but MUST NOT advertise this capability or claim seller deliverability. Absence means the caller selects a representation before sending a seller-bound manifest; the agent MUST NOT guess silently.'
        ),
    ] = None
    supports_transformers: Annotated[
        StrictBool | None,
        Field(
            description='When true, this agent exposes account-scoped creative transformers via list_transformers (the creative analog of media-buy products) and accepts transformer_id + config on build_creative. Buyers SHOULD call list_transformers to discover available transformers, their typed config params (and account-scoped enumerable option values via expand_params), and pricing. When false or absent, the agent does not offer the transformer surface.'
        ),
    ] = False
    supports_refinement: Annotated[
        StrictBool | None,
        Field(
            description="When true, this agent retains produced build_variant leaves for an agent-defined retention window and can re-build from one via build_creative's refine_from_build_variant_id — applying a natural-language instruction in message plus an optional config delta, returning new lineage-linked variants. A build-time agent capability independent of generation/transformation. When false or absent, refine_from_build_variant_id is rejected with UNSUPPORTED_FEATURE; buyers refine instead via the transform path (creative_manifest + message)."
        ),
    ] = False
    supports_spend_controls: Annotated[
        StrictBool | None,
        Field(
            description='When true, build_creative honors a per-call `max_spend` ceiling (producing partial paid results and returning budget_status:"capped" + a BUDGET_CAP_REACHED advisory rather than overspending) AND supports mode:"estimate" dry-runs (a projected cost band, producing/billing nothing). When false or absent, max_spend / mode:estimate are rejected with UNSUPPORTED_FEATURE. Out-of-band billers (bills_through_adcp:false) have no AdCP cost truth to cap against, so this is meaningful only alongside bills_through_adcp:true.'
        ),
    ] = False
    supports_evaluator: Annotated[
        StrictBool | None,
        Field(
            description="Experimental (x-status: experimental) — agents setting this true MUST also list `creative.evaluator` in `experimental_features`; the surface MAY change between 3.x releases with notice (see docs/reference/experimental-status). When true, build_creative accepts an advisory `evaluator` input (exemplars / account-arranged evaluator_id / agent_url, plus an optional `feature_requirement[]` gate, a `rank_by` ordering, and an allowlisted `feature_agent` pointer). Feature discovery uses this response's governance.creative_features catalog: rank_by, feature_requirement, and eval.features[] all share the same creative-feature vocabulary as get_creative_features. evaluator_id is not discovered from this catalog; it is a pre-provisioned account preset whose emitted feature_ids still come from it. The evaluator populates a per-leaf `eval` block of creative-feature values (creative-feature-result[], the same shape get_creative_features returns) on BuildCreativeVariantSuccess leaves, which is what the recommended/rank it sets on the best_of_n axis are computed over. The agent runs a gate-then-rank pipeline over its best_of_n exploration: it evaluates each leaf, DROPS leaves failing `feature_requirement[]` from its recommended survivors, then orders survivors by `rank_by`. The gate is internal pruning of which leaves the agent recommends/returns from its own exploration — it never blocks an already-produced billable leaf: what is produced and billed is governed by max_variants/max_creatives/max_spend, not the evaluator. When the evaluator names an external agent, it MUST appear in `creative_policy.accepted_verifiers[]` (off-list → EVALUATOR_AGENT_NOT_ACCEPTED), and the producing agent authenticates the outbound evaluator call on the transport. Evaluator credentials and caller-supplied trust material MUST NOT be passed in the build_creative payload; credential- or trust-material payload keys should be rejected with CREDENTIAL_IN_ARGS. When false or absent, the `evaluator` input is ignored and no `eval` block is emitted."
        ),
    ] = False
    refinable_retention_seconds: Annotated[
        SchemaInt | None,
        Field(
            description='When supports_refinement is true, the GUARANTEED-MINIMUM window (a floor, not a ceiling) during which a produced build_variant_id remains refinable via refine_from_build_variant_id: a ref within this window from production SHOULD resolve; the agent MAY retain longer. Omit when the retention window is agent-defined and not advertised — buyers then treat refinability as best-effort and handle REFERENCE_NOT_FOUND.',
            ge=0,
        ),
    ] = None
    multiplicity: Annotated[
        Multiplicity | None,
        Field(
            description="Pre-call discriminators for build_creative fan-out, so a buyer knows BEFORE sending max_creatives / max_variants whether this agent supports them and the ceilings. Over-limit requests are CLAMPED to these ceilings (the agent produces up to the limit and signals the shortfall via items_returned < items_total on BuildCreativeVariantSuccess), not rejected — consistent with item_limit's 'use the lesser' rule. Absent means no fan-out: build_creative produces a single creative and max_creatives/max_variants>1 are not supported."
        ),
    ] = None
    supported_formats: Annotated[
        list[SupportedFormat] | None,
        Field(
            description='Canonical-format capability catalog for this creative agent. This is the 3.2 source of truth for discovering which format contracts the agent can build, validate, or preview; it replaces the deprecated `list_creative_formats` task. Each entry uses the authority-free `CreativeOperationFormatDeclaration` projection of a product format declaration: canonical shape and creative-route macro processing are preserved, while seller production commitments are excluded. New 3.2 producers MUST publish a stable agent-local `capability_id` and explicit `operations` for task routing. Every emitted `capability_id` MUST be unique within this catalog so a route selects exactly one entry. During the 3.x compatibility window, consumers MUST also accept legacy entries that omit either field; absent `operations` means `["build"]`, while an absent `capability_id` means the entry is discoverable by canonical contract but cannot be selected through a capability-ID route.\n\n**Publisher-specific support.** To claim exact support for a publisher declaration, `format` carries the declaration\'s `{publisher_domain, format_option_id}` pair plus its canonical `format_kind` and narrowed `params`. Generic creative agents MAY instead advertise a canonical parameter envelope without publisher identity. A generic capability matches a target declaration only when the capability can satisfy every target constraint; matching canonical names alone is insufficient. Registries MAY reverse-index these entries by `format.format_kind`, `format.publisher_domain`, and `format.format_option_id`.\n\nThis catalog describes creative operations, not sales-agent inventory deliverability. Sales agents publish the purchasable closed set on each `Product.format_options[]`; publisher acceptance lives in `adagents.json.formats[]`.'
        ),
    ] = None
    preview: Annotated[
        Preview | None,
        Field(
            description='Per-route preview_creative capability metadata. New 3.2 producers whose supported_formats[] explicitly advertises a routable preview operation MUST emit this block. rendering_origin describes how each route is implemented but is informational and never grants presentation authority: only a matching publisher-origin placement preview_provider delegation can do that. routes[].capability_id MUST equal the set of capability IDs on supported_formats[] entries whose operations contains preview.'
        ),
    ] = None
    localization: Annotated[
        Localization | None,
        Field(
            description='Materialized creative-localization support for sync_creatives/list_creatives, including source-only monolingual topology. Presence opts the agent into exact locale-variant round-trip, strict RFC 4647 Lookup, optional buyer-declared language-family fallback rules, explicit final default/unmatched behavior, creative-wide review, transactional replacement, seller product-format locale-policy enforcement, and delivery attribution. This is a coarse structural capability, not a promise that every locale/format/account combination is accepted; sellers publish accepted ranges on product format declarations and validate each write before mutation. Omit this object when localization is unsupported.'
        ),
    ] = None
    bills_through_adcp: Annotated[
        StrictBool | None,
        Field(
            description='When true, this creative agent bills through the AdCP rate-card surface: list_creatives returns pricing_options when include_pricing=true with an authenticated account, build_creative populates pricing_option_id and vendor_cost on the response, and report_usage accepts records against the rate card. When false or absent, the agent bills out of band (flat license, SaaS contract, bundled enterprise agreement) and buyers should skip pricing fields and tolerate report_usage returning accepted: 0 with errors carrying BILLING_OUT_OF_BAND. A pre-call discriminator so buyer agents can route across many creative agents without first establishing an account to probe pricing.'
        ),
    ] = False
    canonical_catalog_version: Annotated[
        str | None,
        Field(
            description="Optional. The AdCP canonical-formats catalog version this agent's runtime is built against (e.g., `3.1`, `3.2.0`). Lets buyer SDKs detect canonical-catalog skew between their generated types and the seller's actual support. SDKs MAY declare the version they were generated against (typically the AdCP version they ship for); when seller and SDK versions disagree, SDKs SHOULD soft-warn rather than fail (the open-enum semantics on `canonical-format-kind.json` make unknown canonicals safe to retain, so skew is not a hard error — it just means the older side might not understand newer canonical values). Omitted by sellers who haven't yet generated against a versioned catalog; absence is interpreted as the AdCP version advertised by the broader capabilities response.",
            pattern='^\\d+\\.\\d+(\\.\\d+)?$',
        ),
    ] = 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

Class variables

var bills_through_adcp : bool | None

var canonical_catalog_version : str | None

var has_creative_library : bool | None

var localization : Localization | None

var model_config

var multiplicity : Multiplicity | None

var preview : Preview | None

var refinable_retention_seconds : int | None

var representation_resolution : RepresentationResolution | None

var supported_formats : list[SupportedFormat] | None

var supports_compliance : bool | None

var supports_evaluator : bool | None

var supports_generation : bool | None

var supports_refinement : bool | None

var supports_revisions : bool | None

var supports_spend_controls : bool | None

var supports_transformation : bool | None

var supports_transformers : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeAction (*args, **kwds)

Expand source code

class CreativeAction(StrEnum):
    created = 'created'
    updated = 'updated'
    unchanged = 'unchanged'
    failed = 'failed'
    deleted = 'deleted'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var created

var deleted

var failed

var unchanged

var updated

class Action (*args, **kwds)

Expand source code

class CreativeAction(StrEnum):
    created = 'created'
    updated = 'updated'
    unchanged = 'unchanged'
    failed = 'failed'
    deleted = 'deleted'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var created

var deleted

var failed

var unchanged

var updated

class CreativeAgent (**data: Any)

Expand source code

class CreativeAgent(AdCPBaseModel):
    agent_url: Annotated[
        AnyUrl,
        Field(
            description="Base URL for the creative agent (e.g., 'https://reference.example.com', 'https://dco.example.com')."
        ),
    ]
    agent_name: Annotated[
        str | None, Field(description='Human-readable name for the creative agent')
    ] = None
    capabilities: Annotated[
        list[creative_agent_capability.CreativeAgentCapability] | None,
        Field(description='Capabilities this creative agent provides'),
    ] = 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

Class variables

var agent_name : str | None

var agent_url : pydantic.networks.AnyUrl

var capabilities : list[CreativeAgentCapability] | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeAgentCapability (*args, **kwds)

Expand source code

class CreativeAgentCapability(StrEnum):
    validation = 'validation'
    assembly = 'assembly'
    generation = 'generation'
    preview = 'preview'
    delivery = 'delivery'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var assembly

var delivery

var generation

var preview

var validation

class Capability (*args, **kwds)

Expand source code

class CreativeAgentCapability(StrEnum):
    validation = 'validation'
    assembly = 'assembly'
    generation = 'generation'
    preview = 'preview'
    delivery = 'delivery'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var assembly

var delivery

var generation

var preview

var validation

class CreativeApproval (**data: Any)

Expand source code

class CreativeApproval(IndicatorBearingResourceState):
    model_config = ConfigDict(
        extra='allow',
    )
    indicator_types_evaluated: Annotated[
        list[IndicatorTypesEvaluatedEnum2] | None,
        Field(
            description='Indicator types covered by this snapshot. Required whenever indicators is present. Types omitted from this list remain unknown even when indicators is empty. Every returned indicator.type MUST appear in this list.',
            min_length=1,
        ),
    ] = None
    indicators: Annotated[
        list[Indicator2] | None,
        Field(
            description='Current seller assertions for the indicator types and publisher/placement coverage named by the sibling evaluation fields. Omitted means unknown or not evaluated. A present empty array means evaluated with no current assertion for indicator_types_evaluated in the evaluated scope.'
        ),
    ] = None
    creative_id: Annotated[str, Field(description='Creative identifier')]
    approval_status: creative_approval_status.CreativeApprovalStatus
    rejection_reason: Annotated[
        str | None,
        Field(
            description="Human-readable explanation of why the creative was rejected. Present only when approval_status is 'rejected'."
        ),
    ] = None
    approval_scopes: Annotated[
        list[creative_approval_scope.ScopedCreativeApproval] | None,
        Field(
            description='Complete, disjoint publisher/placement approval partition when approval_status is partially_approved. A normalized scope appears once. For one publisher, use either one publisher-wide row or placement-specific rows, never both. Omit when one approval_status applies uniformly to the whole assignment. The same scoped outcomes are mirrored on list_creatives.',
            min_length=2,
        ),
    ] = None
    indicators_as_of: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller last completed the evaluation represented by indicators for this relationship. Required whenever indicators is present, including an empty array.'
        ),
    ] = None
    indicators_evaluated_scope: Annotated[
        list[indicator_scope.IndicatorScope] | None,
        Field(
            description='Optional publisher or placement scopes covered by this evaluation. Omit when indicators covers the whole package–creative assignment. When present, scopes not listed remain unknown; every returned indicator.scope entry MUST be contained by this set.',
            min_length=1,
        ),
    ] = 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

• IndicatorBearingResourceState
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var approval_scopes : list[ScopedCreativeApproval] | None

var approval_status : CreativeApprovalStatus

var creative_id : str

var indicator_types_evaluated : list[IndicatorTypesEvaluatedEnum2] | None

var indicators : list[Indicator2] | None

var indicators_as_of : pydantic.types.AwareDatetime | None

var indicators_evaluated_scope : list[IndicatorScope] | None

var model_config

var rejection_reason : str | None

Inherited members

• IndicatorBearingResourceState:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeApprovalStatus (*args, **kwds)

Expand source code

class CreativeApprovalStatus(StrEnum):
    pending_review = 'pending_review'
    approved = 'approved'
    partially_approved = 'partially_approved'
    rejected = 'rejected'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var approved

var partially_approved

var pending_review

var rejected

class CreativeAsset (**data: Any)

Expand source code

class CreativeAsset(_CanonicalCreativeWire, CanonicalBoundaryModel):
    """Canonical creative asset; the format kind is required, not optional.

    The kind is narrowed to required and nothing else: it stays ``str`` and the
    model refuses no value. A buyer SENDS a creative asset, and the
    producer-side "sellers MUST NOT mint ad-hoc kinds" rule is the sender's
    obligation, not something a pinned library can tell from a kind defined
    after its pin — :func:`is_canonical_format_kind` is how a caller meets it.
    """

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_id: _RemovedFormatId = Field(default=None, init=False)

    format_kind: str

Canonical creative asset; the format kind is required, not optional.

The kind is narrowed to required and nothing else: it stays str and the model refuses no value. A buyer SENDS a creative asset, and the producer-side "sellers MUST NOT mint ad-hoc kinds" rule is the sender's obligation, not something a pinned library can tell from a kind defined after its pin — :func:is_canonical_format_kind() is how a caller meets it.

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

• CreativeAsset
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var format_id : FormatReferenceStructuredObject | None

var format_kind : str

var model_config

Instance variables

var placement_ids : list[str] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class LegacyCreativeAsset (**data: Any)

Expand source code

class CreativeAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[
        str,
        Field(
            description='Unique identifier for the creative. Stable across legacy named-format and 3.1+ canonical-format paths — a creative registered against `format_id` retains the same `creative_id` when later viewed through a canonical-format flatten.'
        ),
    ]
    name: Annotated[str, Field(description='Human-readable creative name')]
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format path retained for older 3.x peers. New creative assets use `format_kind` and optional `format_option_ref`.',
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Canonical format name this creative targets (e.g., `image`, `video_hosted`). Mutually exclusive with deprecated `format_id`.'
        ),
    ] = None
    format_option_ref: Annotated[
        format_option_ref_1.FormatOptionReference | None,
        Field(
            description='3.1+ format-option path, optional. Structured format option reference matching one of the target product\'s `format_options[]` declarations. Publisher-catalog-backed options match by `{ scope: "publisher", publisher_domain, format_option_id }`; product-local options match by `{ scope: "product", format_option_id }`. Required when the target product has multiple `format_options` entries sharing the same `format_kind`; optional when `format_kind` alone routes the creative to a single declaration. Product-scoped refs require an enclosing target product/package context.'
        ),
    ] = None
    representation_selection: Annotated[
        representation_selection_1.RepresentationSelection | None,
        Field(
            description='Readback lineage to the complete CreativeRepresentationSet revision and representation selected before this seller-bound creative was synced.'
        ),
    ] = None
    assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z0-9_]+$')], asset_union.AssetVariant | Assets],
        Field(
            description='Assets required by the format, keyed by asset_id or canonical asset_group_id. Each slot value is either a single asset object or an array of asset objects (for slots with `min`/`max > 1` like carousel `cards` or responsive_creative `headlines`). Each asset value carries an `asset_type` discriminator that selects the matching asset schema, including reference assets such as `published_post` when a product accepts already-published post references.'
        ),
    ]
    component_assets: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-z][a-z0-9_]*$')], creative_assets.CreativeAssets] | None,
        Field(
            description='Component-addressed canonical asset maps for `coordinated_placements`. Keys match coordinated component IDs. This field is preserved by creative-library sync and list readback; it MUST be absent for every other format kind.'
        ),
    ] = None
    inputs: Annotated[
        list[Input] | None,
        Field(
            description='Preview contexts for generative formats - defines what scenarios to generate previews for'
        ),
    ] = None
    tags: Annotated[
        list[str] | None, Field(description='User-defined tags for organization and searchability')
    ] = None
    status: Annotated[
        creative_status.CreativeStatus | None,
        Field(
            description="For generative creatives: set to 'approved' to finalize, 'rejected' to request regeneration with updated assets/message. Omit for non-generative creatives (system will set based on processing state)."
        ),
    ] = None
    weight: Annotated[
        StrictFloat | None,
        Field(
            description='Optional delivery weight for creative rotation when uploading via create_media_buy or update_media_buy (0-100). If omitted, platform determines rotation. Only used during upload to media buy - not stored in creative library.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    placement_refs: Annotated[
        list[placement_ref.PlacementReference] | None,
        Field(
            description="Optional structured product-context placement references where this uploaded creative should run when uploading via create_media_buy or update_media_buy. These items always use placement-ref product-context semantics, even when tolerated additional members make an item resemble placement-identity. Receivers match only against the target package's committed placement set; kind and seller_agent are non-authoritative for routing and MUST NOT expand or reinterpret that set. A receiver MUST reject a ref when the enclosing product and committed set do not yield one unambiguous match. New senders SHOULD include publisher_domain for publisher-catalog placements. If omitted, creative runs on all buyer-targetable placements. If both `placement_refs` and legacy `placement_ids` are present, `placement_refs` wins and receivers MUST ignore `placement_ids`. Only used during upload to media buy - not stored in creative library.",
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            deprecated=True,
            description='Legacy shorthand array of placement IDs where this creative should run when uploading via create_media_buy or update_media_buy. New senders SHOULD use `placement_refs` because placement IDs are publisher-scoped and strings are ambiguous in multi-publisher products. If omitted, creative runs on all buyer-targetable placements. If `placement_refs` is also present, receivers MUST ignore this field. Only used during upload to media buy - not stored in creative library.',
            min_length=1,
        ),
    ] = None
    industry_identifiers: Annotated[
        list[industry_identifier.IndustryIdentifier] | None,
        Field(
            description='Industry-standard or market-specific identifiers for this creative (e.g., Ad-ID, ISCI, Clearcast clock number, IDcrea). In broadcast and scheduled audio/video buying, these identifiers tie the creative to rotation instructions, clearance records, and traffic systems. A creative may have multiple identifiers when different systems reference the same asset. Add a PR to extend creative-identifier-type when another shared identifier scheme needs first-class support.'
        ),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this creative. Serves as the default provenance for all manifests and assets within this creative. A manifest or asset with its own provenance replaces this object entirely (no field-level merging).'
        ),
    ] = None
    rights: Annotated[
        list[rights_constraint.RightsConstraint] | None,
        Field(
            description='Rights constraints that MUST survive sync, package assignment, and list readback. Buyer-carried constraints and references do not authorize serving; the seller evaluates them under media_buy.rights_attestations and its adcp.attestations policy.',
            min_length=1,
        ),
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> CreativeAsset:
        # ``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 (('format_id',), ('format_kind',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'CreativeAsset requires at least one of these field groups: format_id | format_kind'
        )

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

• CreativeAsset
• Creative

Class variables

var assets : dict[str, ImageAsset | VideoAsset | AudioAsset | VastAsset | DisplayTagAsset | TextAsset | UrlAsset | HtmlAsset | JavascriptAsset | ZipAsset | WebhookAsset | CssAsset | DaastAsset | MarkdownAsset | BriefAsset | CatalogAsset | PublishedPostAsset | CardAsset | PixelTrackerAsset | VastTrackerAsset | DaastTrackerAsset | Assets]

var component_assets : dict[str, CreativeAssets] | None

var creative_id : str

var format_id : FormatReferenceStructuredObject | None

var format_kind : str | None

var format_option_ref : FormatOptionReference1 | FormatOptionReference2 | None

var industry_identifiers : list[IndustryIdentifier] | None

var inputs : list[Input] | None

var model_config

var name : str

var placement_ids : list[str] | None

var placement_refs : list[PlacementReference] | None

var provenance : Provenance | None

var representation_selection : RepresentationSelection | None

var rights : list[RightsConstraint] | None

var status : CreativeStatus | None

var tags : list[str] | None

var weight : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeAssignment (**data: Any)

Expand source code

class CreativeAssignment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    weight: Annotated[
        StrictFloat | None,
        Field(
            description="Relative delivery weight for this creative (0–100). Valid when the package's effective rotation_mode is weighted, including the backward-compatible default when rotation_mode is omitted. Weights determine impression distribution proportionally — a creative with weight 2 gets twice the delivery of weight 1. When omitted, the creative receives equal weight with other unweighted creatives. A weight of 0 means the creative is assigned but paused (receives no delivery).",
            ge=0.0,
            le=100.0,
        ),
    ] = None
    rotation_mode: Annotated[
        RotationMode | None,
        Field(
            description='Package-scoped rotation policy repeated on assignment rows for wire compatibility. Omission means weighted, preserving existing weight behavior. Every assignment in a package MUST resolve to the same effective mode: weighted uses relative weights; even balances delivery across eligible assignments; sequential cycles through sequence_position in ascending order within each group; random makes an independent uniform selection from eligible assignments. Sellers MUST reject conflicting effective modes rather than choose one by array order.'
        ),
    ] = None
    group_id: Annotated[
        str | None,
        Field(
            description="Package-local creative pool identifier. The identifier has no meaning outside this package. Assignments that omit group_id belong to the package's default group; one eligible creative is selected from each applicable group per serving opportunity.",
            min_length=1,
        ),
    ] = None
    sequence_position: Annotated[
        SchemaInt | None,
        Field(
            description="One-based order within the assignment's package-local group. Required only for sequential rotation and unique within that group.",
            ge=1,
        ),
    ] = None
    placement_refs: Annotated[
        list[placement_ref.PlacementReference] | None,
        Field(
            description="Optional structured product-context refs routing this creative within already-purchased package inventory. These items always use placement-ref product-context semantics, even when tolerated additional members make an item resemble placement-identity. Receivers match only against the package's committed placement set; kind and seller_agent are non-authoritative for routing and MUST NOT expand or reinterpret that set. A receiver MUST reject a ref when the enclosing product and committed set do not yield one unambiguous match. This field never narrows purchased inventory; use targeting_overlay.placement_selection for that. Every ref MUST fall within the package's committed placement selection. New senders SHOULD include publisher_domain for publisher-catalog placements. When omitted, the creative runs across the purchased placements compatible with its format. If both placement_refs and legacy placement_ids are present, placement_refs wins.",
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            deprecated=True,
            description='Legacy shorthand routing IDs within already-purchased inventory. This field never narrows purchased inventory; use targeting_overlay.placement_selection. New senders SHOULD use placement_refs because IDs are publisher-scoped. If placement_refs is also present, receivers MUST ignore this field.',
            min_length=1,
        ),
    ] = 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

Class variables

var creative_id : str

var group_id : str | None

var model_config

var placement_ids : list[str] | None

var placement_refs : list[PlacementReference] | None

var rotation_mode : RotationMode | None

var sequence_position : int | None

var weight : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeFilters (**data: Any)

Expand source code

class CreativeFilters(_LegacyCreativeFilters, CanonicalBoundaryModel):
    """Canonical creative filters; legacy identity selection is unavailable."""

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_ids: _RemovedFormatIds = Field(default=None, init=False)

Canonical creative filters; legacy identity selection is unavailable.

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

• CreativeFilters
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var format_ids : list[FormatReferenceStructuredObject] | None

var model_config

class LegacyCreativeFilters (**data: Any)

Expand source code

class CreativeFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    accounts: Annotated[
        list[account_ref.AccountReference] | None,
        Field(
            description='Filter creatives by owning accounts. Useful for agencies managing multiple client accounts.',
            min_length=1,
        ),
    ] = None
    statuses: Annotated[
        list[creative_status.CreativeStatus] | None,
        Field(description='Filter by creative approval statuses', min_length=1),
    ] = None
    tags: Annotated[
        list[str] | None,
        Field(description='Filter by creative tags (all tags must match)', min_length=1),
    ] = None
    tags_any: Annotated[
        list[str] | None,
        Field(description='Filter by creative tags (any tag must match)', min_length=1),
    ] = None
    name_contains: Annotated[
        str | None,
        Field(description='Filter by creative names containing this text (case-insensitive)'),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(description='Filter by specific creative IDs', max_length=100, min_length=1),
    ] = None
    created_after: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives created after this date (ISO 8601)'),
    ] = None
    created_before: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives created before this date (ISO 8601)'),
    ] = None
    updated_after: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives last updated after this date (ISO 8601)'),
    ] = None
    updated_before: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives last updated before this date (ISO 8601)'),
    ] = None
    assigned_to_packages: Annotated[
        list[str] | None,
        Field(
            description='Filter creatives assigned to any of these packages. Sales-agent-specific — standalone creative agents SHOULD ignore this filter.',
            min_length=1,
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter creatives assigned to any of these media buys. Sales-agent-specific — standalone creative agents SHOULD ignore this filter.',
            min_length=1,
        ),
    ] = None
    unassigned: Annotated[
        StrictBool | None,
        Field(
            description='Filter for unassigned creatives when true, assigned creatives when false. Sales-agent-specific — standalone creative agents SHOULD ignore this filter.'
        ),
    ] = None
    has_served: Annotated[
        StrictBool | None,
        Field(
            description='When true, return only creatives that have served at least one impression. When false, return only creatives that have never served.'
        ),
    ] = None
    indicator_types: Annotated[
        list[indicator_type.IndicatorType] | None,
        Field(
            description='Return creatives with at least one package assignment carrying any requested current indicator type. Values within this field use OR logic; this field composes with other filters using AND logic. Sales-agent-specific: sellers support this filter only when media_buy.relationship_notifications.projection_tasks includes list_creatives. Other agents SHOULD ignore it and apply remaining filters. Buyers needing exact results MUST verify capability support and paginate the outer result set; assignment_projection: matching bounds nested rows.',
            min_length=1,
        ),
    ] = None
    concept_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter by creative concept IDs. Concepts group related creatives across sizes and formats (e.g., Flashtalking concepts, Celtra campaign folders, CM360 creative groups).',
            min_length=1,
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Filter legacy named-format creatives. Use `format_kinds` for canonical libraries.',
            min_length=1,
        ),
    ] = None
    format_kinds: Annotated[
        list[str] | None,
        Field(
            description='Filter by canonical format kinds. Returns creatives matching any supplied kind.',
            min_length=1,
        ),
    ] = None
    asset_types: Annotated[
        list[asset_content_type.AssetContentType] | None,
        Field(
            description="Filter by asset types present on direct object values in the creative's top-level `assets` map. A creative matches when any directly assigned object has an `asset_type` in this array (OR within this field); this filter is conjunctive with every other active filter (AND across fields). Do not inspect array-valued slots or recurse into nested asset fields such as `cards[].media`; broader traversal is deferred. Agents that do not implement this filter MUST ignore it and apply the remaining filters rather than reject the request. Exact asset-type values use the shared AssetContentType vocabulary; `published_post` selects existing-published-post reference creatives without relying on publisher-specific format IDs.",
            min_length=1,
        ),
    ] = None
    has_variables: Annotated[
        StrictBool | None,
        Field(
            description='When true, return only creatives with dynamic variables (DCO). When false, return only static creatives.'
        ),
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(
            description='Vendor-namespaced extension parameters for seller- or platform-specific creative filter criteria not covered by standard fields. Keys MUST be namespaced under a vendor or platform key (e.g., ext.gam, ext.platform_x). Sellers MUST treat all values as untrusted buyer input; avoid unbounded logging or labels, and do not interpolate values into caller-visible error strings, LLM prompts, SQL queries, or system commands without sanitization. Persistent use of an extension key across multiple buyers is a signal to propose standardization.'
        ),
    ] = 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

• CreativeFilters

Class variables

var accounts : list[AccountReference1 | AccountReference2] | None

var asset_types : list[AssetContentType] | None

var assigned_to_packages : list[str] | None

var concept_ids : list[str] | None

var created_after : pydantic.types.AwareDatetime | None

var created_before : pydantic.types.AwareDatetime | None

var creative_ids : list[str] | None

var ext : ExtensionObject | None

var format_ids : list[FormatReferenceStructuredObject] | None

var format_kinds : list[str] | None

var has_served : bool | None

var has_variables : bool | None

var indicator_types : list[IndicatorType] | None

var media_buy_ids : list[str] | None

var model_config

var name_contains : str | None

var statuses : list[CreativeStatus] | None

var tags : list[str] | None

var tags_any : list[str] | None

var unassigned : bool | None

var updated_after : pydantic.types.AwareDatetime | None

var updated_before : pydantic.types.AwareDatetime | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeManifest (**data: Any)

Expand source code

class CreativeManifest(_CanonicalCreativeManifestWire, CanonicalBoundaryModel):
    """Canonical manifest accepting the SDK's public standalone asset models.

    The 3.2 aggregate asset-union schema currently generates structurally
    duplicate Pydantic classes. Convert public ``ImageContent``/``UrlContent``
    (and peers) back to their wire dictionaries before the aggregate union
    validates them. This keeps the public constructors composable without
    relaxing the on-wire discriminator checks.
    """

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_id: _RemovedFormatId = Field(default=None, init=False)

    @model_validator(mode="before")
    @classmethod
    def _normalize_standalone_assets(cls, data: Any) -> Any:
        if not isinstance(data, dict) or not isinstance(data.get("assets"), dict):
            return data

        def wire_value(value: Any) -> Any:
            if isinstance(value, AdCPBaseModel):
                return value.model_dump(mode="json", exclude_none=True)
            if isinstance(value, list):
                return [wire_value(item) for item in value]
            return value

        return {
            **data,
            "assets": {key: wire_value(value) for key, value in data["assets"].items()},
        }

Canonical manifest accepting the SDK's public standalone asset models.

The 3.2 aggregate asset-union schema currently generates structurally duplicate Pydantic classes. Convert public ImageAsset/UrlAsset (and peers) back to their wire dictionaries before the aggregate union validates them. This keeps the public constructors composable without relaxing the on-wire discriminator checks.

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

• CreativeManifest
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

Inherited members

• CreativeManifest:
  • format_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class CreativePolicy (**data: Any)

Expand source code

class CreativePolicy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    co_branding: Annotated[
        co_branding_requirement.CoBrandingRequirement, Field(description='Co-branding requirement')
    ]
    landing_page: Annotated[
        landing_page_requirement.LandingPageRequirement,
        Field(description='Landing page requirements'),
    ]
    templates_available: Annotated[
        StrictBool, Field(description='Whether creative templates are provided')
    ]
    provenance_required: Annotated[
        StrictBool | None,
        Field(
            description='Whether creatives must include provenance metadata. When true, the seller requires buyers to attach provenance declarations to creative submissions. The seller may independently verify claims via get_creative_features.'
        ),
    ] = None
    provenance_requirements: Annotated[
        ProvenanceRequirements | None,
        Field(
            description='Structured provenance requirements for creatives. Refines `provenance_required`: when `provenance_required` is true, the fields in this object specify which provenance features the seller requires. When `provenance_required` is false or absent, this object SHOULD be absent; if present, receivers MUST ignore it. Existing seller agents that do not read this object are unaffected; the wire shape does not change for them. Sellers that publish a requirement here MUST enforce it on creative submission: a `sync_creatives` request that omits a required field is rejected with the corresponding `PROVENANCE_*` error code (see error-code.json), and a creative whose provenance claim is contradicted by an independent verification (`get_creative_features` against a governance agent the seller operates or has allowlisted via `accepted_verifiers`) is rejected with `PROVENANCE_CLAIM_CONTRADICTED`. This is the structural-rejection surface; the truth-of-claim surface lives in `get_creative_features`. Field-level requirements are seller-enforced — JSON Schema validation does not check them.'
        ),
    ] = None
    accepted_verifiers: Annotated[
        list[AcceptedVerifier] | None,
        Field(
            description='Governance agents the seller operates, has allowlisted, or otherwise trusts to verify provenance claims via `get_creative_features`. Buyers attaching a `verify_agent` pointer on `embedded_provenance[]` or `watermarks[]` MUST select an `agent_url` that appears in this list (canonicalized per /docs/reference/url-canonicalization: lowercase scheme and host, strip default port, normalize path dot-segments) - the buyer is *representing* that they used a verifier the seller will recognize, not asserting unilateral routing. Sellers MUST reject `sync_creatives` submissions whose `verify_agent.agent_url` does not match any entry here with `PROVENANCE_VERIFIER_NOT_ACCEPTED`. The seller is the verifier-of-record: it is the seller, not the buyer, that decides which agent it will call. Publishing the list lets buyers pre-flight their creative shape against `get_products` and lets multiple buyers converge on the same verifier without coordinating with each other.',
            min_length=1,
        ),
    ] = 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

Class variables

var accepted_verifiers : list[AcceptedVerifier] | None

var co_branding : CoBrandingRequirement

var landing_page : LandingPageRequirement

var model_config

var provenance_required : bool | None

var provenance_requirements : ProvenanceRequirements | None

var templates_available : bool

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeRejectedDetails (**data: Any)

Expand source code

class CreativeRejectedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    policy_id: Annotated[str | None, Field(description='Identifier for the violated policy')] = None
    policy_url: Annotated[
        AnyUrl | None, Field(description='URL where the full policy can be reviewed')
    ] = None
    reasons: Annotated[
        list[str] | None, Field(description='Specific reasons the creative was rejected')
    ] = 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

Class variables

var model_config

var policy_id : str | None

var policy_url : pydantic.networks.AnyUrl | None

var reasons : list[str] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeRepresentationUnresolvedDetails (**data: Any)

Expand source code

class CreativeRepresentationUnresolvedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    representation_rejections: Annotated[
        list[representation_rejection.RepresentationRejection], Field(min_length=1)
    ]

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

Class variables

var model_config

var representation_rejections : list[RepresentationRejection]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeRevisionContentMismatchDetails (**data: Any)

Expand source code

class CreativeRevisionContentMismatchDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    creative_id: Annotated[str, Field(min_length=1)]
    revision_id: creative_revision_id.CreativeRevisionId

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

Class variables

var creative_id : str

var model_config

var revision_id : CreativeRevisionId

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CreativeStatus (*args, **kwds)

Expand source code

class CreativeStatus(StrEnum):
    processing = 'processing'
    pending_review = 'pending_review'
    approved = 'approved'
    suspended = 'suspended'
    rejected = 'rejected'
    archived = 'archived'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var approved

var archived

var pending_review

var processing

var rejected

var suspended

class CreativeVariant (**data: Any)

Expand source code

class CreativeVariant(_LegacyCreativeVariant, CanonicalBoundaryModel):
    """Canonical creative variant whose manifest is the canonical manifest."""

    manifest: CreativeManifest | None = None

Canonical creative variant whose manifest is the canonical manifest.

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

• CreativeVariant
• DeliveryMetrics
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var manifest : CreativeManifest | None

var model_config

Inherited members

• CreativeVariant:
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class CreditLimit (**data: Any)

Expand source code

class CreditLimit(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    amount: Annotated[float, Field(ge=0)]
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')]

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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var amount : float

var currency : str

var model_config

class CoreCreditLimit (**data: Any)

Expand source code

class CreditLimit(AdCPBaseModel):
    amount: Annotated[StrictFloat, Field(ge=0.0)]
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]

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

Class variables

var amount : float

var currency : str

var model_config

class SyncAccountsCreditLimit (**data: Any)

Expand source code

class CreditLimit(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    amount: Annotated[float, Field(ge=0)]
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')]

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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var amount : float

var currency : str

var model_config

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class CssContent (**data: Any)

Expand source code

class CssAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['css'],
        Field(
            description='Discriminator identifying this as a CSS asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'css'
    content: Annotated[str, Field(description='CSS content')]
    media: Annotated[
        str | None, Field(description="CSS media query context (e.g., 'screen', 'print')")
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var asset_type : Literal['css']

var content : str

var media : str | None

var model_config

var provenance : Provenance | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DaastAsset (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class DaastAsset(RootModel[DaastAsset3 | DaastAsset4]):
    root: Annotated[
        DaastAsset3 | DaastAsset4,
        Field(
            description='DAAST (Digital Audio Ad Serving Template) tag for third-party audio ad serving',
            discriminator='delivery_type',
            title='DAAST Asset',
        ),
    ]
    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

-----=

root

The root object of the model.

__pydantic_root_model__

Whether the model is a RootModel.

__pydantic_private__

Private fields in the model.

__pydantic_extra__

Extra fields in the model.

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.root_model.RootModel[Union[DaastAsset3, DaastAsset4]]
• pydantic.root_model.RootModel
• pydantic.main.BaseModel
• typing.Generic

Class variables

var model_config

var root : DaastAsset3 | DaastAsset4

class UrlDaastAsset (**data: Any)

Expand source code

class DaastAsset1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['daast'],
        Field(
            description='Discriminator identifying this as a DAAST asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'daast'
    daast_version: Annotated[
        DaastVersion | None, Field(description='DAAST specification version')
    ] = None
    duration_ms: Annotated[
        SchemaInt | None,
        Field(description='Expected audio duration in milliseconds (if known)', ge=0),
    ] = None
    tracking_events: Annotated[
        list[DaastTrackingEvent] | None,
        Field(description='Tracking events supported by this DAAST tag'),
    ] = None
    companion_ads: Annotated[
        StrictBool | None, Field(description='Whether companion display ads are included')
    ] = None
    transcript_url: Annotated[
        AnyUrl | None, Field(description='URL to text transcript of the audio content')
    ] = None
    provenance: Annotated[
        Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None
    macro_declarations: Annotated[
        list[MacroDeclaration6] | None,
        Field(
            description='One declaration per occurrence in a field carried by this asset. URL-delivered assets declare only locator-URL occurrences; receivers do not infer declarations for tokens discovered later in a fetched document.',
            min_length=1,
        ),
    ] = None
    delivery_type: Annotated[
        Literal['url'],
        Field(description='Discriminator indicating DAAST is delivered via URL endpoint'),
    ] = 'url'
    url: Annotated[
        MacroBearingUrl,
        Field(
            description='URL endpoint returning DAAST XML. Macro delimiters remain byte-preserved and are processed only under attached occurrence declarations.'
        ),
    ]

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

Class variables

var asset_type : Literal['daast']

var companion_ads : bool | None

var daast_version : DaastVersion | None

var delivery_type : Literal['url']

var duration_ms : int | None

var macro_declarations : list[MacroDeclaration6] | None

var model_config

var provenance : Provenance | None

var tracking_events : list[DaastTrackingEvent] | None

var transcript_url : pydantic.networks.AnyUrl | None

var url : str | MacroBearingUrl1 | MacroBearingUrl2

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class InlineDaastAsset (**data: Any)

Expand source code

class DaastAsset2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['daast'],
        Field(
            description='Discriminator identifying this as a DAAST asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'daast'
    daast_version: Annotated[
        DaastVersion | None, Field(description='DAAST specification version')
    ] = None
    duration_ms: Annotated[
        SchemaInt | None,
        Field(description='Expected audio duration in milliseconds (if known)', ge=0),
    ] = None
    tracking_events: Annotated[
        list[DaastTrackingEvent] | None,
        Field(description='Tracking events supported by this DAAST tag'),
    ] = None
    companion_ads: Annotated[
        StrictBool | None, Field(description='Whether companion display ads are included')
    ] = None
    transcript_url: Annotated[
        AnyUrl | None, Field(description='URL to text transcript of the audio content')
    ] = None
    provenance: Annotated[
        Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None
    macro_declarations: Annotated[
        list[MacroDeclaration7] | None,
        Field(
            description='One declaration per occurrence in a field carried by this asset. URL-delivered assets declare only locator-URL occurrences; receivers do not infer declarations for tokens discovered later in a fetched document.',
            min_length=1,
        ),
    ] = None
    delivery_type: Annotated[
        Literal['inline'],
        Field(description='Discriminator indicating DAAST is delivered as inline XML content'),
    ] = 'inline'
    content: Annotated[str, Field(description='Inline DAAST XML content')]

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

Class variables

var asset_type : Literal['daast']

var companion_ads : bool | None

var content : str

var daast_version : DaastVersion | None

var delivery_type : Literal['inline']

var duration_ms : int | None

var macro_declarations : list[MacroDeclaration7] | None

var model_config

var provenance : Provenance | None

var tracking_events : list[DaastTrackingEvent] | None

var transcript_url : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DaastTrackerAsset (**data: Any)

Expand source code

class DaastTrackerAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['daast_tracker'],
        Field(
            description='Discriminator identifying this as a DAAST tracker asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'daast_tracker'
    daast_event: Annotated[
        daast_tracking_event.DaastTrackingEvent,
        Field(
            description='The DAAST tracking event this URL fires on. MUST NOT be `impression` (model as `url` asset with `url_type: "tracker_pixel"`), `clickTracking` / `customClick` (click-tracking trackers go on their own URL asset), `error`, or any of the `ViewableImpression`-element children (`viewable`, `notViewable`, `viewUndetermined`, `measurableImpression`, `viewableImpression`).'
        ),
    ]
    url: Annotated[
        macro_bearing_url.MacroBearingUrl,
        Field(
            description='Tracker URL fired for the DAAST event. Attached declarations identify each macro occurrence, processing actor, and exact encoding profile.'
        ),
    ]
    macro_declarations: Annotated[
        list[MacroDeclaration] | None,
        Field(
            description='Exact tokens in `url` and their resolver/encoding contracts.', min_length=1
        ),
    ] = None
    offset: Annotated[
        str | None,
        Field(
            description='DAAST `offset` attribute. Required when `daast_event` is `progress` (DAAST 1.1 §3.2.4.3); ignored otherwise for compatibility with existing 3.x manifests. Same format as VAST 4.2 `Tracking@offset`: `HH:MM:SS` or `HH:MM:SS.mmm` for absolute time (two-digit hours, minutes 00–59, seconds 00–59), or an integer percentage 0–100 suffixed with `%`. Negative offsets are NOT permitted.',
            pattern='^(\\d{2}:[0-5]\\d:[0-5]\\d(\\.\\d{3})?|(100|\\d{1,2})%)$',
        ),
    ] = None
    target: Annotated[
        Target | None,
        Field(
            description='Which DAAST creative element this tracker scopes to — `linear` for `<Linear>/<TrackingEvents>` (DAAST 1.1 §3.2.1.7), `companion` for `<CompanionAds>/<Companion>/<TrackingEvents>` (DAAST 1.1 §3.2.2.7). DAAST has no `<NonLinearAds>` element. Defaults to `linear`. Existing 3.x assets remain structurally permissive; a tracker execution contract applies the standards-valid event/target matrix when matching a creative to a product.'
        ),
    ] = Target.linear
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance.'
        ),
    ] = 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

Class variables

var asset_type : Literal['daast_tracker']

var daast_event : DaastTrackingEvent

var macro_declarations : list[MacroDeclaration] | None

var model_config

var offset : str | None

var provenance : Provenance | None

var target : Target | None

var url : str | MacroBearingUrl3 | MacroBearingUrl4

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DaastTrackingEvent (*args, **kwds)

Expand source code

class DaastTrackingEvent(StrEnum):
    impression = 'impression'
    creativeView = 'creativeView'
    start = 'start'
    firstQuartile = 'firstQuartile'
    midpoint = 'midpoint'
    thirdQuartile = 'thirdQuartile'
    complete = 'complete'
    mute = 'mute'
    unmute = 'unmute'
    pause = 'pause'
    resume = 'resume'
    rewind = 'rewind'
    skip = 'skip'
    progress = 'progress'
    clickTracking = 'clickTracking'
    customClick = 'customClick'
    close = 'close'
    error = 'error'
    viewable = 'viewable'
    notViewable = 'notViewable'
    viewUndetermined = 'viewUndetermined'
    measurableImpression = 'measurableImpression'
    viewableImpression = 'viewableImpression'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var clickTracking

var close

var complete

var creativeView

var customClick

var error

var firstQuartile

var impression

var measurableImpression

var midpoint

var mute

var notViewable

var pause

var progress

var resume

var rewind

var skip

var start

var thirdQuartile

var unmute

var viewUndetermined

var viewable

var viewableImpression

class DaastVersion (*args, **kwds)

Expand source code

class DaastVersion(StrEnum):
    field_1_0 = '1.0'
    field_1_1 = '1.1'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var field_1_0

var field_1_1

class DailyBreakdownItem (**data: Any)

Expand source code

class DailyBreakdownItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    date: Annotated[
        str,
        Field(
            description="Calendar date (YYYY-MM-DD) in the reporting timezone: reporting_period.timezone when present, otherwise this package's product reporting_capabilities.timezone. The row covers that local day, which can be 23 or 25 hours long across a DST change.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ]
    impressions: Annotated[
        StrictFloat, Field(description='Daily impressions for this package', ge=0.0)
    ]
    spend: Annotated[StrictFloat, Field(description='Daily spend for this package', ge=0.0)]
    conversions: Annotated[
        StrictFloat | None, Field(description='Daily conversions for this package', ge=0.0)
    ] = None
    conversion_value: Annotated[
        StrictFloat | None, Field(description='Daily conversion value for this package', ge=0.0)
    ] = None
    commissionable_value: Annotated[
        StrictFloat | None,
        Field(
            description='Daily settled conversion value eligible for revenue-share commission for this package',
            ge=0.0,
        ),
    ] = None
    roas: Annotated[
        StrictFloat | None,
        Field(description='Daily return on ad spend (conversion_value / spend)', ge=0.0),
    ] = None
    new_to_brand_rate: Annotated[
        StrictFloat | None,
        Field(
            description='Daily fraction of conversions from first-time brand buyers (0 = none, 1 = all)',
            ge=0.0,
            le=1.0,
        ),
    ] = 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

Class variables

var commissionable_value : float | None

var conversion_value : float | None

var conversions : float | None

var date : str

var impressions : float

var model_config

var new_to_brand_rate : float | None

var roas : float | None

var spend : float

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DateRange (**data: Any)

Expand source code

class DateRange(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    start: Annotated[date, Field(description='Start date (inclusive), ISO 8601')]
    end: Annotated[date, Field(description='End date (inclusive), ISO 8601')]

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

Class variables

var end : datetime.date

var model_config

var start : datetime.date

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DatetimeRange (**data: Any)

Expand source code

class DatetimeRange(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    start: Annotated[AwareDatetime, Field(description='Start timestamp (inclusive), ISO 8601')]
    end: Annotated[AwareDatetime, Field(description='End timestamp (inclusive), ISO 8601')]

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

Class variables

var end : pydantic.types.AwareDatetime

var model_config

var start : pydantic.types.AwareDatetime

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DayOfWeek (*args, **kwds)

Expand source code

class DayOfWeek(StrEnum):
    monday = 'monday'
    tuesday = 'tuesday'
    wednesday = 'wednesday'
    thursday = 'thursday'
    friday = 'friday'
    saturday = 'saturday'
    sunday = 'sunday'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var friday

var monday

var saturday

var sunday

var thursday

var tuesday

var wednesday

class DaypartTarget (**data: Any)

Expand source code

class DaypartTarget(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    days: Annotated[
        list[day_of_week.DayOfWeek],
        Field(
            description='Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object).',
            min_length=1,
        ),
    ]
    start_hour: Annotated[
        SchemaInt,
        Field(
            description='Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm.',
            ge=0,
            le=23,
        ),
    ]
    end_hour: Annotated[
        SchemaInt,
        Field(
            description='End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour.',
            ge=1,
            le=24,
        ),
    ]
    timezone: Annotated[
        Literal['inventory_local'] | iana_timezone.IanaTimezoneIdentifier | None,
        Field(
            description="Civil-time clock used to evaluate this window. 'inventory_local' evaluates the hours in the seller-assigned local timezone of each inventory unit that can deliver the impression, such as a screen, venue, station, or publisher property; it never means the buyer, account, or server timezone. A concrete IANA timezone identifier (for example, 'America/New_York', 'CET', or 'UTC') evaluates one shared civil-time clock across the targeted inventory. Omission defaults to 'inventory_local'. Buyers that begin with a user or account preference MUST resolve it to a concrete IANA identifier before sending the daypart; 'user_timezone' and 'account_timezone' are not wire values. For each candidate delivery instant, convert the instant into this clock and compare its resulting local day and hour with the half-open window: a skipped DST hour has no matching instants, while both occurrences of a repeated hour match. This delivery clock is independent of reporting_capabilities.timezone.",
            validate_default=True,
        ),
    ] = 'inventory_local'
    label: Annotated[
        str | None,
        Field(
            description="Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')"
        ),
    ] = 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

Class variables

var days : list[DayOfWeek]

var end_hour : int

var label : str | None

var model_config

var start_hour : int

var timezone : Literal['inventory_local'] | IanaTimezoneIdentifier | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ProvenanceDeclaredBy (**data: Any)

Expand source code

class DeclaredBy(AdCPBaseModel):
    agent_url: Annotated[
        AnyUrl | None,
        Field(description='URL of the agent or service that declared this provenance'),
    ] = None
    role: Annotated[Role, Field(description='Role of the declaring party in the supply chain')]

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

Class variables

var agent_url : pydantic.networks.AnyUrl | None

var model_config

var role : Role

class SiSponsoredContextDeclaredBy (**data: Any)

Expand source code

class DeclaredBy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    agent_url: Annotated[
        AnyUrl | None, Field(description='HTTPS URL of the declaring agent or service.')
    ] = None
    role: Annotated[Role, Field(description='Role of the declaring party.')]

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

Class variables

var agent_url : pydantic.networks.AnyUrl | None

var model_config

var role : Role

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DeclineProposalsRequest (**data: Any)

Expand source code

class DeclineProposalsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    context_id: Annotated[
        str | None,
        Field(
            description='MCP compatibility field: servers ignore this value; A2A uses transport-native Message/Task contextId.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    governance_context: Annotated[str | None, Field(max_length=4096, min_length=1)] = None
    push_notification_config: push_notification_config_1.PushNotificationConfig | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated key required for retry-safe proposal decline.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    declines: Annotated[
        list[proposal_decline.ProposalDecline],
        Field(
            description='Proposal declines to apply. proposal_id is the semantic uniqueness key and values MUST be unique even when two entries otherwise differ; implementations enforce this rule because JSON Schema uniqueItems only compares whole objects. Results preserve request order.',
            max_length=25,
            min_length=1,
        ),
    ]
    opportunity: Annotated[
        opportunity_context.OpportunityContext | None,
        Field(
            description='Optional planning-cycle update. Every named proposal MUST belong to this opportunity_id. Sellers apply the update only when every result is declined; if any result is unable, the opportunity remains unchanged. Use status closed when these declines end the broader opportunity.'
        ),
    ] = 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 context_id : str | None

var declines : list[ProposalDecline]

var governance_context : str | None

var idempotency_key : str

var model_config

var opportunity : OpportunityContext | None

var push_notification_config : PushNotificationConfig | 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 DeleteCollectionListRequest (**data: Any)

Expand source code

class DeleteCollectionListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list_id: Annotated[str, Field(description='ID of the collection list to delete')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts; optional otherwise.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var list_id : 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 DeleteCollectionListResponse (**data: Any)

Expand source code

class DeleteCollectionListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    deleted: Annotated[StrictBool, Field(description='Whether the list was successfully deleted')]
    list_id: Annotated[str, Field(description='ID of the deleted list')]
    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
    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.

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 context : ContextObject | None

var deleted : bool

var ext : ExtensionObject | None

var list_id : str

var model_config

var replayed : bool | 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 DeletePropertyListRequest (**data: Any)

Expand source code

class DeletePropertyListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list_id: Annotated[str, Field(description='ID of the property list to delete')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts; optional otherwise.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var list_id : 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 DeletePropertyListResponse (**data: Any)

Expand source code

class DeletePropertyListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    deleted: Annotated[StrictBool, Field(description='Whether the list was successfully deleted')]
    list_id: Annotated[str, Field(description='ID of the deleted list')]
    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
    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.

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 context : ContextObject | None

var deleted : bool

var ext : ExtensionObject | None

var list_id : str

var model_config

var replayed : bool | 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 DeliveryForecast (**data: Any)

Expand source code

class DeliveryForecast(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    points: Annotated[
        list[forecast_point.ForecastPoint],
        Field(
            description='Forecasted delivery data points. For spend curves (default), points at ascending budget levels show how metrics scale with spend. For availability forecasts, points represent total available inventory independent of budget. See forecast_range_unit for interpretation.',
            min_length=1,
        ),
    ]
    forecast_range_unit: Annotated[
        forecast_range_unit_1.ForecastRangeUnit | None,
        Field(
            description="How to interpret the points array. 'spend' (default when omitted): points at ascending budget levels. 'availability': total available inventory, budget omitted. 'reach_freq': points at ascending reach/frequency targets. 'weekly'/'daily': metrics are per-period values. 'clicks'/'conversions': points at ascending outcome targets. 'package': each point is a distinct inventory package."
        ),
    ] = None
    method: Annotated[
        forecast_method.ForecastMethod, Field(description='Method used to produce this forecast')
    ]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code for monetary values in this forecast (spend, budget)'
        ),
    ]
    demographic_system: Annotated[
        demographic_system_1.DemographicSystem | None,
        Field(
            description='Measurement system for the demographic field. Ensures buyer and seller agree on demographic notation.'
        ),
    ] = None
    demographic: Annotated[
        str | None,
        Field(
            description='Target demographic code within the specified demographic_system. For Nielsen: P18-49, M25-54, W35+. For BARB: ABC1 Adults, 16-34. For AGF: E 14-49.',
            examples=['P18-49', 'A25-54', 'W35+', 'M18-34'],
        ),
    ] = None
    measurement_source: Annotated[
        str | None,
        Field(
            description='Third-party measurement provider whose data was used to produce this forecast. Distinct from demographic_system, which specifies demographic notation — measurement_source identifies whose data produced the forecast numbers. Should be present when measured_impressions is used. Lowercase slug format.',
            examples=[
                'nielsen',
                'videoamp',
                'comscore',
                'geopath',
                'barb',
                'agf',
                'oztam',
                'kantar',
                'barc',
                'route',
                'rajar',
                'triton',
            ],
            max_length=64,
            pattern='^[a-z0-9_]+$',
        ),
    ] = None
    reach_unit: Annotated[
        reach_unit_1.ReachUnit | None,
        Field(
            description='Unit of measurement for reach and audience_size metrics in this forecast. Required for cross-channel forecast comparison.'
        ),
    ] = None
    generated_at: Annotated[
        AwareDatetime | None, Field(description='When this forecast was computed')
    ] = None
    valid_until: Annotated[
        AwareDatetime | None,
        Field(
            description='When this forecast expires. After this time, the forecast should be refreshed. Forecast expiry does not affect proposal executability.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var currency : str

var demographic : str | None

var demographic_system : DemographicSystem | None

var ext : ExtensionObject | None

var forecast_range_unit : ForecastRangeUnit | None

var generated_at : pydantic.types.AwareDatetime | None

var measurement_source : str | None

var method : ForecastMethod

var model_config

var points : list[ForecastPoint]

var reach_unit : ReachUnit | None

var valid_until : pydantic.types.AwareDatetime | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DeliveryMeasurement (**data: Any)

Expand source code

class DeliveryMeasurement(AdCPBaseModel):
    vendors: Annotated[
        list[brand_ref.BrandReference] | None,
        Field(
            description="Measurement vendors used for this product, as structured `BrandRef` identities. Multiple entries when multiple vendors play different roles (e.g., the ad server plus a separate viewability vendor like IAS or DV; or a retail-media seller plus a third-party retail measurement vendor like Circana or NielsenIQ). Each vendor's `brand.json` `agents[type='measurement']` is the discovery anchor; metric definitions live on the agent's `get_adcp_capabilities.measurement.metrics[]` block. Distinct from `performance_standards[].vendor` which carries vendor identity for *committed* metrics with thresholds — this field carries vendor identity for the overall measurement story, including non-committed-but-reported metrics.",
            min_length=1,
        ),
    ] = None
    provider: Annotated[
        str | None,
        Field(
            deprecated=True,
            description="**Deprecated as of this minor.** Free-form measurement provider description (e.g., 'Google Ad Manager with IAS viewability', 'Nielsen DAR', 'Geopath for DOOH impressions'). New implementations SHOULD use the structured `vendors` field instead. Retained for one-minor backwards compatibility; removed at the next major. When both `vendors` and `provider` are present, consumers MUST use `vendors` for vendor identity and treat `provider` as informational text.",
        ),
    ] = None
    notes: Annotated[
        str | None,
        Field(
            description="Additional details about measurement methodology in plain language (e.g., 'MRC-accredited viewability. 50% in-view for 1s display / 2s video', 'Panel-based demographic measurement updated monthly'). Free-form prose for context that doesn't fit the structured `vendors` field."
        ),
    ] = 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

Class variables

var model_config

var notes : str | None

var provider : str | None

var vendors : list[BrandReference] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DeliveryMetrics (**data: Any)

Expand source code

class DeliveryMetrics(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    impressions: Annotated[
        StrictFloat | None, Field(description='Impressions delivered', ge=0.0)
    ] = None
    spend: Annotated[StrictFloat | None, Field(description='Amount spent', ge=0.0)] = None
    clicks: Annotated[StrictFloat | None, Field(description='Total clicks', ge=0.0)] = None
    ctr: Annotated[
        StrictFloat | None,
        Field(description='Click-through rate (clicks/impressions)', ge=0.0, le=1.0),
    ] = None
    views: Annotated[
        StrictFloat | None,
        Field(
            description="Content engagements counted toward the billable view threshold. For video this is a platform-defined view event (e.g., 30 seconds or video midpoint); for audio/podcast it is a stream start; for other formats it follows the pricing model's view definition. When the package uses CPV pricing, spend = views × rate.",
            ge=0.0,
        ),
    ] = None
    completed_views: Annotated[
        StrictFloat | None,
        Field(
            description='Video/audio completions. When the package has a completed_views optimization goal with view_duration_seconds, completions are counted at that threshold rather than 100% completion.',
            ge=0.0,
        ),
    ] = None
    completion_rate: Annotated[
        StrictFloat | None,
        Field(
            description='Completion rate (completed_views/impressions). Null indicates the metric is not applicable to this package/buy (e.g. completion rate on a non-video buy).',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    conversions: Annotated[
        StrictFloat | None,
        Field(
            description='Total conversions attributed to this delivery. When by_event_type is present, this equals the sum of all by_event_type[].count entries.',
            ge=0.0,
        ),
    ] = None
    conversion_value: Annotated[
        StrictFloat | None,
        Field(
            description='Total monetary value of attributed conversions (in the reporting currency)',
            ge=0.0,
        ),
    ] = None
    commissionable_value: Annotated[
        StrictFloat | None,
        Field(
            description='Settled portion of attributed conversion value eligible for revenue-share commission, in the reporting currency. For revenue_share pricing, spend = round_currency(commissionable_value × commission_rate). This is distinct from conversion_value because taxes, shipping, discounts, returns, cancellations, or ineligible items may be excluded under the agreed commission basis.',
            ge=0.0,
        ),
    ] = None
    roas: Annotated[
        StrictFloat | None,
        Field(description='Return on ad spend (conversion_value / spend)', ge=0.0),
    ] = None
    cost_per_acquisition: Annotated[
        StrictFloat | None, Field(description='Cost per conversion (spend / conversions)', ge=0.0)
    ] = None
    new_to_brand_rate: Annotated[
        StrictFloat | None,
        Field(
            description='Fraction of `conversions` (transactions) from first-time brand buyers, 0 = none, 1 = all. For retail-media unit-volume tracking of first-time buyers, see `new_to_brand_units` (count, not rate).',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    leads: Annotated[
        StrictFloat | None,
        Field(
            description="Leads generated (convenience alias for by_event_type where event_type='lead')",
            ge=0.0,
        ),
    ] = None
    incremental_sales_lift: Annotated[
        StrictFloat | None,
        Field(
            description="Incremental sales lift attributed to the campaign — sales above the control/holdout baseline. Reported as a fraction (0.15 = 15% lift) or as an absolute value depending on seller convention. The seller's `attribution_methodology` qualifier (typically `deterministic_purchase` or `modeled`) and `attribution_window` qualifier on the matching `committed_metrics` entry disambiguate the methodology and window.",
            ge=0.0,
        ),
    ] = None
    brand_lift: Annotated[
        StrictFloat | None,
        Field(
            description="Brand lift — measured change in a brand metric (awareness, consideration, favorability, purchase intent, or ad recall) attributed to the campaign. Typically panel-based or survey-based. Reported as a fraction (0.05 = 5% lift). **Multidimensional in production** — Kantar, Upwave, Cint, DV all report each dimension separately with its own sample size and confidence interval. The dimension flows through `qualifier.lift_dimension` on `committed_metrics` / `by_package[].metric_values` (`awareness` | `consideration` | `favorability` | `purchase_intent` | `ad_recall`); rows under different dimensions are different surveyed outcomes and must not be combined. Use `attribution_methodology: 'panel_based'` qualifier when the underlying methodology is a panel.",
            ge=0.0,
        ),
    ] = None
    foot_traffic: Annotated[
        StrictFloat | None,
        Field(
            description="Store visits attributed to ad exposure. Count of incremental visits over baseline. Typically uses location-data panel methodology (`attribution_methodology: 'panel_based'`) or deterministic loyalty-card match (`attribution_methodology: 'deterministic_purchase'`).",
            ge=0.0,
        ),
    ] = None
    conversion_lift: Annotated[
        StrictFloat | None,
        Field(
            description='Incremental conversions attributed to the campaign — conversions above the control/holdout baseline. Reported as a fraction (0.10 = 10% lift) or as an absolute count depending on seller convention. Distinct from `conversions` (raw count of attributed conversions); conversion_lift requires a control group and an incrementality methodology.',
            ge=0.0,
        ),
    ] = None
    brand_search_lift: Annotated[
        StrictFloat | None,
        Field(
            description='Lift in brand search query volume attributed to the campaign — measured via search-data partnerships (Google, Microsoft) or survey methodology. Reported as a fraction (0.20 = 20% lift in branded search).',
            ge=0.0,
        ),
    ] = None
    plays: Annotated[
        StrictFloat | None,
        Field(
            description="Number of times the ad creative was displayed or played on DOOH or broadcast inventory. Raw play count before any impression multiplier is applied. Mirrors `forecastable-metric.json`'s `plays` token for forecast↔delivery reconciliation. Distinct from `dooh_metrics.loop_plays` (scheduled-rotation count) and from `impressions` (multiplied audience figure).",
            ge=0.0,
        ),
    ] = None
    measurement_source: Annotated[
        str | None,
        Field(
            description="Third-party measurement provider whose data produced this row's audience numbers. Mirrors delivery-forecast.json's measurement_source so forecast and delivery reconcile on the same declaration — distinct from demographic_system, which specifies demographic notation. Makes measured-channel rows (radio, broadcast, OOH) self-describing: a reconciliation join can tie delivered numbers to the system that measured them without consulting out-of-band context. Lowercase slug format.",
            examples=[
                'nielsen',
                'nielsen_audio',
                'videoamp',
                'comscore',
                'geopath',
                'barb',
                'agf',
                'oztam',
                'kantar',
                'barc',
                'route',
                'rajar',
                'triton',
            ],
            max_length=64,
            pattern='^[a-z0-9_]+$',
        ),
    ] = None
    by_event_type: Annotated[
        list[ByEventTypeItem] | None,
        Field(
            description='Conversion metrics broken down by event type. Spend-derived metrics (ROAS, CPA) are only available at the package/totals level since spend cannot be attributed to individual event types.'
        ),
    ] = None
    grps: Annotated[
        StrictFloat | None, Field(description='Gross Rating Points delivered (for CPP)', ge=0.0)
    ] = None
    reach: Annotated[
        StrictFloat | None,
        Field(
            description='Unique reach in the units specified by reach_unit. When reach_unit is omitted, units are unspecified — do not compare reach values across packages or media buys without a common reach_unit. The measurement window for this value is declared in `reach_window`; when `reach_window` is omitted, the window is unspecified and buyers MUST NOT sum reach across reports (the value MAY be a daily snapshot, a cumulative total, or something else).',
            ge=0.0,
        ),
    ] = None
    reach_unit: Annotated[
        reach_unit_1.ReachUnit | None,
        Field(
            description='Unit of measurement for the reach field. Aligns with the reach_unit declared on optimization goals and delivery forecasts. Required when reach is present to enable cross-platform comparison.'
        ),
    ] = None
    reach_window: Annotated[
        ReachWindow | None,
        Field(
            description='Measurement window for the reported `reach` and `frequency` values in this row. Declares whether the values are a per-period snapshot, a trailing rolling window, or cumulative-to-date — without this declaration, buyers summing `reach` across rows (e.g., daily delivery reports) can silently double-count audiences. Sellers SHOULD populate this whenever `reach` is present.'
        ),
    ] = None
    frequency: Annotated[
        StrictFloat | None,
        Field(
            description="Average frequency per reach unit, measured over the window declared in `reach_window`. When `reach_unit` is 'households', this is average exposures per household; when 'accounts', per logged-in account; etc. When `reach_window` is omitted, the window is unspecified — buyers MUST NOT compare or average frequency values across rows.",
            ge=0.0,
        ),
    ] = None
    quartile_data: Annotated[
        QuartileData | None,
        Field(
            description="Audio/video quartile completion data. Null indicates the metric is not applicable to this package/buy (e.g. quartile data on a non-video buy). Individual quartiles are addressable via the leaf metric identities `quartile_25` (q1_views), `quartile_50` (q2_views), `quartile_75` (q3_views), and `quartile_100` (q4_views) for declaration, commitments, aggregates, and breakdown sorting; this object remains the canonical carrier of the values. Quartiles are player-fired events (VAST firstQuartile/midpoint/thirdQuartile/complete). `quartile_100` counts 100%-of-duration completions and is distinct from `completed_views`, which counts completions at the seller's billable view threshold (`view_duration_seconds`) when one is set."
        ),
    ] = None
    time_based_views: Annotated[
        list[TimeBasedView] | None,
        Field(
            description="Time-threshold video view counts. Each entry reports views that met a continuous duration threshold under a stated basis, rather than a completion percentage (percentage-based completion is quartile_data). Thresholds of 2 and 6 seconds are RECOMMENDED cross-platform reporting points; any seller-defined threshold is permitted. One entry per (threshold_seconds, basis) pair per reporting period — sellers MUST de-duplicate before emission and MUST NOT emit the same pair twice; buyers MAY treat duplicate pairs as a seller-side conformance bug. Entries under different bases are different metrics and MUST NOT be summed (see view-threshold-basis). Primarily an autoplay/skippable-video metric (social, olv, in-feed video); completion metrics remain the currency for lean-back CTV/cinema inventory. Distinct from `views` (the single billable-threshold scalar) and from `viewability.viewed_seconds` (average in-view duration, not a threshold count). Array entries are not individually sortable in breakdown sort_by. Disclosure-grade surface: (threshold_seconds, basis) is not part of the committed-metric qualifier vocabulary, so a `committed_metrics` entry for `time_based_views` contracts the array's presence, not specific thresholds."
        ),
    ] = None
    dooh_metrics: Annotated[
        DoohMetrics1 | None,
        Field(description='DOOH-specific metrics (only included for DOOH campaigns)'),
    ] = None
    ooh_metrics: Annotated[
        OohMetrics | None,
        Field(
            description='Classic (static) OOH metrics — printed bulletins, posters, transit, and street furniture (only included for ooh campaigns). Experimental in AdCP 3.2. Static units have no play event: the delivery number is a period-level modeled audience estimate whose methodology tier is declared in estimation_basis (provider identity rides the row-level measurement_source), and the settlement artifact is the posting record — it proves the posting period, not an airing.'
        ),
    ] = None
    viewability: Annotated[
        Viewability1 | None,
        Field(
            description="Viewability metrics. Viewable rate should be calculated as viewable_impressions / measurable_impressions (not total impressions), since some environments cannot measure viewability. Includes `viewed_seconds` — average in-view duration — plus optional percentile and histogram distributions over that duration; all three use the same `measurable_impressions` population and are governed by the same viewability threshold (`standard`). Sellers SHOULD include `standard` whenever measured viewability values are reported because MRC and GroupM rows are not interchangeable. The numeric leaves are addressable via the leaf metric identities `viewable_rate`, `viewable_impressions`, `measurable_impressions`, and `viewed_seconds` for declaration, commitments, aggregates, and breakdown sorting. The structured distribution carriers require explicit `viewed_seconds_percentiles` and `viewed_seconds_histogram` identities for declaration, commitment, and selection; they are not numeric aggregate rows or sort keys. This object remains the canonical carrier of every value. When a buy reports under more than one standard, contract a specific standard via the `viewability_standard` qualifier on `committed_metrics`; when the package's `committed_metrics` carry a `viewability_standard` qualifier, sellers MUST populate `standard` on reported viewability objects so reconciliation can match the qualifier."
        ),
    ] = None
    engagements: Annotated[
        StrictFloat | None,
        Field(
            description="Total engagements — direct interactions with the ad beyond viewing. Includes social reactions/comments/shares, story/unit opens, interactive overlay taps on CTV, companion banner interactions on audio. Platform-specific; corresponds to the 'engagements' optimization metric. Maps to DBCFM KPI_INTERACTIONS (Interaktionen) in the Reporting/Performance block.",
            ge=0.0,
        ),
    ] = None
    follows: Annotated[
        StrictFloat | None,
        Field(
            description='New followers, page likes, artist/podcast/channel follows, or free channel/feed subscribes attributed to this delivery. Paid subscriptions are conversion events with `event_type: subscribe`, not `follows`.',
            ge=0.0,
        ),
    ] = None
    saves: Annotated[
        StrictFloat | None,
        Field(
            description='Saves, bookmarks, playlist adds, pins attributed to this delivery.', ge=0.0
        ),
    ] = None
    profile_visits: Annotated[
        StrictFloat | None,
        Field(
            description="Visits to the brand's in-platform page (profile, artist page, channel, or storefront) attributed to this delivery. Does not include external website clicks.",
            ge=0.0,
        ),
    ] = None
    engagement_rate: Annotated[
        StrictFloat | None,
        Field(
            description='Platform-specific engagement rate (0.0 to 1.0). Typically engagements/impressions, but definition varies by platform.',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    cost_per_click: Annotated[
        StrictFloat | None, Field(description='Cost per click (spend / clicks)', ge=0.0)
    ] = None
    cost_per_completed_view: Annotated[
        StrictFloat | None,
        Field(
            description="Cost per completed view (spend / completed_views). Primary CPCV pricing scalar for video/audio inventory; the package's `pricing_model` is `cpcv` when this field is the billing basis.",
            ge=0.0,
        ),
    ] = None
    cpm: Annotated[
        StrictFloat | None,
        Field(
            description="Cost per thousand impressions, computed as (spend / impressions) × 1000. Universal pricing scalar across CTV, display, mobile/web video, native, audio, and DOOH inventory; the package's `pricing_model` is `cpm` when this field is the billing basis. Field name aligns with the canonical `cpm` token in `enums/pricing-model.json` and `pricing-options/cpm-option.json` so buyers cross-walk pricing model → reported scalar without a translation table.",
            ge=0.0,
        ),
    ] = None
    downloads: Annotated[
        StrictFloat | None,
        Field(
            description="Audio/podcast downloads (IAB Podcast Measurement Technical Guidelines 2.x methodology). Distinct from `views` — for podcast inventory this is the count of podcast episode downloads; for streaming audio it is the count of stream starts that meet the platform's download threshold. Prefer this over `views` for audio inventory.",
            ge=0.0,
        ),
    ] = None
    units_sold: Annotated[
        StrictFloat | None,
        Field(
            description='Items sold attributed to this delivery. Retail-media scalar distinct from `conversions` — a single conversion (transaction) may carry multiple `units_sold`. Used by retail media platforms where the buyer optimizes against unit movement, not transaction count. Attribution lookback windows are platform-specific (commonly 7/14/30 days, view-through and click-through variants); sellers SHOULD declare the window via `reporting_capabilities.measurement_windows` or `measurement_terms` rather than encoding it in this scalar.',
            ge=0.0,
        ),
    ] = None
    new_to_brand_units: Annotated[
        StrictFloat | None,
        Field(
            description='Units sold to first-time brand buyers (count, not rate). Retail-media scalar — the unit-volume parallel to the conversion-fraction `new_to_brand_rate`. Used by retail media platforms where new-customer acquisition unit volume is a primary KPI. Same attribution-window note as `units_sold` applies.',
            ge=0.0,
        ),
    ] = None
    by_action_source: Annotated[
        list[ByActionSourceItem] | None,
        Field(
            description='Conversion metrics broken down by action source (website, app, in_store, etc.). Useful for omnichannel sellers where conversions occur across digital and physical channels.'
        ),
    ] = None
    vendor_metric_values: Annotated[
        list[vendor_metric_value.VendorMetricValue] | None,
        Field(
            description="Reported values for vendor-defined metrics that the product's `reporting_capabilities.vendor_metrics` declared. Each entry carries the vendor (BrandRef), the metric identifier within the vendor's vocabulary, the value, optional unit, and `measurable_impressions` as the coverage denominator — vendor measurement is rarely 100% of delivered impressions, since vendors only score impressions where their SDK fires or their panel matches. When a declared vendor metric is omitted from this array, buyers infer no measurement happened (no integration). One row per `(vendor.domain, vendor.brand_id, metric_id, qualifier)` per reporting period — the same vendor metric MAY appear in multiple rows only when each carries a distinct qualifier (e.g., 7-day and 30-day attribution windows); sellers MUST de-duplicate before emission and MUST NOT emit two rows with the same tuple; buyers MAY treat duplicate rows as a seller-side conformance bug. The structured `vendor_metric_values` array is the recommended path for vendor metrics; `additionalProperties: true` on this parent object is preserved so existing free-form vendor emissions remain conformant during migration."
        ),
    ] = 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

• CatalogItemDeliveryMetrics
• CollectionDeliveryMetrics
• CollectionPropertyDeliveryMetrics
• CreativeDeliveryMetrics
• CreativeVariant
• GeoDeliveryMetrics
• InstallmentDeliveryMetrics
• InstallmentPropertyDeliveryMetrics
• KeywordDeliveryMetrics
• PlacementDeliveryMetrics
• PlacementPropertyDeliveryMetrics
• PropertyDeliveryMetrics
• ByAudienceItem
• ByDemographicItem
• ByDevicePlatformItem
• ByDeviceTypeItem
• ByFormatItem
• ByPackageItem
• ByPackageItem1
• BySpotItem
• Totals
• ByPackageItem
• Totals

Class variables

var brand_lift : float | None

var brand_search_lift : float | None

var by_action_source : list[ByActionSourceItem] | None

var by_event_type : list[ByEventTypeItem] | None

var clicks : float | None

var commissionable_value : float | None

var completed_views : float | None

var completion_rate : float | None

var conversion_lift : float | None

var conversion_value : float | None

var conversions : float | None

var cost_per_acquisition : float | None

var cost_per_click : float | None

var cost_per_completed_view : float | None

var cpm : float | None

var ctr : float | None

var dooh_metrics : DoohMetrics1 | None

var downloads : float | None

var engagement_rate : float | None

var engagements : float | None

var follows : float | None

var foot_traffic : float | None

var frequency : float | None

var grps : float | None

var impressions : float | None

var incremental_sales_lift : float | None

var leads : float | None

var measurement_source : str | None

var model_config

var new_to_brand_rate : float | None

var new_to_brand_units : float | None

var ooh_metrics : OohMetrics | None

var plays : float | None

var profile_visits : float | None

var quartile_data : QuartileData | None

var reach : float | None

var reach_unit : ReachUnit | None

var reach_window : ReachWindow | None

var roas : float | None

var saves : float | None

var spend : float | None

var time_based_views : list[TimeBasedView] | None

var units_sold : float | None

var vendor_metric_values : list[VendorMetricValue] | None

var viewability : Viewability1 | None

var views : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DeliveryStatus (*args, **kwds)

Expand source code

class DeliveryStatus(StrEnum):
    delivering = 'delivering'
    not_delivering = 'not_delivering'
    completed = 'completed'
    budget_exhausted = 'budget_exhausted'
    flight_ended = 'flight_ended'
    goal_met = 'goal_met'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var budget_exhausted

var completed

var delivering

var flight_ended

var goal_met

var not_delivering

class DeliveryType (*args, **kwds)

Expand source code

class DeliveryType(StrEnum):
    guaranteed = 'guaranteed'
    non_guaranteed = 'non_guaranteed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var guaranteed

var non_guaranteed

class DemographicSystem (*args, **kwds)

Expand source code

class DemographicSystem(StrEnum):
    nielsen = 'nielsen'
    nielsen_audio = 'nielsen_audio'
    barb = 'barb'
    agf = 'agf'
    oztam = 'oztam'
    mediametrie = 'mediametrie'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var agf

var barb

var custom

var mediametrie

var nielsen

var nielsen_audio

var oztam

class PlatformDeployment (**data: Any)

Expand source code

class Deployment1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['platform'],
        Field(description='Discriminator indicating this is a platform-based deployment'),
    ] = 'platform'
    platform: Annotated[str, Field(description='Platform identifier for DSPs')]
    account: Annotated[str | None, Field(description='Account identifier if applicable')] = None
    is_live: Annotated[
        StrictBool, Field(description='Whether signal is currently active on this deployment')
    ]
    activation_key: Annotated[
        activation_key_1.ActivationKey | None,
        Field(
            description='The key to use for targeting. Only present if is_live=true AND requester has access to this deployment.'
        ),
    ] = None
    estimated_activation_duration_minutes: Annotated[
        StrictFloat | None,
        Field(
            description='Estimated time to activate if not live, or to complete activation if in progress',
            ge=0.0,
        ),
    ] = None
    deployed_at: Annotated[
        AwareDatetime | None,
        Field(description='Timestamp when activation completed (if is_live=true)'),
    ] = 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

Class variables

var account : str | None

var activation_key : ActivationKey1 | ActivationKey2 | None

var deployed_at : pydantic.types.AwareDatetime | None

var estimated_activation_duration_minutes : float | None

var is_live : bool

var model_config

var platform : str

var type : Literal['platform']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AgentDeployment (**data: Any)

Expand source code

class Deployment2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['agent'],
        Field(description='Discriminator indicating this is an agent URL-based deployment'),
    ] = 'agent'
    agent_url: Annotated[AnyUrl, Field(description='URL identifying the deployment agent')]
    account: Annotated[str | None, Field(description='Account identifier if applicable')] = None
    is_live: Annotated[
        StrictBool, Field(description='Whether signal is currently active on this deployment')
    ]
    activation_key: Annotated[
        activation_key_1.ActivationKey | None,
        Field(
            description='The key to use for targeting. Only present if is_live=true AND requester has access to this deployment.'
        ),
    ] = None
    estimated_activation_duration_minutes: Annotated[
        StrictFloat | None,
        Field(
            description='Estimated time to activate if not live, or to complete activation if in progress',
            ge=0.0,
        ),
    ] = None
    deployed_at: Annotated[
        AwareDatetime | None,
        Field(description='Timestamp when activation completed (if is_live=true)'),
    ] = 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

Class variables

var account : str | None

var activation_key : ActivationKey1 | ActivationKey2 | None

var agent_url : pydantic.networks.AnyUrl

var deployed_at : pydantic.types.AwareDatetime | None

var estimated_activation_duration_minutes : float | None

var is_live : bool

var model_config

var type : Literal['agent']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PlatformDestination (**data: Any)

Expand source code

class Destination1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['platform'],
        Field(description='Discriminator indicating this is a platform-based deployment'),
    ] = 'platform'
    platform: Annotated[
        str,
        Field(description="Platform identifier for DSPs (e.g., 'the-trade-desk', 'amazon-dsp')"),
    ]
    account: Annotated[
        str | None, Field(description='Optional account identifier on the platform')
    ] = 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

Class variables

var account : str | None

var model_config

var platform : str

var type : Literal['platform']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AgentDestination (**data: Any)

Expand source code

class Destination2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['agent'],
        Field(description='Discriminator indicating this is an agent URL-based deployment'),
    ] = 'agent'
    agent_url: Annotated[
        AnyUrl, Field(description='URL identifying the deployment agent (for sales agents, etc.)')
    ]
    account: Annotated[
        str | None, Field(description='Optional account identifier on the agent')
    ] = 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

Class variables

var account : str | None

var agent_url : pydantic.networks.AnyUrl

var model_config

var type : Literal['agent']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DevicePlatform (*args, **kwds)

Expand source code

class DevicePlatform(StrEnum):
    ios = 'ios'
    android = 'android'
    windows = 'windows'
    macos = 'macos'
    linux = 'linux'
    chromeos = 'chromeos'
    tvos = 'tvos'
    tizen = 'tizen'
    webos = 'webos'
    fire_os = 'fire_os'
    roku_os = 'roku_os'
    unknown = 'unknown'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var android

var chromeos

var fire_os

var ios

var linux

var macos

var roku_os

var tizen

var tvos

var unknown

var webos

var windows

class DeviceType (*args, **kwds)

Expand source code

class DeviceType(StrEnum):
    desktop = 'desktop'
    mobile = 'mobile'
    tablet = 'tablet'
    ctv = 'ctv'
    dooh = 'dooh'
    unknown = 'unknown'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var ctv

var desktop

var dooh

var mobile

var tablet

var unknown

class DimensionUnit (*args, **kwds)

Expand source code

class DimensionUnit(StrEnum):
    px = 'px'
    dp = 'dp'
    inches = 'inches'
    cm = 'cm'
    mm = 'mm'
    pt = 'pt'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var cm

var dp

var inches

var mm

var pt

var px

class Unit (*args, **kwds)

Expand source code

class DimensionUnit(StrEnum):
    px = 'px'
    dp = 'dp'
    inches = 'inches'
    cm = 'cm'
    mm = 'mm'
    pt = 'pt'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var cm

var dp

var inches

var mm

var pt

var px

class V1CanonicalDimensions (**data: Any)

Expand source code

class Dimensions(AdCPBaseModel):
    width: SchemaInt | None = None
    height: SchemaInt | None = 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

Class variables

var height : int | None

var model_config

var width : int | None

class Dimensions (**data: Any)

Expand source code

class Dimensions(AdCPBaseModel):
    width: Annotated[
        StrictFloat | None,
        Field(description='Fixed width. Interpretation depends on unit (default: pixels).', gt=0.0),
    ] = None
    height: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed height. Interpretation depends on unit (default: pixels).', gt=0.0
        ),
    ] = None
    min_width: Annotated[
        StrictFloat | None, Field(description='Minimum width for responsive renders', gt=0.0)
    ] = None
    min_height: Annotated[
        StrictFloat | None, Field(description='Minimum height for responsive renders', gt=0.0)
    ] = None
    max_width: Annotated[
        StrictFloat | None, Field(description='Maximum width for responsive renders', gt=0.0)
    ] = None
    max_height: Annotated[
        StrictFloat | None, Field(description='Maximum height for responsive renders', gt=0.0)
    ] = None
    unit: Annotated[
        dimension_unit.DimensionUnit | None,
        Field(
            description="Unit of measurement for width/height values. Defaults to 'px' when absent. Print formats use 'inches' or 'cm'."
        ),
    ] = None
    responsive: Annotated[
        Responsive | None, Field(description='Indicates which dimensions are responsive/fluid')
    ] = None
    aspect_ratio: Annotated[
        str | None,
        Field(
            description="Fixed aspect ratio constraint (e.g., '16:9', '4:3', '1:1', '1.91:1')",
            pattern='^\\d+(\\.\\d+)?:\\d+(\\.\\d+)?$',
        ),
    ] = 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

• Dimensions1

Class variables

var aspect_ratio : str | None

var height : float | None

var max_height : float | None

var max_width : float | None

var min_height : float | None

var min_width : float | None

var model_config

var responsive : Responsive | None

var unit : DimensionUnit | None

var width : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Disclaimer (**data: Any)

Expand source code

class Disclaimer(AdCPBaseModel):
    text: str
    context: str | None = None
    required: StrictBool | None = True

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

Class variables

var context : str | None

var model_config

var required : bool | None

var text : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DoohMetrics (**data: Any)

Expand source code

class DoohMetrics(DoohMetrics1):
    pass

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

• DoohMetrics1
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

Inherited members

• DoohMetrics1:
  • model_dump
  • model_dump_json
  • model_summary

class DownstreamConnectionRequirement (**data: Any)

Expand source code

class DownstreamConnectionRequirement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    provider: Annotated[
        str | None,
        Field(
            description='Stable provider or platform namespace, preferably lowercase. Examples: `social.example`, `shortvideo.example`, or a seller-defined namespace. Omit only when the requirement is provider-agnostic, or when an `authorization_url` fully routes the human to the correct provider-specific connection flow.'
        ),
    ] = None
    connection_type: Annotated[
        ConnectionType,
        Field(
            description='Kind of downstream connection required. `advertiser_account` is the platform account used to buy/manage ads. `publisher_identity` is the creator, page, channel, organization, or profile that owns source posts. `post_authorization` is a post-scoped grant when the platform authorizes individual posts instead of, or in addition to, the owning identity.'
        ),
    ]
    required_for: Annotated[
        list[RequiredForItem] | None,
        Field(
            description='Concrete AdCP protocol operation names that require this downstream connection. Sellers SHOULD include this in product declarations when the requirement is known ahead of time, and in AUTHORIZATION_REQUIRED details when it explains the failed operation. Prefer specific operation names such as `list_creatives`, `sync_creatives`, `create_media_buy`, `get_media_buy_delivery`, or `get_creative_delivery` over broad category labels such as `reporting`.'
        ),
    ] = None
    scope: Annotated[Scope | None, Field(description='Granularity of the downstream grant.')] = None
    status: Annotated[
        Status | None,
        Field(
            description='Current seller-observed state for this downstream connection when known. Product declarations MAY omit status or use `unknown`; AUTHORIZATION_REQUIRED details SHOULD use `missing`, `expired`, or `revoked` for the connection that blocked the call.'
        ),
    ] = None
    connection_id: Annotated[
        str | None,
        Field(
            description='Seller-defined identifier for an already-created downstream connection. Omit when no connection exists yet or when exposing it would leak platform/account state.'
        ),
    ] = None
    resource_ref: Annotated[
        ResourceRef | None,
        Field(
            description='Optional opaque provider-native resource hint, such as a platform account id, profile URL, handle, channel id, post id, or post URL. This is a hint for routing authorization, not proof that authorization exists.'
        ),
    ] = None
    authorization_url: Annotated[
        AnyUrl | None,
        Field(
            description='Seller-hosted or provider-hosted URL where a human can complete or restore this downstream connection.'
        ),
    ] = None
    authorization_instructions: Annotated[
        str | None,
        Field(
            description='Human-readable instructions for completing or restoring this downstream connection.'
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(description='Expiration time for the downstream grant, when known.'),
    ] = 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

• Connection

Class variables

var authorization_instructions : str | None

var authorization_url : pydantic.networks.AnyUrl | None

var connection_id : str | None

var connection_type : ConnectionType

var expires_at : pydantic.types.AwareDatetime | None

var model_config

var provider : str | None

var required_for : list[RequiredForItem] | None

var resource_ref : ResourceRef | None

var scope : Scope | None

var status : Status | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Duration (**data: Any)

Expand source code

class Duration(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    interval: Annotated[
        SchemaInt,
        Field(description="Number of time units. Must be 1 when unit is 'campaign'.", ge=1),
    ]
    unit: Annotated[
        Unit,
        Field(
            description="Time unit. 'seconds' for sub-minute precision. 'campaign' spans the full campaign flight."
        ),
    ]

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

• MaximumAge
• MaximumAge

Class variables

var interval : int

var model_config

var unit : Unit

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.

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

• 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 EventType (*args, **kwds)

Expand source code

class EventType(StrEnum):
    page_view = 'page_view'
    view_content = 'view_content'
    select_content = 'select_content'
    select_item = 'select_item'
    search = 'search'
    share = 'share'
    add_to_cart = 'add_to_cart'
    remove_from_cart = 'remove_from_cart'
    viewed_cart = 'viewed_cart'
    add_to_wishlist = 'add_to_wishlist'
    initiate_checkout = 'initiate_checkout'
    add_payment_info = 'add_payment_info'
    purchase = 'purchase'
    refund = 'refund'
    lead = 'lead'
    qualify_lead = 'qualify_lead'
    close_convert_lead = 'close_convert_lead'
    disqualify_lead = 'disqualify_lead'
    complete_registration = 'complete_registration'
    subscribe = 'subscribe'
    follow = 'follow'
    content_view = 'content_view'
    watch_milestone = 'watch_milestone'
    start_trial = 'start_trial'
    app_install = 'app_install'
    app_launch = 'app_launch'
    contact = 'contact'
    schedule = 'schedule'
    donate = 'donate'
    submit_application = 'submit_application'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var add_payment_info

var add_to_cart

var add_to_wishlist

var app_install

var app_launch

var close_convert_lead

var complete_registration

var contact

var content_view

var custom

var disqualify_lead

var donate

var follow

var initiate_checkout

var lead

var page_view

var purchase

var qualify_lead

var refund

var remove_from_cart

var schedule

var search

var select_content

var select_item

var share

var start_trial

var submit_application

var subscribe

var view_content

var viewed_cart

var watch_milestone

class ExecutionRequirementUnmetDetails (**data: Any)

Expand source code

class ExecutionRequirementUnmetDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    unmet_requirements: Annotated[list[UnmetRequirement], Field(min_length=1)]

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

Class variables

var model_config

var unmet_requirements : list[UnmetRequirement]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ExtensionObject (**data: Any)

Expand source code

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

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

Class variables

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingConsumerFailureCode (*args, **kwds)

Expand source code

class FailureCode(StrEnum):
    access_denied = 'access_denied'
    resource_not_found = 'resource_not_found'
    integrity_mismatch = 'integrity_mismatch'
    reader_incompatible = 'reader_incompatible'
    transport_failed = 'transport_failed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var access_denied

var integrity_mismatch

var reader_incompatible

var resource_not_found

var transport_failed

class FeedFormat (*args, **kwds)

Expand source code

class FeedFormat(StrEnum):
    google_merchant_center = 'google_merchant_center'
    facebook_catalog = 'facebook_catalog'
    shopify = 'shopify'
    linkedin_jobs = 'linkedin_jobs'
    tiktok_shop = 'tiktok_shop'
    pinterest_catalog = 'pinterest_catalog'
    openai_product_feed = 'openai_product_feed'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var custom

var facebook_catalog

var google_merchant_center

var linkedin_jobs

var openai_product_feed

var pinterest_catalog

var shopify

var tiktok_shop

class FeedbackSource (*args, **kwds)

Expand source code

class FeedbackSource(StrEnum):
    buyer_attribution = 'buyer_attribution'
    third_party_measurement = 'third_party_measurement'
    platform_analytics = 'platform_analytics'
    verification_partner = 'verification_partner'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var buyer_attribution

var platform_analytics

var third_party_measurement

var verification_partner

class ListCreativesField (*args, **kwds)

Expand source code

class Field1(StrEnum):
    description = 'description'
    industries = 'industries'
    keller_type = 'keller_type'
    logos = 'logos'
    colors = 'colors'
    fonts = 'fonts'
    visual_guidelines = 'visual_guidelines'
    tone = 'tone'
    tagline = 'tagline'
    voice_synthesis = 'voice_synthesis'
    assets = 'assets'
    rights = 'rights'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var assets

var colors

var description

var fonts

var industries

var keller_type

var logos

var rights

var tagline

var tone

var visual_guidelines

var voice_synthesis

class GetProductsField (*args, **kwds)

Expand source code

class Field1(StrEnum):
    """Compatibility union of canonical and get-products-only fields."""

    product_id = 'product_id'
    name = 'name'
    description = 'description'
    publisher_properties = 'publisher_properties'
    channels = 'channels'
    video_placement_types = 'video_placement_types'
    audio_distribution_types = 'audio_distribution_types'
    sponsored_placement_types = 'sponsored_placement_types'
    social_placement_surfaces = 'social_placement_surfaces'
    format_options = 'format_options'
    placements = 'placements'
    delivery_type = 'delivery_type'
    exclusivity = 'exclusivity'
    pricing_options = 'pricing_options'
    forecast = 'forecast'
    reporting_capabilities = 'reporting_capabilities'
    measurement_terms = 'measurement_terms'
    performance_standards = 'performance_standards'
    catalog_types = 'catalog_types'
    signal_targeting_allowed = 'signal_targeting_allowed'
    signal_targeting_rules = 'signal_targeting_rules'
    demographic_targeting = 'demographic_targeting'
    overlay_support = 'overlay_support'
    collections = 'collections'
    collection_targeting_allowed = 'collection_targeting_allowed'
    media_buy_support = 'media_buy_support'
    audience_evidence = 'audience_evidence'
    audience_evidence_selections = 'audience_evidence_selections'
    max_optimization_goals = 'max_optimization_goals'
    catalog_match = 'catalog_match'
    list_applications = 'list_applications'
    brief_relevance = 'brief_relevance'
    targeting_resolution = 'targeting_resolution'
    acceptance_policy_profile_ids = 'acceptance_policy_profile_ids'
    identity = 'identity'
    execution_requirements = 'execution_requirements'
    expires_at = 'expires_at'
    allowed_actions = 'allowed_actions'
    format_ids = 'format_ids'
    outcome_measurement = 'outcome_measurement'
    delivery_measurement = 'delivery_measurement'
    creative_policy = 'creative_policy'
    metric_optimization = 'metric_optimization'
    conversion_tracking = 'conversion_tracking'
    data_provider_signals = 'data_provider_signals'
    included_signals = 'included_signals'
    signal_targeting_options = 'signal_targeting_options'
    installments = 'installments'
    is_custom = 'is_custom'
    product_card = 'product_card'
    product_card_detailed = 'product_card_detailed'
    enforced_policies = 'enforced_policies'
    trusted_match = 'trusted_match'

Compatibility union of canonical and get-products-only fields.

Ancestors

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

Class variables

var acceptance_policy_profile_ids

var allowed_actions

var audience_evidence

var audience_evidence_selections

var audio_distribution_types

var brief_relevance

var catalog_match

var catalog_types

var channels

var collection_targeting_allowed

var collections

var conversion_tracking

var creative_policy

var data_provider_signals

var delivery_measurement

var delivery_type

var demographic_targeting

var description

var enforced_policies

var exclusivity

var execution_requirements

var expires_at

var forecast

var format_ids

var format_options

var identity

var included_signals

var installments

var is_custom

var list_applications

var max_optimization_goals

var measurement_terms

var media_buy_support

var metric_optimization

var name

var outcome_measurement

var overlay_support

var performance_standards

var placements

var pricing_options

var product_card

var product_card_detailed

var product_id

var publisher_properties

var reporting_capabilities

var signal_targeting_allowed

var signal_targeting_options

var signal_targeting_rules

var social_placement_surfaces

var sponsored_placement_types

var targeting_resolution

var trusted_match

var video_placement_types

class GetBrandIdentityField (*args, **kwds)

Expand source code

class Field1(StrEnum):
    description = 'description'
    industries = 'industries'
    keller_type = 'keller_type'
    logos = 'logos'
    colors = 'colors'
    fonts = 'fonts'
    visual_guidelines = 'visual_guidelines'
    tone = 'tone'
    tagline = 'tagline'
    voice_synthesis = 'voice_synthesis'
    assets = 'assets'
    rights = 'rights'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var assets

var colors

var description

var fonts

var industries

var keller_type

var logos

var rights

var tagline

var tone

var visual_guidelines

var voice_synthesis

class FieldModel (*args, **kwds)

Expand source code

class Field1(StrEnum):
    """Compatibility union of canonical and get-products-only fields."""

    product_id = 'product_id'
    name = 'name'
    description = 'description'
    publisher_properties = 'publisher_properties'
    channels = 'channels'
    video_placement_types = 'video_placement_types'
    audio_distribution_types = 'audio_distribution_types'
    sponsored_placement_types = 'sponsored_placement_types'
    social_placement_surfaces = 'social_placement_surfaces'
    format_options = 'format_options'
    placements = 'placements'
    delivery_type = 'delivery_type'
    exclusivity = 'exclusivity'
    pricing_options = 'pricing_options'
    forecast = 'forecast'
    reporting_capabilities = 'reporting_capabilities'
    measurement_terms = 'measurement_terms'
    performance_standards = 'performance_standards'
    catalog_types = 'catalog_types'
    signal_targeting_allowed = 'signal_targeting_allowed'
    signal_targeting_rules = 'signal_targeting_rules'
    demographic_targeting = 'demographic_targeting'
    overlay_support = 'overlay_support'
    collections = 'collections'
    collection_targeting_allowed = 'collection_targeting_allowed'
    media_buy_support = 'media_buy_support'
    audience_evidence = 'audience_evidence'
    audience_evidence_selections = 'audience_evidence_selections'
    max_optimization_goals = 'max_optimization_goals'
    catalog_match = 'catalog_match'
    list_applications = 'list_applications'
    brief_relevance = 'brief_relevance'
    targeting_resolution = 'targeting_resolution'
    acceptance_policy_profile_ids = 'acceptance_policy_profile_ids'
    identity = 'identity'
    execution_requirements = 'execution_requirements'
    expires_at = 'expires_at'
    allowed_actions = 'allowed_actions'
    format_ids = 'format_ids'
    outcome_measurement = 'outcome_measurement'
    delivery_measurement = 'delivery_measurement'
    creative_policy = 'creative_policy'
    metric_optimization = 'metric_optimization'
    conversion_tracking = 'conversion_tracking'
    data_provider_signals = 'data_provider_signals'
    included_signals = 'included_signals'
    signal_targeting_options = 'signal_targeting_options'
    installments = 'installments'
    is_custom = 'is_custom'
    product_card = 'product_card'
    product_card_detailed = 'product_card_detailed'
    enforced_policies = 'enforced_policies'
    trusted_match = 'trusted_match'

Compatibility union of canonical and get-products-only fields.

Ancestors

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

Class variables

var acceptance_policy_profile_ids

var allowed_actions

var audience_evidence

var audience_evidence_selections

var audio_distribution_types

var brief_relevance

var catalog_match

var catalog_types

var channels

var collection_targeting_allowed

var collections

var conversion_tracking

var creative_policy

var data_provider_signals

var delivery_measurement

var delivery_type

var demographic_targeting

var description

var enforced_policies

var exclusivity

var execution_requirements

var expires_at

var forecast

var format_ids

var format_options

var identity

var included_signals

var installments

var is_custom

var list_applications

var max_optimization_goals

var measurement_terms

var media_buy_support

var metric_optimization

var name

var outcome_measurement

var overlay_support

var performance_standards

var placements

var pricing_options

var product_card

var product_card_detailed

var product_id

var publisher_properties

var reporting_capabilities

var signal_targeting_allowed

var signal_targeting_options

var signal_targeting_rules

var social_placement_surfaces

var sponsored_placement_types

var targeting_resolution

var trusted_match

var video_placement_types

class FlatRatePricingOption (**data: Any)

Expand source code

class FlatRatePricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['flat_rate'], Field(description='Fixed cost regardless of delivery volume')
    ] = 'flat_rate'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Flat rate cost. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    parameters: Annotated[
        Parameters | None,
        Field(
            description='DOOH inventory allocation parameters. Sponsorship and takeover flat_rate options omit this field entirely — only include for digital out-of-home inventory.',
            title='DoohParameters',
        ),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var min_spend_per_package : float | None

var model_config

var parameters : Parameters | None

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['flat_rate']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Fonts (**data: Any)

Expand source code

class Fonts(AdCPBaseModel):
    __pydantic_extra__: Dict[str, FontRole]
    model_config = ConfigDict(
        extra='allow',
    )
    primary: Annotated[FontRole | None, Field(description='Primary font family')] = None
    secondary: Annotated[FontRole | None, Field(description='Secondary font family')] = 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

Class variables

var model_config

var primary : FontRole | None

var secondary : FontRole | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ForecastMethod (*args, **kwds)

Expand source code

class ForecastMethod(StrEnum):
    estimate = 'estimate'
    modeled = 'modeled'
    guaranteed = 'guaranteed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var estimate

var guaranteed

var modeled

class ForecastPoint (**data: Any)

Expand source code

class ForecastPoint(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    label: Annotated[
        str | None,
        Field(
            description="Human-readable name for this forecast point. Required when forecast_range_unit is 'package' so buyer agents can identify and reference individual packages. Optional for other forecast types.",
            examples=['Primetime', 'Morning Drive', 'Large Format Transit'],
            max_length=128,
        ),
    ] = None
    budget: Annotated[
        StrictFloat | None,
        Field(
            description='Budget amount for this forecast point. Required for spend curves; omit for availability forecasts where the metrics represent total available inventory. For allocation-level forecasts, this is the absolute budget for that allocation (not the percentage). For proposal-level forecasts, this is the total proposal budget. When omitted, use metrics.spend to express the estimated cost of the available inventory.',
            ge=0.0,
        ),
    ] = None
    product_id: Annotated[
        str | None,
        Field(
            description='Optional product context for this forecast row. Usually omitted on product-level and allocation-level forecasts where the product is already implied. On proposal-level forecasts, populate when a dimensional row, especially a placement row, maps to a specific product allocation so buyers can turn the row into an executable package choice. Omit for true aggregate proposal rows spanning multiple products.'
        ),
    ] = None
    dimensions: Annotated[
        forecast_point_dimensions.ForecastPointDimensions | None,
        Field(
            description='Dimension constraints represented by this forecast point, such as country, region, placement, device type, platform, audience, signal value, time window, or intersections such as placement x country or product x signal. Each item declares one dimension family; when multiple items are present, the point represents their intersection. Sellers MUST NOT emit more than one item for each `kind` on a point; consumers MUST NOT treat repeated kinds as OR semantics. Use multiple points with dimensions to expose country/placement/signal availability within one product, proposal, or signal coverage forecast without creating separate products solely for each dimension. Dimensions describe the forecast row and are independent of pricing_options.'
        ),
    ] = None
    availability_status: Annotated[
        availability_status_1.AvailabilityStatus | None,
        Field(
            description="Bookability of the inventory this row describes, as of the forecast's generated_at. Most meaningful on rows with a time dimension in an availability forecast (forecast_range_unit 'availability'). This is a snapshot, not a hold: valid_until bounds freshness, and proposal finalization or purchase remains the commitment boundary. When omitted, the row makes no bookability claim. 'unavailable' rows may carry empty metrics."
        ),
    ] = None
    metrics: Annotated[
        Metrics,
        Field(
            description='Forecasted metric values. Keys are forecastable-metric enum values for delivery/engagement or event-type enum values for outcomes. Values are ForecastRange objects (low/mid/high). Use { "mid": value } for point estimates. When budget is present, these are the expected metrics at that spend level. When budget is omitted, these represent total available inventory — use spend to express the estimated cost. Additional keys beyond the documented properties are allowed for event-type values (purchase, lead, app_install, etc.).'
        ),
    ]
    viewability: Annotated[
        Viewability | None,
        Field(
            description='Forecasted viewability metrics. Mirrors delivery-metrics.viewability, but numeric values are ForecastRange objects because forecast rows may provide low/mid/high bounds. Use this for pre-buy viewability expectations by forecast point without folding measurement metrics into pricing_options.'
        ),
    ] = None
    vendor_metric_values: Annotated[
        list[forecast_vendor_metric_value.ForecastVendorMetricValue] | None,
        Field(
            description="Forecasted values for vendor-defined metrics that the product's reporting_capabilities.vendor_metrics declared. Mirrors delivery-metrics.vendor_metric_values, but value and measurable_impressions use ForecastRange. These forecasted measurement values are independent of pricing_options."
        ),
    ] = 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

• Point

Class variables

var availability_status : AvailabilityStatus | None

var budget : float | None

var dimensions : ForecastPointDimensions | None

var label : str | None

var metrics : Metrics

var model_config

var product_id : str | None

var vendor_metric_values : list[ForecastVendorMetricValue] | None

var viewability : Viewability | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ForecastRange (**data: Any)

Expand source code

class ForecastRange(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    low: Annotated[
        StrictFloat | None, Field(description='Conservative (low-end) forecast value', ge=0.0)
    ] = None
    mid: Annotated[
        StrictFloat | None, Field(description='Expected (most likely) forecast value', ge=0.0)
    ] = None
    high: Annotated[
        StrictFloat | None, Field(description='Optimistic (high-end) forecast value', ge=0.0)
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> ForecastRange:
        # ``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 (('mid',), ('low', 'high'),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'ForecastRange requires at least one of these field groups: mid | low+high'
        )

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

• CoverageRate
• ForecastRateRange

Class variables

var high : float | None

var low : float | None

var mid : float | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ForecastRangeUnit (*args, **kwds)

Expand source code

class ForecastRangeUnit(StrEnum):
    spend = 'spend'
    availability = 'availability'
    reach_freq = 'reach_freq'
    weekly = 'weekly'
    daily = 'daily'
    clicks = 'clicks'
    conversions = 'conversions'
    package = 'package'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var availability

var clicks

var conversions

var daily

var package

var reach_freq

var spend

var weekly

class ForecastableMetric (*args, **kwds)

Expand source code

class ForecastableMetric(StrEnum):
    audience_size = 'audience_size'
    reach = 'reach'
    frequency = 'frequency'
    impressions = 'impressions'
    clicks = 'clicks'
    spend = 'spend'
    views = 'views'
    completed_views = 'completed_views'
    grps = 'grps'
    engagements = 'engagements'
    follows = 'follows'
    saves = 'saves'
    profile_visits = 'profile_visits'
    measured_impressions = 'measured_impressions'
    downloads = 'downloads'
    plays = 'plays'
    coverage_rate = 'coverage_rate'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audience_size

var clicks

var completed_views

var coverage_rate

var downloads

var engagements

var follows

var frequency

var grps

var impressions

var measured_impressions

var plays

var profile_visits

var reach

var saves

var spend

var views

class Format (**data: Any)

Expand source code

class Format(CanonicalBoundaryModel):
    """Canonical format declaration exposed as ``adcp.Format``."""

    format_option_id: str | None = Field(
        default=None,
        description="Stable option identifier within the product or publisher namespace.",
    )
    publisher_domain: str | None = Field(
        default=None,
        pattern=r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$",
    )
    display_name: str | None = None
    applies_to_channels: list[MediaChannel] | None = None
    seller_preference: SellerPreference | None = None
    canonical_formats_only: bool | None = None
    experimental: bool | None = None
    format_shape: str | None = None
    format_schema: PlatformExtensionReference | None = None
    format_kind: str
    params: dict[str, Any]

    _legacy_format_refs: list[LegacyFormatId] = PrivateAttr(default_factory=list)

    @model_validator(mode="before")
    @classmethod
    def _reject_legacy_conflicts_and_credentials(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        if data.get("canonical_formats_only") is True and data.get("v1_format_ref"):
            raise ValueError(
                "canonical_formats_only=True is mutually exclusive with legacy v1_format_ref"
            )
        for bag_name, bag in (
            ("params", data.get("params")),
            (
                "extras",
                {
                    key: value
                    for key, value in data.items()
                    if key not in cls.model_fields and key != "v1_format_ref"
                },
            ),
        ):
            found = _walk_for_credential_keys(bag, path=bag_name)
            if found is not None:
                raise ValueError(
                    f"{found!r} matches a credential-shaped key suffix and cannot "
                    "be stored in a canonical format declaration"
                )
        return data

    def __init__(self, **data: Any) -> None:
        refs = data.get("v1_format_ref")
        if "capability_id" in data and "format_option_id" not in data:
            data["format_option_id"] = data.pop("capability_id")
        super().__init__(**data)
        if self.__pydantic_extra__ is not None:
            self.__pydantic_extra__.pop("v1_format_ref", None)
        if refs:
            self._legacy_format_refs = [
                LegacyFormatId.model_validate(copy.deepcopy(ref)) for ref in refs
            ]

    @property
    def legacy_format_refs(self) -> tuple[LegacyFormatId, ...]:
        """Original tuples retained only for an explicit compatibility adapter."""

        return tuple(copy.deepcopy(ref) for ref in self._legacy_format_refs)

    def params_as(self, canonical_type: type[_CanonicalParamsT]) -> _CanonicalParamsT:
        """Validate the open parameter bag against a typed canonical model."""

        return canonical_type.model_validate(self.params)

    @model_validator(mode="after")
    def _validate_custom_shape(self) -> Format:
        if self.format_kind == CanonicalFormatKind.custom.value:
            if not self.format_shape:
                raise ValueError("custom formats require format_shape")
            if self.format_schema is None:
                raise ValueError("custom formats require format_schema")
        elif self.format_shape is not None or self.format_schema is not None:
            raise ValueError("format_shape and format_schema are only valid for custom formats")
        return self

Canonical format declaration exposed as Format.

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

• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var applies_to_channels : list[MediaChannel] | None

var canonical_formats_only : bool | None

var display_name : str | None

var experimental : bool | None

var format_kind : str

var format_option_id : str | None

var format_schema : PlatformExtensionReference | None

var format_shape : str | None

var model_config

var params : dict[str, typing.Any]

var publisher_domain : str | None

var seller_preference : SellerPreference | None

Instance variables

prop legacy_format_refs : tuple[FormatReferenceStructuredObject, ...]

Expand source code

@property
def legacy_format_refs(self) -> tuple[LegacyFormatId, ...]:
    """Original tuples retained only for an explicit compatibility adapter."""

    return tuple(copy.deepcopy(ref) for ref in self._legacy_format_refs)

Original tuples retained only for an explicit compatibility adapter.

Methods

def model_post_init(self: BaseModel, context: Any, /) ‑> None

Expand source code

def init_private_attributes(self: BaseModel, context: Any, /) -> None:
    """This function is meant to behave like a BaseModel method to initialize private attributes.

    It takes context as an argument since that's what pydantic-core passes when calling it.

    Args:
        self: The BaseModel instance.
        context: The context.
    """
    if getattr(self, '__pydantic_private__', None) is None:
        pydantic_private = {}
        for name, private_attr in self.__private_attributes__.items():
            # Avoid needlessly creating a new dict for the validated data:
            if private_attr.default_factory_takes_validated_data:
                default = private_attr.get_default(
                    call_default_factory=True, validated_data={**self.__dict__, **pydantic_private}
                )
            else:
                default = private_attr.get_default(call_default_factory=True)
            if default is not PydanticUndefined:
                pydantic_private[name] = default
        object_setattr(self, '__pydantic_private__', pydantic_private)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that's what pydantic-core passes when calling it.

Args

-----=

self

The BaseModel instance.

context

The context.

def params_as(self, canonical_type: type[_CanonicalParamsT]) ‑> ~_CanonicalParamsT

Expand source code

def params_as(self, canonical_type: type[_CanonicalParamsT]) -> _CanonicalParamsT:
    """Validate the open parameter bag against a typed canonical model."""

    return canonical_type.model_validate(self.params)

Validate the open parameter bag against a typed canonical model.

class ProductFormatDeclaration (**data: Any)

Expand source code

class Format(CanonicalBoundaryModel):
    """Canonical format declaration exposed as ``adcp.Format``."""

    format_option_id: str | None = Field(
        default=None,
        description="Stable option identifier within the product or publisher namespace.",
    )
    publisher_domain: str | None = Field(
        default=None,
        pattern=r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$",
    )
    display_name: str | None = None
    applies_to_channels: list[MediaChannel] | None = None
    seller_preference: SellerPreference | None = None
    canonical_formats_only: bool | None = None
    experimental: bool | None = None
    format_shape: str | None = None
    format_schema: PlatformExtensionReference | None = None
    format_kind: str
    params: dict[str, Any]

    _legacy_format_refs: list[LegacyFormatId] = PrivateAttr(default_factory=list)

    @model_validator(mode="before")
    @classmethod
    def _reject_legacy_conflicts_and_credentials(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        if data.get("canonical_formats_only") is True and data.get("v1_format_ref"):
            raise ValueError(
                "canonical_formats_only=True is mutually exclusive with legacy v1_format_ref"
            )
        for bag_name, bag in (
            ("params", data.get("params")),
            (
                "extras",
                {
                    key: value
                    for key, value in data.items()
                    if key not in cls.model_fields and key != "v1_format_ref"
                },
            ),
        ):
            found = _walk_for_credential_keys(bag, path=bag_name)
            if found is not None:
                raise ValueError(
                    f"{found!r} matches a credential-shaped key suffix and cannot "
                    "be stored in a canonical format declaration"
                )
        return data

    def __init__(self, **data: Any) -> None:
        refs = data.get("v1_format_ref")
        if "capability_id" in data and "format_option_id" not in data:
            data["format_option_id"] = data.pop("capability_id")
        super().__init__(**data)
        if self.__pydantic_extra__ is not None:
            self.__pydantic_extra__.pop("v1_format_ref", None)
        if refs:
            self._legacy_format_refs = [
                LegacyFormatId.model_validate(copy.deepcopy(ref)) for ref in refs
            ]

    @property
    def legacy_format_refs(self) -> tuple[LegacyFormatId, ...]:
        """Original tuples retained only for an explicit compatibility adapter."""

        return tuple(copy.deepcopy(ref) for ref in self._legacy_format_refs)

    def params_as(self, canonical_type: type[_CanonicalParamsT]) -> _CanonicalParamsT:
        """Validate the open parameter bag against a typed canonical model."""

        return canonical_type.model_validate(self.params)

    @model_validator(mode="after")
    def _validate_custom_shape(self) -> Format:
        if self.format_kind == CanonicalFormatKind.custom.value:
            if not self.format_shape:
                raise ValueError("custom formats require format_shape")
            if self.format_schema is None:
                raise ValueError("custom formats require format_schema")
        elif self.format_shape is not None or self.format_schema is not None:
            raise ValueError("format_shape and format_schema are only valid for custom formats")
        return self

Canonical format declaration exposed as Format.

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

• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var applies_to_channels : list[MediaChannel] | None

var canonical_formats_only : bool | None

var display_name : str | None

var experimental : bool | None

var format_kind : str

var format_option_id : str | None

var format_schema : PlatformExtensionReference | None

var format_shape : str | None

var model_config

var params : dict[str, typing.Any]

var publisher_domain : str | None

var seller_preference : SellerPreference | None

Instance variables

prop legacy_format_refs : tuple[FormatReferenceStructuredObject, ...]

Expand source code

@property
def legacy_format_refs(self) -> tuple[LegacyFormatId, ...]:
    """Original tuples retained only for an explicit compatibility adapter."""

    return tuple(copy.deepcopy(ref) for ref in self._legacy_format_refs)

Original tuples retained only for an explicit compatibility adapter.

Methods

def model_post_init(self: BaseModel, context: Any, /) ‑> None

Expand source code

def init_private_attributes(self: BaseModel, context: Any, /) -> None:
    """This function is meant to behave like a BaseModel method to initialize private attributes.

    It takes context as an argument since that's what pydantic-core passes when calling it.

    Args:
        self: The BaseModel instance.
        context: The context.
    """
    if getattr(self, '__pydantic_private__', None) is None:
        pydantic_private = {}
        for name, private_attr in self.__private_attributes__.items():
            # Avoid needlessly creating a new dict for the validated data:
            if private_attr.default_factory_takes_validated_data:
                default = private_attr.get_default(
                    call_default_factory=True, validated_data={**self.__dict__, **pydantic_private}
                )
            else:
                default = private_attr.get_default(call_default_factory=True)
            if default is not PydanticUndefined:
                pydantic_private[name] = default
        object_setattr(self, '__pydantic_private__', pydantic_private)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that's what pydantic-core passes when calling it.

Args

-----=

self

The BaseModel instance.

context

The context.

def params_as(self, canonical_type: type[_CanonicalParamsT]) ‑> ~_CanonicalParamsT

Expand source code

def params_as(self, canonical_type: type[_CanonicalParamsT]) -> _CanonicalParamsT:
    """Validate the open parameter bag against a typed canonical model."""

    return canonical_type.model_validate(self.params)

Validate the open parameter bag against a typed canonical model.

class LegacyFormat (**data: Any)

Expand source code

class Format(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject,
        Field(
            description="This format's own identifier — a structured object {agent_url, id}, not a string. See /schemas/core/format-id.json for the full shape."
        ),
    ]
    name: Annotated[str, Field(description='Human-readable format name')]
    description: Annotated[
        str | None,
        Field(
            description='Plain text explanation of what this format does and what assets it requires'
        ),
    ] = None
    example_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional URL to showcase page with examples and interactive demos of this format'
        ),
    ] = None
    accepts_parameters: Annotated[
        list[format_id_parameter.FormatIdParameter] | None,
        Field(
            description='List of parameters this format accepts in format_id. Template formats define which parameters (dimensions, duration, etc.) can be specified when instantiating the format. Empty or omitted means this is a concrete format with fixed parameters.'
        ),
    ] = None
    renders: Annotated[
        list[Renders | Renders1] | None,
        Field(
            description='Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.',
            min_length=1,
        ),
    ] = None
    assets: Annotated[
        list[
            Assets
            | Assets9
            | Assets10
            | Assets11
            | Assets12
            | Assets13
            | Assets14
            | Assets15
            | Assets16
            | Assets17
            | Assets18
            | Assets19
            | Assets20
            | Assets21
            | Assets22
            | Assets23
            | Assets24
            | Assets25
            | Assets26
            | Assets27
            | Assets28
            | Assets29
        ]
        | None,
        Field(
            description="Array of all assets supported for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Use the 'required' boolean on each asset to indicate whether it's mandatory."
        ),
    ] = None
    delivery: Annotated[
        dict[str, Any] | None,
        Field(description='Delivery method specifications (e.g., hosted, VAST, third-party tags)'),
    ] = None
    supported_macros: Annotated[
        list[universal_macro.UniversalMacro | str] | None,
        Field(
            description='List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling. See docs/creative/universal-macros.mdx for full documentation.'
        ),
    ] = None
    input_format_ids: Annotated[
        list[format_id_1.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.1. Removed at 4.0.** Use `list_transformers` instead — a transformer declares its own `input_format_ids`/`output_format_ids`, so build capability is a property of the transformer (the unit you select and that carries pricing), not a relationship hung on a format. Discover build capability via `list_transformers` (optionally filtered by `input_format_ids`/`output_format_ids`).\n\nMigration: sellers that expressed transform capability by hanging `input_format_ids` on a format SHOULD declare a transformer via `list_transformers` instead. Buyers SHOULD discover build capability via `list_transformers` rather than filtering formats.\n\n*Legacy behavior, retained for 3.1–3.x backward compatibility:* array of format IDs this format accepts as input creative manifests; when present, indicates this format can take existing creatives in these formats as input. SDKs reading 3.1 catalogs MUST continue to honor this field when present; 4.0+ SDKs MAY reject it. New code SHOULD NOT emit this field.',
        ),
    ] = None
    output_format_ids: Annotated[
        list[format_id_1.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.1. Removed at 4.0.** Use `list_transformers` instead — a transformer declares its own `output_format_ids`, so what a builder can produce is a property of the transformer, not a relationship hung on a format. Discover via `list_transformers`.\n\nMigration: sellers that expressed multi-output build capability (e.g. a multi-publisher template) by hanging `output_format_ids` on a format SHOULD declare a transformer via `list_transformers` instead.\n\n*Legacy behavior, retained for 3.1–3.x backward compatibility:* array of format IDs this format can produce as output; when present, indicates this format can build creatives in these output formats. SDKs reading 3.1 catalogs MUST continue to honor this field when present; 4.0+ SDKs MAY reject it. New code SHOULD NOT emit this field.',
        ),
    ] = None
    format_card: Annotated[
        FormatCard | None,
        Field(
            description='Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.'
        ),
    ] = None
    accessibility: Annotated[
        Accessibility | None,
        Field(
            description='Accessibility posture of this format. Declares the WCAG conformance level that creatives produced by this format will meet.'
        ),
    ] = None
    supported_disclosure_positions: Annotated[
        list[disclosure_position.DisclosurePosition] | None,
        Field(
            description='Disclosure positions this format can render. Buyers use this to determine whether a format can satisfy their compliance requirements before submitting a creative. When omitted, the format makes no disclosure rendering guarantees — creative agents SHOULD treat this as incompatible with briefs that require specific disclosure positions. Values correspond to positions on creative-brief.json required_disclosures.',
            min_length=1,
        ),
    ] = None
    disclosure_capabilities: Annotated[
        list[DisclosureCapability] | None,
        Field(
            description='Structured disclosure capabilities per position with persistence modes. Declares which persistence behaviors each disclosure position supports, enabling persistence-aware matching against provenance render guidance and brief requirements. When present, supersedes supported_disclosure_positions for persistence-aware queries. The flat supported_disclosure_positions field is retained for backward compatibility. Each position MUST appear at most once; validators and agents SHOULD reject duplicates.',
            min_length=1,
        ),
    ] = None
    format_card_detailed: Annotated[
        FormatCardDetailed | None,
        Field(
            description='Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.'
        ),
    ] = None
    reported_metrics: Annotated[
        list[available_metric.AvailableMetric] | None,
        Field(
            description='Metrics this format can produce in delivery reporting. Buyers receive the intersection of format reported_metrics and product available_metrics. Under `enums/available-metric.json`, a container such as `viewability` subsumes numeric leaves such as `viewable_rate`; structured distributions match only their explicit `viewed_seconds_percentiles` or `viewed_seconds_histogram` identities. If omitted, the format defers entirely to product-level metric declarations.',
            min_length=1,
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.1. Removed at 4.0.** Use `transformer.pricing_options` (via `list_transformers`) instead — pricing belongs on the transformer (the unit selected and billed), exactly as it belongs on a media-buy product. Once formats only describe output shape, format-level pricing is vestigial.\n\nMigration: transformation/generation agents that charged via `format.pricing_options` SHOULD move the same `vendor-pricing-option` entries onto the corresponding transformer. The applied option is echoed per-leaf on the build_creative response and reconciled via report_usage, unchanged.\n\n*Legacy behavior, retained for 3.1–3.x backward compatibility:* pricing options for this format, used by transformation/generation agents that charge per format adapted, per image generated, or per unit of work; present when the request included include_pricing=true and account. SDKs reading 3.1 catalogs MUST continue to honor this field when present; 4.0+ SDKs MAY reject it. New code SHOULD NOT emit this field.',
            min_length=1,
        ),
    ] = None
    canonical: Annotated[
        canonical_projection_ref.CanonicalProjectionReference | None,
        Field(
            description='Optional v2 canonical-projection annotation. Always an object — bare-string shorthand (`canonical: "image"`) is not supported; the minimal form is `canonical: { "kind": "image" }`. Carries `kind` (which canonical the v1 format projects to) plus optional `asset_source` and `slots_override` for cases where the v1 format\'s shape doesn\'t follow the canonical\'s defaults (e.g., generative entries whose input is `generation_prompt: text` instead of `image_main: image`).\n\nWhen set, SDKs use this annotation as the authoritative v1 → v2 mapping for this format, bypassing the [v1 canonical mapping registry](/schemas/registries/v1-canonical-mapping.json) lookup. Combined with the slot-level `asset_group_id` declarations on each `assets[i]` entry, a v1 format declaration with `canonical` set is fully self-describing for v1↔v2 translation.\n\nResolution order for SDK projection from v1 wire shape to v2 (per RFC #3305 amendment #3767):\n1. If this `canonical` field is set, use it (seller-declared, highest priority). Apply `asset_source` and `slots_override` from the projection ref when present; otherwise inherit the canonical\'s defaults.\n2. Else, look up `format_id` in the canonical mapping registry\'s `format_id_glob` entries.\n3. Else, attempt structural match against the registry\'s `structural` entries (asset types, slot shape, vast_versions, etc.).\n4. Else, fail closed: SDK MUST NOT emit `format_options` for products carrying this format. Surface `FORMAT_PROJECTION_FAILED` on the response `errors[]` suggesting the seller add an explicit `canonical` annotation or file a registry entry.\n\nWhen `canonical.kind` is `custom`, the seller MUST also declare `canonical_format_shape` and `canonical_format_schema` (parallel to ProductFormatDeclaration\'s `format_shape` and `format_schema`) so buyer SDKs can fetch the seller\'s custom format schema.\n\nSee `canonical-projection-ref.json` for full projection semantics and examples (default-slot case, generative case, brief-driven case).'
        ),
    ] = None
    canonical_parameters: Annotated[
        CanonicalParameters | None,
        Field(
            deprecated=True,
            description="**DEPRECATED in 3.1. Removed at 4.0.** Use `v1_format_ref` on the v2 `ProductFormatDeclaration` instead — the seller authors a v2 declaration (in `Product.format_options` or `creative.supported_formats`) and links it back to this v1 format via `v1_format_ref: { agent_url, id }`. The directional link from v2 → v1 is the same fact as `canonical_parameters` without the parallel-shape drift surface (v1 file and `canonical_parameters` were two declarations of the same thing; hand-authored, drifting silently).\n\nMigration: every seller currently authoring `canonical_parameters` SHOULD migrate to authoring a v2 declaration on the corresponding product (or capability) with `v1_format_ref` pointing back at this v1 format. v1 files become pure v1 again — no v2-shape mirroring.\n\n*Legacy behavior, retained for 3.1–3.x backward compatibility:* When `canonical` is set, this field carries the full ProductFormatDeclaration that the SDK projects this v1 format into. The `format_kind` MUST equal the `canonical` field value (validators enforce). When set, this is the authoritative source for SDK v1→v2 projection — the registry's structural-match parameter inference is bypassed. SDKs reading 3.1 catalogs MUST continue to honor `canonical_parameters` when present; 4.0+ SDKs MAY reject the field. New code SHOULD NOT emit this field. Seller execution authority is never projected through this deprecated field, so tracker_execution_contract and tracker_execution_contract_digest are forbidden.\n\n**Drift contract (still normative while supported).** Hand-authored `canonical_parameters` MUST satisfy the *narrows* relation against this v1 format's `requirements` and `assets[*]` shape (see canonical-formats.mdx 'Narrows — formal definition'). SDKs that read this v1 file SHOULD lint-time check the equivalence at build/load and emit `FORMAT_PROJECTION_FAILED` if the two disagree.",
        ),
    ] = 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

Class variables

var accepts_parameters : list[FormatIdParameter] | None

var accessibility : Accessibility | None

var assets : list[typing.Union[Assets, Assets9, Assets10, Assets11, Assets12, Assets13, Assets14, Assets15, Assets17, Assets18, Assets19, Assets20, Assets21, Assets22, Assets29, UnknownFormatAsset]] | None

var canonical : CanonicalProjectionReference | None

var delivery : dict[str, typing.Any] | None

var description : str | None

var disclosure_capabilities : list[DisclosureCapability] | None

var example_url : pydantic.networks.AnyUrl | None

var format_card : FormatCard | None

var format_card_detailed : FormatCardDetailed | None

var format_id : FormatReferenceStructuredObject

var model_config

var name : str

var renders : list[Renders | Renders1] | None

var reported_metrics : list[AvailableMetric] | None

var supported_disclosure_positions : list[DisclosurePosition] | None

var supported_macros : list[UniversalMacro | str] | None

Instance variables

var canonical_parameters : CanonicalParameters | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var input_format_ids : list[FormatReferenceStructuredObject] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var output_format_ids : list[FormatReferenceStructuredObject] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class FormatCard (**data: Any)

Expand source code

class FormatCard(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject,
        Field(
            description='Creative format defining the card layout (typically format_card_standard)'
        ),
    ]
    manifest: Annotated[
        dict[str, Any],
        Field(description='Asset manifest for rendering the card, structure defined by the format'),
    ]

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

Class variables

var format_id : FormatReferenceStructuredObject

var manifest : dict[str, typing.Any]

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class FormatCardDetailed (**data: Any)

Expand source code

class FormatCardDetailed(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatReferenceStructuredObject,
        Field(
            description='Creative format defining the detailed card layout (typically format_card_detailed)'
        ),
    ]
    manifest: Annotated[
        dict[str, Any],
        Field(
            description='Asset manifest for rendering the detailed card, structure defined by the format'
        ),
    ]

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

Class variables

var format_id : FormatReferenceStructuredObject

var manifest : dict[str, typing.Any]

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class FormatIdParameter (*args, **kwds)

Expand source code

class FormatIdParameter(StrEnum):
    dimensions = 'dimensions'
    duration = 'duration'
    pixel_ratio = 'pixel_ratio'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var dimensions

var duration

var pixel_ratio

class LegacyFormatId (**data: Any)

Expand source code

class FormatReferenceStructuredObject(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    agent_url: Annotated[
        WireUrl,
        Field(
            description="URL of the agent that defines this format (e.g., 'https://creative.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats). Callers comparing two `format-id` values MUST canonicalize `agent_url` per the AdCP URL canonicalization rules before treating two formats as the same. See docs/reference/url-canonicalization."
        ),
    ]
    id: Annotated[
        str,
        Field(
            description="Format identifier within the agent's namespace (e.g., 'display_static', 'video_hosted', 'audio_standard'). When used alone, references a template format. When combined with dimension/duration fields, creates a parameterized format ID for a specific variant.",
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ]
    width: Annotated[
        SchemaInt | None,
        Field(
            description='Width in pixels for visual formats. When specified, height must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
            ge=1,
        ),
    ] = None
    height: Annotated[
        SchemaInt | None,
        Field(
            description='Height in pixels for visual formats. When specified, width must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
            ge=1,
        ),
    ] = None
    duration_ms: Annotated[
        StrictFloat | None,
        Field(
            description='Duration in milliseconds for time-based formats (video, audio). When specified, creates a parameterized format ID. Omit to reference a template format without parameters.',
            ge=1.0,
        ),
    ] = None
    pixel_ratio: Annotated[
        StrictFloat | None,
        Field(
            description='Required intrinsic-pixel density for a parameterized visual format, expressed as intrinsic pixels per logical pixel. Requires `width` and `height`. Example: `{id: "display_image", width: 300, height: 250, pixel_ratio: 2}` identifies a 300×250 logical render supplied by a 600×500 image. Omit for the backward-compatible 1x variant.',
            gt=0.0,
        ),
    ] = 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

Class variables

var agent_url : str

var duration_ms : float | None

var height : int | None

var id : str

var model_config

var pixel_ratio : float | None

var width : int | None

class LegacyFormatReferenceStructuredObject (**data: Any)

Expand source code

class FormatReferenceStructuredObject(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    agent_url: Annotated[
        WireUrl,
        Field(
            description="URL of the agent that defines this format (e.g., 'https://creative.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats). Callers comparing two `format-id` values MUST canonicalize `agent_url` per the AdCP URL canonicalization rules before treating two formats as the same. See docs/reference/url-canonicalization."
        ),
    ]
    id: Annotated[
        str,
        Field(
            description="Format identifier within the agent's namespace (e.g., 'display_static', 'video_hosted', 'audio_standard'). When used alone, references a template format. When combined with dimension/duration fields, creates a parameterized format ID for a specific variant.",
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ]
    width: Annotated[
        SchemaInt | None,
        Field(
            description='Width in pixels for visual formats. When specified, height must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
            ge=1,
        ),
    ] = None
    height: Annotated[
        SchemaInt | None,
        Field(
            description='Height in pixels for visual formats. When specified, width must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
            ge=1,
        ),
    ] = None
    duration_ms: Annotated[
        StrictFloat | None,
        Field(
            description='Duration in milliseconds for time-based formats (video, audio). When specified, creates a parameterized format ID. Omit to reference a template format without parameters.',
            ge=1.0,
        ),
    ] = None
    pixel_ratio: Annotated[
        StrictFloat | None,
        Field(
            description='Required intrinsic-pixel density for a parameterized visual format, expressed as intrinsic pixels per logical pixel. Requires `width` and `height`. Example: `{id: "display_image", width: 300, height: 250, pixel_ratio: 2}` identifies a 300×250 logical render supplied by a 600×500 image. Omit for the backward-compatible 1x variant.',
            gt=0.0,
        ),
    ] = 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

Class variables

var agent_url : str

var duration_ms : float | None

var height : int | None

var id : str

var model_config

var pixel_ratio : float | None

var width : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class FrequencyCap (**data: Any)

Expand source code

class FrequencyCap(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    suppress: Annotated[
        duration.Duration | None,
        Field(
            description='Cooldown period between consecutive exposures to the same entity. Prevents back-to-back ad delivery (e.g. {"interval": 60, "unit": "minutes"} for a 1-hour cooldown). Preferred over suppress_minutes.'
        ),
    ] = None
    suppress_minutes: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='Deprecated — use suppress instead. Cooldown period in minutes between consecutive exposures to the same entity (e.g. 60 for a 1-hour cooldown).',
            ge=0.0,
        ),
    ] = None
    max_impressions: Annotated[
        SchemaInt | None,
        Field(
            description="Maximum number of impressions per entity per window. For duration windows, implementations typically use a rolling window. campaign applies across the owning field's full flight: the package flight for a targeting overlay, or the MediaBuy flight for a root cap.",
            ge=1,
        ),
    ] = None
    per: Annotated[
        reach_unit.ReachUnit | None,
        Field(
            description='Entity granularity for impression counting. Required when max_impressions is set.'
        ),
    ] = None
    window: Annotated[
        duration.Duration | None,
        Field(
            description='Time window for the max_impressions cap (e.g. {"interval": 7, "unit": "days"} or {"interval": 1, "unit": "campaign"} for the full flight). Required when max_impressions is set.'
        ),
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> FrequencyCap:
        # ``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 (('suppress',), ('suppress_minutes',), ('max_impressions',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'FrequencyCap requires at least one of these field groups: suppress | suppress_minutes | max_impressions'
        )

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

• MediaBuyFrequencyCap

Class variables

var max_impressions : int | None

var model_config

var per : ReachUnit | None

var suppress : Duration | None

var suppress_minutes : float | None

var window : Duration | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class FrequencyCapScope (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class FrequencyCapScope(RootModel[Literal['package']]):
    root: Annotated[
        Literal['package'],
        Field(description='Scope for frequency cap application', title='Frequency Cap Scope'),
    ] = 'package'

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

-----=

root

The root object of the model.

__pydantic_root_model__

Whether the model is a RootModel.

__pydantic_private__

Private fields in the model.

__pydantic_extra__

Extra fields in the model.

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.root_model.RootModel[Literal['package']]
• pydantic.root_model.RootModel
• pydantic.main.BaseModel
• typing.Generic

Class variables

var model_config

var root : Literal['package']

class GeoCountry (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class GeoCountry(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{2}$'}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

Subclasses

• GeoCountriesExcludeItem

class GeoMetro (**data: Any)

Expand source code

class GeoMetro(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    system: Annotated[
        metro_system.MetroAreaSystem,
        Field(description="Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2')"),
    ]
    values: Annotated[
        list[str],
        Field(
            description="Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs)",
            min_length=1,
        ),
    ]

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

Class variables

var model_config

var system : MetroAreaSystem

var values : list[str]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class GeoRegion (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class GeoRegion(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{2}-[A-Z0-9]{1,3}$'}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

Subclasses

• GeoRegionsExcludeItem

class GetAccountFinancialsRequest (**data: Any)

Expand source code

class GetAccountFinancialsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference,
        Field(description='Account to query financials for. Must be an operator-billed account.'),
    ]
    period: Annotated[
        date_range.DateRange | None,
        Field(
            description='Date range for the spend summary. Defaults to the current billing cycle if omitted.'
        ),
    ] = 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 account : AccountReference1 | AccountReference2

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var period : DateRange | 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 GetAccountFinancialsResponse1 (**data: Any)

Expand source code

class GetAccountFinancialsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    account: account_ref_1.AccountReference
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')]
    period: date_range_1.DateRange
    timezone: str
    spend: Spend | None = None
    credit: Credit | None = None
    balance: Balance | None = None
    payment_status: Literal['current', 'past_due', 'suspended'] | None = None
    payment_terms: payment_terms_1.PaymentTerms | None = None
    invoices: list[Invoice] | None = 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.

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 : AccountReference1 | AccountReference2

var balance : Balance | None

var context : ContextObject | None

var credit : Credit | None

var currency : str

var ext : ExtensionObject | None

var invoices : list[Invoice] | None

var model_config

var payment_status : Literal['current', 'past_due', 'suspended'] | None

var payment_terms : PaymentTerms | None

var period : DateRange

var spend : Spend | None

var timezone : str

class GetAccountFinancialsSuccessResponse (**data: Any)

Expand source code

class GetAccountFinancialsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    account: account_ref_1.AccountReference
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')]
    period: date_range_1.DateRange
    timezone: str
    spend: Spend | None = None
    credit: Credit | None = None
    balance: Balance | None = None
    payment_status: Literal['current', 'past_due', 'suspended'] | None = None
    payment_terms: payment_terms_1.PaymentTerms | None = None
    invoices: list[Invoice] | None = 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.

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 : AccountReference1 | AccountReference2

var balance : Balance | None

var context : ContextObject | None

var credit : Credit | None

var currency : str

var ext : ExtensionObject | None

var invoices : list[Invoice] | None

var model_config

var payment_status : Literal['current', 'past_due', 'suspended'] | None

var payment_terms : PaymentTerms | None

var period : DateRange

var spend : Spend | None

var timezone : str

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 GetAccountFinancialsErrorResponse (**data: Any)

Expand source code

class GetAccountFinancialsResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 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 GetBrandIdentityRequest (**data: Any)

Expand source code

class GetBrandIdentityRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    brand_id: Annotated[str, Field(description='Brand identifier from brand.json brands array')]
    fields: Annotated[
        list[Field1] | None,
        Field(
            description='Optional identity sections to include in the response. When omitted, all sections the caller is authorized to see are returned. Core fields (brand_id, house, names) are always returned and do not need to be requested.',
            min_length=1,
        ),
    ] = None
    use_case: Annotated[
        str | None,
        Field(
            description="Intended use case, so the agent can tailor the response. A 'voice_synthesis' use case returns voice configs; a 'likeness' use case returns high-res photos and appearance guidelines."
        ),
    ] = 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 brand_id : str

var context : ContextObject | None

var ext : ExtensionObject | None

var fields : list[Field1] | None

var model_config

var use_case : str | 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 GetBrandIdentitySuccessResponse (**data: Any)

Expand source code

class GetBrandIdentityResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    brand_id: str
    house: House
    names: list[dict[str, str]]
    description: str | None = None
    industries: Annotated[list[str], Field(min_length=1)] | None = None
    keller_type: Literal['master', 'sub_brand', 'endorsed', 'independent'] | None = None
    logos: list[Logo] | None = None
    colors: Colors | None = None
    fonts: Fonts | None = None
    visual_guidelines: dict[str, Any] | None = None
    tone: Tone | None = None
    tagline: str | Annotated[list[dict[str, Annotated[str, StringConstraints(min_length=1)]]], Field(min_length=1)] | None = None
    voice_synthesis: VoiceSynthesis | None = None
    assets: list[Asset] | None = None
    rights: Rights | None = None
    available_fields: list[Literal['description', 'industries', 'keller_type', 'logos', 'colors', 'fonts', 'visual_guidelines', 'tone', 'tagline', 'voice_synthesis', 'assets', 'rights']] | None = 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.

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 assets : list[Asset] | None

var available_fields : list[typing.Literal['description', 'industries', 'keller_type', 'logos', 'colors', 'fonts', 'visual_guidelines', 'tone', 'tagline', 'voice_synthesis', 'assets', 'rights']] | None

var brand_id : str

var colors : Colors | None

var context : ContextObject | None

var description : str | None

var ext : ExtensionObject | None

var fonts : Fonts | None

var house : House

var industries : list[str] | None

var keller_type : Literal['master', 'sub_brand', 'endorsed', 'independent'] | None

var logos : list[Logo] | None

var model_config

var names : list[dict[str, str]]

var rights : Rights | None

var tagline : str | list[dict[str, str]] | None

var tone : Tone | None

var visual_guidelines : dict[str, typing.Any] | None

var voice_synthesis : VoiceSynthesis | None

class GetBrandIdentityResponse1 (**data: Any)

Expand source code

class GetBrandIdentityResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    brand_id: str
    house: House
    names: list[dict[str, str]]
    description: str | None = None
    industries: Annotated[list[str], Field(min_length=1)] | None = None
    keller_type: Literal['master', 'sub_brand', 'endorsed', 'independent'] | None = None
    logos: list[Logo] | None = None
    colors: Colors | None = None
    fonts: Fonts | None = None
    visual_guidelines: dict[str, Any] | None = None
    tone: Tone | None = None
    tagline: str | Annotated[list[dict[str, Annotated[str, StringConstraints(min_length=1)]]], Field(min_length=1)] | None = None
    voice_synthesis: VoiceSynthesis | None = None
    assets: list[Asset] | None = None
    rights: Rights | None = None
    available_fields: list[Literal['description', 'industries', 'keller_type', 'logos', 'colors', 'fonts', 'visual_guidelines', 'tone', 'tagline', 'voice_synthesis', 'assets', 'rights']] | None = 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.

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 assets : list[Asset] | None

var available_fields : list[typing.Literal['description', 'industries', 'keller_type', 'logos', 'colors', 'fonts', 'visual_guidelines', 'tone', 'tagline', 'voice_synthesis', 'assets', 'rights']] | None

var brand_id : str

var colors : Colors | None

var context : ContextObject | None

var description : str | None

var ext : ExtensionObject | None

var fonts : Fonts | None

var house : House

var industries : list[str] | None

var keller_type : Literal['master', 'sub_brand', 'endorsed', 'independent'] | None

var logos : list[Logo] | None

var model_config

var names : list[dict[str, str]]

var rights : Rights | None

var tagline : str | list[dict[str, str]] | None

var tone : Tone | None

var visual_guidelines : dict[str, typing.Any] | None

var voice_synthesis : VoiceSynthesis | 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 GetBrandIdentityErrorResponse (**data: Any)

Expand source code

class GetBrandIdentityResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 GetCollectionListRequest (**data: Any)

Expand source code

class GetCollectionListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list_id: Annotated[str, Field(description='ID of the collection list to retrieve')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts and the list_id is not globally unique within that scope; optional otherwise.'
        ),
    ] = None
    resolve: Annotated[
        StrictBool | None,
        Field(
            description='Whether to apply filters and return resolved collections (default: true)'
        ),
    ] = True
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination parameters. Uses higher limits than standard pagination because collection lists can contain thousands of entries.'
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var list_id : str

var model_config

var pagination : Pagination | None

var resolve : bool | 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 GetCollectionListResponse (**data: Any)

Expand source code

class GetCollectionListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list: Annotated[
        collection_list.CollectionList,
        Field(description='The collection list metadata (always returned)'),
    ]
    collections: Annotated[
        list[Collection] | None,
        Field(
            description='Resolved collections that passed filters (if resolve=true). Each entry contains identification and key metadata for seller matching.'
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    resolved_at: Annotated[
        AwareDatetime | None, Field(description='When the list was resolved')
    ] = None
    cache_valid_until: Annotated[
        AwareDatetime | None,
        Field(
            description='Cache expiration timestamp. Re-fetch the list after this time to get updated collections.'
        ),
    ] = None
    coverage_gaps: Annotated[
        dict[str, list[CoverageGap]] | None,
        Field(
            description="Collections included in the list despite missing metadata for a filtered dimension. Maps dimension name (e.g., 'genre', 'content_rating') to arrays of distribution identifiers for collections not covered. Only present when filters are applied and some collections lack the filtered metadata."
        ),
    ] = 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.

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 cache_valid_until : pydantic.types.AwareDatetime | None

var collections : list[Collection] | None

var context : ContextObject | None

var coverage_gaps : dict[str, list[CoverageGap]] | None

var ext : ExtensionObject | None

var list : CollectionList

var model_config

var pagination : PaginationResponse | None

var resolved_at : pydantic.types.AwareDatetime | 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 GetContentStandardsRequest (**data: Any)

Expand source code

class GetContentStandardsRequest(AdcpRequest, AdcpVersionEnvelope):
    standards_id: Annotated[
        str, Field(description='Identifier for the standards configuration to retrieve')
    ]
    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 standards_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 GetContentStandardsResponse1 (**data: Any)

Expand source code

class GetContentStandardsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

class GetContentStandardsSuccessResponse (**data: Any)

Expand source code

class GetContentStandardsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

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 GetContentStandardsErrorResponse (**data: Any)

Expand source code

class GetContentStandardsResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: list[error_1.Error]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 GetCreativeDeliveryRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> GetCreativeDeliveryRequest:
        # ``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 (('media_buy_ids',), ('creative_ids',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'GetCreativeDeliveryRequest requires at least one of these field groups: media_buy_ids | creative_ids'
        )

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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var creative_ids : list[str] | None

var end_date : str | None

var ext : ExtensionObject | None

var max_variants : int | None

var media_buy_ids : list[str] | None

var model_config

var pagination : PaginationRequest | None

var start_date : str | None

class GetCreativeDeliveryByBuyerRefRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> GetCreativeDeliveryRequest:
        # ``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 (('media_buy_ids',), ('creative_ids',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'GetCreativeDeliveryRequest requires at least one of these field groups: media_buy_ids | creative_ids'
        )

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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var creative_ids : list[str] | None

var end_date : str | None

var ext : ExtensionObject | None

var max_variants : int | None

var media_buy_ids : list[str] | None

var model_config

var pagination : PaginationRequest | None

var start_date : str | None

class GetCreativeDeliveryByCreativeRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> GetCreativeDeliveryRequest:
        # ``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 (('media_buy_ids',), ('creative_ids',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'GetCreativeDeliveryRequest requires at least one of these field groups: media_buy_ids | creative_ids'
        )

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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var creative_ids : list[str] | None

var end_date : str | None

var ext : ExtensionObject | None

var max_variants : int | None

var media_buy_ids : list[str] | None

var model_config

var pagination : PaginationRequest | None

var start_date : str | None

class GetCreativeDeliveryByMediaBuyRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> GetCreativeDeliveryRequest:
        # ``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 (('media_buy_ids',), ('creative_ids',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'GetCreativeDeliveryRequest requires at least one of these field groups: media_buy_ids | creative_ids'
        )

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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var creative_ids : list[str] | None

var end_date : str | None

var ext : ExtensionObject | None

var max_variants : int | None

var media_buy_ids : list[str] | None

var model_config

var pagination : PaginationRequest | None

var start_date : str | 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 GetCreativeDeliveryResponse (**data: Any)

Expand source code

class GetCreativeDeliveryResponse(_LegacyGetCreativeDeliveryResponse, CanonicalBoundaryModel):
    """Canonical creative delivery response; rows are the read-back delivery creatives."""

    creatives: Sequence[DeliveryCreative]

Canonical creative delivery response; rows are the read-back delivery creatives.

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

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

Class variables

var creatives : Sequence[DeliveryCreative]

var model_config

class LegacyGetCreativeDeliveryResponse (**data: Any)

Expand source code

class GetCreativeDeliveryResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account_id: Annotated[
        str | None,
        Field(
            description='Account identifier. Present when the response spans or is scoped to a specific account.'
        ),
    ] = None
    media_buy_id: Annotated[
        str | None,
        Field(
            description="Publisher's media buy identifier. Present when the request was scoped to a single media buy."
        ),
    ] = None
    currency: Annotated[
        str,
        Field(
            description="ISO 4217 currency code for monetary values in this response (e.g., 'USD', 'EUR')",
            pattern='^[A-Z]{3}$',
        ),
    ]
    reporting_period: Annotated[ReportingPeriod, Field(description='Date range for the report.')]
    creatives: Annotated[
        Sequence[Creative], Field(description='Creative delivery data with variant breakdowns')
    ]
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination information. Present when the request included pagination parameters. **Note:** `get_creative_delivery` uses page-based pagination (`limit`/`offset`) for historical reasons, distinct from the cursor-based [`PaginationResponse`](/schemas/v3/core/pagination-response.json) used by `list_*` tools. Field naming aligned with `PaginationResponse.total_count` in 3.1; the legacy `total` field is retained as a deprecated alias until 4.0. Sellers MUST populate both fields identically; buyers SHOULD prefer `total_count` (the canonical name) and ignore `total` if both are present.'
        ),
    ] = 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

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

Subclasses

• GetCreativeDeliveryResponse

Class variables

var account_id : str | None

var context : ContextObject | None

var creatives : Sequence[Creative]

var currency : str

var errors : list[Error] | None

var ext : ExtensionObject | None

var media_buy_id : str | None

var model_config

var pagination : Pagination | None

var reporting_period : ReportingPeriod

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 GetCreativeFeaturesRequest (**data: Any)

Expand source code

class GetCreativeFeaturesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str | None,
        Field(
            description='Optional in AdCP 3.x for wire compatibility; clients SHOULD send a unique key for every logical evaluation. When supplied to a provider that advertises adcp.idempotency.supported: true, exact retries with the same canonical payload MUST return the cached initial response with replayed: true and MUST NOT dispatch a second provider evaluation or record a second consumption or cost event. Reusing the key with a different creative_manifest, account, or feature_ids payload returns IDEMPOTENCY_CONFLICT. The provider MUST retain the replay record for at least 24 hours. Keys MUST be unique per (provider, request) pair to prevent cross-provider correlation. This field becomes required in AdCP 4.0; use a fresh UUID v4 for each logical evaluation.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest,
        Field(
            description='The canonical creative manifest to evaluate. In 3.2 it contains `format_kind`, optional `format_option_ref`, and typed assets. The deprecated named `format_id` branch remains available only for older 3.x peers.'
        ),
    ]
    feature_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional filter to specific features. If omitted, returns all available features.',
            min_length=1,
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for billing this evaluation. Required when the governance agent charges per evaluation.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications. A submitted acknowledgement remains pollable through get_task_status whether or not this field is present. If the provider accepts this field and returns status: submitted, it MUST deliver at least the terminal completion or failure notification to the configured URL. If it cannot honor the webhook channel, it MUST reject the request instead of silently downgrading delivery.'
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var creative_manifest : CreativeManifest

var ext : ExtensionObject | None

var feature_ids : list[str] | None

var idempotency_key : str | None

var model_config

var push_notification_config : PushNotificationConfig | 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 GetCreativeFeaturesResponse1 (**data: Any)

Expand source code

class GetCreativeFeaturesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')

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 model_config

class GetCreativeFeaturesSuccessResponse (**data: Any)

Expand source code

class GetCreativeFeaturesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')

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 model_config

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 GetCreativeFeaturesErrorResponse (**data: Any)

Expand source code

class GetCreativeFeaturesResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    evaluation_id: Annotated[str, StringConstraints(min_length=1)] | None = None
    errors: list[error_1.Error]
    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.

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 context : ContextObject | None

var errors : list[Error]

var evaluation_id : str | None

var ext : ExtensionObject | None

var model_config

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 GetMediaBuyArtifactsRequest (**data: Any)

Expand source code

class GetMediaBuyArtifactsRequest(AdcpRequest, AdcpVersionEnvelope):
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Filter artifacts to a specific account. When omitted, returns artifacts across all accessible accounts.'
        ),
    ] = None
    media_buy_id: Annotated[str, Field(description='Media buy to get artifacts from')]
    package_ids: Annotated[
        list[str] | None,
        Field(description='Filter to specific packages within the media buy', min_length=1),
    ] = None
    failures_only: Annotated[
        StrictBool | None,
        Field(
            description="When true, only return artifacts where the seller's local model returned local_verdict: 'fail'. Useful for auditing false positives. Not useful when the seller does not run a local evaluation model (all verdicts are 'unevaluated')."
        ),
    ] = False
    time_range: Annotated[TimeRange | None, Field(description='Filter to specific time period')] = (
        None
    )
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination parameters. Uses higher limits than standard pagination because artifact result sets can be very large.'
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var failures_only : bool | None

var media_buy_id : str

var model_config

var package_ids : list[str] | None

var pagination : Pagination | None

var time_range : TimeRange | 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 GetMediaBuyArtifactsResponse1 (**data: Any)

Expand source code

class GetMediaBuyArtifactsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    media_buy_id: str
    artifacts: list[Artifact]
    collection_info: CollectionInfo | None = None
    pagination: pagination_response_1.PaginationResponse | None = 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.

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 artifacts : list[Artifact]

var collection_info : CollectionInfo | None

var context : ContextObject | None

var ext : ExtensionObject | None

var media_buy_id : str

var model_config

var pagination : PaginationResponse | None

class GetMediaBuyArtifactsSuccessResponse (**data: Any)

Expand source code

class GetMediaBuyArtifactsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    media_buy_id: str
    artifacts: list[Artifact]
    collection_info: CollectionInfo | None = None
    pagination: pagination_response_1.PaginationResponse | None = 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.

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 artifacts : list[Artifact]

var collection_info : CollectionInfo | None

var context : ContextObject | None

var ext : ExtensionObject | None

var media_buy_id : str

var model_config

var pagination : PaginationResponse | 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 GetMediaBuyArtifactsErrorResponse (**data: Any)

Expand source code

class GetMediaBuyArtifactsResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: list[error_1.Error]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 GetMediaBuyDeliveryRequest (**data: Any)

Expand source code

class GetMediaBuyDeliveryRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Filter delivery data to a specific account. When omitted, returns data across all accessible accounts.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(description='Array of media buy IDs to get delivery data for', min_length=1),
    ] = None
    reporting_revision_id: Annotated[
        str | None,
        Field(
            description='Exact immutable reporting revision to retrieve. This additive Reliable Reporting selector returns content bound to that revision, including its immutable row count, control totals, and content SHA-256. It is mutually exclusive with media-buy, date, metric, and breakdown selectors.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Cursor pagination. With reporting_revision_id, pages immutable authoritative rows while all revision metadata repeats on every page.'
        ),
    ] = None
    status_filter: Annotated[
        media_buy_status.MediaBuyStatus | StatusFilter | None,
        Field(description='Filter by status. Can be a single status or array of statuses'),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Inclusive start date for the reporting period (YYYY-MM-DD), as a calendar date in the reporting timezone: the reporting_capabilities.timezone of the products behind the in-scope packages. It is a UTC day only when that timezone is UTC. When omitted along with end_date, returns campaign lifetime data. Only accepted when the product's reporting_capabilities.date_range_support is 'date_range'. A date-bounded request whose in-scope packages span more than one reporting timezone MUST be rejected with VALIDATION_ERROR. The buyer narrows media_buy_ids to buys that share one reporting timezone, or omits both dates when a single buy's packages span reporting timezones.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="Exclusive end date for the reporting period (YYYY-MM-DD), as a calendar date in the same reporting timezone as start_date. Must be later than start_date. When omitted along with start_date, returns campaign lifetime data. Only accepted when the product's reporting_capabilities.date_range_support is 'date_range'.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    include_package_daily_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='When true, include daily_breakdown arrays within each package in by_package. Useful for per-package pacing analysis and line-item monitoring. Omit or set false to reduce response size — package daily data can be large for multi-package buys over long flights.'
        ),
    ] = False
    requested_metrics: Annotated[
        list[available_metric.AvailableMetric] | None,
        Field(
            description="Optional list of metrics to include in the response. When omitted, all available metrics are included (unchanged behavior). Applies to every metrics-bearing object in the response: totals, by_package, daily and window slices, and breakdown rows. impressions and spend are always included regardless of this list, except that a legacy or externally created mixed-currency buy MUST omit monetary and money-derived values from media-buy and window totals, MUST omit daily_breakdown, and MUST report monetary values only on currency-qualified package rows (including window package rows). Requesting a leaf metric identity returns its canonical nested carrier — e.g. requesting viewable_rate returns the viewability object, requesting quartile_75 returns quartile_data — never a flat duplicate. Metrics requested but not available for this buy are omitted from the response without error; contract accountability is unchanged — missing_metrics still reconciles against committed_metrics, but sellers MUST NOT list a metric in missing_metrics when its absence is solely due to this narrowing. Must be a subset of the product's reporting_capabilities.available_metrics; values outside the declared set are ignored. Subset evaluation follows the container-subsumption rule in enums/available-metric.json. Sort is evaluated before narrowing: excluding a metric from this list never triggers the sort_by fallback, and breakdown rows may be ordered by a metric absent from the narrowed payload — the applied-sort echo still names it. Same narrowing semantics as reporting_webhook.requested_metrics, with one shape difference: this field requires at least one entry when present (omit it entirely for full payloads), while the webhook field permits an empty array with the same meaning as omission.",
            min_length=1,
        ),
    ] = None
    time_granularity: Annotated[
        reporting_frequency.ReportingFrequency | None,
        Field(
            description="Per-window slice granularity for the pull, using the same vocabulary as reporting_webhook.reporting_frequency. When set, the seller returns per-window delivery slices over the date range — useful for reconstructing data a buyer's webhook receiver missed, since the slice payload is shape-aligned with what reporting_webhook would have delivered for the same window. Capability-scoped: the value MUST be one of the seller's declared reporting_capabilities.windowed_pull_granularities; otherwise the seller MUST return UNSUPPORTED_GRANULARITY. When set to daily, weekly, monthly, or quarterly and the in-scope packages span more than one reporting timezone, the seller MUST return VALIDATION_ERROR. When omitted, behavior is unchanged (cumulative aggregates plus optional daily breakdowns per existing fields)."
        ),
    ] = None
    include_window_breakdown: Annotated[
        StrictBool | None,
        Field(
            description="When true, the response includes media_buy_deliveries[].windows[] — an array of per-window delivery slices over the date range at the requested time_granularity. Ignored when time_granularity is omitted. Each window's payload mirrors what reporting_webhook would have delivered for the same window, enabling lossless GET-path recovery for buyers who missed webhook fires. Omit or set false to reduce response size when only cumulative aggregates are needed."
        ),
    ] = False
    attribution_window: Annotated[
        AttributionWindow | None,
        Field(
            description='Attribution window to apply for conversion metrics. When provided, the seller returns conversion data using the requested lookback windows instead of their platform default. The seller echoes the applied window in the response. Sellers that do not support configurable windows ignore this field and return their default. Check get_adcp_capabilities conversion_tracking.attribution_windows for available options.'
        ),
    ] = None
    reporting_dimensions: Annotated[
        ReportingDimensions | None,
        Field(
            description='Request dimensional breakdowns in delivery reporting. Each key enables a specific breakdown dimension within by_package — include as an empty object (e.g., "device_type": {}) to activate with defaults. Omit entirely for no breakdowns (backward compatible). Unsupported dimensions are silently omitted from the response. For every requested dimension that the product declares supported, the seller MUST return the corresponding array (possibly empty) and its truncated flag. Metric-sorted dimensions also return their applied-sort echoes; demographic and property-grain arrays also return their suppressed flag. Spot uses aired_at ordering and has no sort echoes. Note: keyword, catalog_item, and creative breakdowns are returned automatically when the seller supports them; including their keys here is optional and upgrades them to this negotiated contract without changing the automatic default.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _validate_delivery_selector_mode(self) -> GetMediaBuyDeliveryRequest:
        if self.reporting_revision_id is not None:
            if self.model_fields_set.intersection(('media_buy_ids', 'start_date', 'end_date', 'status_filter', 'requested_metrics', 'reporting_dimensions', 'attribution_window', 'include_package_daily_breakdown', 'time_granularity', 'include_window_breakdown')):
                raise ValueError('exact revision requests forbid aggregate selectors, even false or null')
        elif self.pagination is not None:
            raise ValueError('pagination requires reporting_revision_id')
        return self

    @model_serializer(mode='wrap')
    def _serialize_delivery_selector_mode(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
        value: dict[str, Any] = handler(self)
        if self.reporting_revision_id is not None:
            for name in ('media_buy_ids', 'start_date', 'end_date', 'status_filter', 'requested_metrics', 'reporting_dimensions', 'attribution_window', 'include_package_daily_breakdown', 'time_granularity', 'include_window_breakdown'):
                if name not in self.model_fields_set:
                    value.pop(name, None)
        return value

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 account : AccountReference1 | AccountReference2 | None

var attribution_window : AttributionWindow | None

var context : ContextObject | None

var end_date : str | None

var ext : ExtensionObject | None

var include_package_daily_breakdown : bool | None

var include_window_breakdown : bool | None

var media_buy_ids : list[str] | None

var model_config

var pagination : PaginationRequest | None

var reporting_dimensions : ReportingDimensions | None

var reporting_revision_id : str | None

var requested_metrics : list[AvailableMetric] | None

var start_date : str | None

var status_filter : MediaBuyStatus | StatusFilter | None

var time_granularity : ReportingFrequency | 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 GetMediaBuyDeliveryResponse (**data: Any)

Expand source code

class GetMediaBuyDeliveryResponse(_LegacyGetMediaBuyDeliveryResponse, CanonicalBoundaryModel):
    """Canonical media-buy delivery response."""

Canonical media-buy delivery response.

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

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

Class variables

var model_config

class LegacyGetMediaBuyDeliveryResponse (**data: Any)

Expand source code

class GetMediaBuyDeliveryResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    notification_type: Annotated[
        NotificationType | None,
        Field(
            description='Type of webhook notification (only present in webhook deliveries): scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = resending period with corrected data (same window), window_update = resending period with a wider measurement window (e.g., C3 superseding live, C7 superseding C3)'
        ),
    ] = None
    partial_data: Annotated[
        StrictBool | None,
        Field(
            description='Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)'
        ),
    ] = None
    unavailable_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of media buys with reporting_delayed or failed status (only present in webhook deliveries when partial_data is true)',
            ge=0,
        ),
    ] = None
    sequence_number: Annotated[
        SchemaInt | None,
        Field(
            description='Sequential notification number (only present in webhook deliveries, starts at 1)',
            ge=1,
        ),
    ] = None
    next_expected_at: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp for next expected notification (only present in webhook deliveries when notification_type is not 'final')"
        ),
    ] = None
    reporting_period: Annotated[
        ReportingPeriod,
        Field(
            description="Half-open period for the report: start is inclusive and end is exclusive. Both are instants. For a date-bounded request they are the instants at which start_date and end_date begin in the reporting timezone (the in-scope products' reporting_capabilities.timezone, echoed in timezone). They fall on UTC midnight only when that timezone is UTC. An exact reporting_revision_id read returns the revision's period instead, whose source_timezone names its calendar."
        ),
    ]
    reporting_revision_binding: Annotated[
        ReportingRevisionBinding | None,
        Field(
            description='Present only for a reporting_revision_id selector. Binds the complete ordered reporting_rows sequence obtained by concatenating every cursor page to one immutable Reliable Reporting revision; consumers verify content_sha256 over RFC 8785 JCS of {reporting_revision_id,row_count,control_totals,reporting_rows} before using it as revision evidence.'
        ),
    ] = None
    reporting_revision: Annotated[
        reporting_revision_1.ReportingRevision | None,
        Field(
            description='Full immutable revision metadata, identical to the get_reporting_status revision record.'
        ),
    ] = None
    reporting_rows: Annotated[
        list[dict[str, Any]] | None,
        Field(
            description="One page of authoritative logical rows for an exact reporting_revision_id read. Validate every row against the revision's digest-pinned schema; concatenate pages in cursor order before verifying the binding digest."
        ),
    ] = None
    pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(
            description='Exact revision pages are frozen for the cursor walk. total_count is mandatory for reporting_revision_id and equals reporting_revision_1.row_count and reporting_revision_binding.row_count; it counts the complete ordered row sequence, not this page.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2 and removed in AdCP 4.0. Optional legacy response-wide ISO 4217 currency code. It may be used only when every monetary value in the response has that denomination. A delivery response can contain media buys with different currencies, so buyers MUST NOT interpret this field as an aggregation currency or evidence of currency conversion. Prefer media_buy_deliveries[].currency when present and package-level currency otherwise.',
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    attribution_window: Annotated[
        attribution_window_1.AttributionWindow | None,
        Field(
            description='Attribution methodology and lookback windows used for conversion metrics in this response. All media buys from a single seller share the same attribution methodology. Enables cross-platform comparison (e.g., Amazon 14-day click vs. Criteo 30-day click).'
        ),
    ] = None
    aggregated_totals: Annotated[
        AggregatedTotals | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2 and removed in AdCP 4.0. Legacy combined metrics across all returned media buys. When this field is present, the deprecated response-wide currency is required and denominates its spend. Cross-buy totals are unsafe when currencies, metric qualifiers, measurement windows, finality, or deduplication semantics differ. Sellers SHOULD omit this field; buyers SHOULD aggregate media_buy_deliveries[] only when the relevant row semantics are compatible.',
        ),
    ] = None
    media_buy_deliveries: Annotated[
        Sequence[MediaBuyDelivery],
        Field(
            description='Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.'
        ),
    ]
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors and warnings (e.g., missing delivery data, reporting platform issues)'
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = 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.

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

Subclasses

• GetMediaBuyDeliveryResponse

Class variables

var attribution_window : AttributionWindow | None

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var media_buy_deliveries : Sequence[MediaBuyDelivery]

var model_config

var next_expected_at : pydantic.types.AwareDatetime | None

var notification_type : NotificationType | None

var pagination : PaginationResponse | None

var partial_data : bool | None

var reporting_period : ReportingPeriod

var reporting_revision : ReportingRevision | None

var reporting_revision_binding : ReportingRevisionBinding | None

var reporting_rows : list[dict[str, typing.Any]] | None

var sandbox : bool | None

var sequence_number : int | None

var status : TaskStatus | None

var unavailable_count : int | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var aggregated_totals : AggregatedTotals | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var currency : str | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class Results (**data: Any)

Expand source code

class GetMediaBuyDeliveryResponse(_LegacyGetMediaBuyDeliveryResponse, CanonicalBoundaryModel):
    """Canonical media-buy delivery response."""

Canonical media-buy delivery response.

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

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

Class variables

var model_config

Inherited members

• GetMediaBuyDeliveryResponse:
  • adcp_major_version
  • aggregated_totals
  • currency
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class GetMediaBuysRequest (**data: Any)

Expand source code

class GetMediaBuysRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account to retrieve media buys for. When omitted, returns data across all accessible accounts.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Array of media buy IDs to retrieve. When omitted, returns a paginated set of accessible media buys matching status_filter.',
            min_length=1,
        ),
    ] = None
    status_filter: Annotated[
        media_buy_status.MediaBuyStatus | StatusFilter | None,
        Field(
            description='Filter by status. Can be a single status or array of statuses. Defaults to ["active"] when media_buy_ids is omitted. When media_buy_ids is provided, no implicit status filter is applied.'
        ),
    ] = None
    indicator_types: Annotated[
        list[indicator_type.IndicatorType] | None,
        Field(
            description='Return media buys with at least one matching current indicator on the media buy, a package, or a package–creative assignment. Values within this field use OR logic; this field composes with status_filter using AND logic. Buyers MUST NOT send this filter unless the seller advertises every requested type in get_adcp_capabilities.media_buy.supported_indicator_types. A seller MAY reject a request that violates this precondition with UNSUPPORTED_FEATURE rather than silently returning an unfiltered superset.',
            min_length=1,
        ),
    ] = None
    include_snapshot: Annotated[
        StrictBool | None,
        Field(
            description='When true, include a near-real-time delivery snapshot for each package. Snapshots reflect the latest available entity-level stats from the platform (e.g., updated every ~15 minutes on GAM, ~1 hour on batch-only platforms). The staleness_seconds field on each snapshot indicates data freshness. If a snapshot cannot be returned, package.snapshot_unavailable_reason explains why. Defaults to false.'
        ),
    ] = False
    include_history: Annotated[
        SchemaInt | None,
        Field(
            description='When present, include the last N revision history entries for each media buy (returns min(N, available entries)). Each entry contains revision number, timestamp, actor, and a summary of what changed. Omit or set to 0 to exclude history (default). Recommended: 5-10 for monitoring, 50+ for audit.',
            ge=0,
            le=1000,
        ),
    ] = 0
    include_webhook_activity: Annotated[
        StrictBool | None,
        Field(
            description="When true, each returned media buy includes a `webhook_activity` array describing recent delivery-report webhook fires for the calling principal. Used by buyer agents to verify whether a publisher actually fired against the buyer's registered endpoint and what the endpoint returned — closes the operator-ticket loop for webhook debugging. Scoped to the calling principal: a buyer sees only fires targeting its own endpoint, even when multiple principals share visibility into the same media buy. Defaults to false. See `webhook_activity_limit` for the per-buy cap."
        ),
    ] = False
    webhook_activity_limit: Annotated[
        SchemaInt | None,
        Field(
            description="Maximum number of webhook delivery records to return per media buy, ordered most-recent first. Ignored when `include_webhook_activity` is false. Sellers that surface webhook activity MUST retain records for at least 30 days from each record's `completed_at` (see `webhook_activity` description in the response schema for the `pending`-status carve-out); sellers unable to honor that floor MUST omit the field entirely rather than truncate. When a buy has more historical fires than the limit, only the most recent are returned — there is no cursor for older fires; this surface is a debug aid, not a full audit log.",
            ge=1,
            le=200,
        ),
    ] = 50
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Cursor-based pagination controls. Strongly recommended when querying broad scopes (for example, all active media buys in an account).'
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var include_history : int | None

var include_snapshot : bool | None

var include_webhook_activity : bool | None

var indicator_types : list[IndicatorType] | None

var media_buy_ids : list[str] | None

var model_config

var pagination : PaginationRequest | None

var status_filter : MediaBuyStatus | StatusFilter | None

var webhook_activity_limit : int | 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 GetMediaBuysResponse (**data: Any)

Expand source code

class GetMediaBuysResponse(_LegacyGetMediaBuysResponse, CanonicalBoundaryModel):
    """Canonical media-buy listing; rows are canonical media buys."""

    media_buys: Sequence[MediaBuy]

Canonical media-buy listing; rows are canonical media buys.

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

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

Class variables

var media_buys : Sequence[MediaBuy]

var model_config

class LegacyGetMediaBuysResponse (**data: Any)

Expand source code

class GetMediaBuysResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buys: Annotated[
        Sequence[MediaBuy],
        Field(
            description='Array of media buys with status, creative approval state, and optional delivery snapshots'
        ),
    ]
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors. A read may return media_buys plus nonfatal resource-state errors. If a pinned place target becomes unexecutable, sellers MUST include PLACE_TARGET_UNAVAILABLE with recovery=correctable, field pointing to the exact media_buys[N].packages[M].targeting_overlay.geo_places[_exclude][A].values[V] response path, and details containing media_buy_id, package_id, system, system_version, country, place_type, and value. The persisted target remains echoed until an intentional update replaces it.'
        ),
    ] = None
    pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(description='Pagination metadata for the media_buys array.'),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = 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.

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

Subclasses

• GetMediaBuysResponse

Class variables

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var media_buys : Sequence[MediaBuy]

var model_config

var pagination : PaginationResponse | None

var sandbox : bool | 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 GetPlanAuditLogsRequest (**data: Any)

Expand source code

class GetPlanAuditLogsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    plan_ids: Annotated[
        list[str] | None,
        Field(
            description='Plan IDs to retrieve. For a single plan, pass a one-element array. Plans uniquely scope account and operator; do not include a separate `account` field — the governance agent resolves account from each plan. Including `account` is rejected by `additionalProperties: false`.',
            min_length=1,
        ),
    ] = None
    portfolio_plan_ids: Annotated[
        list[str] | None,
        Field(
            description='Portfolio plan IDs. The governance agent expands each to its member_plan_ids and returns combined audit data.',
            min_length=1,
        ),
    ] = None
    governance_contexts: Annotated[
        list[str] | None,
        Field(
            description='Filter audit entries by governance context. Returns only checks and outcomes that share these governance contexts, enabling lifecycle tracing across purchase types.',
            min_length=1,
        ),
    ] = None
    purchase_types: Annotated[
        list[purchase_type.PurchaseType] | None,
        Field(
            description="Filter audit entries by purchase type. Returns only checks and outcomes matching these purchase types (e.g., ['rights_license'] to see all rights activity).",
            min_length=1,
        ),
    ] = None
    include_entries: Annotated[
        StrictBool | None, Field(description='Include the full audit trail. Default: false.')
    ] = False
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> GetPlanAuditLogsRequest:
        # ``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 (('plan_ids',), ('portfolio_plan_ids',), ('governance_contexts',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'GetPlanAuditLogsRequest requires at least one of these field groups: plan_ids | portfolio_plan_ids | governance_contexts'
        )

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 governance_contexts : list[str] | None

var include_entries : bool | None

var model_config

var plan_ids : list[str] | None

var portfolio_plan_ids : list[str] | None

var purchase_types : list[PurchaseType] | 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 GetPlanAuditLogsResponse (**data: Any)

Expand source code

class GetPlanAuditLogsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    plans: Annotated[list[Plan], Field(description='Audit data for each requested plan.')]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var plans : list[Plan]

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.

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

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.

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 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 GetProductsInputRequiredResponse (**data: Any)

Expand source code

class GetProductsInputRequired(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    reason: Annotated[
        Reason | None, Field(description='Reason code indicating why input is needed')
    ] = None
    partial_results: Annotated[
        list[product.Product] | None,
        Field(description='Partial product results that may help inform the clarification'),
    ] = None
    suggestions: Annotated[
        list[str] | None, Field(description='Suggested values or options for the required input')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var partial_results : list[Product] | None

var reason : Reason | None

var suggestions : list[str] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class GetProductsRequest (**data: Any)

Expand source code

class GetProductsRequest(_LegacyGetProductsRequest, CanonicalBoundaryModel):
    """Canonical discovery request with legacy response-field selection rejected."""

    filters: ProductFilters | None = None

    @field_validator("fields")
    @classmethod
    def _reject_legacy_fields(cls, value: Any) -> Any:
        if value and any(
            is_legacy_creative_identity_key(getattr(item, "value", item)) for item in value
        ):
            raise ValueError(
                "format_id and format_ids are unavailable on the canonical get_products API"
            )
        return value

Canonical discovery request with legacy response-field selection rejected.

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

• GetProductsRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var filters : ProductFilters | None

var model_config

class LegacyGetProductsRequest (**data: Any)

Expand source code

class GetProductsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str | None,
        Field(
            description='Optional client-generated key on the AdCP 3.x compatibility facade. The field remains optional on every arm for wire compatibility. A seller MAY ignore a supplied key on a guaranteed side-effect-free synchronous read. Buyers SHOULD supply a key whenever the request may allocate a task, finalize a proposal, or otherwise change observable state. When a key is supplied on such a request and the seller declares adcp.idempotency.supported: true, the seller MUST apply the AdCP replay contract before that effect. If the key is omitted or the seller declares adcp.idempotency.supported: false, the buyer has no portable at-most-once retry guarantee after an ambiguous result. New callers SHOULD use the compact 3.2 tasks; each stateful split task has its own idempotency identity, so callers MUST retry with the same tool name. Keys MUST be unique per seller and logical request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    buying_mode: Annotated[
        BuyingMode,
        Field(
            description="Declares buyer intent for this request. 'brief': publisher curates product recommendations from the provided brief. 'wholesale': buyer requests raw product inventory to apply their own audiences — brief must not be provided, and proposals are omitted. 'refine': iterate on products and proposals from a previous get_products response using the refine array of change requests. v3 clients MUST include buying_mode. Sellers receiving requests from pre-v3 clients without buying_mode SHOULD default to 'brief'. Timing semantics: 'wholesale' is a wholesale product feed read — sellers SHOULD return a synchronous response and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field (with optional estimated_wait), not via a task-handoff envelope. 'brief' and 'refine' MAY complete synchronously, or MAY return a Submitted envelope (see get-products-async-response-submitted.json) when curation requires upstream-system queries or HITL review the seller cannot complete inside time_budget. Buyers needing predictable fast wholesale product feed access MUST use 'wholesale'; buyers open to slower curation use 'brief' or 'refine'."
        ),
    ]
    brief: Annotated[
        str | None,
        Field(
            description="Natural language description of campaign requirements. Required when buying_mode is 'brief'. Must not be provided when buying_mode is 'wholesale' or 'refine'. Buyers SHOULD use structured fields for every requirement that can be expressed structurally, and reserve brief prose for goals, context, preferences, and requirements without a structured representation. Sellers MUST apply explicit hard requirements stated in the brief even when the buyer did not duplicate them in a structured field. When a seller translates hard prose into structured targeting that materially affects product eligibility, pricing, or forecasting, it MUST confirm that interpretation once in GetProductsResponse.targeting_resolution.brief_targeting; otherwise confirmation remains a best practice. If hard prose contradicts a structured field, sellers MUST reject the request with INVALID_REQUEST rather than choose one interpretation or return an unexplained empty result."
        ),
    ] = None
    refine: Annotated[
        list[Refine] | None,
        Field(
            description="Array of change requests for iterating on products and proposals from a previous get_products response. Each entry declares a scope (request, product, or proposal) and what the buyer is asking for. Only valid when buying_mode is 'refine'. The seller responds to each entry via refinement_applied in the response, matched by position.\n\nFinalize-exclusivity rule: if any entry has `action: 'finalize'`, ALL entries in the array MUST be proposal-scoped with `action: 'finalize'` — mixing finalize entries with `include`/`omit` entries or with request- / product-scoped entries MUST be rejected by the seller with `INVALID_REQUEST`. Finalize is a commit, not a refinement; the buyer expressing intent to commit means refinements have already converged. Buyers needing to refine AND commit in close succession sequence the calls: first a refine call (no finalize), then a finalize call against the resulting `proposal_id`(s).\n\nMulti-finalize semantics: multiple finalize entries against different `proposal_id` values in a single call are allowed and MUST be **atomic at the observation point** — sellers MUST NOT return a success response unless every named proposal has both completed and been persisted as committed. Pre-commit validation runs before any side-effects (inventory pull, terms lock, governance attestation); if any proposal fails validation, the seller MUST reject the entire call without committing any of the named proposals. There is no rollback operation in the spec — an `unfinalize` would itself be a new mutation surface; the atomicity guarantee runs entirely on the seller's pre-commit validation gate, not on post-commit reversal. Sellers that cannot guarantee atomic pre-commit validation MUST reject multi-finalize arrays with `MULTI_FINALIZE_UNSUPPORTED` (preferred — distinguishes seller-side capability gap from a malformed request) or `INVALID_REQUEST` (acceptable fallback for sellers on a pre-3.1 error catalog). If a mid-commit failure occurs *after* validation passed but before all proposals persist (e.g., a downstream ad server fails between commits one and two), the seller MUST return `INTERNAL_ERROR` with `refinement_applied[]` carrying per-position outcomes — the spec does NOT define a recovery path for this case, and buyers SHOULD treat the resulting state as undefined and re-read via `get_media_buys` / equivalent before retrying. Buyers MUST NOT assume multi-finalize support without a successful first attempt — there is no capability flag for this; the failure response is the discovery surface. Buyers whose intent specifically requires atomic commit (e.g., budget-shared proposals where one finalizing without the other is incoherent) MUST be prepared to abandon the intent if the seller returns `MULTI_FINALIZE_UNSUPPORTED` — there is no recovery for that loss of buyer intent beyond sequencing single-finalize calls and accepting the looser commit guarantee.",
            min_length=1,
        ),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand reference for product discovery context. Resolved to full brand identity at execution time.'
        ),
    ] = None
    acceptance_context: Annotated[
        acceptance_context_1.AcceptanceContext | None,
        Field(
            description='Structured campaign and advertiser facts for seller acceptance-policy preflight. Sellers may infer omitted facts from brand and brief, but uncertainty never implies acceptance.'
        ),
    ] = None
    catalog: Annotated[
        catalog_1.Catalog | None,
        Field(
            description='Catalog of items the buyer wants to promote. The seller matches catalog items against its inventory and returns products where matches exist. Supports all catalog types: a job catalog finds job ad products, a product catalog finds sponsored product slots. Reference a synced catalog by catalog_id, or provide inline items.'
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for product lookup. Returns products with pricing specific to this account's rate card."
        ),
    ] = None
    preferred_delivery_types: Annotated[
        list[delivery_type.DeliveryType] | None,
        Field(
            description='Delivery types the buyer prefers, in priority order. Unlike filters.delivery_type which excludes non-matching products, this signals preference for curation — the publisher may still include other delivery types when they match the brief well.',
            min_length=1,
        ),
    ] = None
    filters: Annotated[
        product_filters.ProductFilters | None,
        Field(
            description="Offer filters. Valid in brief, wholesale, and refine modes. In every mode, sellers MUST exclude products that do not satisfy them: brief controls curation, wholesale controls feed behavior, and refine controls iteration, but none changes filter semantics. On refine, presence is the complete replacement filter state; when omitted, each referenced product's bound discovery constraints remain in force. Targeting-like legacy fields remain accepted during migration but are deprecated in favor of targeting_overlay and required_overlay_support."
        ),
    ] = None
    targeting_overlay: Annotated[
        targeting.TargetingOverlay | None,
        Field(
            description="Concrete delivery constraints the buyer expects to carry into create_media_buy. Buyers SHOULD use this field instead of putting equivalent exact targeting only in brief prose. Sellers evaluate these constraints during discovery and scope returned pricing and forecasts to the effective targeting. If a product cannot honor the request exactly, the seller may omit it or return a request-scoped configured product with Product targeting_resolution modifications. Absence of Product targeting_resolution means exact acceptance of this structured overlay; it does not confirm how targeting in the brief was interpreted. On refine, presence is complete replacement state for returned configurations; when omitted, each referenced product's bound targeting remains in force."
        ),
    ] = None
    media_buy_frequency_cap: Annotated[
        media_buy_frequency_cap_1.MediaBuyFrequencyCap | None,
        Field(
            description='Concrete aggregate max-impression cap intended for the MediaBuy root. Every returned product must participate in one shared counter for this exact value. Legacy proposals echo it as proposals[].frequency_cap; direct buyers repeat it at purchase.'
        ),
    ] = None
    required_overlay_support: Annotated[
        targeting_overlay_requirements.TargetingOverlayRequirements | None,
        Field(
            description="Minimum product-scoped targeting dimensions the buyer must be able to set independently on packages later. This requests selectable capability, not current targeting values, value-specific availability or forecasts, and not one product per possible value. A requirement true matches support true or any valid support object; an object requirement matches support true or an object containing every requested boolean and requested array subset. The backward-compatible daypart_targets support true is the exception: it satisfies inventory_local requirements only, not iana requirements. Unrequested object fields and numeric limits do not participate. Missing or unknown requirement fields do not match. Seller limit fields are response-only and cannot be requested here. On refine, presence is complete replacement state; when omitted, each referenced product's bound future-support requirements remain in force."
        ),
    ] = None
    required_media_buy_support: Annotated[
        media_buy_support_requirements.ProductMediaBuySupportRequirements | None,
        Field(
            description='Minimum product participation in shared MediaBuy-level controls. For a frequency cap, every returned product must be composable in one seller-maintained aggregate counter for every requested per unit. On refine, presence is complete replacement state.'
        ),
    ] = None
    property_list: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            deprecated=True,
            description='DEPRECATED discovery-only property filter. On compact discovery tasks use criteria.offer_filters.property_list to preserve product eligibility. Use targeting_overlay.property_list only when the buyer intends a delivery constraint, or required_overlay_support.property_list for future selectability. A facade MUST NOT convert this discovery filter into delivery targeting.',
        ),
    ] = None
    fields: Annotated[
        list[product_fields.ProductResponseField | Fields] | None,
        Field(
            description='Specific product fields to include in the response. When omitted, all fields are returned. Use for lightweight discovery calls where only a subset of product data is needed. product_id and name are always included. `format_ids` is a deprecated 3.x compatibility projection; new integrations request canonical `format_options`. Safety-critical request-specific fields override projection: Product.targeting_resolution and expires_at MUST be included whenever the seller returns modifications, overlay_support MUST be included when required_overlay_support was requested, media_buy_support MUST be included when required_media_buy_support or media_buy_frequency_cap was requested, list_applications MUST be included when a property or collection list is in the effective targeting, and audience_evidence_selections MUST be included when filters.audience_evidence_requirements affects eligibility or ranking. fields controls the optional audience_evidence payload, not either decision receipt. Response-level brief targeting confirmation is not a projected product field.',
            min_length=1,
        ),
    ] = None
    time_budget: Annotated[
        duration.Duration | None,
        Field(
            description='Maximum time the buyer will commit to this request. The seller returns the best results achievable within this budget and does not start processes (human approvals, expensive external queries) that cannot complete in time. When omitted, the seller decides timing.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on curated discovery. Meaningful only for `buying_mode: "brief"` and `buying_mode: "refine"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief/refine request includes this field and the seller returns a Submitted envelope, the seller MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the seller cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: sellers MUST NOT route `buying_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description="Cursor-based pagination controls for get_products. Valid in all buying modes. In brief mode, pagination bounds the seller's returned products[] for the curated answer to the brief and is not an exhaustive catalog-enumeration contract. In refine mode, pagination bounds the refined products[] result implied by refine[] and filters; proposals may accompany a page as plan metadata but are not independently counted by this pagination envelope. In wholesale mode, pagination walks the wholesale product feed and may be combined with wholesale feed versioning."
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_products response from this agent. Only valid when buying_mode is wholesale. When provided, the seller compares against its current wholesale product feed version for the buyer's cache_scope and MAY return an unchanged: true response (with products omitted) if nothing has changed. The token is scope-keyed: buyers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog) for cache_scope: 'public'; that tuple plus account identity for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. Backward-compatible: pre-v3.1 agents that ignore this field simply return the full payload, same as the unchanged-server path. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_products response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → seller returns the full payload (pricing is implicitly stale); (2) if_wholesale_feed_version matches but if_pricing_version mismatches → seller returns the full payload so the buyer sees updated pricing_options; (3) both match → seller MAY return unchanged: true. Agents that don't track pricing separately ignore if_pricing_version and fall back to if_wholesale_feed_version semantics. Useful for storefronts that re-price compositions far more often than they re-render product mirrors."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    required_policies: Annotated[
        list[str] | None,
        Field(
            description='Registry policy IDs that the buyer requires to be enforced for products in this response. Sellers filter products to only those that comply with or already enforce the requested policies.'
        ),
    ] = 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

Subclasses

• GetProductsRequest

Class variables

var acceptance_context : AcceptanceContext | None

var account : AccountReference1 | AccountReference2 | None

var brand : BrandReference | None

var brief : str | None

var buying_mode : BuyingMode | None

var catalog : Catalog | None

var context : ContextObject | None

var ext : ExtensionObject | None

var fields : list[ProductResponseField | Fields] | None

var filters : ProductFilters | None

var idempotency_key : str | None

var if_pricing_version : str | None

var if_wholesale_feed_version : str | None

var media_buy_frequency_cap : MediaBuyFrequencyCap | None

var model_config

var pagination : PaginationRequest | None

var preferred_delivery_types : list[DeliveryType] | None

var push_notification_config : PushNotificationConfig | None

var refine : list[Refine1 | Refine2 | Refine3] | None

var required_media_buy_support : ProductMediaBuySupportRequirements | None

var required_overlay_support : TargetingOverlayRequirements | None

var required_policies : list[str] | None

var targeting_overlay : TargetingOverlay | None

var time_budget : Duration | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var property_list : PropertyListReference | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class GetProductsBriefRequest (**data: Any)

Expand source code

class GetProductsRequest(_LegacyGetProductsRequest, CanonicalBoundaryModel):
    """Canonical discovery request with legacy response-field selection rejected."""

    filters: ProductFilters | None = None

    @field_validator("fields")
    @classmethod
    def _reject_legacy_fields(cls, value: Any) -> Any:
        if value and any(
            is_legacy_creative_identity_key(getattr(item, "value", item)) for item in value
        ):
            raise ValueError(
                "format_id and format_ids are unavailable on the canonical get_products API"
            )
        return value

Canonical discovery request with legacy response-field selection rejected.

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

• GetProductsRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var filters : ProductFilters | None

var model_config

class GetProductsRefineRequest (**data: Any)

Expand source code

class GetProductsRequest(_LegacyGetProductsRequest, CanonicalBoundaryModel):
    """Canonical discovery request with legacy response-field selection rejected."""

    filters: ProductFilters | None = None

    @field_validator("fields")
    @classmethod
    def _reject_legacy_fields(cls, value: Any) -> Any:
        if value and any(
            is_legacy_creative_identity_key(getattr(item, "value", item)) for item in value
        ):
            raise ValueError(
                "format_id and format_ids are unavailable on the canonical get_products API"
            )
        return value

Canonical discovery request with legacy response-field selection rejected.

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

• GetProductsRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var filters : ProductFilters | None

var model_config

class GetProductsWholesaleRequest (**data: Any)

Expand source code

class GetProductsRequest(_LegacyGetProductsRequest, CanonicalBoundaryModel):
    """Canonical discovery request with legacy response-field selection rejected."""

    filters: ProductFilters | None = None

    @field_validator("fields")
    @classmethod
    def _reject_legacy_fields(cls, value: Any) -> Any:
        if value and any(
            is_legacy_creative_identity_key(getattr(item, "value", item)) for item in value
        ):
            raise ValueError(
                "format_id and format_ids are unavailable on the canonical get_products API"
            )
        return value

Canonical discovery request with legacy response-field selection rejected.

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

• GetProductsRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var filters : ProductFilters | None

var model_config

Inherited members

• GetProductsRequest:
  • adcp_major_version
  • get_account
  • get_adcp_major_version
  • get_adcp_version
  • get_context
  • get_idempotency_key
  • get_push_notification_config
  • model_dump
  • model_dump_json
  • model_summary
  • property_list
• CanonicalBoundaryModel:
  • model_json_schema

class GetProductsResponse (**data: Any)

Expand source code

class GetProductsResponse(_LegacyGetProductsResponse, CanonicalBoundaryModel):
    """Canonical discovery response; products are canonical products."""

    products: list[Product] | None = None  # type: ignore[assignment]

Canonical discovery response; products are canonical products.

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

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

Class variables

var model_config

var products : list[Product] | None

class LegacyGetProductsResponse (**data: Any)

Expand source code

class GetProductsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    products: Annotated[
        list[product.Product] | None, Field(description='Array of matching products')
    ] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description='Request-level confirmation of structured hard targeting inferred from the brief. Sellers MUST include this when their structured interpretation of hard prose materially affects product eligibility, pricing, or forecasting; otherwise inclusion is a best practice. Omitted when no hard targeting was inferred from the brief.'
        ),
    ] = None
    extensions: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^https?://[^@]+@sha256:[a-f0-9]{64}$')], Extensions] | None,
        Field(
            description='Bundled platform-extension definitions referenced by any product in `products`. Keyed by `<extension_uri>@<digest>` (e.g., `https://creative.adcontextprotocol.org/translated/meta/extensions/meta_pixel@sha256:abc...`). When present, lets buyers resolve `platform_extensions` references on product format declarations without a separate fetch. Buyer SDKs cache by URI@digest; subsequent get_products responses MAY omit definitions the buyer already has cached and rely on the digest match. Each value is an extension definition with `extends` (the canonical concept it extends, e.g., `tracking`), `fields` (the schema for additional fields the extension contributes), `version`, and optional `description`.'
        ),
    ] = None
    proposals: Annotated[
        list[proposal.Proposal] | None,
        Field(
            description='Optional legacy proposed media plans. When the request carries media_buy_frequency_cap, every returned proposal echoes the bound value as proposal.frequency_cap. Buyers may refine or execute a committed proposal by ID.'
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(description='Task-specific errors and warnings (e.g., product filtering issues)'),
    ] = None
    reason: Annotated[
        str | None,
        Field(
            description='Buyer-facing market explanation required only on the GetProductsRejected arm. MAY be sanitized to protect confidential seller rules. Plain text only.',
            max_length=2000,
            min_length=1,
        ),
    ] = None
    suggestions: Annotated[
        list[Suggestion] | None,
        Field(
            description='Actionable alternatives available only on the GetProductsRejected arm.',
            max_length=20,
        ),
    ] = None
    property_list_applied: Annotated[
        StrictBool | None,
        Field(
            description='[AdCP 3.0] Indicates whether deprecated top-level property_list filtering was applied. True if the agent filtered products based on the provided property_list; every returned product also carries the corresponding property/include list_applications receipt. Absent or false if property_list was not provided or not supported by this agent.'
        ),
    ] = None
    catalog_applied: Annotated[
        StrictBool | None,
        Field(
            description='Whether the seller filtered results based on the provided catalog. True if the seller matched catalog items against its inventory. Absent or false if no catalog was provided or the seller does not support catalog matching.'
        ),
    ] = None
    refinement_applied: Annotated[
        list[RefinementApplied] | None,
        Field(
            description="Seller's response to each change request in the refine array, matched by position. Each entry acknowledges whether the corresponding ask was applied, partially applied, or unable to be fulfilled. MUST contain the same number of entries in the same order as the request's refine array. Only present when the request used buying_mode: 'refine'. Each entry MUST echo the request entry's scope and — for product and proposal scopes — the matching id field (product_id or proposal_id), so orchestrators can cross-validate alignment."
        ),
    ] = None
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description="Declares what the seller could not finish within the buyer's time_budget or due to internal limits while still returning a usable response. Each entry identifies a scope that is missing or partial. Absent when the response is fully complete. This field does not classify the condition as retryable; retryability is carried by error.recovery on the error channel.",
            min_length=1,
        ),
    ] = None
    filter_diagnostics: Annotated[
        FilterDiagnostics | None,
        Field(
            description="Optional non-fatal diagnostic block describing how the request's `filters` narrowed the candidate set. Use this to disambiguate empty/small result lists between 'no inventory matches the brief' and 'a specific filter excluded everything', without breaking the filter-not-fail convention (sellers still silently exclude unmatched products; this block is observability, not error reporting). Sellers MAY populate this when meaningful narrowing occurred; buyers MAY use it for triage UX without depending on its presence. Counts only — products are not enumerated by name to avoid leaking competitive intelligence about adjacent campaigns or seller inventory. `total_candidates` and `excluded_by` are independently optional — sellers whose baseline candidate set size is sensitive MAY emit `excluded_by` without `total_candidates`, or vice versa.",
            examples=[
                {
                    'semantics': 'only',
                    'total_candidates': 47,
                    'excluded_by': {
                        'required_metrics': {'count': 31, 'values': ['completed_views']},
                        'required_geo_targeting': {'count': 9},
                        'pricing_currencies': {'count': 3, 'values': ['USD']},
                        'budget_range': {'count': 7},
                    },
                }
            ],
        ),
    ] = None
    pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(
            description="Cursor metadata for paginated get_products responses. In brief/refine mode, continuation pages bound returned products[] for the seller's curated or refined answer; proposals may accompany a page as plan metadata but are not independently counted by this pagination envelope, and pagination does not convert the response into an exhaustive feed contract. In wholesale mode, continuation pages walk the wholesale product feed."
        ),
    ] = None
    wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque token representing the version of the wholesale product feed state used to compose this response. Sellers that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so buyers can cache and probe later. Buyers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A buyer caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model."
        ),
    ] = None
    pricing_version: Annotated[
        str | None,
        Field(
            description='Opaque token representing the version of the pricing layer, including product pricing_options and nested signal_targeting_options pricing_options. When the seller supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Same cache_scope keying as wholesale_feed_version. Sellers not separating these MAY omit pricing_version and use wholesale_feed_version for both.'
        ),
    ] = None
    cache_scope: Annotated[
        CacheScope | None,
        Field(
            description="Declares whether the wholesale_feed_version and pricing_version on this response describe a universal layer or an account-specific overlay. REQUIRED on every 3.1+ response (the 3.1 schema enforces this — the safety property of the two-layer cache model depends on it). 'public': this response describes the seller's published rate card; the buyer MAY dedupe under (agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog) without scoping by account. 'account': this response includes account-specific overrides; the buyer MUST cache the version under that tuple plus account_id. When the request did NOT include `account`, the seller MUST return `cache_scope: 'public'`. When the request included `account`, the seller MUST return either: 'public' (this account prices off the public rate card — buyer dedupes) or 'account' (account-specific overrides exist — buyer caches under the account key). Sellers MAY return 'public' on an account-scoped request that previously had overrides — buyers SHOULD interpret this as a downgrade and drop their account-overlay. Without schema-required cache_scope, a seller silently omitting the field on an account-scoped response would cause buyers to mis-key the cache and serve account-overlay payloads to other accounts. **Backward-compatibility note for 3.1 validators:** SDKs that validate strictly against the 3.1 schema MUST select the validator based on the server-declared `adcp_version` (release-precision version negotiation, 3.1). For responses with `adcp_version` starting `3.0`, the 3.1 cache_scope-required constraint MUST be relaxed."
        ),
    ] = CacheScope.public
    unchanged: Annotated[
        Literal[True] | None,
        Field(
            description="Present and `true` ONLY on wholesale-mode responses when the request carried if_wholesale_feed_version (and/or if_pricing_version) matching the seller's current version for the buyer's cache_scope, in which case products[] MUST be omitted; wholesale_feed_version (echoed), cache_scope (echoed), and pricing_version (echoed when used) MUST still be present. Buyers receiving unchanged: true MUST NOT mutate their local wholesale product mirror. **One shape per state:** sellers MUST NOT emit `unchanged: false` — the absence of the field IS the signal that the response carries products. Two shapes ({ unchanged: false, products: [...] } vs. { products: [...] }) for the same state would let some sellers always emit the field and some never would, creating an inconsistency the wire shouldn't carry. **Cross-scope isolation:** the comparator that decides `unchanged` MUST be keyed on `(cache_scope, wholesale_feed_version)`, not on the token value alone. A seller MUST NOT emit `unchanged: true` when it resolves the request to a different `cache_scope` than the one whose token the buyer echoed in `if_wholesale_feed_version` (and/or `if_pricing_version`): because the token is scope-keyed, a value minted for `cache_scope: 'public'` cannot match the seller's current token for `cache_scope: 'account'` (or vice-versa), so such a request MUST return the full feed for the resolved scope with that scope's own token."
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = 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.

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

Subclasses

• GetProductsResponse

Class variables

var cache_scope : CacheScope | None

var catalog_applied : bool | None

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var extensions : dict[str, Extensions] | None

var filter_diagnostics : FilterDiagnostics | None

var incomplete : list[IncompleteItem] | None

var model_config

var pagination : PaginationResponse | None

var pricing_version : str | None

var products : list[Product] | None

var property_list_applied : bool | None

var proposals : list[Proposal] | None

var reason : str | None

var refinement_applied : list[RefinementApplied1 | RefinementApplied2 | RefinementApplied3] | None

var sandbox : bool | None

var status : TaskStatus | None

var suggestions : list[Suggestion] | None

var targeting_resolution : ProductDiscoveryTargetingResolution | None

var unchanged : Literal[True] | None

var wholesale_feed_version : str | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class GetProductsSuccessResponse (**data: Any)

Expand source code

class GetProductsResponse(_LegacyGetProductsResponse, CanonicalBoundaryModel):
    """Canonical discovery response; products are canonical products."""

    products: list[Product] | None = None  # type: ignore[assignment]

Canonical discovery response; products are canonical products.

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

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

Class variables

var model_config

var products : list[Product] | None

Inherited members

• GetProductsResponse:
  • adcp_major_version
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class GetProductsSubmittedResponse (**data: Any)

Expand source code

class GetProductsSubmitted(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['submitted'],
        Field(
            description='Task-level status literal. Discriminates this async envelope from the synchronous success shape, whose products array is issued in-line. See task-status.json for the full task-status enum.'
        ),
    ] = 'submitted'
    task_id: Annotated[
        str,
        Field(
            description='Task handle the buyer uses with get_task_status (or the legacy AdCP tasks/get alias), and that the seller references on push-notification callbacks. The products array is issued on the completion artifact, not here. This AdCP application-layer handle remains the snake_case task_id in every transport payload and is distinct from any transport-native A2A Task id.'
        ),
    ]
    message: Annotated[
        str | None,
        Field(
            description="Optional human-readable explanation of why the task is submitted — e.g., 'Custom curation queued; typical turnaround 10–30 minutes.' Plain text only. Buyers MUST treat this as untrusted seller input: escape before rendering to HTML UIs, and sanitize or isolate before passing to an LLM prompt context — a hostile seller may inject prompt-injection payloads aimed at the buyer's agent.",
            max_length=2000,
        ),
    ] = None
    estimated_completion: Annotated[
        AwareDatetime | None, Field(description='Estimated completion time for the search')
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories, governance observations). Terminal failures belong in the error branch, not here.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var errors : list[Error] | None

var estimated_completion : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal['submitted']

var task_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class GetProductsWorkingResponse (**data: Any)

Expand source code

class GetProductsWorking(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    percentage: Annotated[
        StrictFloat | None,
        Field(description='Progress percentage of the search operation', ge=0.0, le=100.0),
    ] = None
    current_step: Annotated[
        str | None,
        Field(
            description="Current step in the search process (e.g., 'searching_inventory', 'validating_availability')"
        ),
    ] = None
    total_steps: Annotated[
        SchemaInt | None, Field(description='Total number of steps in the search process')
    ] = None
    step_number: Annotated[
        SchemaInt | None, Field(description='Current step number (1-indexed)')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var current_step : str | None

var ext : ExtensionObject | None

var model_config

var percentage : float | None

var step_number : int | None

var total_steps : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class GetPropertyListRequest (**data: Any)

Expand source code

class GetPropertyListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list_id: Annotated[str, Field(description='ID of the property list to retrieve')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts and the list_id is not globally unique within that scope; optional otherwise.'
        ),
    ] = None
    resolve: Annotated[
        StrictBool | None,
        Field(
            description='Whether to apply filters and return resolved identifiers (default: true)'
        ),
    ] = True
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination parameters. Uses higher limits than standard pagination because property lists can contain tens of thousands of identifiers.'
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var list_id : str

var model_config

var pagination : Pagination | None

var resolve : bool | 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 GetPropertyListResponse (**data: Any)

Expand source code

class GetPropertyListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list: Annotated[
        property_list.PropertyList,
        Field(description='The property list metadata (always returned)'),
    ]
    identifiers: Annotated[
        _list[identifier.Identifier] | None,
        Field(
            description='Resolved identifiers that passed filters (if resolve=true). Cache these locally for real-time use.'
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    resolved_at: Annotated[
        AwareDatetime | None, Field(description='When the list was resolved')
    ] = None
    cache_valid_until: Annotated[
        AwareDatetime | None,
        Field(
            description='Cache expiration timestamp. Re-fetch the list after this time to get updated identifiers.'
        ),
    ] = None
    coverage_gaps: Annotated[
        dict[str, _list[identifier.Identifier]] | None,
        Field(
            description="Properties included in the list despite missing feature data. Only present when a feature_requirement has if_not_covered='include'. Maps feature_id to list of identifiers not covered for that feature."
        ),
    ] = 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.

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 cache_valid_until : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var coverage_gaps : dict[str, list[Identifier]] | None

var ext : ExtensionObject | None

var identifiers : list[Identifier] | None

var list : PropertyList

var model_config

var pagination : PaginationResponse | None

var resolved_at : pydantic.types.AwareDatetime | 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 GetReportingStatusRequest (**data: Any)

Expand source code

class GetReportingStatusRequest(AdcpRequest, AdcpVersionEnvelope):
    account: Annotated[
        canonical_account_ref.CanonicalAccountReference,
        Field(description='Account whose caller-owned reporting status is queried.'),
    ]
    view: ReportingStatusView
    media_buy_ids: Annotated[
        list[reporting_coverage.ReportingMediaBuyId] | None,
        Field(
            description='Optional summary/periods scope. Omit for every accessible media buy in the account.',
            max_length=100,
            min_length=1,
        ),
    ] = None
    delivery_config_ids: Annotated[
        list[DeliveryConfigId] | None,
        Field(
            description='Optional summary/periods scope. Use to reconcile billing, analytics, and pacing independently. Omit for every active caller-owned configuration.',
            max_length=16,
            min_length=1,
        ),
    ] = None
    feed_purposes: Annotated[
        list[reporting_delivery_offering.ReportingFeedPurpose] | None,
        Field(
            description='Optional summary/periods feed filter. The response echoes exact resolved configuration generations so this never creates an opaque aggregate.',
            min_length=1,
        ),
    ] = None
    period: Annotated[
        Period | None,
        Field(
            description="Half-open summary/periods horizon. Omit for the seller's documented operational default horizon; the response always echoes the evaluated scope."
        ),
    ] = None
    health: Annotated[
        list[reporting_health.ReportingHealth] | None,
        Field(
            description='Periods-view result filter only; it never changes summary health.',
            min_length=1,
        ),
    ] = None
    finality: Annotated[list[reporting_finality.ReportingFinality] | None, Field(min_length=1)] = (
        None
    )
    reporting_revision_id: Annotated[
        str | None,
        Field(
            description='Exact retained revision to resolve in revision view.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    changes_after: Annotated[
        str | None,
        Field(
            description='Periods-view incremental-repair checkpoint previously returned as changes_checkpoint after fully consuming a response. Returns newly committed obligations, revisions, adjustments, materializations, consumer status statements, revision receipts, and adjustment receipts plus the current projection of each affected obligation. Omit for a full ledger read.',
            max_length=2048,
            min_length=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Periods or revision-view pagination. Cursors are bound to the authenticated caller, account, filters, and ledger snapshot.'
        ),
    ] = 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 account : CanonicalAccountReference1 | CanonicalAccountReference2

var changes_after : str | None

var context : ContextObject | None

var delivery_config_ids : list[DeliveryConfigId] | None

var ext : ExtensionObject | None

var feed_purposes : list[ReportingFeedPurpose] | None

var finality : list[ReportingFinality] | None

var health : list[ReportingHealth] | None

var media_buy_ids : list[ReportingMediaBuyId] | None

var model_config

var pagination : PaginationRequest | None

var period : Period | None

var reporting_revision_id : str | None

var view : ReportingStatusView

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 GetReportingStatusResponse (**data: Any)

Expand source code

class GetReportingStatusResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    view: get_reporting_status_request.ReportingStatusView | None = None
    ledger_snapshot_id: Annotated[
        str | None,
        Field(
            description="Opaque identity of the seller's consistent reporting-ledger snapshot. Every page reached from one periods cursor MUST return the same value.",
            max_length=255,
            min_length=1,
        ),
    ] = None
    ledger_as_of: Annotated[
        AwareDatetime | None,
        Field(
            description='Exclusive observation boundary for ledger_snapshot_id. Revisions committed later appear only in a later reconciliation.'
        ),
    ] = None
    changes_checkpoint: Annotated[
        str | None,
        Field(
            description='Opaque durable incremental-repair checkpoint for this periods snapshot. Consumers persist it only after consuming every page, then send it as changes_after. It is bound to authenticated caller, account, and filters and MUST order every committed obligation, revision, adjustment, materialization, consumer status statement, revision receipt, and adjustment receipt without gaps.',
            max_length=2048,
            min_length=1,
        ),
    ] = None
    account_id: Annotated[
        str | None,
        Field(description='Resolved seller/storefront account identifier.', min_length=1),
    ] = None
    scope: Annotated[
        Scope | None,
        Field(
            description='Exact denominator evaluated for summary or periods health. complete is valid only when scope_closed is true.'
        ),
    ] = None
    health: reporting_health.ReportingHealth | None = None
    coverage: Annotated[
        reporting_coverage.ReportingCoverage | None,
        Field(
            description='Aggregated effective coverage for the exact selected scope. This remains independent of reporting health and finality so a fresh covered subset cannot look like complete campaign reporting.'
        ),
    ] = None
    data_through: Annotated[
        AwareDatetime | None,
        Field(
            description='Conservative latest included event time across satisfied obligations in scope, or null when unavailable/unknown.'
        ),
    ] = None
    next_expected_at: Annotated[
        AwareDatetime | None,
        Field(
            description='Next obligation due time for an open scope. In a complete summary (view: summary, health: complete), the nearest future period start, strictly after ledger_as_of, across all active committed configuration generations in scope.delivery_config_generations. Sellers MUST populate it when such a scheduled period exists outside the closed evaluated scope, and omit it when none exists. This complete-scope projection applies only to summary responses. It is derived from the configuration schedule and does not represent an open obligation in the evaluated scope; its presence does not indicate that the scope is still open. Projecting it MUST NOT create, expose, lease, count, or alter an obligation whose period has not closed, or change obligation_counts, scope, or coverage. Obligation expected_at remains period.end plus schedule.delivery_sla; get_media_buy_delivery.next_expected_at remains the next webhook notification time.'
        ),
    ] = None
    obligation_counts: ObligationCounts | None = None
    issues: list[reporting_status_issue.ReportingStatusIssue] | None = None
    periods: list[reporting_obligation.ReportingObligation] | None = None
    revisions: Annotated[
        list[reporting_revision.ReportingRevision] | None,
        Field(
            description='Revision ledger records on this page. Pagination is over the flat union of obligations, revisions, adjustments, materializations, consumer status statements, revision receipts, and adjustment receipts, avoiding unbounded nested history.'
        ),
    ] = None
    adjustments: Annotated[
        list[reporting_adjustment.ReportingAdjustment] | None,
        Field(
            description='Immutable post-official accounting corrections on this page. They preserve the original invoice-to-revision binding and are included in flat ledger pagination.'
        ),
    ] = None
    consumer_statuses: Annotated[
        list[reporting_consumer_status.ReportingConsumerStatus] | None,
        Field(
            description="Authenticated caller's append-only reporting status history on this page. Current leaves are identified by obligation current_consumer_status_id or, for a missing seller obligation, by the supersession chain over configuration generation, report definition, and period. No other consumer's status is disclosed."
        ),
    ] = None
    adjustment_receipts: Annotated[
        list[reporting_adjustment_receipt.ReportingAdjustmentReceipt] | None,
        Field(
            description='Authenticated Reconciled Billing outcomes for adjustments on this page.'
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    revision: reporting_revision.ReportingRevision | None = None
    materializations: list[reporting_materialization.ReportingMaterialization] | None = None
    receipts: Annotated[
        list[reporting_receipt.ReportingReceipt] | None,
        Field(
            description="Authenticated caller's durable reconciliation receipts. Receipts from another consumer principal are never disclosed."
        ),
    ] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    status: Status

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> GetReportingStatusResponse:
        # ``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 (('status',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'GetReportingStatusResponse requires at least one of these field groups: status'
        )

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_id : str | None

var adjustment_receipts : list[ReportingAdjustmentReceipt] | None

var adjustments : list[ReportingAdjustment] | None

var changes_checkpoint : str | None

var consumer_statuses : list[ReportingConsumerStatus] | None

var context : ContextObject | None

var coverage : ReportingCoverage | None

var data_through : pydantic.types.AwareDatetime | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var health : ReportingHealth | None

var issues : list[ReportingStatusIssue] | None

var ledger_as_of : pydantic.types.AwareDatetime | None

var ledger_snapshot_id : str | None

var materializations : list[ReportingMaterialization] | None

var model_config

var next_expected_at : pydantic.types.AwareDatetime | None

var obligation_counts : ObligationCounts | None

var pagination : PaginationResponse | None

var periods : list[ReportingObligation] | None

var receipts : list[ReportingReceipt] | None

var revision : ReportingRevision | None

var revisions : list[ReportingRevision] | None

var scope : Scope | None

var status : Status

var view : ReportingStatusView | 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 GetRightsRequest (**data: Any)

Expand source code

class GetRightsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    query: Annotated[
        str,
        Field(
            description='Natural language description of desired rights. The agent interprets intent, budget signals, and compatibility from this text.',
            max_length=2000,
        ),
    ]
    uses: Annotated[
        list[right_use.RightUse],
        Field(
            description='Rights uses being requested. The agent returns options covering these uses, potentially bundled into composite pricing.',
            min_length=1,
        ),
    ]
    buyer_brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description="The buyer's brand. The agent fetches the buyer's brand.json for compatibility filtering (e.g., dietary conflicts, competitor exclusions)."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where rights are needed (ISO 3166-1 alpha-2). Filters to rights available in these markets.'
        ),
    ] = None
    brand_id: Annotated[
        str | None,
        Field(
            description="Search within a specific brand's rights. If omitted, searches across the agent's full roster."
        ),
    ] = None
    right_type: Annotated[
        right_type_1.RightType | None,
        Field(description='Filter by type of rights (talent, music, stock_media, etc.)'),
    ] = None
    include_excluded: Annotated[
        StrictBool | None,
        Field(
            description='Include filtered-out results in the excluded array with reasons. Defaults to false.'
        ),
    ] = False
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(description='Pagination parameters for large result sets'),
    ] = 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 brand_id : str | None

var buyer_brand : BrandReference | None

var context : ContextObject | None

var countries : list[Country] | None

var ext : ExtensionObject | None

var include_excluded : bool | None

var model_config

var pagination : PaginationRequest | None

var query : str

var right_type : RightType | None

var uses : list[RightUse]

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 GetRightsSuccessResponse (**data: Any)

Expand source code

class GetRightsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    rights: list[Right]
    excluded: list[Excluded] | None = 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.

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 context : ContextObject | None

var excluded : list[Excluded] | None

var ext : ExtensionObject | None

var model_config

var rights : list[Right]

class GetRightsResponse1 (**data: Any)

Expand source code

class GetRightsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    rights: list[Right]
    excluded: list[Excluded] | None = 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.

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 context : ContextObject | None

var excluded : list[Excluded] | None

var ext : ExtensionObject | None

var model_config

var rights : list[Right]

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 GetRightsErrorResponse (**data: Any)

Expand source code

class GetRightsResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 GetSignalsRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    discovery_mode: Annotated[
        DiscoveryMode | None,
        Field(
            description="Declares caller intent for this request. 'brief' (default): semantic discovery — signal_spec, signal_refs, or legacy signal_ids is required and the agent performs inference/RAG. 'wholesale': raw wholesale signals feed enumeration — signal_spec, signal_refs, and signal_ids MUST NOT be provided and the agent returns its full priced signals feed, paginated, scoped by filters/account/destinations/countries when present. Sellers receiving requests from pre-v3.1 clients without discovery_mode MUST default to 'brief'. Timing semantics: 'wholesale' is a wholesale signals feed read — agents SHOULD respond synchronously and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field, not via a task-handoff envelope. Agents that do not implement wholesale enumeration MAY return INVALID_REQUEST for wholesale calls; callers SHOULD probe via get_adcp_capabilities (signals.discovery_modes) first."
        ),
    ] = DiscoveryMode.brief
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for this request. When provided, the signals agent returns per-account pricing options if configured. In 'wholesale' mode, this is the rate-card scope: when omitted in wholesale mode, agents return their default rate-card pricing or omit pricing_options entirely."
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description="Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_refs, provides context for the agent but signal_ref matches are returned first. MUST NOT be provided when discovery_mode is 'wholesale'."
        ),
    ] = None
    signal_refs: Annotated[
        list[signal_ref_1.SignalRef] | None,
        Field(
            description="Specific signals to look up by reference. Returns exact matches for the requested SignalRef values. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id_1.SignalId] | None,
        Field(
            deprecated=True,
            description="DEPRECATED. Use signal_refs instead. Legacy exact lookup field using SignalId objects. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific signal fields to include in the response, aligned with get_products.fields. Required identity and activation fields such as signal_ref or signal_id, signal_agent_segment_id, name, description, signal_type, coverage_percentage, and deployments are always included when required by the response schema. Use for progressive disclosure of rich signal-definition metadata: request fields such as demographic_predicate, taxonomy, data_sources, methodology, segmentation_criteria, criteria_url, refresh_cadence, lookback_window, onboarder, modeling, audience_expansion, device_expansion, countries, consent_basis, restricted_attributes, policy_categories, art9_basis, data_subject_rights, and last_updated when the buyer needs them inline. Omit for the agent's default discovery projection. Agents SHOULD honor requested fields for exact lookup, refinement, small custom-signal result sets, and private/source-native signals when available. fields is a projection request, not an entitlement grant; agents MAY redact requested definition fields unless the caller is authorized for the underlying lineage, methodology, and rights-routing metadata. When demographic_predicate, consent_basis, or art9_basis is projected for another provider's signal, the value remains provider-declared signal-definition posture; sellers and federating agents MUST NOT substitute their own semantics or processing basis. For broad discovery and wholesale pages, agents MAY return compact pointers instead of inlining large resources, especially when provider-published definitions can be resolved from signal_ref, taxonomy.ref, criteria_url, disclosure_url, and validators such as resolved URL plus catalog_etag, HTTP ETag/Last-Modified, or taxonomy.etag.",
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        SchemaInt | None,
        Field(
            deprecated=True,
            description='DEPRECATED: Use pagination.max_results instead. When both fields are present, agents MUST honor pagination.max_results. When only this field is present without a pagination envelope, agents SHOULD treat it as the page size subject to a maximum of 100 results. This field will be removed in AdCP 4.0.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters. Use pagination.max_results (max: 100, default: 50) and pagination.cursor for cursor-based page walks. When the deprecated top-level max_results field is also present, pagination.max_results takes precedence.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on semantic signal discovery. Meaningful only for `discovery_mode: "brief"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: agents MUST NOT route `discovery_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_signals response from this agent. Only valid when discovery_mode is wholesale. When provided, the agent compares against its current wholesale signals feed version for the caller's cache_scope and MAY return an unchanged: true response (with signals omitted) if nothing has changed. The token is scope-keyed: callers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_signals response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → agent returns the full payload; (2) if_wholesale_feed_version matches but if_pricing_version mismatches → agent returns the full payload so the caller sees updated pricing_options; (3) both match → agent MAY return unchanged: true. Agents that don't track pricing separately ignore this and fall back to if_wholesale_feed_version semantics."
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var countries : list[Country] | None

var destinations : list[Destination1 | Destination2] | None

var discovery_mode : DiscoveryMode | None

var ext : ExtensionObject | None

var fields : list[Field1] | None

var filters : SignalFilters | None

var if_pricing_version : str | None

var if_wholesale_feed_version : str | None

var max_results : int | None

var model_config

var pagination : PaginationRequest | None

var push_notification_config : PushNotificationConfig | None

var signal_ids : list[SignalId8 | SignalId9] | None

var signal_refs : list[SignalRef1 | SignalRef2 | SignalRef3] | None

var signal_spec : str | None

class GetSignalsDiscoveryRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    discovery_mode: Annotated[
        DiscoveryMode | None,
        Field(
            description="Declares caller intent for this request. 'brief' (default): semantic discovery — signal_spec, signal_refs, or legacy signal_ids is required and the agent performs inference/RAG. 'wholesale': raw wholesale signals feed enumeration — signal_spec, signal_refs, and signal_ids MUST NOT be provided and the agent returns its full priced signals feed, paginated, scoped by filters/account/destinations/countries when present. Sellers receiving requests from pre-v3.1 clients without discovery_mode MUST default to 'brief'. Timing semantics: 'wholesale' is a wholesale signals feed read — agents SHOULD respond synchronously and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field, not via a task-handoff envelope. Agents that do not implement wholesale enumeration MAY return INVALID_REQUEST for wholesale calls; callers SHOULD probe via get_adcp_capabilities (signals.discovery_modes) first."
        ),
    ] = DiscoveryMode.brief
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for this request. When provided, the signals agent returns per-account pricing options if configured. In 'wholesale' mode, this is the rate-card scope: when omitted in wholesale mode, agents return their default rate-card pricing or omit pricing_options entirely."
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description="Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_refs, provides context for the agent but signal_ref matches are returned first. MUST NOT be provided when discovery_mode is 'wholesale'."
        ),
    ] = None
    signal_refs: Annotated[
        list[signal_ref_1.SignalRef] | None,
        Field(
            description="Specific signals to look up by reference. Returns exact matches for the requested SignalRef values. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id_1.SignalId] | None,
        Field(
            deprecated=True,
            description="DEPRECATED. Use signal_refs instead. Legacy exact lookup field using SignalId objects. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific signal fields to include in the response, aligned with get_products.fields. Required identity and activation fields such as signal_ref or signal_id, signal_agent_segment_id, name, description, signal_type, coverage_percentage, and deployments are always included when required by the response schema. Use for progressive disclosure of rich signal-definition metadata: request fields such as demographic_predicate, taxonomy, data_sources, methodology, segmentation_criteria, criteria_url, refresh_cadence, lookback_window, onboarder, modeling, audience_expansion, device_expansion, countries, consent_basis, restricted_attributes, policy_categories, art9_basis, data_subject_rights, and last_updated when the buyer needs them inline. Omit for the agent's default discovery projection. Agents SHOULD honor requested fields for exact lookup, refinement, small custom-signal result sets, and private/source-native signals when available. fields is a projection request, not an entitlement grant; agents MAY redact requested definition fields unless the caller is authorized for the underlying lineage, methodology, and rights-routing metadata. When demographic_predicate, consent_basis, or art9_basis is projected for another provider's signal, the value remains provider-declared signal-definition posture; sellers and federating agents MUST NOT substitute their own semantics or processing basis. For broad discovery and wholesale pages, agents MAY return compact pointers instead of inlining large resources, especially when provider-published definitions can be resolved from signal_ref, taxonomy.ref, criteria_url, disclosure_url, and validators such as resolved URL plus catalog_etag, HTTP ETag/Last-Modified, or taxonomy.etag.",
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        SchemaInt | None,
        Field(
            deprecated=True,
            description='DEPRECATED: Use pagination.max_results instead. When both fields are present, agents MUST honor pagination.max_results. When only this field is present without a pagination envelope, agents SHOULD treat it as the page size subject to a maximum of 100 results. This field will be removed in AdCP 4.0.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters. Use pagination.max_results (max: 100, default: 50) and pagination.cursor for cursor-based page walks. When the deprecated top-level max_results field is also present, pagination.max_results takes precedence.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on semantic signal discovery. Meaningful only for `discovery_mode: "brief"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: agents MUST NOT route `discovery_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_signals response from this agent. Only valid when discovery_mode is wholesale. When provided, the agent compares against its current wholesale signals feed version for the caller's cache_scope and MAY return an unchanged: true response (with signals omitted) if nothing has changed. The token is scope-keyed: callers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_signals response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → agent returns the full payload; (2) if_wholesale_feed_version matches but if_pricing_version mismatches → agent returns the full payload so the caller sees updated pricing_options; (3) both match → agent MAY return unchanged: true. Agents that don't track pricing separately ignore this and fall back to if_wholesale_feed_version semantics."
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var countries : list[Country] | None

var destinations : list[Destination1 | Destination2] | None

var discovery_mode : DiscoveryMode | None

var ext : ExtensionObject | None

var fields : list[Field1] | None

var filters : SignalFilters | None

var if_pricing_version : str | None

var if_wholesale_feed_version : str | None

var max_results : int | None

var model_config

var pagination : PaginationRequest | None

var push_notification_config : PushNotificationConfig | None

var signal_ids : list[SignalId8 | SignalId9] | None

var signal_refs : list[SignalRef1 | SignalRef2 | SignalRef3] | None

var signal_spec : str | None

class GetSignalsLookupRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    discovery_mode: Annotated[
        DiscoveryMode | None,
        Field(
            description="Declares caller intent for this request. 'brief' (default): semantic discovery — signal_spec, signal_refs, or legacy signal_ids is required and the agent performs inference/RAG. 'wholesale': raw wholesale signals feed enumeration — signal_spec, signal_refs, and signal_ids MUST NOT be provided and the agent returns its full priced signals feed, paginated, scoped by filters/account/destinations/countries when present. Sellers receiving requests from pre-v3.1 clients without discovery_mode MUST default to 'brief'. Timing semantics: 'wholesale' is a wholesale signals feed read — agents SHOULD respond synchronously and MUST NOT route a 'wholesale' request through the async/Submitted arm; partial completion is signalled via the response's incomplete[] field, not via a task-handoff envelope. Agents that do not implement wholesale enumeration MAY return INVALID_REQUEST for wholesale calls; callers SHOULD probe via get_adcp_capabilities (signals.discovery_modes) first."
        ),
    ] = DiscoveryMode.brief
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account for this request. When provided, the signals agent returns per-account pricing options if configured. In 'wholesale' mode, this is the rate-card scope: when omitted in wholesale mode, agents return their default rate-card pricing or omit pricing_options entirely."
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description="Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_refs, provides context for the agent but signal_ref matches are returned first. MUST NOT be provided when discovery_mode is 'wholesale'."
        ),
    ] = None
    signal_refs: Annotated[
        list[signal_ref_1.SignalRef] | None,
        Field(
            description="Specific signals to look up by reference. Returns exact matches for the requested SignalRef values. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id_1.SignalId] | None,
        Field(
            deprecated=True,
            description="DEPRECATED. Use signal_refs instead. Legacy exact lookup field using SignalId objects. MUST NOT be provided when discovery_mode is 'wholesale'.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific signal fields to include in the response, aligned with get_products.fields. Required identity and activation fields such as signal_ref or signal_id, signal_agent_segment_id, name, description, signal_type, coverage_percentage, and deployments are always included when required by the response schema. Use for progressive disclosure of rich signal-definition metadata: request fields such as demographic_predicate, taxonomy, data_sources, methodology, segmentation_criteria, criteria_url, refresh_cadence, lookback_window, onboarder, modeling, audience_expansion, device_expansion, countries, consent_basis, restricted_attributes, policy_categories, art9_basis, data_subject_rights, and last_updated when the buyer needs them inline. Omit for the agent's default discovery projection. Agents SHOULD honor requested fields for exact lookup, refinement, small custom-signal result sets, and private/source-native signals when available. fields is a projection request, not an entitlement grant; agents MAY redact requested definition fields unless the caller is authorized for the underlying lineage, methodology, and rights-routing metadata. When demographic_predicate, consent_basis, or art9_basis is projected for another provider's signal, the value remains provider-declared signal-definition posture; sellers and federating agents MUST NOT substitute their own semantics or processing basis. For broad discovery and wholesale pages, agents MAY return compact pointers instead of inlining large resources, especially when provider-published definitions can be resolved from signal_ref, taxonomy.ref, criteria_url, disclosure_url, and validators such as resolved URL plus catalog_etag, HTTP ETag/Last-Modified, or taxonomy.etag.",
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        SchemaInt | None,
        Field(
            deprecated=True,
            description='DEPRECATED: Use pagination.max_results instead. When both fields are present, agents MUST honor pagination.max_results. When only this field is present without a pagination envelope, agents SHOULD treat it as the page size subject to a maximum of 100 results. This field will be removed in AdCP 4.0.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters. Use pagination.max_results (max: 100, default: 50) and pagination.cursor for cursor-based page walks. When the deprecated top-level max_results field is also present, pagination.max_results takes precedence.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async terminal completion/failure notifications on semantic signal discovery. Meaningful only for `discovery_mode: "brief"` requests that enter the async lifecycle. Submitted envelopes with `task_id` remain pollable through `get_task_status` (legacy `tasks/get`) whether or not this field is present. If a brief request includes this field and the agent returns a Submitted envelope, the agent MUST deliver at least the terminal completion/failure notification to the configured URL; intermediate progress notifications are MAY. If the agent cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. This field does not change wholesale timing semantics: agents MUST NOT route `discovery_mode: "wholesale"` requests through the async/Submitted arm or emit async delivery solely because `push_notification_config` is present; partial wholesale completion is reported via `incomplete[]`.'
        ),
    ] = None
    if_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque wholesale_feed_version token returned by a prior wholesale-mode get_signals response from this agent. Only valid when discovery_mode is wholesale. When provided, the agent compares against its current wholesale signals feed version for the caller's cache_scope and MAY return an unchanged: true response (with signals omitted) if nothing has changed. The token is scope-keyed: callers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full sync pattern."
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description="Opaque pricing_version token from a prior get_signals response. MUST only be sent together with if_wholesale_feed_version — pricing version has no structural baseline to compare against on its own. Evaluation order: (1) if_wholesale_feed_version mismatch → agent returns the full payload; (2) if_wholesale_feed_version matches but if_pricing_version mismatches → agent returns the full payload so the caller sees updated pricing_options; (3) both match → agent MAY return unchanged: true. Agents that don't track pricing separately ignore this and fall back to if_wholesale_feed_version semantics."
        ),
    ] = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var countries : list[Country] | None

var destinations : list[Destination1 | Destination2] | None

var discovery_mode : DiscoveryMode | None

var ext : ExtensionObject | None

var fields : list[Field1] | None

var filters : SignalFilters | None

var if_pricing_version : str | None

var if_wholesale_feed_version : str | None

var max_results : int | None

var model_config

var pagination : PaginationRequest | None

var push_notification_config : PushNotificationConfig | None

var signal_ids : list[SignalId8 | SignalId9] | None

var signal_refs : list[SignalRef1 | SignalRef2 | SignalRef3] | None

var signal_spec : str | 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 GetSignalsResponse (**data: Any)

Expand source code

class GetSignalsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    signals: Annotated[Sequence[Signal] | None, Field(description='Array of matching signals')] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors and warnings (e.g., signal discovery or pricing issues)'
        ),
    ] = None
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description="Declares what the agent could not finish within the caller's time_budget or due to internal limits. Each entry identifies a scope that is missing or partial. Absent when the response is fully complete.",
            min_length=1,
        ),
    ] = None
    wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque token representing the version of the wholesale signals feed state used to compose this response. Agents that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so callers can cache and probe later. Callers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A caller caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model."
        ),
    ] = None
    pricing_version: Annotated[
        str | None,
        Field(
            description='Opaque token representing the version of the pricing layer. When the agent supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Same cache_scope keying as wholesale_feed_version. Agents not separating these MAY omit pricing_version and use wholesale_feed_version for both.'
        ),
    ] = None
    cache_scope: Annotated[
        CacheScope | None,
        Field(
            description="Declares whether the wholesale_feed_version and pricing_version on this response describe a universal layer or an account-specific overlay. REQUIRED on every 3.1+ response (the 3.1 schema enforces this — the safety property of the two-layer cache model depends on it). 'public': this response describes the agent's published rate card; the caller MAY dedupe under (agent, discovery_mode, filters, destinations, countries) without scoping by account. 'account': this response includes account-specific overrides; the caller MUST cache the version under that tuple plus account_id. When the request did NOT include `account`, the agent MUST return `cache_scope: 'public'`. When the request included `account`, the agent MUST return either 'public' (this account prices off the public rate card — caller dedupes) or 'account' (account-specific overrides exist — caller caches under the account key). Agents MAY return 'public' on an account-scoped request that previously had overrides — callers SHOULD interpret this as a downgrade. Without schema-required cache_scope, an agent silently omitting the field on an account-scoped response would cause callers to mis-key the cache and serve account-overlay payloads to other accounts — the canonical safety invariant of the entire cache layering model. **Backward-compatibility note for 3.1 validators:** SDKs validating strictly against the 3.1 schema MUST select the validator based on the server-declared `adcp_version`. For responses with `adcp_version` starting `3.0`, the 3.1 cache_scope-required constraint MUST be relaxed — pre-3.1 agents correctly emit no cache_scope and remain conformant to their declared version. This is a tightening within 3.1, not a 3.0 break."
        ),
    ] = CacheScope.public
    unchanged: Annotated[
        Literal[True] | None,
        Field(
            description="Present and `true` ONLY on wholesale-mode responses when the request carried if_wholesale_feed_version (and/or if_pricing_version) matching the agent's current version for the caller's cache_scope, in which case signals[] MUST be omitted; wholesale_feed_version (echoed), cache_scope (echoed), and pricing_version (echoed when used) MUST still be present. Callers receiving unchanged: true MUST NOT mutate their local wholesale signals mirror. **One shape per state:** agents MUST NOT emit `unchanged: false` — the absence of the field IS the signal that the response carries signals. **Cross-scope isolation:** the comparator that decides `unchanged` MUST be keyed on `(cache_scope, wholesale_feed_version)`, not on the token value alone. An agent MUST NOT emit `unchanged: true` when it resolves the request to a different `cache_scope` than the one whose token the caller echoed in `if_wholesale_feed_version` (and/or `if_pricing_version`): because the token is scope-keyed, a value minted for `cache_scope: 'public'` cannot match the agent's current token for `cache_scope: 'account'` (or vice-versa), so such a request MUST return the full feed for the resolved scope with that scope's own token."
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = 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.

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 cache_scope : CacheScope | None

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var incomplete : list[IncompleteItem] | None

var model_config

var pagination : PaginationResponse | None

var pricing_version : str | None

var sandbox : bool | None

var signals : collections.abc.Sequence[Signal] | None

var unchanged : Literal[True] | None

var wholesale_feed_version : str | None

class GetSignalsSuccessResponse (**data: Any)

Expand source code

class GetSignalsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    signals: Annotated[Sequence[Signal] | None, Field(description='Array of matching signals')] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors and warnings (e.g., signal discovery or pricing issues)'
        ),
    ] = None
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description="Declares what the agent could not finish within the caller's time_budget or due to internal limits. Each entry identifies a scope that is missing or partial. Absent when the response is fully complete.",
            min_length=1,
        ),
    ] = None
    wholesale_feed_version: Annotated[
        str | None,
        Field(
            description="Opaque token representing the version of the wholesale signals feed state used to compose this response. Agents that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so callers can cache and probe later. Callers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A caller caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, discovery_mode, filters, destinations, countries) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model."
        ),
    ] = None
    pricing_version: Annotated[
        str | None,
        Field(
            description='Opaque token representing the version of the pricing layer. When the agent supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Same cache_scope keying as wholesale_feed_version. Agents not separating these MAY omit pricing_version and use wholesale_feed_version for both.'
        ),
    ] = None
    cache_scope: Annotated[
        CacheScope | None,
        Field(
            description="Declares whether the wholesale_feed_version and pricing_version on this response describe a universal layer or an account-specific overlay. REQUIRED on every 3.1+ response (the 3.1 schema enforces this — the safety property of the two-layer cache model depends on it). 'public': this response describes the agent's published rate card; the caller MAY dedupe under (agent, discovery_mode, filters, destinations, countries) without scoping by account. 'account': this response includes account-specific overrides; the caller MUST cache the version under that tuple plus account_id. When the request did NOT include `account`, the agent MUST return `cache_scope: 'public'`. When the request included `account`, the agent MUST return either 'public' (this account prices off the public rate card — caller dedupes) or 'account' (account-specific overrides exist — caller caches under the account key). Agents MAY return 'public' on an account-scoped request that previously had overrides — callers SHOULD interpret this as a downgrade. Without schema-required cache_scope, an agent silently omitting the field on an account-scoped response would cause callers to mis-key the cache and serve account-overlay payloads to other accounts — the canonical safety invariant of the entire cache layering model. **Backward-compatibility note for 3.1 validators:** SDKs validating strictly against the 3.1 schema MUST select the validator based on the server-declared `adcp_version`. For responses with `adcp_version` starting `3.0`, the 3.1 cache_scope-required constraint MUST be relaxed — pre-3.1 agents correctly emit no cache_scope and remain conformant to their declared version. This is a tightening within 3.1, not a 3.0 break."
        ),
    ] = CacheScope.public
    unchanged: Annotated[
        Literal[True] | None,
        Field(
            description="Present and `true` ONLY on wholesale-mode responses when the request carried if_wholesale_feed_version (and/or if_pricing_version) matching the agent's current version for the caller's cache_scope, in which case signals[] MUST be omitted; wholesale_feed_version (echoed), cache_scope (echoed), and pricing_version (echoed when used) MUST still be present. Callers receiving unchanged: true MUST NOT mutate their local wholesale signals mirror. **One shape per state:** agents MUST NOT emit `unchanged: false` — the absence of the field IS the signal that the response carries signals. **Cross-scope isolation:** the comparator that decides `unchanged` MUST be keyed on `(cache_scope, wholesale_feed_version)`, not on the token value alone. An agent MUST NOT emit `unchanged: true` when it resolves the request to a different `cache_scope` than the one whose token the caller echoed in `if_wholesale_feed_version` (and/or `if_pricing_version`): because the token is scope-keyed, a value minted for `cache_scope: 'public'` cannot match the agent's current token for `cache_scope: 'account'` (or vice-versa), so such a request MUST return the full feed for the resolved scope with that scope's own token."
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = 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.

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 cache_scope : CacheScope | None

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var incomplete : list[IncompleteItem] | None

var model_config

var pagination : PaginationResponse | None

var pricing_version : str | None

var sandbox : bool | None

var signals : collections.abc.Sequence[Signal] | None

var unchanged : Literal[True] | None

var wholesale_feed_version : str | 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 GetSignalsSubmittedResponse (**data: Any)

Expand source code

class GetSignalsSubmitted(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['submitted'],
        Field(
            description='Task-level status literal. Discriminates this async envelope from the synchronous success shape, whose signals array is issued in-line. See task-status.json for the full task-status enum.'
        ),
    ] = 'submitted'
    task_id: Annotated[
        str,
        Field(
            description='Task handle the caller uses with get_task_status (or the legacy AdCP tasks/get alias), and that the agent references on push-notification callbacks. The signals array is issued on the completion artifact, not here. This AdCP application-layer handle remains the snake_case task_id in every transport payload and is distinct from any transport-native A2A Task id.'
        ),
    ]
    message: Annotated[
        str | None,
        Field(
            description="Optional human-readable explanation of why the task is submitted — e.g., 'Provider discovery queued; typical turnaround 10-30 minutes.' Plain text only. Callers MUST treat this as untrusted agent input: escape before rendering to HTML UIs, and sanitize or isolate before passing to an LLM prompt context — a hostile agent may inject prompt-injection payloads aimed at the caller's agent.",
            max_length=2000,
        ),
    ] = None
    estimated_completion: Annotated[
        AwareDatetime | None,
        Field(description='Estimated completion time for the signal discovery task.'),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories or partial provider unavailability). Terminal failures belong in the error branch, not here.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var errors : list[Error] | None

var estimated_completion : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal['submitted']

var task_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class GetSignalsWorkingResponse (**data: Any)

Expand source code

class GetSignalsWorking(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    percentage: Annotated[
        StrictFloat | None,
        Field(
            description='Progress percentage of the signal discovery operation.', ge=0.0, le=100.0
        ),
    ] = None
    current_step: Annotated[
        str | None,
        Field(
            description='Current step in the signal discovery process, such as `querying_providers`, `ranking_signals`, or `checking_deployments`.'
        ),
    ] = None
    total_steps: Annotated[
        SchemaInt | None,
        Field(description='Total number of steps in the signal discovery process.'),
    ] = None
    step_number: Annotated[
        SchemaInt | None, Field(description='Current step number (1-indexed).')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var current_step : str | None

var ext : ExtensionObject | None

var model_config

var percentage : float | None

var step_number : int | None

var total_steps : int | None

Inherited members

• AdCPBaseModel:
  • 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.

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 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.

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 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 GovernanceAgent (**data: Any)

Expand source code

class GovernanceAgent(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    url: Annotated[AnyUrl, Field(description='Governance agent endpoint URL. Must use HTTPS.')]
    authentication: Annotated[
        Authentication,
        Field(description='Authentication the seller presents when calling this governance agent.'),
    ]

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

Class variables

var authentication : Authentication

var model_config

var url : pydantic.networks.AnyUrl

class CoreGovernanceAgent (**data: Any)

Expand source code

class GovernanceAgent(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    url: Annotated[AnyUrl, Field(description='Governance agent endpoint URL. Must use HTTPS.')]

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

Class variables

var model_config

var url : pydantic.networks.AnyUrl

class SyncGovernanceGovernanceAgent (**data: Any)

Expand source code

class GovernanceAgent(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    url: Annotated[AnyUrl, Field(description='Governance agent endpoint URL. Must use HTTPS.')]
    authentication: Annotated[
        Authentication,
        Field(description='Authentication the seller presents when calling this governance agent.'),
    ]

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

Class variables

var authentication : Authentication

var model_config

var url : pydantic.networks.AnyUrl

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Gtin (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class Gtin(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[0-9]{8,14}$'}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class HtmlContent (**data: Any)

Expand source code

class HtmlAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['html'],
        Field(
            description='Discriminator identifying this as an HTML asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'html'
    content: Annotated[str, Field(description='HTML content')]
    version: Annotated[str | None, Field(description="HTML version (e.g., 'HTML5')")] = None
    accessibility: Annotated[
        Accessibility | None,
        Field(description='Self-declared accessibility properties for this opaque creative'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var accessibility : Accessibility | None

var asset_type : Literal['html']

var content : str

var model_config

var provenance : Provenance | None

var version : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class HttpMethod (*args, **kwds)

Expand source code

class HttpMethod(StrEnum):
    GET = 'GET'
    POST = 'POST'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var GET

var POST

class Method (*args, **kwds)

Expand source code

class HttpMethod(StrEnum):
    GET = 'GET'
    POST = 'POST'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var GET

var POST

class Identifier (**data: Any)

Expand source code

class Identifier(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    type: Annotated[
        identifier_types.PropertyIdentifierTypes, Field(description='Type of identifier')
    ]
    value: Annotated[
        str,
        Field(
            description="The identifier value. For domain type: 'example.com' matches base domain plus www and m subdomains; 'edition.example.com' matches that specific subdomain; '*.example.com' matches ALL subdomains but NOT base domain"
        ),
    ]

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

Class variables

var model_config

var type : PropertyIdentifierTypes

var value : str

class PropertyIdentifier (**data: Any)

Expand source code

class Identifier(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        identifier_types.PropertyIdentifierTypes,
        Field(description='Type of identifier for this property'),
    ]
    value: Annotated[
        str,
        Field(
            description="The identifier value. For domain type: 'example.com' matches base domain plus www and m subdomains; 'edition.example.com' matches that specific subdomain; '*.example.com' matches ALL subdomains but NOT base domain"
        ),
    ]

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

Class variables

var model_config

var type : PropertyIdentifierTypes

var value : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class IdentityMatchRequest (**data: Any)

Expand source code

class IdentityMatchRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['identity_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'identity_match_request'
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any context match request_id.'
        ),
    ]
    seller_agent_url: Annotated[
        AnyUrl,
        Field(
            description="API endpoint URL of the seller agent issuing this request. The buyer's identity-match service uses this to resolve the active package set it has registered for this seller; when `package_ids` is omitted, evaluation occurs against that full set. If `seller_agent_url` does not match any seller for which the buyer has registered active packages, the buyer MUST return an empty `eligible_package_ids` set — it MUST NOT fall back to evaluating against another seller's active set. Compared using the AdCP URL canonicalization rules, not byte-equality — see docs/reference/url-canonicalization. Consistent with `seller_agent.agent_url` on `AvailablePackage` and `agent_url` in `adagents.json`."
        ),
    ]
    identities: Annotated[
        list[Identity],
        Field(
            description='Identity tokens for the user, each tagged with its type. Publishers SHOULD include every token they have available — the buyer resolves on whichever graph matches. Entry order is not semantically significant; buyers use their own preference order when multiple entries resolve. Duplicate `(uid_type, user_token)` pairs MUST NOT appear; routers MAY reject or dedupe. `maxItems: 3` matches the TMPX plaintext budget (~120 bytes after HPKE overhead fits three 32-byte tokens); exceeding it forces buyer-side truncation.',
            max_length=3,
            min_length=1,
        ),
    ]
    consent: Annotated[
        Consent | None,
        Field(
            description='Privacy consent signals. Buyers in regulated jurisdictions MUST NOT process the user token without consent information.'
        ),
    ] = None
    package_ids: Annotated[
        list[str] | None,
        Field(
            description="Optional. When omitted, the buyer evaluates eligibility against the full set of active packages it has registered for `seller_agent_url`. When provided, the composition of `package_ids` MUST be statistically independent of the current placement — sending only the page-specific subset would let the buyer correlate Identity Match with Context Match by comparing package sets. Two acceptable modes: (a) **all-active** — include every active package this buyer has at this publisher; (b) **fuzzed** — include a random sample of active packages, optionally padded with synthetic non-existent IDs, drawn from a distribution that does not depend on the current placement. The buyer's silent-drop behavior on unknown IDs (specified below) is what makes synthetic-ID padding safe — they do not affect the response shape and cannot leak registry membership. When both `seller_agent_url` and `package_ids` are present, the buyer evaluates against the intersection of its registered active set and `package_ids`; IDs in `package_ids` that the buyer has not registered for this seller MUST be silently ignored (not surfaced as errors) to avoid leaking registry membership back to the publisher.",
            min_length=1,
        ),
    ] = None
    country: Annotated[
        str | None,
        Field(
            description='ISO 3166-1 alpha-2 country code. Routing directive for the TMP Router — used to select the correct regional provider. The router MUST strip this field before forwarding the request to the buyer agent. Not an identity signal.',
            pattern='^[A-Z]{2}$',
        ),
    ] = None
    sealed_credentials: Annotated[
        list[SealedCredential] | None,
        Field(
            description='Optional HPKE-sealed credentials addressed to specific audiences — the network-as-RP ("issuer-as-RP"/Mechanism B) carrier. Each payload is opaque to the publisher, who relays it untouched; the inner plaintext is an `attestation` (see identities[].attestation) scoped to the audience\'s relying party. Reuses the TMPX envelope format. Router handling (normative — see docs/trusted-match/specification.mdx): the router forwards each entry only to the provider that owns its `audience_kid` (not broadcast), folds `sealed_credentials` into the per-provider re-signature canonical bytes so an injected/swapped blob breaks the signature, and includes a `sealed_credentials_hash` in the dedup cache key. Receivers decrypt only entries whose `audience_kid` they hold a key for and ignore the rest. Receivers MUST bound count and size to prevent DoS amplification.',
            max_length=8,
        ),
    ] = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var consent : Consent | None

var country : str | None

var field_schema : pydantic.networks.AnyUrl | None

var identities : list[Identity]

var model_config

var package_ids : list[str] | None

var protocol_version : str | None

var request_id : str

var sealed_credentials : list[SealedCredential] | None

var seller_agent_url : pydantic.networks.AnyUrl

var type : Literal['identity_match_request']

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class IdentityMatchResponse (**data: Any)

Expand source code

class IdentityMatchResponseRouterPublisher(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['identity_match_response'],
        Field(description='Message type discriminator for deserialization.'),
    ] = 'identity_match_response'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the identity match request')
    ]
    eligible_package_ids: Annotated[
        list[str],
        Field(
            description='Package IDs the user is eligible for. Packages not listed are ineligible.'
        ),
    ]
    serve_window_sec: Annotated[
        SchemaInt,
        Field(
            description="Per-package single-shot fcap window, in seconds. After serving the user one impression on each eligible package within this window, the publisher MUST re-query Identity Match before serving from those packages again. This is NOT a router response cache TTL — it is a buyer-asserted serve throttle. Multi-impression frequency caps are handled separately by the buyer's impression tracker, which writes cap-fire events to the IdentityMatch cap-state store at the boundary regardless of this window. Maximum 300 — longer windows reduce IdentityMatch load but coarsen fcap granularity below what most campaigns require.",
            ge=1,
            le=300,
        ),
    ]
    tmpx: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='DEPRECATED in favor of tmpx_providers. Routers MAY continue to populate this field for back-compat with consumers that only know the single-token shape; when both fields are present, tmpx_providers is authoritative. Single HPKE-encrypted exposure token containing the resolved user identity tokens. Wire format: kid.base64url_nopad(ciphertext) — unpadded base64url per RFC 4648 section 5 (no = characters). Publishers MUST treat this value as opaque pass-through data. Removed in 4.0.',
        ),
    ] = None
    tmpx_providers: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[A-Za-z0-9_]+$', min_length=1, max_length=64)], TmpxProviders] | None,
        Field(
            description="Router-populated: ordered TMPX chunk/value pairs grouped by the originating identity provider's `provider_id`. Each entry's `chunks[]` is a copy of the provider's emitted `tmpx_chunks` list, in the same order. Each chunk carries a provider-local `slot_id` (from the provider's registered `tmpx_slots`) and an opaque URL-safe `value`; the publisher's deployment configuration (see publisher-tmpx-config.json) resolves each `(provider_id, slot_id)` pair to the ad-server macro name, targeting key, VAST substitution, or play-log field for that surface. The protocol carries values and attribution only. Required by router conformance when any identity provider emitted TMPX in this request; collapsing per-provider tokens into a single string loses attribution and breaks per-provider impression accounting. Map keys MUST match the provider_id charset registered in provider-registration.json (enforced by `propertyNames`). Publishers MUST NOT parse, decode, or transform any chunk's `value` — each is an opaque URL-safe wire string substituted verbatim into the mapped destination."
        ),
    ] = None

    @model_validator(mode='after')
    def _validate_tmpx_provider_ids(self) -> IdentityMatchResponseRouterPublisher:
        if self.tmpx_providers is None:
            return self
        invalid = [
            provider_id
            for provider_id in self.tmpx_providers
            if not _PROVIDER_ID_PATTERN.fullmatch(provider_id)
        ]
        if invalid:
            raise ValueError('tmpx_providers keys must be valid provider_id values')
        return self

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

• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var eligible_package_ids : list[str]

var model_config

var request_id : str

var serve_window_sec : int

var tmpx : str | None

var tmpx_providers : dict[str, TmpxProviders] | None

var type : Literal['identity_match_response']

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class ImageContent (**data: Any)

Expand source code

class ImageAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['image'],
        Field(
            description='Discriminator identifying this as an image asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'image'
    url: Annotated[AnyUrl, Field(description='URL to the image asset')]
    width: Annotated[SchemaInt, Field(description='Width in pixels', ge=1)]
    height: Annotated[SchemaInt, Field(description='Height in pixels', ge=1)]
    file_size_bytes: Annotated[
        SchemaInt | None,
        Field(
            description='Image file size in bytes. Required by agents that advertise a max_file_size_kb constraint.',
            ge=1,
        ),
    ] = None
    pixel_ratio: Annotated[
        StrictFloat | None,
        Field(
            description='Intrinsic pixels per logical render pixel (for example `2` for a 600×500 image intended to render at 300×250). Optional because a validator can infer the ratio when the target format declares logical dimensions. When supplied, it MUST agree with both `width / logical_width` and `height / logical_height`; it is never a substitute for the intrinsic `width` and `height` fields.',
            gt=0.0,
        ),
    ] = None
    state_id: Annotated[
        str | None,
        Field(
            description='Binding used only when this image populates a `seller_rendered_stateful_display` `state_canvases` slot. It MUST match one declared `states[].state_id` (semantic validators resolve it). Omit for ordinary image slots.'
        ),
    ] = None
    breakpoint_id: Annotated[
        str | None,
        Field(
            description='Binding used only when this image populates a `seller_rendered_stateful_display` `state_canvases` slot. It MUST match one breakpoint declared on the selected state (semantic validators resolve it). Omit for ordinary image slots.'
        ),
    ] = None
    focal_point: Annotated[
        list[FocalPointItem] | None,
        Field(
            description="Normalized `[x, y]` coordinates (0–1 from top-left) of the image's visual anchor. Seller-side renderers crop toward the focal point when deriving renditions across breakpoints and aspect ratios; absent, cropping falls back to center-weighted defaults.",
            max_length=2,
            min_length=2,
        ),
    ] = None
    format: Annotated[
        str | None, Field(description='Image file format (jpg, png, gif, webp, etc.)')
    ] = None
    alt_text: Annotated[str | None, Field(description='Alternative text for accessibility')] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var alt_text : str | None

var asset_type : Literal['image']

var breakpoint_id : str | None

var file_size_bytes : int | None

var focal_point : list[FocalPointItem] | None

var format : str | None

var height : int

var model_config

var pixel_ratio : float | None

var provenance : Provenance | None

var state_id : str | None

var url : pydantic.networks.AnyUrl

var width : int

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Input (**data: Any)

Expand source code

class Input(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    name: Annotated[str, Field(description='Human-readable name for this preview variant')]
    macros: Annotated[
        dict[str, str] | None, Field(description='Macro values to apply for this preview')
    ] = None
    context_description: Annotated[
        str | None,
        Field(description='Natural language description of the context for AI-generated content'),
    ] = 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

Class variables

var context_description : str | None

var macros : dict[str, str] | None

var model_config

var name : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Issue (**data: Any)

Expand source code

class Issue(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pointer: Annotated[
        str,
        Field(
            description="RFC 6901 JSON Pointer to the offending field in the request payload (e.g., '/packages/0/targeting/geo_countries/2'). Format chosen to match Ajv's native validation output (`instancePath`); standardized and unambiguous on keys containing `/` or `~`. NOTE: this differs from the legacy top-level `field` which uses JSONPath-lite (`packages[0].targeting.geo_countries[2]`). When sellers populate `field` from `issues[0].pointer` for backward compatibility (see `field` description), they MUST translate the format — `/packages/0/x` → `packages[0].x`. Future major versions will deprecate `field` in favor of `issues[].pointer`."
        ),
    ]
    message: Annotated[
        str,
        Field(description='Human-readable description of why this specific field was rejected.'),
    ]
    keyword: Annotated[
        str,
        Field(
            description="Schema keyword that rejected the payload, drawn from the JSON Schema vocabulary (e.g., 'required', 'type', 'format', 'enum', 'pattern', 'minimum', 'maxLength'). Matches the keyword names emitted by JSON Schema validators (Ajv, jsonschema, etc.) so agents can pattern-match on rejection class without parsing message text. Implementers SHOULD use the validator's native keyword name; do not invent custom values here."
        ),
    ]
    schemaPath: Annotated[
        str | None,
        Field(
            description="Optional. JSON Schema tree path of the rejecting keyword (e.g. '#/properties/packages/items/oneOf/1'). 3.1+ consumers SHOULD prefer `schema_id`; `schemaPath` is retained for 3.0.x compatibility (renamed to `schema_path` in a future major). See error-handling.mdx for the validator-internals production-emit rules."
        ),
    ] = None
    schema_id: Annotated[
        str | None,
        Field(
            description="Optional. `$id` of the rejecting (sub-)schema (e.g. `/schemas/3.1.0/core/activation-key.json`). MUST resolve to a `$id` published in the spec at the version the seller advertises via `get_adcp_capabilities` — either a deep sub-schema (the typical case) or the response-root `$id` (the bundled-tree fallback for tools served from bundles built before #3868). Sellers MUST NOT emit when the rejection occurred against a private extension, server-only sub-schema, or pre-release element — the public-spec replay rationale only holds when the rejecting element is reachable from the public bundle. Sellers populating `schemaPath` SHOULD also populate `schema_id` when they have it so 3.1+ readers don't get strictly less than 3.0.x readers. See error-handling.mdx for resolution guidance and the bundled-tree caveat."
        ),
    ] = None
    discriminator: Annotated[
        list[DiscriminatorItem] | None,
        Field(
            description="Optional. Const-discriminator property/value pair(s) identifying the variant the validator selected from values present in the payload. Sellers MUST populate only when (a) the rejecting schema is a const-discriminated `oneOf` / `anyOf` and (b) the discriminator property is present in the payload — emission on partial-match inference would fingerprint the seller's validator implementation. MUST omit when zero variants survive. Compound discriminators (e.g. `(type, value_type)`) produce multiple entries ordered by declaration in the rejecting schema's `properties` block. Same private-extensions / version-skew carve-out as `schema_id`. See error-handling.mdx."
        ),
    ] = 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

Class variables

var discriminator : list[DiscriminatorItem] | None

var keyword : str

var message : str

var model_config

var pointer : str

var schemaPath : str | None

var schema_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingIssueState (*args, **kwds)

Expand source code

class IssueState(StrEnum):
    open = 'open'
    acknowledged = 'acknowledged'
    resolved = 'resolved'
    waived = 'waived'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var acknowledged

var open

var resolved

var waived

class JavascriptContent (**data: Any)

Expand source code

class JavascriptAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['javascript'],
        Field(
            description='Discriminator identifying this as a JavaScript asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'javascript'
    content: Annotated[str, Field(description='JavaScript content')]
    module_type: Annotated[
        javascript_module_type.JavascriptModuleType | None,
        Field(description='JavaScript module type'),
    ] = None
    accessibility: Annotated[
        Accessibility | None,
        Field(description='Self-declared accessibility properties for this opaque creative'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var accessibility : Accessibility | None

var asset_type : Literal['javascript']

var content : str

var model_config

var module_type : JavascriptModuleType | None

var provenance : Provenance | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class JavascriptModuleType (*args, **kwds)

Expand source code

class JavascriptModuleType(StrEnum):
    esm = 'esm'
    commonjs = 'commonjs'
    script = 'script'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var commonjs

var esm

var script

class ModuleType (*args, **kwds)

Expand source code

class JavascriptModuleType(StrEnum):
    esm = 'esm'
    commonjs = 'commonjs'
    script = 'script'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var commonjs

var esm

var script

class KellerType (*args, **kwds)

Expand source code

class KellerType(StrEnum):
    master = 'master'
    sub_brand = 'sub_brand'
    endorsed = 'endorsed'
    independent = 'independent'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var endorsed

var independent

var master

var sub_brand

class LandingPageRequirement (*args, **kwds)

Expand source code

class LandingPageRequirement(StrEnum):
    any = 'any'
    retailer_site_only = 'retailer_site_only'
    must_include_retailer = 'must_include_retailer'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var any

var must_include_retailer

var retailer_site_only

class LandingPage (*args, **kwds)

Expand source code

class LandingPageRequirement(StrEnum):
    any = 'any'
    retailer_site_only = 'retailer_site_only'
    must_include_retailer = 'must_include_retailer'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var any

var must_include_retailer

var retailer_site_only

class ListAccountChangesRequest (**data: Any)

Expand source code

class ListAccountChangesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference,
        Field(
            description='Account whose change feed to read. The resolved account and returned cursor are bound to the authenticated principal.'
        ),
    ]
    cursor: Annotated[
        str | None,
        Field(
            description='Opaque checkpoint returned by a prior call using the same authenticated principal, authorization scope epoch, account, and normalized filters. Returns changes strictly after the scanned high-water represented by this value. Sellers MUST reject reuse under a different principal, account, or filter set with INVALID_REQUEST at field cursor; an authorization-scope epoch change returns CURSOR_EXPIRED and requires snapshot rebootstrap.',
            max_length=4096,
            min_length=1,
        ),
    ] = None
    starting_position: Annotated[
        StartingPosition | None,
        Field(
            description='Initial position when cursor is absent. Mutually exclusive with cursor; sellers enforce this semantic rule at runtime so the emitted MCP input schema can remain a plain root object. earliest intentionally begins at the oldest retained change. latest returns a checkpoint at the current seller-ingestion high-water and is used before a race-free snapshot bootstrap.'
        ),
    ] = StartingPosition.earliest
    resource_types: Annotated[
        list[ResourceType] | None,
        Field(
            description='Optional exact resource-type filter. The cursor is bound to the normalized filter. Unknown resource types are allowed for forward compatibility.',
            max_length=50,
            min_length=1,
        ),
    ] = None
    max_results: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum changes to return. Sellers still scan through nonmatching records and advance the returned cursor.',
            ge=1,
            le=100,
        ),
    ] = 50
    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 account : AccountReference1 | AccountReference2

var context : ContextObject | None

var cursor : str | None

var ext : ExtensionObject | None

var max_results : int | None

var model_config

var resource_types : list[ResourceType] | None

var starting_position : StartingPosition | 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 ListAccountChangesResponse (**data: Any)

Expand source code

class ListAccountChangesResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    changes: Annotated[
        list[account_change.AccountChange] | None,
        Field(
            description='Matching changes in oldest-first total account order. Timestamps are descriptive and do not define this order.',
            max_length=100,
        ),
    ] = None
    cursor: Annotated[
        str | None,
        Field(
            description='Opaque checkpoint strictly after the high-water scanned by this page. Always persist this value, including when changes is empty or has_more is false. A filtered empty page still advances past scanned nonmatching records.',
            max_length=4096,
            min_length=1,
        ),
    ] = None
    has_more: Annotated[
        StrictBool | None,
        Field(
            description='True when more retained matching changes were available at generation time. False means caught up to seller ingestion, not necessarily to an unavailable or delayed connected source.'
        ),
    ] = None
    available_since: Annotated[
        AwareDatetime | None,
        Field(
            description='Oldest time for which the seller currently retains change records for this account and caller. The capability guarantees at least 90 days after adoption; pre-adoption history is not fabricated.'
        ),
    ] = None
    generated_at: Annotated[
        AwareDatetime | None,
        Field(
            description='Seller time when this page and its source-coverage watermarks were generated.'
        ),
    ] = None
    source_coverage: Annotated[
        list[SourceCoverageItem] | None,
        Field(
            description='Account-specific feed and connector coverage. Buyers use this to distinguish feed catch-up from upstream freshness. Omission means no additional connected-source coverage is declared.',
            max_length=50,
        ),
    ] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    status: Status22

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> ListAccountChangesResponse:
        # ``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 (('status', 'changes', 'cursor', 'has_more', 'available_since', 'generated_at'), ('status', 'adcp_error', 'errors'),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'ListAccountChangesResponse requires at least one of these field groups: status+changes+cursor+has_more+available_since+generated_at | status+adcp_error+errors'
        )

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 available_since : pydantic.types.AwareDatetime | None

var changes : list[AccountChange] | None

var context : ContextObject | None

var cursor : str | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var generated_at : pydantic.types.AwareDatetime | None

var has_more : bool | None

var model_config

var source_coverage : list[SourceCoverageItem] | None

var status : Status22

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 ListAccountsRequest (**data: Any)

Expand source code

class ListAccountsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Optional exact account filter. Use `account_id` to retrieve one known seller/storefront account, or the complete natural key (`brand` + `operator` + optional `operator_unit`, fixed `currency`, buyer-selected account `timezone`, and `sandbox`) for buyer-declared accounts. When present, the seller returns only matching accounts visible to the authenticated caller.'
        ),
    ] = None
    status: Annotated[
        Status | None,
        Field(description='Filter accounts by status. Omit to return accounts in all statuses.'),
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    sandbox: Annotated[
        StrictBool | None,
        Field(
            description='Filter by sandbox status. true returns only sandbox accounts, false returns only production accounts. Omit to return all accounts. Primarily used with account-id namespaces where sandbox accounts are pre-existing test accounts on the platform.'
        ),
    ] = None
    include_webhook_activity: Annotated[
        StrictBool | None,
        Field(
            description='When true, request recent webhook delivery attempts for each returned account in account.webhook_activity[]. Sellers MAY omit webhook_activity if they do not expose this debug log; when present, three-state semantics match the shared webhook_activity[] contract.'
        ),
    ] = False
    webhook_activity_limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of webhook_activity[] records to return per account when include_webhook_activity is true.',
            ge=1,
            le=200,
        ),
    ] = 50
    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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var include_webhook_activity : bool | None

var model_config

var pagination : PaginationRequest | None

var sandbox : bool | None

var status : Status | None

var webhook_activity_limit : int | 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 ListAccountsResponse (**data: Any)

Expand source code

class ListAccountsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    accounts: Annotated[
        list[account_with_authorization.AccountWithAuthorization],
        Field(
            description='Array of accounts accessible to the authenticated agent. Each entry is the full Account object plus optional authorization. Buyer-declared entries include brand, operator, and any operator_unit, fixed currency, buyer-selected account timezone, and sandbox qualifiers so the natural AccountRef round-trips after a cold start.'
        ),
    ]
    errors: Annotated[
        list[error.Error] | None, Field(description='Task-specific errors and warnings')
    ] = None
    pagination: pagination_response.PaginationResponse | None = 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.

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 accounts : list[AccountWithAuthorization]

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var model_config

var pagination : PaginationResponse | 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 ListCollectionListsRequest (**data: Any)

Expand source code

class ListCollectionListsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Filter to lists owned by this account. When omitted, returns lists across all accounts accessible to the authenticated agent.'
        ),
    ] = None
    name_contains: Annotated[
        str | None, Field(description='Filter to lists whose name contains this string')
    ] = None
    pagination: pagination_request.PaginationRequest | None = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var name_contains : str | None

var pagination : PaginationRequest | 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 ListCollectionListsResponse (**data: Any)

Expand source code

class ListCollectionListsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    lists: Annotated[
        list[collection_list.CollectionList],
        Field(description='Array of collection lists (metadata only, not resolved collections)'),
    ]
    pagination: pagination_response.PaginationResponse | None = 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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var lists : list[CollectionList]

var model_config

var pagination : PaginationResponse | 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 ListContentStandardsRequest (**data: Any)

Expand source code

class ListContentStandardsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    channels: Annotated[
        list[channels_1.MediaChannel] | None, Field(description='Filter by channel', min_length=1)
    ] = None
    languages: Annotated[
        list[str] | None, Field(description='Filter by BCP 47 language tags', min_length=1)
    ] = None
    countries: Annotated[
        list[str] | None,
        Field(description='Filter by ISO 3166-1 alpha-2 country codes', min_length=1),
    ] = None
    pagination: pagination_request.PaginationRequest | None = 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 channels : list[MediaChannel] | None

var context : ContextObject | None

var countries : list[str] | None

var ext : ExtensionObject | None

var languages : list[str] | None

var model_config

var pagination : PaginationRequest | 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 ListContentStandardsResponse (**data: Any)

Expand source code

class ListContentStandardsResponse(AdcpResponse, ResponseArmDispatchMixin, AdcpVersionEnvelope, ProtocolEnvelope):
    """Constructible compatibility base for generated response arms."""

    @classmethod
    def _response_arm_models(cls) -> tuple[type[ListContentStandardsResponse], ...]:
        return (
            ListContentStandardsResponse1,
            ListContentStandardsResponse2,
        )

Constructible compatibility base for generated response arms.

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
• ResponseArmDispatchMixin
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• ListContentStandardsResponse1
• ListContentStandardsResponse2

Class variables

var model_config

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• ResponseArmDispatchMixin:
  • model_validate
  • model_validate_json
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class ListContentStandardsResponse1 (**data: Any)

Expand source code

class ListContentStandardsResponse1(ListContentStandardsResponse):
    standards: Annotated[
        list[content_standards.ContentStandards],
        Field(description='Array of content standards configurations matching the filter criteria'),
    ]
    pagination: pagination_response.PaginationResponse | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var pagination : PaginationResponse | None

var standards : list[ContentStandards]

class ListContentStandardsSuccessResponse (**data: Any)

Expand source code

class ListContentStandardsResponse1(ListContentStandardsResponse):
    standards: Annotated[
        list[content_standards.ContentStandards],
        Field(description='Array of content standards configurations matching the filter criteria'),
    ]
    pagination: pagination_response.PaginationResponse | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var pagination : PaginationResponse | None

var standards : list[ContentStandards]

Inherited members

• ListContentStandardsResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class ListContentStandardsErrorResponse (**data: Any)

Expand source code

class ListContentStandardsResponse2(ListContentStandardsResponse):
    errors: list[error.Error]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

Inherited members

• ListContentStandardsResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class LegacyListCreativeFormatsRequest (**data: Any)

Expand source code

class ListCreativeFormatsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Return only these specific named-format IDs (for example, from a 3.x get_products response). Use canonical-format discovery in 4.0.',
            min_length=1,
        ),
    ] = None
    asset_types: Annotated[
        list[asset_content_type.AssetContentType] | None,
        Field(
            description="Filter to formats that include these asset types. For third-party tags, search for 'html' or 'javascript'. For published-post reference formats, search for 'published_post'. E.g., ['image', 'text'] returns formats with images and text, ['javascript'] returns formats accepting JavaScript tags.",
            min_length=1,
        ),
    ] = None
    max_width: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum width in pixels (inclusive). Returns formats where ANY render has width <= this value. For multi-render formats, matches if at least one render fits.'
        ),
    ] = None
    max_height: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum height in pixels (inclusive). Returns formats where ANY render has height <= this value. For multi-render formats, matches if at least one render fits.'
        ),
    ] = None
    min_width: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum width in pixels (inclusive). Returns formats where ANY render has width >= this value.'
        ),
    ] = None
    min_height: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum height in pixels (inclusive). Returns formats where ANY render has height >= this value.'
        ),
    ] = None
    is_responsive: Annotated[
        StrictBool | None,
        Field(
            description='Filter for responsive formats that adapt to container size. When true, returns formats without fixed dimensions.'
        ),
    ] = None
    name_search: Annotated[
        str | None, Field(description='Search for formats by name (case-insensitive partial match)')
    ] = None
    publisher_domain: Annotated[
        str | None,
        Field(
            deprecated=True,
            description="Deprecated compatibility filter for older 3.x callers. A compatibility implementation MAY project publisher-origin or community-catalog declarations obtained through the registry publisher lookup, but MUST NOT synthesize a publisher catalog from seller products. New callers use `GET /api/registry/publisher?domain=...` for publisher acceptance and `get_products` for this seller's deliverability. The pattern below is a syntactic floor, not an SSRF guard.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    property_id: Annotated[
        property_id_1.PropertyId | None,
        Field(
            description="Filter to formats supported on the named property within the publisher's catalog. Resolves to a property in the publisher's `adagents.json` `properties[]`; the agent returns only `formats[]` entries whose `applies_to_property_ids` includes this property (or entries with no scope, which apply to all properties). Typically used in combination with `publisher_domain`."
        ),
    ] = None
    wcag_level: Annotated[
        wcag_level_1.WcagLevel | None,
        Field(
            description='Filter to formats that meet at least this WCAG conformance level (A < AA < AAA)'
        ),
    ] = None
    disclosure_positions: Annotated[
        list[disclosure_position.DisclosurePosition] | None,
        Field(
            description="Filter to formats that support all of these disclosure positions. When a format has disclosure_capabilities, match against those positions. Otherwise fall back to supported_disclosure_positions. Use to find formats compatible with a brief's compliance requirements.",
            min_length=1,
        ),
    ] = None
    disclosure_persistence: Annotated[
        list[disclosure_persistence_1.DisclosurePersistence] | None,
        Field(
            description='Filter to formats where each requested persistence mode is supported by at least one position in disclosure_capabilities. Different positions may satisfy different modes. Use to find formats compatible with jurisdiction-specific persistence requirements (e.g., continuous for EU AI Act).',
            min_length=1,
        ),
    ] = None
    output_format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            description="Filter to formats whose output_format_ids includes any of these format IDs. Returns formats that can produce these outputs — inspect each result's input_format_ids to see what inputs they accept.",
            min_length=1,
        ),
    ] = None
    input_format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            description="Filter to formats whose input_format_ids includes any of these format IDs. Returns formats that accept these creatives as input — inspect each result's output_format_ids to see what they can produce.",
            min_length=1,
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            deprecated=True,
            description="**DEPRECATED with `list_creative_formats` in 3.2. Removed at 4.0.** Use `get_products` with `account`; each `Product.format_options[]` lists the formats this seller can deliver for that account. *Legacy 3.x behavior:* scopes the returned formats to this account. Sellers that keep account-specific format catalogs (including sandbox accounts) return that account's formats; sellers with a single catalog MAY ignore this field.",
        ),
    ] = None
    pagination: pagination_request.PaginationRequest | None = 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 asset_types : list[AssetContentType] | None

var context : ContextObject | None

var disclosure_persistence : list[DisclosurePersistence] | None

var disclosure_positions : list[DisclosurePosition] | None

var ext : ExtensionObject | None

var input_format_ids : list[FormatReferenceStructuredObject] | None

var is_responsive : bool | None

var max_height : int | None

var max_width : int | None

var min_height : int | None

var min_width : int | None

var model_config

var name_search : str | None

var output_format_ids : list[FormatReferenceStructuredObject] | None

var pagination : PaginationRequest | None

var property_id : PropertyId | None

var wcag_level : WcagLevel | None

Instance variables

var account : AccountReference1 | AccountReference2 | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var format_ids : list[FormatReferenceStructuredObject] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var publisher_domain : str | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 LegacyListCreativeFormatsResponse (**data: Any)

Expand source code

class ListCreativeFormatsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    formats: Annotated[
        list[format.Format],
        Field(
            deprecated=True,
            description="Deprecated named-format definitions projected for older 3.x callers. This list is neither the publisher acceptance catalog nor the seller's canonical product deliverability contract.",
        ),
    ]
    source: Annotated[
        Source | None,
        Field(
            deprecated=True,
            description='Deprecated compatibility provenance. `publisher` means publisher-origin catalog; `aao_mirror` means community catalog; `agent_derived` is retained only to parse historical 3.x responses and MUST NOT be produced by a new 3.2 implementation because seller products are not publisher authority.',
        ),
    ] = None
    creative_agents: Annotated[
        list[CreativeAgent] | None,
        Field(
            deprecated=True,
            description="Deprecated recursive discovery projection retained for historical 3.x responses. New buyers query the registry's canonical creative capability index and confirm candidates with get_adcp_capabilities; they do not recursively walk agent-provided lists.",
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(description='Task-specific errors and warnings (e.g., format availability issues)'),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var model_config

var pagination : PaginationResponse | None

var sandbox : bool | None

var status : TaskStatus | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var creative_agents : list[CreativeAgent] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var formats : list[Format]

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var source : Source | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 ListCreativesRequest (**data: Any)

Expand source code

class ListCreativesRequest(_LegacyListCreativesRequest, CanonicalBoundaryModel):
    """Canonical creative read request with legacy field selection rejected."""

    filters: CreativeFilters | None = None

    @field_validator("fields")
    @classmethod
    def _reject_legacy_fields(cls, value: Any) -> Any:
        if value and any(
            is_legacy_creative_identity_key(getattr(item, "value", item)) for item in value
        ):
            raise ValueError(
                "format_id and format_ids are unavailable on the canonical list_creatives API"
            )
        return value

Canonical creative read request with legacy field selection rejected.

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

• ListCreativesRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var filters : CreativeFilters | None

var model_config

class LegacyListCreativesRequest (**data: Any)

Expand source code

class ListCreativesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    filters: creative_filters.CreativeFilters | None = None
    sort: Annotated[Sort | None, Field(description='Sorting parameters')] = None
    pagination: pagination_request.PaginationRequest | None = None
    include_assignments: Annotated[
        StrictBool | None, Field(description='Include package assignment information in response')
    ] = True
    assignment_projection: Annotated[
        AssignmentProjection | None,
        Field(
            description='Controls nested assigned_packages projection when assignments are included. all returns up to assignment_limit active assignments per creative. matching returns only assignments matching filters.indicator_types and requires that filter. Use matching for compact indicator discovery; get_media_buys remains the complete authoritative repair path when assignments_truncated is true.'
        ),
    ] = AssignmentProjection.all
    assignment_limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum assigned_packages rows returned per creative. Sellers MUST set assignments.assignments_truncated when additional qualifying rows exist.',
            ge=1,
            le=200,
        ),
    ] = 50
    include_snapshot: Annotated[
        StrictBool | None,
        Field(
            description='Include a lightweight delivery snapshot per creative (lifetime impressions and last-served date). For detailed performance analytics, use get_creative_delivery.'
        ),
    ] = False
    include_items: Annotated[
        StrictBool | None,
        Field(description='Include items for multi-asset formats like carousels and native ads'),
    ] = False
    include_variables: Annotated[
        StrictBool | None,
        Field(
            description='Include dynamic content variable definitions (DCO slots) for each creative'
        ),
    ] = False
    include_pricing: Annotated[
        StrictBool | None,
        Field(
            description='Include pricing_options on each creative. Requires account to be provided. When false or omitted, pricing is not computed.'
        ),
    ] = False
    include_purged: Annotated[
        StrictBool | None,
        Field(
            description="Include soft-purged creative tombstones in the result set. When true, creatives destroyed via `creative.purged` with `purge_kind: soft` surface as tombstone records carrying `purged: true`, `purged_at`, and the purge reason — within the seller's webhook activity retention window (30 days from `purged_at`, MUST match `webhook-activity-record` retention). Hard-purged creatives MUST NOT appear regardless of this flag. When false or omitted, the result set excludes all purged creatives — same default as today."
        ),
    ] = False
    include_webhook_activity: Annotated[
        StrictBool | None,
        Field(
            description='Include recent webhook activity per creative. When true, each returned creative carries a `webhook_activity[]` array of the most recent fires scoped to that creative — `creative.status_changed` and `creative.purged` deliveries. Adoption of the `webhook_activity[]` pattern per `snapshot-and-log.mdx § Webhook activity log pattern`. Retention is 30 days from `completed_at` (MUST). Three-state presence applies: omitted = seller does not surface; `[]` = persists but no recent fires; non-empty = actual records.'
        ),
    ] = False
    webhook_activity_limit: Annotated[
        SchemaInt | None,
        Field(
            description="Maximum number of `webhook_activity[]` records to return per creative. Only meaningful when `include_webhook_activity: true`. Sellers MUST respect the cap; structural enforcement is provided by the response schema's `maxItems: 200` on the array.",
            ge=1,
            le=200,
        ),
    ] = 50
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account reference for pricing and access. When provided with include_pricing, the agent returns pricing_options from this account's rate card on each creative."
        ),
    ] = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific fields to include in response (omit for all fields). The 'concept' value returns both concept_id and concept_name. `format_id` is a deprecated 3.x compatibility projection; new integrations request `format_kind` and `format_option_ref`. Selecting localization automatically includes creative_id, status, assets, the selected format identity, and localization_unavailable when applicable. Selecting rights_attestation_evaluations automatically includes rights so each seller-produced result can be reconciled with the exact retained constraint and reference.",
            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

Subclasses

• ListCreativesRequest

Class variables

var account : AccountReference1 | AccountReference2 | None

var assignment_limit : int | None

var assignment_projection : AssignmentProjection | None

var context : ContextObject | None

var ext : ExtensionObject | None

var fields : list[Field1] | None

var filters : CreativeFilters | None

var include_assignments : bool | None

var include_items : bool | None

var include_pricing : bool | None

var include_purged : bool | None

var include_snapshot : bool | None

var include_variables : bool | None

var include_webhook_activity : bool | None

var model_config

var pagination : PaginationRequest | None

var sort : Sort | None

var webhook_activity_limit : int | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 ListCreativesResponse (**data: Any)

Expand source code

class ListCreativesResponse(_LegacyListCreativesResponse, CanonicalBoundaryModel):
    """Canonical creative listing; rows are canonical listed creatives."""

    creatives: list[Creative]

Canonical creative listing; rows are canonical listed creatives.

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

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

Class variables

var creatives : list[Creative]

var model_config

class LegacyListCreativesResponse (**data: Any)

Expand source code

class ListCreativesResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    query_summary: Annotated[
        QuerySummary, Field(description='Summary of the query that was executed')
    ]
    pagination: pagination_response.PaginationResponse
    creatives: Annotated[
        Sequence[Creative], Field(description='Array of creative assets matching the query')
    ]
    format_summary: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-zA-Z0-9_-]+$')], SchemaInt] | None,
        Field(
            description='Breakdown of creatives by canonical format kind. Keys SHOULD be `format_kind` values; an implementation may append a stable option suffix when separate product or publisher options must be distinguished.'
        ),
    ] = None
    status_summary: Annotated[
        StatusSummary | None, Field(description='Breakdown of creatives by status')
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(description='Task-specific errors (e.g., invalid filters, account not found)'),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = 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.

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

Subclasses

• ListCreativesResponse

Class variables

var context : ContextObject | None

var creatives : Sequence[Creative]

var errors : list[Error] | None

var ext : ExtensionObject | None

var format_summary : dict[str, int] | None

var model_config

var pagination : PaginationResponse

var query_summary : QuerySummary

var sandbox : bool | None

var status : TaskStatus | None

var status_summary : StatusSummary | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 ListProductsRequest (**data: Any)

Expand source code

class ListProductsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str | None,
        Field(
            description='Optional replay key accepted uniformly on read calls.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    context_id: Annotated[
        str | None,
        Field(
            description='MCP compatibility field: servers ignore this value; A2A uses transport-native Message/Task contextId.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    governance_context: Annotated[str | None, Field(max_length=4096, min_length=1)] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Uniform per-call envelope field accepted for SDK compatibility. This does not register a wholesale feed subscription; durable product.* and wholesale_feed.bulk_change subscribers are registered through sync_accounts notification_configs.'
        ),
    ] = None
    account: Annotated[
        canonical_account_ref.CanonicalAccountReference | None,
        Field(
            description='Account scope for pricing and availability. A natural-key account is the single brand source and MUST NOT be combined with top-level brand.'
        ),
    ] = None
    brand: brand_key.BrandKey | None = None
    criteria: product_discovery_criteria.ProductDiscoveryCriteria | None = None
    fields: product_fields.ProductResponseFields | None = None
    cursor: Annotated[str | None, Field(min_length=1)] = None
    max_results: Annotated[SchemaInt | None, Field(ge=1, le=100)] = 25
    if_feed_version: Annotated[
        str | None,
        Field(
            description='Opaque feed version returned by a prior list_products response or wholesale product-feed webhook for the same cache scope and canonicalized selection. Used for repair and conditional reconciliation, not routine polling when webhooks are active.'
        ),
    ] = None
    if_pricing_version: Annotated[
        str | None,
        Field(
            description='Opaque pricing version returned by a prior list_products response. Valid only with if_feed_version.'
        ),
    ] = 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 account : CanonicalAccountReference1 | CanonicalAccountReference2 | None

var brand : BrandKey | None

var context : ContextObject | None

var context_id : str | None

var criteria : ProductDiscoveryCriteria | None

var cursor : str | None

var fields : ProductResponseFields | None

var governance_context : str | None

var idempotency_key : str | None

var if_feed_version : str | None

var if_pricing_version : str | None

var max_results : int | None

var model_config

var push_notification_config : PushNotificationConfig | 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 ListPropertyListsRequest (**data: Any)

Expand source code

class ListPropertyListsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Filter to lists owned by this account. When omitted, returns lists across all accounts accessible to the authenticated agent.'
        ),
    ] = None
    name_contains: Annotated[
        str | None, Field(description='Filter to lists whose name contains this string')
    ] = None
    pagination: pagination_request.PaginationRequest | None = 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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var name_contains : str | None

var pagination : PaginationRequest | 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 ListPropertyListsResponse (**data: Any)

Expand source code

class ListPropertyListsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    lists: Annotated[
        list[property_list.PropertyList],
        Field(description='Array of property lists (metadata only, not resolved properties)'),
    ]
    pagination: pagination_response.PaginationResponse | None = 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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var lists : list[PropertyList]

var model_config

var pagination : PaginationResponse | 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 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.

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 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.

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 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 ListTransformersRequest (**data: Any)

Expand source code

class ListTransformersRequestCreativeAgent(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    transformer_ids: Annotated[
        list[str] | None,
        Field(description='Return only these specific transformer IDs.', min_length=1),
    ] = None
    input_format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Filter by legacy named input formats. Use input_format_kinds.',
            min_length=1,
        ),
    ] = None
    output_format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Filter by legacy named output formats. Use output_capability_ids.',
            min_length=1,
        ),
    ] = None
    input_format_kinds: Annotated[
        list[str] | None,
        Field(
            description='Filter to transformers whose canonical input_formats include any of these canonical format kinds.',
            min_length=1,
        ),
    ] = None
    output_capability_ids: Annotated[
        list[OutputCapabilityId] | None,
        Field(
            description='Filter to transformers that can produce any of these canonical creative.supported_formats capability IDs.',
            min_length=1,
        ),
    ] = None
    name_search: Annotated[
        str | None,
        Field(description='Search transformers by name (case-insensitive partial match).'),
    ] = None
    brief: Annotated[
        str | None,
        Field(
            description="Natural-language brief used to rank and filter transformers (and their enumerable option values when expanded) — e.g. 'warm female Spanish-language voiceover'. Curates to intent rather than returning the full set, the way get_products curates inventory."
        ),
    ] = None
    expand_params: Annotated[
        list[str] | None,
        Field(
            description="Param `field` names for which to return the FIRST page of account-scoped option VALUES inline on each transformer's `params[].options[]`. Omit to return param descriptors without enumerated values (the lean default). When a param's options are truncated, its `params[].options_cursor` is set — fetch the next page via `expand_pagination` (below).",
            min_length=1,
        ),
    ] = None
    expand_pagination: Annotated[
        list[ExpandPaginationItem] | None,
        Field(
            description="Fetch the NEXT page of a specific param's account-scoped options, using the `options_cursor` a prior response returned for that `(transformer, param)`. Scoped per `(transformer_id, field)` so multiple params can be paged independently. Use this instead of `expand_params` once you hold a cursor.",
            min_length=1,
        ),
    ] = None
    include_pricing: Annotated[
        StrictBool | None,
        Field(description='Include `pricing_options` on each transformer. Requires `account`.'),
    ] = False
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account reference. Transformers are account-scoped — the returned set, the enumerable option values, and (with include_pricing) the rate card are all resolved for this credential.'
        ),
    ] = None
    pagination: pagination_request.PaginationRequest | None = 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 account : AccountReference1 | AccountReference2 | None

var brief : str | None

var context : ContextObject | None

var expand_pagination : list[ExpandPaginationItem] | None

var expand_params : list[str] | None

var ext : ExtensionObject | None

var include_pricing : bool | None

var input_format_ids : list[FormatReferenceStructuredObject] | None

var input_format_kinds : list[str] | None

var model_config

var name_search : str | None

var output_capability_ids : list[OutputCapabilityId] | None

var output_format_ids : list[FormatReferenceStructuredObject] | None

var pagination : PaginationRequest | None

var transformer_ids : list[str] | 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 ListTransformersResponse (**data: Any)

Expand source code

class ListTransformersResponseCreativeAgent(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    transformers: Annotated[
        list[transformer.Transformer],
        Field(description='Transformer descriptors matching the query.'),
    ]
    errors: Annotated[
        list[error.Error] | None, Field(description='Task-specific errors and warnings.')
    ] = None
    pagination: pagination_response.PaginationResponse | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var model_config

var pagination : PaginationResponse | None

var transformers : list[Transformer]

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 LogEventRequest (**data: Any)

Expand source code

class LogEventRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    event_source_id: Annotated[
        str, Field(description='Event source configured on the account via sync_event_sources')
    ]
    test_event_code: Annotated[
        str | None,
        Field(
            description="Test event code for validation without affecting production data. Events with this code appear in the platform's test events UI."
        ),
    ] = None
    events: Annotated[
        list[event.Event], Field(description='Events to log', max_length=10000, min_length=1)
    ]
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate event logging on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 event_source_id : str

var events : list[Event]

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var test_event_code : str | 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 LogEventResponse1 (**data: Any)

Expand source code

class LogEventResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    events_received: Annotated[int, Field(ge=0)]
    events_processed: Annotated[int, Field(ge=0)]
    partial_failures: list[PartialFailure] | None = None
    warnings: list[str] | None = None
    match_quality: Annotated[float, Field(ge=0, le=1)] | None = None
    sandbox: bool | None = 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.

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 context : ContextObject | None

var events_processed : int

var events_received : int

var ext : ExtensionObject | None

var match_quality : float | None

var model_config

var partial_failures : list[PartialFailure] | None

var sandbox : bool | None

var warnings : list[str] | None

class LogEventSuccessResponse (**data: Any)

Expand source code

class LogEventResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    events_received: Annotated[int, Field(ge=0)]
    events_processed: Annotated[int, Field(ge=0)]
    partial_failures: list[PartialFailure] | None = None
    warnings: list[str] | None = None
    match_quality: Annotated[float, Field(ge=0, le=1)] | None = None
    sandbox: bool | None = 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.

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 context : ContextObject | None

var events_processed : int

var events_received : int

var ext : ExtensionObject | None

var match_quality : float | None

var model_config

var partial_failures : list[PartialFailure] | None

var sandbox : bool | None

var warnings : list[str] | 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 LogEventErrorResponse (**data: Any)

Expand source code

class LogEventResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 Logo (**data: Any)

Expand source code

class Logo(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    url: AnyUrl
    orientation: Literal['square', 'horizontal', 'vertical', 'stacked'] | None = None
    background: Literal['dark-bg', 'light-bg', 'transparent-bg'] | None = None
    variant: Literal['primary', 'secondary', 'icon', 'wordmark', 'full-lockup'] | None = None
    tags: list[str] | None = None
    usage: str | None = None
    width: int | None = None
    height: int | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var background : Literal['dark-bg', 'light-bg', 'transparent-bg'] | None

var height : int | None

var model_config

var orientation : Literal['square', 'horizontal', 'vertical', 'stacked'] | None

var tags : list[str] | None

var url : pydantic.networks.AnyUrl

var usage : str | None

var variant : Literal['primary', 'secondary', 'icon', 'wordmark', 'full-lockup'] | None

var width : int | None

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class MacroResolutionFailedDetails (**data: Any)

Expand source code

class MacroResolutionFailedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    macro_resolution_results: Annotated[
        list[macro_resolution_result.MacroResolutionResult], Field(min_length=1)
    ]

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

Class variables

var macro_resolution_results : list[MacroResolutionResult]

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class V1CanonicalMapping (**data: Any)

Expand source code

class Mapping(AdCPBaseModel):
    v1_pattern: Annotated[
        V1Pattern | V1Pattern1,
        Field(description='Match pattern. Carries either format_id_glob OR structural, not both.'),
    ]
    v2: V2
    deprecated: Annotated[
        StrictBool | None,
        Field(
            description='When true, this mapping is retained for backward-compatibility but should not be used for new mappings. SDKs SHOULD emit lint warnings when matching a deprecated entry.'
        ),
    ] = False
    notes: Annotated[
        str | None,
        Field(description='Optional human-readable explanation, examples, or rationale.'),
    ] = 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

Class variables

var deprecated : bool | None

var model_config

var notes : str | None

var v1_pattern : V1Pattern | V1Pattern1

var v2 : V2

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MarkdownAsset (**data: Any)

Expand source code

class MarkdownAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['markdown'],
        Field(
            description='Discriminator identifying this as a markdown asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'markdown'
    content: Annotated[
        str,
        Field(
            description='Markdown content following CommonMark spec with optional GitHub Flavored Markdown extensions'
        ),
    ]
    language: Annotated[
        str | None,
        Field(
            description='Optional language claim for this markdown. In a materialized creative localization variant, localized-creative-asset.json requires this value to use /schemas/core/locale-tag.json and conformance requires exact equality with the enclosing variant locale. General non-localized assets retain the legacy unconstrained string for compatibility.'
        ),
    ] = None
    markdown_flavor: Annotated[
        markdown_flavor_1.MarkdownFlavor | None,
        Field(
            description='Markdown flavor used. CommonMark for strict compatibility, GFM for tables/task lists/strikethrough.'
        ),
    ] = markdown_flavor_1.MarkdownFlavor.commonmark
    allow_raw_html: Annotated[
        StrictBool | None,
        Field(
            description='Whether raw HTML blocks are allowed in the markdown. False recommended for security.'
        ),
    ] = False

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

Class variables

var allow_raw_html : bool | None

var asset_type : Literal['markdown']

var content : str

var language : str | None

var markdown_flavor : MarkdownFlavor | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MarkdownFlavor (*args, **kwds)

Expand source code

class MarkdownFlavor(StrEnum):
    commonmark = 'commonmark'
    gfm = 'gfm'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var commonmark

var gfm

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.

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

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 MeasurementPeriod (**data: Any)

Expand source code

class MeasurementPeriod(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    start: Annotated[
        AwareDatetime, Field(description='ISO 8601 start timestamp for measurement period')
    ]
    end: Annotated[
        AwareDatetime, Field(description='ISO 8601 end timestamp for measurement period')
    ]

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

Class variables

var end : pydantic.types.AwareDatetime

var model_config

var start : pydantic.types.AwareDatetime

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MediaBuy (**data: Any)

Expand source code

class MediaBuy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buy_id: Annotated[str, Field(description="Seller's unique identifier for the media buy")]
    name: Annotated[
        str | None,
        Field(
            description='Human-readable name for this media buy, shared by buyer and seller for trafficking UI display and operational communication. Sellers MUST include the persisted name on read surfaces such as get_media_buys when the media buy was created through AdCP with name. Sellers MAY omit name for media buys created outside AdCP or created without name. This display label is not an identifier or financial reference.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    accepted_proposal_id: Annotated[
        str | None,
        Field(
            description='Current accepted commercial snapshot. Compact-lifecycle buyers pass this ID to refine_proposals after restart or handoff. Updated atomically when an amendment or negotiated cancellation is accepted.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    accepted_proposal_terms_digest: Annotated[
        str | None,
        Field(
            description='Digest of the current accepted proposal commercial_terms, allowing buyers and governance agents to verify the recovered snapshot.',
            pattern='^sha256:[A-Za-z0-9_-]{43}$',
        ),
    ] = None
    account: Annotated[
        account_1.Account | None, Field(description='Account billed for this media buy')
    ] = None
    status: media_buy_status.MediaBuyStatus
    health: Annotated[
        media_buy_health.MediaBuyHealth | None,
        Field(
            description="Aggregate health based on open impairments[]. Orthogonal to status — a paused, pending, or active buy can each be impaired. Defaults to 'ok' when impairments[] is empty."
        ),
    ] = media_buy_health.MediaBuyHealth.ok
    impairments: Annotated[
        list[impairment.Impairment] | None,
        Field(
            description="Open impairments — upstream dependency state changes that affect delivery for at least one package on this buy. Empty when health is 'ok'. Sellers MUST add an entry on next sync/poll response after a referenced resource transitions to an offline state, and MUST remove the entry (flipping health to 'ok' when the array empties) when the resource returns to a serviceable state. Staleness budget: the snapshot MUST reflect the impairment within 5 minutes of impairment.observed_at regardless of buyer poll cadence — sellers cannot rely on rare buyer polls to defer write propagation. See impairment.coherence assertion for the cross-resource invariant."
        ),
    ] = None
    rejection_reason: Annotated[
        str | None,
        Field(
            description="Reason provided by the seller when status is 'rejected'. Present only when status is 'rejected'."
        ),
    ] = None
    confirmed_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when the seller committed to this media buy. May be null until seller commitment occurs in deferred/manual approval flows. Once populated, remains stable through later pause, resume, activation, completion, cancellation, and reporting transitions.'
        ),
    ]
    cancellation: Annotated[
        Cancellation | None,
        Field(description="Cancellation metadata. Present only when status is 'canceled'."),
    ] = None
    total_budget: Annotated[
        StrictFloat, Field(description='Hard aggregate lifetime budget amount', ge=0.0)
    ]
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Current hard aggregate spend ceiling per calendar day. Sellers MUST echo this whenever an aggregate daily cap is set. It bounds total media-buy spend without allocating or reserving spend for packages.',
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Current hard MediaBuy-level cap. Sellers MUST echo it whenever set. Its counter aggregates exposures across all participating packages; each package targeting_overlay.frequency_cap remains independently binding.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='IANA timezone defining the shared calendar-day boundary for every aggregate and package daily cap on this media buy. Sellers MUST echo it whenever any daily cap is set.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description="Single ISO 4217 denomination for total_budget, every package budget/minimum, and every canonical BiddingPolicy monetary field. Every package's selected pricing option MUST declare this currency; packages requiring another currency belong in a separate media buy.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    budget_allocation: Annotated[
        budget_allocation_1.BudgetAllocation | None,
        Field(
            description='Accepted cross-package budget allocation configuration. Omitted means fixed allocation for legacy buys.'
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Aggregate pacing strategy for total_budget across the media-buy flight.'
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Media-buy-authored bidding policy. This is the complete default inherited by packages that omit package.bidding; `{automatic:true}` is an explicit authored automatic policy. In seller-optimized mode, cost_per/roas bind to the primary budget_allocation optimization goal. In fixed mode, inherited cost_per requires compatible package primary-goal result units and inherited roas requires value-bearing primary goals. Monetary fields use media_buy.currency; every affected pricing option MUST declare the same currency. Package overrides are permitted only where advertised; conflicts MUST be rejected atomically with BIDDING_PLACEMENT_CONFLICT.'
        ),
    ] = None
    packages: Annotated[
        list[package.Package], Field(description='Array of packages within this media buy')
    ]
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque media-buy-level correlation data echoed unchanged from the create_media_buy request. Sellers MUST include persisted context on read surfaces such as get_media_buys when the media buy was created through AdCP with context, so buyers can reconcile seller-assigned media_buy_id values with their own tracking state. Sellers MAY omit context for media buys created outside AdCP or created without context. Sellers MUST NOT parse this object for business logic.'
        ),
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description="Per-buy override for who receives the invoice. When provided, the seller invoices this entity instead of the account's default billing_entity. The seller MUST validate the invoice recipient is authorized for this account. When governance_agents are configured, the seller MUST include invoice_recipient in the check_governance request."
        ),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None, Field(description='ISO 8601 timestamp for creative upload deadline')
    ] = None
    revision: Annotated[
        SchemaInt,
        Field(
            description='Monotonically increasing optimistic concurrency token. Incremented on every mutating state change or update; reads, validation-only calls, and exact idempotency replays do not increment it. Callers SHOULD include this in update_media_buy requests intended to change state — when provided, sellers MUST reject with CONFLICT if the revision does not match the current value, and MUST enforce that comparison atomically with the write.',
            ge=1,
        ),
    ]
    created_at: Annotated[AwareDatetime | None, Field(description='Creation timestamp')] = None
    updated_at: Annotated[AwareDatetime | None, Field(description='Last update timestamp')] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var accepted_proposal_id : str | None

var accepted_proposal_terms_digest : str | None

var account : Account | None

var bidding : BiddingPolicy | None

var budget_allocation : BudgetAllocation1 | BudgetAllocation2 | None

var budget_cap_timezone : str | None

var cancellation : Cancellation | None

var confirmed_at : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var created_at : pydantic.types.AwareDatetime | None

var creative_deadline : pydantic.types.AwareDatetime | None

var currency : str | None

var daily_budget_cap : float | None

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var health : MediaBuyHealth | None

var impairments : list[Impairment] | None

var invoice_recipient : BusinessEntity | None

var media_buy_id : str

var model_config

var name : str | None

var pacing : Pacing | None

var packages : list[Package]

var rejection_reason : str | None

var revision : int

var status : MediaBuyStatus

var total_budget : float

var updated_at : pydantic.types.AwareDatetime | None

class CoreMediaBuy (**data: Any)

Expand source code

class MediaBuy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buy_id: Annotated[str, Field(description="Seller's unique identifier for the media buy")]
    name: Annotated[
        str | None,
        Field(
            description='Human-readable name for this media buy, shared by buyer and seller for trafficking UI display and operational communication. Sellers MUST include the persisted name on read surfaces such as get_media_buys when the media buy was created through AdCP with name. Sellers MAY omit name for media buys created outside AdCP or created without name. This display label is not an identifier or financial reference.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    accepted_proposal_id: Annotated[
        str | None,
        Field(
            description='Current accepted commercial snapshot. Compact-lifecycle buyers pass this ID to refine_proposals after restart or handoff. Updated atomically when an amendment or negotiated cancellation is accepted.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    accepted_proposal_terms_digest: Annotated[
        str | None,
        Field(
            description='Digest of the current accepted proposal commercial_terms, allowing buyers and governance agents to verify the recovered snapshot.',
            pattern='^sha256:[A-Za-z0-9_-]{43}$',
        ),
    ] = None
    account: Annotated[
        account_1.Account | None, Field(description='Account billed for this media buy')
    ] = None
    status: media_buy_status.MediaBuyStatus
    health: Annotated[
        media_buy_health.MediaBuyHealth | None,
        Field(
            description="Aggregate health based on open impairments[]. Orthogonal to status — a paused, pending, or active buy can each be impaired. Defaults to 'ok' when impairments[] is empty."
        ),
    ] = media_buy_health.MediaBuyHealth.ok
    impairments: Annotated[
        list[impairment.Impairment] | None,
        Field(
            description="Open impairments — upstream dependency state changes that affect delivery for at least one package on this buy. Empty when health is 'ok'. Sellers MUST add an entry on next sync/poll response after a referenced resource transitions to an offline state, and MUST remove the entry (flipping health to 'ok' when the array empties) when the resource returns to a serviceable state. Staleness budget: the snapshot MUST reflect the impairment within 5 minutes of impairment.observed_at regardless of buyer poll cadence — sellers cannot rely on rare buyer polls to defer write propagation. See impairment.coherence assertion for the cross-resource invariant."
        ),
    ] = None
    rejection_reason: Annotated[
        str | None,
        Field(
            description="Reason provided by the seller when status is 'rejected'. Present only when status is 'rejected'."
        ),
    ] = None
    confirmed_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when the seller committed to this media buy. May be null until seller commitment occurs in deferred/manual approval flows. Once populated, remains stable through later pause, resume, activation, completion, cancellation, and reporting transitions.'
        ),
    ]
    cancellation: Annotated[
        Cancellation | None,
        Field(description="Cancellation metadata. Present only when status is 'canceled'."),
    ] = None
    total_budget: Annotated[
        StrictFloat, Field(description='Hard aggregate lifetime budget amount', ge=0.0)
    ]
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Current hard aggregate spend ceiling per calendar day. Sellers MUST echo this whenever an aggregate daily cap is set. It bounds total media-buy spend without allocating or reserving spend for packages.',
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Current hard MediaBuy-level cap. Sellers MUST echo it whenever set. Its counter aggregates exposures across all participating packages; each package targeting_overlay.frequency_cap remains independently binding.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='IANA timezone defining the shared calendar-day boundary for every aggregate and package daily cap on this media buy. Sellers MUST echo it whenever any daily cap is set.'
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description="Single ISO 4217 denomination for total_budget, every package budget/minimum, and every canonical BiddingPolicy monetary field. Every package's selected pricing option MUST declare this currency; packages requiring another currency belong in a separate media buy.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    budget_allocation: Annotated[
        budget_allocation_1.BudgetAllocation | None,
        Field(
            description='Accepted cross-package budget allocation configuration. Omitted means fixed allocation for legacy buys.'
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Aggregate pacing strategy for total_budget across the media-buy flight.'
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Media-buy-authored bidding policy. This is the complete default inherited by packages that omit package.bidding; `{automatic:true}` is an explicit authored automatic policy. In seller-optimized mode, cost_per/roas bind to the primary budget_allocation optimization goal. In fixed mode, inherited cost_per requires compatible package primary-goal result units and inherited roas requires value-bearing primary goals. Monetary fields use media_buy.currency; every affected pricing option MUST declare the same currency. Package overrides are permitted only where advertised; conflicts MUST be rejected atomically with BIDDING_PLACEMENT_CONFLICT.'
        ),
    ] = None
    packages: Annotated[
        list[package.Package], Field(description='Array of packages within this media buy')
    ]
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque media-buy-level correlation data echoed unchanged from the create_media_buy request. Sellers MUST include persisted context on read surfaces such as get_media_buys when the media buy was created through AdCP with context, so buyers can reconcile seller-assigned media_buy_id values with their own tracking state. Sellers MAY omit context for media buys created outside AdCP or created without context. Sellers MUST NOT parse this object for business logic.'
        ),
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description="Per-buy override for who receives the invoice. When provided, the seller invoices this entity instead of the account's default billing_entity. The seller MUST validate the invoice recipient is authorized for this account. When governance_agents are configured, the seller MUST include invoice_recipient in the check_governance request."
        ),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None, Field(description='ISO 8601 timestamp for creative upload deadline')
    ] = None
    revision: Annotated[
        SchemaInt,
        Field(
            description='Monotonically increasing optimistic concurrency token. Incremented on every mutating state change or update; reads, validation-only calls, and exact idempotency replays do not increment it. Callers SHOULD include this in update_media_buy requests intended to change state — when provided, sellers MUST reject with CONFLICT if the revision does not match the current value, and MUST enforce that comparison atomically with the write.',
            ge=1,
        ),
    ]
    created_at: Annotated[AwareDatetime | None, Field(description='Creation timestamp')] = None
    updated_at: Annotated[AwareDatetime | None, Field(description='Last update timestamp')] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var accepted_proposal_id : str | None

var accepted_proposal_terms_digest : str | None

var account : Account | None

var bidding : BiddingPolicy | None

var budget_allocation : BudgetAllocation1 | BudgetAllocation2 | None

var budget_cap_timezone : str | None

var cancellation : Cancellation | None

var confirmed_at : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var created_at : pydantic.types.AwareDatetime | None

var creative_deadline : pydantic.types.AwareDatetime | None

var currency : str | None

var daily_budget_cap : float | None

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var health : MediaBuyHealth | None

var impairments : list[Impairment] | None

var invoice_recipient : BusinessEntity | None

var media_buy_id : str

var model_config

var name : str | None

var pacing : Pacing | None

var packages : list[Package]

var rejection_reason : str | None

var revision : int

var status : MediaBuyStatus

var total_budget : float

var updated_at : pydantic.types.AwareDatetime | None

class GetMediaBuysMediaBuy (**data: Any)

Expand source code

class MediaBuy(IndicatorBearingResourceState):
    model_config = ConfigDict(
        extra='allow',
    )
    indicator_types_evaluated: Annotated[
        list[IndicatorTypesEvaluatedEnum] | None,
        Field(
            description='Indicator types covered by this snapshot. Required whenever indicators is present. Types omitted from this list remain unknown even when indicators is empty. Every returned indicator.type MUST appear in this list.',
            min_length=1,
        ),
    ] = None
    indicators: Annotated[
        list[Indicator] | None,
        Field(
            description='Current seller assertions for the indicator types and publisher/placement coverage named by the sibling evaluation fields. Omitted means unknown or not evaluated. A present empty array means evaluated with no current assertion for indicator_types_evaluated in the evaluated scope.'
        ),
    ] = None
    media_buy_id: Annotated[str, Field(description="Seller's unique identifier for the media buy")]
    name: Annotated[
        str | None,
        Field(
            description='Persisted human-readable name for this media buy, shared by buyer and seller for trafficking UI display and operational communication. Sellers MUST include name when the media buy was created through AdCP with name. Sellers MAY omit it for media buys created outside AdCP or created without name. This display label is not an identifier or financial reference.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    accepted_proposal_id: Annotated[
        str | None,
        Field(
            description='Current accepted commercial snapshot for compact-lifecycle refinement. Updated atomically when an amendment or negotiated cancellation is accepted.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    accepted_proposal_terms_digest: Annotated[
        str | None,
        Field(
            description='Digest of the current accepted proposal commercial_terms.',
            pattern='^sha256:[A-Za-z0-9_-]{43}$',
        ),
    ] = None
    accepted_proposal: Annotated[
        AcceptedProposal | None,
        Field(
            description='Current accepted compact proposal, including the complete digested commercial envelope. Required whenever accepted_proposal_id is present so restarted SDKs can recover control-versus-refinement routing without reconstructing historical offers.'
        ),
    ] = None
    account: Annotated[
        account_1.Account | None, Field(description='Account billed for this media buy')
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description='Per-buy invoice recipient when provided at creation. Confirms the seller accepted the billing override. Bank details are omitted (write-only).'
        ),
    ] = None
    status: media_buy_status.MediaBuyStatus
    status_as_of: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp indicating when the seller last refreshed the returned media-buy-level `status` from its source of truth. Use this to interpret cached or rolled-up list statuses, especially for curator/storefront aggregators where one buyer-facing buy maps to multiple upstream legs. For rolled-up statuses, this timestamp MUST NOT be later than the oldest upstream status observation that could affect the returned roll-up, so it never overstates freshness. Omit or return null to make no freshness assertion; buyers MUST NOT infer that an omitted or null value means the status is live. This is distinct from `updated_at`, which records when the media buy was last modified.'
        ),
    ] = None
    health: Annotated[
        media_buy_health.MediaBuyHealth | None,
        Field(
            description='Dependency health of the media buy, orthogonal to `status`. `ok` (default) when no upstream resource that this buy depends on is in an offline state. `impaired` when at least one such resource (audience, creative, catalog_item, event_source, property) is offline and affects delivery for one or more packages — `impairments[]` MUST be non-empty in that case. On terminal-status buys, the seller MAY leave this field in whatever state held at the terminal transition. See lifecycle.mdx § Compliance and the impairment.coherence assertion.'
        ),
    ] = media_buy_health.MediaBuyHealth.ok
    impairments: Annotated[
        list[impairment.Impairment] | None,
        Field(
            description='Open impairments — upstream dependency state changes that affect delivery for at least one package on this buy. Empty when `health` is `ok`; non-empty iff `health` is `impaired` (health-iff rule on non-terminal buys). Sellers MUST add an entry on the next read after a referenced resource transitions to an offline state, and MUST remove the entry when the resource returns to a serviceable state or stops being a dependency (e.g., via assignment swap via update_media_buy). Staleness budget: the snapshot MUST reflect the impairment within 5 minutes of `impairment.observed_at` regardless of buyer poll cadence — sellers cannot rely on rare buyer polls to defer write propagation. See impairment.coherence assertion for the cross-resource invariant.'
        ),
    ] = None
    rejection_reason: Annotated[
        str | None,
        Field(
            description="Reason provided by the seller when status is 'rejected'. Present only when status is 'rejected'."
        ),
    ] = None
    currency: Annotated[
        str,
        Field(
            description='Single ISO 4217 denomination for total_budget, package budget constraints, and canonical BiddingPolicy monetary fields. Every selected pricing option on an AdCP-authored media buy MUST declare this currency. Legacy or externally-created mixed-currency buys must not expose canonical bidding until normalized or split.',
            pattern='^[A-Z]{3}$',
        ),
    ]
    total_budget: Annotated[
        StrictFloat,
        Field(
            description='Hard aggregate lifetime budget, denominated in media_buy.currency', ge=0.0
        ),
    ]
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Current hard aggregate spend ceiling per calendar day, denominated in media_buy.currency. It bounds total spend without allocating or reserving package spend.',
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Current hard MediaBuy-level cap. Sellers MUST echo it whenever set, separately from package targeting-overlay caps.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='IANA timezone defining the shared calendar-day boundary for every aggregate and package daily cap. Present whenever any daily cap is set on the media buy.'
        ),
    ] = None
    budget_allocation: Annotated[
        budget_allocation_1.BudgetAllocation | None,
        Field(
            description='Current cross-package allocation configuration. Omitted means fixed allocation for legacy buys.'
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(description='Aggregate pacing strategy for the media-buy budget.'),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Current media-buy-authored bidding policy with scope-specific goal binding and media-buy-currency denomination. Package entries omit bidding when they inherit this block; explicit package automatic overrides remain visible as `{automatic:true}`.'
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 flight start time for this media buy (earliest package start_time). Avoids requiring buyers to compute min(packages[].start_time).'
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 flight end time for this media buy (latest package end_time). Avoids requiring buyers to compute max(packages[].end_time).'
        ),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None, Field(description='ISO 8601 timestamp for creative upload deadline')
    ] = None
    confirmed_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when the seller committed to this media buy. May be null until seller commitment occurs in deferred/manual approval flows. Once populated, remains stable through later pause, resume, activation, completion, cancellation, and reporting transitions.'
        ),
    ]
    cancellation: Annotated[
        Cancellation | None,
        Field(description="Cancellation metadata. Present only when status is 'canceled'."),
    ] = None
    revision: Annotated[
        SchemaInt,
        Field(
            description='Current optimistic concurrency token. Pass this in update_media_buy requests intended to change state. Sellers increment it on mutating state changes/updates and reject stale tokens with CONFLICT when a revision token is provided.',
            ge=1,
        ),
    ]
    created_at: Annotated[AwareDatetime | None, Field(description='Creation timestamp')] = None
    updated_at: Annotated[AwareDatetime | None, Field(description='Last update timestamp')] = None
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque media-buy-level correlation data echoed unchanged from the create_media_buy request. Sellers MUST include persisted context on read surfaces when the media buy was created through AdCP with context, so buyers can reconcile seller-assigned media_buy_id values with their own tracking state. Sellers MAY omit context for media buys created outside AdCP or created without context. Sellers MUST NOT parse this object for business logic.'
        ),
    ] = None
    valid_actions: Annotated[
        list[media_buy_valid_action.MediaBuyValidAction] | None,
        Field(
            deprecated=True,
            description='Flat-vocabulary actions the buyer can perform on this media buy in its current state. Eliminates the need for agents to internalize the state machine — the seller declares what is permitted right now. Deprecated in favor of `available_actions[]`, which carries mode, optional SLA, and a 3.2 change_term_id link. Sellers SHOULD populate both during the 3.x deprecation window; consumers MUST prefer `available_actions[]` when both are present. Removed in 4.0.',
        ),
    ] = None
    available_actions: Annotated[
        list[
            canonical_media_buy_action.CanonicalMediaBuyAction
            | media_buy_available_action.MediaBuyAvailableAction
        ]
        | None,
        Field(
            description="Structured per-buy resolution of the actions buyer can perform right now. Authoritative — divergence from product `allowed_actions[]` is expected because accepted proposal terms, current state, authorization, and governance delegation are buy-specific. Each entry carries the resolved mode, optional SLA commitment, and in 3.2 an optional change_term_id linking the accepted proposal right. Deprecated 3.1 terms_ref remains readable as an opaque compatibility pointer. Predicate queries via #4425's `requires` grammar address fields by dotted path, e.g. `available_actions.extend_flight.sla.response_max`. Absent SLA means no commitment, not zero commitment — callers composing duration predicates MUST also compose with `present: true` to avoid silently matching sellers who never declared one."
        ),
    ] = None
    webhook_activity: Annotated[
        list[webhook_activity_record.WebhookActivityRecord] | None,
        Field(
            description='Recent webhook fires relevant to this buy for the calling principal, most-recent first. Includes per-buy delivery/health fires and account-anchored indicators.changed or creative.assignment_changed invalidations whose payload names this media_buy_id. Present only when include_webhook_activity was true and the seller surfaces this debug capability. Account-anchored records MUST include subscriber_id. Three-state presence and the 30-day retention floor follow snapshot-and-log.mdx § Webhook activity log pattern.',
            max_length=200,
        ),
    ] = None
    history: Annotated[
        list[HistoryItem] | None,
        Field(
            description='Revision history entries, most recent first. Only present when include_history > 0 in the request. Each entry represents a state change or update to the media buy. Entries are append-only: sellers MUST NOT modify or delete previously emitted history entries. Callers MAY cache entries by revision number. Returns min(N, available entries) when include_history exceeds the total.'
        ),
    ] = None
    packages: Annotated[
        Sequence[Package],
        Field(
            description='Packages within this media buy, augmented with creative approval status and optional delivery snapshots'
        ),
    ]
    ext: ext_1.ExtensionObject | None = 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

• IndicatorBearingResourceState
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• MediaBuy

Class variables

var accepted_proposal : AcceptedProposal | None

var accepted_proposal_id : str | None

var accepted_proposal_terms_digest : str | None

var account : Account | None

var available_actions : list[typing.Union[CanonicalMediaBuyAction1, CanonicalMediaBuyAction2, CanonicalMediaBuyAction3, MediaBuyAvailableAction]] | None

var bidding : BiddingPolicy | None

var budget_allocation : BudgetAllocation1 | BudgetAllocation2 | None

var budget_cap_timezone : str | None

var cancellation : Cancellation | None

var confirmed_at : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var created_at : pydantic.types.AwareDatetime | None

var creative_deadline : pydantic.types.AwareDatetime | None

var currency : str

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var health : MediaBuyHealth | None

var history : list[HistoryItem] | None

var impairments : list[Impairment] | None

var indicator_types_evaluated : list[IndicatorTypesEvaluatedEnum] | None

var indicators : list[Indicator] | None

var invoice_recipient : BusinessEntity | None

var media_buy_id : str

var model_config

var name : str | None

var pacing : Pacing | None

var packages : Sequence[Package]

var rejection_reason : str | None

var revision : int

var start_time : pydantic.types.AwareDatetime | None

var status : MediaBuyStatus

var status_as_of : pydantic.types.AwareDatetime | None

var total_budget : float

var updated_at : pydantic.types.AwareDatetime | None

var valid_actions : list[MediaBuyValidAction] | None

var webhook_activity : list[WebhookActivityRecord] | None

class CapabilitiesMediaBuy (**data: Any)

Expand source code

class MediaBuy(AdCPBaseModel):
    anonymous_discovery: Annotated[
        StrictBool | None,
        Field(
            description='Whether this seller accepts product discovery without caller credentials. This applies to list_products and to get_products in brief or wholesale mode; it does not apply to proposal refinement or finalization, purchasing, account-scoped reads, or mutations. true means an anonymous discovery request can produce a successful response, but the response may be a public subset and may differ from results for an authenticated principal or selected account. false means these discovery calls require an authenticated principal. Absence means unspecified legacy behavior, so callers probe and handle AUTH_MISSING. A valid authenticated request is never rejected merely because credentials were supplied. true is inconsistent with account.required_for_products=true because an anonymous caller cannot select protected account context.'
        ),
    ] = None
    acceptance_policy_discovery: Annotated[
        AcceptancePolicyDiscovery | None,
        Field(
            description='Registry-backed seller acceptance-policy discovery. Presence means the seller publishes a versioned catalog; it does not claim that the seller evaluates acceptance_context during discovery. Discovery is advisory, exact task responses remain authoritative, and absent capability means support is unknown rather than unrestricted acceptance.'
        ),
    ] = None
    supported_pricing_models: Annotated[
        list[pricing_model.PricingModel] | None,
        Field(
            description='Pricing models this seller supports across its product portfolio. Buyers can use this for pre-flight filtering before querying individual products. Individual products may support a subset of these models.',
            min_length=1,
        ),
    ] = None
    buying_modes: Annotated[
        list[BuyingMode] | None,
        Field(
            description="Buying modes this seller supports on get_products. 'brief' (semantic discovery driven by the brief) is universally supported and implicit. 'wholesale' (raw wholesale product feed enumeration — caller omits brief and the seller returns the full priced product feed, paginated) is opt-in and SHOULD be declared explicitly so buyers can probe before issuing wholesale calls. 'refine' lets buyers iterate on prior products/proposals and is also the vehicle for finalizing draft proposals when the seller returns them. Sellers MAY declare ['brief', 'wholesale'] to signal wholesale support; absent declaration is treated as ['brief'] for wholesale-feed probing purposes and sellers MAY return INVALID_REQUEST for wholesale calls they do not support. Symmetric with signals.discovery_modes.",
            min_length=1,
        ),
    ] = [BuyingMode.brief]
    measurement_terms_acceptance: Annotated[
        StrictBool | None,
        Field(
            description="Whether this seller can accept the default measurement_terms it advertises on a product. A value of true means the seller can return a product carrying measurement_terms for a measurement-specific brief and accept those terms unchanged on a package for that product. This opts the seller into conformance scenarios that discover and replay the product's own terms. False or absent means acceptance is outside the seller's advertised scope, but the seller must still reject unsupported terms with TERMS_REJECTED rather than being graded on an acceptance path it did not claim."
        ),
    ] = False
    availability_horizon: Annotated[
        StrictBool | None,
        Field(
            description='Whether this seller supports flexible-window availability discovery: parsing offer_filters.availability_horizon and answering with time-dimensioned forecast points that carry availability_status. Sellers declaring true MUST apply the full window contract — half-open non-overlapping windows that partition the requested horizon (or signal gaps via incomplete[]), with availability_status computed from all booking eligibility constraints, not only competing holds. false or absent means flexible-window support is unknown: buyers SHOULD use exact start_date/end_date filtering, and sellers MAY ignore the field or reject it. Conformance storyboards gate flexible-window checks on this declaration.'
        ),
    ] = False
    lifecycle_tools: Annotated[
        list[LifecycleTool] | None,
        Field(
            description='Compact product and MediaBuy lifecycle operation names this seller supports. Added in AdCP 3.2 as task-specific contracts that form the 4.0 lifecycle foundation. Sellers may advertise any supported subset while retaining the deprecated get_products/create_media_buy/update_media_buy facades throughout 3.x. Each stateful split task has its own idempotency identity; callers MUST retry with the same tool name.',
            min_length=1,
        ),
    ] = None
    proposal_refinement: Annotated[
        ProposalRefinement | None,
        Field(
            description='Pre-flight support for typed refine_proposals revision dimensions. These declarations mean the seller can parse and mechanically validate a dimension; they never promise that the seller will commercially concede it. Absence means typed-dimension support is unknown and buyers must handle per-result partial or unable outcomes. A dimension omitted from an explicit supported_dimensions list MUST be rejected at task level with UNSUPPORTED_FEATURE before any proposal is created.'
        ),
    ] = None
    reporting_delivery_methods: Annotated[
        list[CapabilityReportingDeliveryMethod] | None,
        Field(
            description="How this seller delivers reporting data to buyers. Polling via get_media_buy_delivery is always available as a baseline regardless of this field. This array declares additional push-based delivery methods the seller supports. 'webhook': seller pushes to buyer-provided URL (configured per buy via reporting_webhook). 'offline': seller pushes batch files to a cloud storage bucket (seller-provisioned per account via reporting_bucket on the account object). When absent, only polling is available.",
            min_length=1,
        ),
    ] = None
    performance_feedback: Annotated[
        PerformanceFeedback | None,
        Field(
            description='Structured seller performance-feedback support beyond the legacy scalar contract. Presence means the seller accepts compact baseline/metric/provenance fields from a buyer orchestrator and returns a feedback_id.'
        ),
    ] = None
    offline_delivery_protocols: Annotated[
        list[cloud_storage_protocol.CloudStorageProtocol] | None,
        Field(
            description="Cloud storage protocols this seller supports for offline file delivery. Only meaningful when reporting_delivery_methods includes 'offline'. Buyers express a protocol preference in sync_accounts; the seller provisions the account's reporting_bucket using a supported protocol.",
            min_length=1,
        ),
    ] = None
    reporting_delivery: Annotated[
        reporting_delivery_capabilities.ReportingDeliveryCapabilities | None,
        Field(
            description='AdCP 3.2 Reliable Reporting capability. The affirmative machine answer to ‘Do you support Reliable Reporting?’ requires this block with supported: true and reliable_reporting_version: 1.0 plus media_buy.reporting_delivery in experimental_features. Core exposes seller get_reporting_status; during the published migration window, consumer_status_task separately advertises opt-in buyer-to-seller sync_reporting_status and becomes required Core only in the next eligible minor. managed_delivery and reconciled_billing identify optional tiers. This generalizes, but does not remove, the legacy reporting_delivery_methods/offline_delivery_protocols surface; those legacy fields and declarations from other protocols do not imply Reliable Reporting support.'
        ),
    ] = None
    supports_proposals: Annotated[
        StrictBool | None,
        Field(
            description='Conformance declaration that this seller supports proposals through either the compact request/refine/finalize lifecycle or the legacy get_products facade. accept_proposal, or the create_media_buy compatibility facade, consumes a finalized committed proposal_id before expires_at.'
        ),
    ] = False
    outcome_target: Annotated[
        StrictBool | None,
        Field(
            description="Whether this seller supports reverse-forecast planning: parsing criteria.outcome_target (a compact goal — a forecastable-metric delivery metric or an event-type conversion event — plus a desired volume, a cost_per target, or both) and planning against it, answering with total_budget_guidance and forecasts whose points carry the goal's key in metrics; see outcome-target.json for cost_per answers and rejections. This flag does not distinguish sellers that plan cost_per; buyers rely on the negotiated adcp_version together with features.bidding_policy. false or absent means support is unknown: buyers SHOULD express outcome goals in brief prose instead, and sellers reject a structured outcome_target on proposal requests with UNSUPPORTED_FEATURE rather than silently ignoring it (list_products ignores it for every seller)."
        ),
    ] = False
    governance_aware: Annotated[
        StrictBool | None,
        Field(
            description='Compatibility claim used by existing media-buy conformance runners. A value of true corresponds only to online governance consultation for create_media_buy, the historically graded surface. Agents use adcp.governance_enforcement for explicit task-scoped claims, including update_media_buy and cross-role signed-context enforcement.'
        ),
    ] = False
    propagation_surfaces: Annotated[
        list[PropagationSurface] | None,
        Field(
            description='Where this seller surfaces dependency-resource impairments (creative suspended/rejected post-approval, audience suspended, catalog item withdrawn, event source insufficient, property depublished) to buyers. Non-exclusive: a seller mirroring impairments on both the buy snapshot AND firing webhooks declares `["snapshot", "webhook"]` (the common case for premium guaranteed sellers). Each value names one surface where buyers can observe an impairment:\n\n- **`snapshot`** — seller propagates resource transitions into `media_buy.health` and `media_buy.impairments[]` on the next `get_media_buys` read. The `impairment.coherence` compliance assertion grades this surface; storyboards that exercise it (`media_buy_seller/dependency_impairment`, `media_buy_seller/dependency_impairment_cardinality`) require `"snapshot"` to be declared, else they grade `not_applicable`.\n- **`webhook`** — seller fires `notification-type: impairment` webhooks (configured via `push_notification_config`). Sellers declaring `"webhook"` MUST satisfy the persistent-channel webhook contract for the impairment event type. A seller declaring `["webhook"]` without `"snapshot"` is webhook-only — buyers reconcile state from the push channel alone, and snapshot-coherence storyboards grade `not_applicable`.\n- **`out_of_band`** — seller propagates via channels outside the AdCP protocol surface entirely (email to trafficker, separate dashboard, partner-specific notification feed). Long-tail and enterprise-bundled platforms commonly use this when impairment workflows are managed in human channels. Sellers declaring only `["out_of_band"]` are not graded by snapshot or webhook compliance — their bar is the offline agreement, not a protocol assertion. If a seller has impairment data in their API under a non-AdCP field name (a mapping gap, not truly out-of-band), they SHOULD document the mapping rather than declare `out_of_band` — the spec\'s gap, not the seller\'s posture, is what `out_of_band` legitimately covers.\n\nDefault: `["snapshot"]` when absent (preserves the existing snapshot-coherence contract for sellers that don\'t declare). Empty array `[]` is invalid (`minItems: 1`) — omit the field to inherit the default rather than declaring no surfaces. Pick the surfaces that honestly describe where buyers will see impairments on this agent. Mixing is normative — `["snapshot", "webhook"]` is the documented common case; `["snapshot", "webhook", "out_of_band"]` is valid for sellers that ship all three surfaces (rare but legal). See lifecycle.mdx § Compliance for the per-surface contract.',
            min_length=1,
        ),
    ] = [PropagationSurface.snapshot]
    creative_approval_mode: Annotated[
        CreativeApprovalMode | None,
        Field(
            description="Tenant-wide applicability signal for media-buy creative approval behavior. This is not a notification or new approval workflow. `auto_approve` means human review does not block serving eligibility after creatives are assigned and automated validation passes. `require_human` means one or more products/accounts may require manual review before creatives become eligible to serve; buyers and compliance runners MUST treat this as a worst-case ceiling across this seller's portfolio unless a future product-level override says otherwise. Compliance runners use this mainly to decide whether auto-approval-dependent storyboards apply. When absent, approval behavior is legacy-unspecified; runners SHOULD NOT treat omission as an affirmative auto-approval claim. `ai_assisted` is intentionally not part of the enum until a behavioral contract is defined."
        ),
    ] = None
    supported_indicator_types: Annotated[
        list[indicator_type.IndicatorType] | None,
        Field(
            description="Indicator types this seller can expose on get_media_buys media-buy/package/creative-assignment snapshots. Each type's meaning is defined by the negotiated AdCP release; indicator types do not carry independent sub-versions. This is availability, not complete upstream coverage. Poll-only sellers may declare this field without relationship_notifications. If relationship_notifications includes indicators.changed, this field is required so receivers know which durable indicator types can be repaired.",
            min_length=1,
        ),
    ] = None
    relationship_notifications: Annotated[
        RelationshipNotifications | None,
        Field(
            description='Optional durable account-level invalidations for indicator, creative-assignment, and assignment-approval changes. A seller may expose indicators only through polling and omit this block. A seller without an indicator catalog may declare creative.assignment_changed alone. get_media_buys is the complete authoritative repair read. creative.assignment_changed is independent of the optional bounded list_creatives reverse projection, so inline-only sellers can advertise approval and assignment invalidations. Presence means the seller accepts the declared subscriptions through sync_accounts notification_configs. Timestamp-only reevaluation does not fire. Poll-based upstream integrations fire when they detect a change; this declaration does not promise upstream detection latency.'
        ),
    ] = None
    features: media_buy_features.MediaBuyFeatures | None = None
    execution: Annotated[
        Execution | None, Field(description='Technical execution capabilities for media buying')
    ] = None
    audience_evidence: Annotated[
        AudienceEvidence | None,
        Field(
            description='Support for structured product audience evidence and buyer-authored evidence policy. Presence means the seller can publish Product.audience_evidence, preserve immutable snapshots through package readback, and evaluate the declared policy modes. It does not declare audience-targeting capability.'
        ),
    ] = None
    rights_attestations: Annotated[
        RightsAttestations | None,
        Field(
            description='Seller evaluation policy for portable rights-grant attestations carried on creative rights constraints. Presence requires adcp.attestations and the rights-grant claim URI in accepted_claim_types. The seller remains verifier-of-record and never treats verification_url or a buyer-authored evaluation as authorization.'
        ),
    ] = None
    audience_targeting: Annotated[
        AudienceTargeting | None,
        Field(
            description='Audience targeting capabilities. Presence of this object indicates the seller supports audience targeting, including sync_audiences and audience_include/audience_exclude in targeting overlays.'
        ),
    ] = None
    supported_optimization_metrics: Annotated[
        list[SupportedOptimizationMetric] | None,
        Field(
            description='Optimization metrics this seller can support on at least one of their products. Seller-level rollup of product-level metric_optimization.supported_metrics declarations (core/product.json). Buyers SHOULD filter their requested optimization goals against this list before submitting briefs. Sellers MUST keep this in sync with their product catalog — if no products support a metric, it must not appear here. Omitting this field means the seller declares no specific guarantees about which metrics they support; buyers should fall back to per-product inspection of metric_optimization.supported_metrics.',
            min_length=1,
        ),
    ] = None
    vendor_metric_optimization: Annotated[
        VendorMetricOptimization | None,
        Field(
            description='Seller-level rollup of vendor-metric optimization capabilities supported by at least one product. Product-level vendor_metric_optimization.supported_metrics[] remains authoritative for the specific (vendor, metric_id) pairs and target kinds a buyer may bind on a package; this seller-level object exists so buyers and compliance runners can discover whether vendor_metric goals are in scope before walking the catalog. Sellers MUST keep this in sync with product-level vendor_metric_optimization declarations.'
        ),
    ] = None
    conversion_tracking: Annotated[
        ConversionTracking | None,
        Field(
            description='Seller-level conversion tracking capabilities. Presence of this object indicates the seller supports sync_event_sources and log_event for conversion event tracking.'
        ),
    ] = None
    frequency_capping: Annotated[
        FrequencyCapping | None,
        Field(
            description='Seller-wide package frequency-capping infrastructure. Presence means the seller honors targeting_overlay.frequency_cap on packages, with an independent counter per package, and MUST reject caps it cannot enforce rather than silently dropping them. Product.overlay_support is the binding per-product declaration. A cap whose single counter spans every package in a MediaBuy is advertised separately through aggregate_frequency_capping.'
        ),
    ] = None
    aggregate_frequency_capping: Annotated[
        media_buy_frequency_cap_capability.MediaBuyFrequencyCapCapability | None,
        Field(
            description='Seller-wide support for a maximum-impression cap whose single counter is shared across every package in a MediaBuy. Presence is required before a buyer sends a root frequency_cap. Products additionally declare media_buy_support.frequency_cap and any narrower constraints.'
        ),
    ] = None
    budget_capping: Annotated[
        BudgetCapping | None,
        Field(
            description='Hard daily budget-cap capabilities. Presence declares only the scopes listed in supported_scopes; sellers MUST reject a daily_budget_cap at an undeclared scope with UNSUPPORTED_FEATURE before mutation and MUST NOT silently drop or soften it. A cap is always a hard ceiling. Sellers that offer a best-effort pacing target must expose that under a separately named feature rather than interpreting daily_budget_cap as soft. Daily caps are orthogonal to pacing.'
        ),
    ] = None
    content_standards: Annotated[
        ContentStandards | None,
        Field(
            description='Content standards implementation details. Presence of this object indicates the seller supports content_standards configuration including sampling rates and category filtering. Gives buyers pre-buy visibility into local evaluation and artifact delivery capabilities. This is a seller-side media-buy capability; governance agents providing content standards services declare `specialisms: ["content-standards"]` instead.'
        ),
    ] = None
    portfolio: Annotated[
        Portfolio | None,
        Field(
            description="Information about the seller's media inventory portfolio. Media-buy sellers SHOULD publish primary_channels and primary_countries as their complete brief-routing scope. Buyers use publisher_domains to verify authorization via adagents.json. Omitted routing arrays mean unknown scope and MUST NOT be interpreted as global coverage."
        ),
    ] = 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

Class variables

var acceptance_policy_discovery : AcceptancePolicyDiscovery | None

var aggregate_frequency_capping : MediaBuyFrequencyCapCapability | None

var anonymous_discovery : bool | None

var audience_evidence : AudienceEvidence | None

var audience_targeting : AudienceTargeting | None

var availability_horizon : bool | None

var budget_capping : BudgetCapping | None

var buying_modes : list[BuyingMode] | None

var content_standards : ContentStandards | None

var conversion_tracking : ConversionTracking | None

var creative_approval_mode : CreativeApprovalMode | None

var execution : Execution | None

var features : MediaBuyFeatures | None

var frequency_capping : FrequencyCapping | None

var governance_aware : bool | None

var lifecycle_tools : list[LifecycleTool] | None

var measurement_terms_acceptance : bool | None

var model_config

var offline_delivery_protocols : list[CloudStorageProtocol] | None

var outcome_target : bool | None

var performance_feedback : PerformanceFeedback | None

var portfolio : Portfolio | None

var propagation_surfaces : list[PropagationSurface] | None

var proposal_refinement : ProposalRefinement | None

var relationship_notifications : RelationshipNotifications | None

var reporting_delivery : ReportingDeliveryCapabilities | None

var reporting_delivery_methods : list[CapabilityReportingDeliveryMethod] | None

var rights_attestations : RightsAttestations | None

var supported_indicator_types : list[IndicatorType] | None

var supported_optimization_metrics : list[SupportedOptimizationMetric] | None

var supported_pricing_models : list[PricingModel] | None

var supports_proposals : bool | None

var vendor_metric_optimization : VendorMetricOptimization | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MediaBuyActionMode (*args, **kwds)

Expand source code

class MediaBuyActionMode(StrEnum):
    self_serve = 'self_serve'
    conditional_self_serve = 'conditional_self_serve'
    seller_managed = 'seller_managed'
    requires_approval = 'requires_approval'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var conditional_self_serve

var requires_approval

var self_serve

var seller_managed

class MediaBuyAvailableAction (**data: Any)

Expand source code

class MediaBuyAvailableAction(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    action: Annotated[
        media_buy_available_action_id.MediaBuyAvailableActionId,
        Field(description='The action identifier.'),
    ]
    mode: Annotated[
        media_buy_action_mode.MediaBuyActionMode,
        Field(
            description='The single mode that applies right now on this buy for this action. Singular because the buy has a concrete state, exactly one mode applies. Buyer SDKs branch on this to decide whether to expect a synchronous response, conditional handling, or an asynchronous approval callback.'
        ),
    ]
    task: Annotated[
        Task | None,
        Field(
            description='Compact-lifecycle task for this resolved action: operational control, commercial refinement, or creative lifecycle mutation.'
        ),
    ] = None
    sla: Annotated[
        sla_window.SlaWindow | None,
        Field(
            description='Optional SLA commitment for this action on this buy. Absence means no commitment, not zero commitment.'
        ),
    ] = None
    change_term_id: media_buy_change_term_id.MediaBuyChangeTermId | None = None
    terms_ref: media_buy_legacy_terms_ref.MediaBuyTermsReference | None = None
    applicable_package_ids: Annotated[
        list[applicable_package_id.ApplicablePackageId] | None,
        Field(
            description='For a package-scoped action, the exact packages currently eligible. Omission means every relevant package. Root actions omit this field.',
            min_length=1,
        ),
    ] = 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

Class variables

var action : MediaBuyValidAction | Literal['update_media_buy_frequency_cap']

var applicable_package_ids : list[ApplicablePackageId] | None

var change_term_id : MediaBuyChangeTermId | None

var mode : MediaBuyActionMode

var model_config

var sla : SlaWindow | None

var task : Task | None

var terms_ref : MediaBuyTermsReference | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MediaBuyChangeTerm (**data: Any)

Expand source code

class MediaBuyChangeTerm(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    term_id: Annotated[str, Field(pattern='^[A-Za-z0-9_.:-]+$')]
    action: canonical_media_buy_action.CanonicalMediaBuyActionName
    service_mode: canonical_media_buy_action_mode.CanonicalMediaBuyActionMode
    allowed_statuses: Annotated[
        list[AllowedStatus] | None,
        Field(
            description='Non-terminal MediaBuy statuses in which this negotiated right may be exercised. When absent, the right applies in every non-terminal status where the canonical action itself is meaningful. This field describes contractual lifecycle scope; available_actions[] remains authoritative for the current instant.',
            min_length=1,
        ),
    ] = None
    processing_sla: Annotated[
        sla_window.SlaWindow | None,
        Field(
            description='Binding elapsed-time acknowledgement and completion commitment. Sellers account for weekends and non-working periods when declaring the maximum.'
        ),
    ] = None
    conditions: Annotated[
        list[Condition] | None,
        Field(
            description='Opaque stable condition identifiers defined by terms_ref or bilateral commercial documentation. Implementations compare identifiers; they MUST NOT execute or interpret them as instructions.',
            min_length=1,
        ),
    ] = None
    constraints: Annotated[
        change_term_constraints.MediaBuyChangeTermConstraints | None,
        Field(
            description='Portable bounds that buyer and seller SDKs can preflight. Omission means no machine-readable bound was promised; opaque conditions remain unevaluated.'
        ),
    ] = None
    terms_ref: Annotated[
        str | None,
        Field(
            description="Stable contract reference. Resolving it cannot expand the typed right and MUST use the caller's normal authenticated contract-document path, never ambient seller credentials.",
            max_length=1000,
            min_length=1,
        ),
    ] = None
    description: Annotated[
        str | None,
        Field(
            description='Display-only summary; it cannot grant authority, add an action, or override typed fields.',
            max_length=1000,
            min_length=1,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _validate_constraint_action(self) -> MediaBuyChangeTerm:
        if self.constraints is None:
            return self
        kind = self.constraints.kind
        allowed = {
            'budget': {
                'increase_budget', 'decrease_budget', 'reallocate_budget',
                'update_budget_allocation', 'update_spend_target',
            },
            'flight': {'extend_flight', 'shorten_flight', 'update_flight_dates'},
            'package_count': {'add_packages', 'remove_packages'},
            'effective_timing': {'pause', 'resume', 'cancel'},
        }
        action = self.action.value
        if action not in allowed.get(kind, set()):
            raise ValueError('constraint kind is incompatible with action')
        return self

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

Class variables

var action : CanonicalMediaBuyActionName

var allowed_statuses : list[AllowedStatus] | None

var conditions : list[Condition] | None

var constraints : MediaBuyChangeTermConstraints1 | MediaBuyChangeTermConstraints2 | MediaBuyChangeTermConstraints3 | MediaBuyChangeTermConstraints4 | None

var description : str | None

var ext : ExtensionObject | None

var model_config

var processing_sla : SlaWindow | None

var service_mode : CanonicalMediaBuyActionMode

var term_id : str

var terms_ref : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BudgetChangeConstraints (**data: Any)

Expand source code

class MediaBuyChangeTermConstraints1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['budget'] = 'budget'
    max_delta_amount: Annotated[
        Money | None,
        Field(
            description='Maximum absolute amount by which the affected budget may change in the direction named by the action.'
        ),
    ] = None
    max_delta_percent: Annotated[
        StrictFloat | None,
        Field(
            description='Maximum percentage change relative to the current committed value. Values above 100 are valid for increases greater than the current value.',
            ge=0.0,
        ),
    ] = None
    min_result_amount: Annotated[
        Money | None, Field(description='Minimum resulting committed value after the change.')
    ] = None
    max_result_amount: Annotated[
        Money | None, Field(description='Maximum resulting committed value after the change.')
    ] = None


    @model_validator(mode='after')
    def _require_portable_bound(self) -> MediaBuyChangeTermConstraints1:
        if not any(getattr(self, name) is not None for name in ('max_delta_amount', 'max_delta_percent', 'min_result_amount', 'max_result_amount')):
            raise ValueError('at least one portable constraint bound is required')
        return self

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

Class variables

var kind : Literal['budget']

var max_delta_amount : Money | None

var max_delta_percent : float | None

var max_result_amount : Money | None

var min_result_amount : Money | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class FlightChangeConstraints (**data: Any)

Expand source code

class MediaBuyChangeTermConstraints2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['flight'] = 'flight'
    max_change: Annotated[
        duration.Duration | None,
        Field(
            description='Maximum extension, shortening, or shift in the direction named by the action.'
        ),
    ] = None
    earliest_result: Annotated[
        AwareDatetime | None,
        Field(description='Earliest resulting start or end timestamp accepted for this action.'),
    ] = None
    latest_result: Annotated[
        AwareDatetime | None,
        Field(description='Latest resulting start or end timestamp accepted for this action.'),
    ] = None
    minimum_notice: Annotated[
        duration.Duration | None,
        Field(
            description='Minimum elapsed notice before the requested flight change may take effect.'
        ),
    ] = None


    @model_validator(mode='after')
    def _require_portable_bound(self) -> MediaBuyChangeTermConstraints2:
        if not any(getattr(self, name) is not None for name in ('max_change', 'earliest_result', 'latest_result', 'minimum_notice')):
            raise ValueError('at least one portable constraint bound is required')
        return self

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

Class variables

var earliest_result : pydantic.types.AwareDatetime | None

var kind : Literal['flight']

var latest_result : pydantic.types.AwareDatetime | None

var max_change : Duration | None

var minimum_notice : Duration | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PackageCountChangeConstraints (**data: Any)

Expand source code

class MediaBuyChangeTermConstraints3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['package_count'] = 'package_count'
    max_additions: Annotated[
        SchemaInt | None,
        Field(description='Maximum packages that may be added by one exercise of the right.', ge=0),
    ] = None
    max_removals: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum packages that may be removed by one exercise of the right.', ge=0
        ),
    ] = None
    max_result_count: Annotated[
        SchemaInt | None, Field(description='Maximum active package count after the change.', ge=0)
    ] = None


    @model_validator(mode='after')
    def _require_portable_bound(self) -> MediaBuyChangeTermConstraints3:
        if not any(getattr(self, name) is not None for name in ('max_additions', 'max_removals', 'max_result_count')):
            raise ValueError('at least one portable constraint bound is required')
        return self

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

Class variables

var kind : Literal['package_count']

var max_additions : int | None

var max_removals : int | None

var max_result_count : int | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class EffectiveTimingChangeConstraints (**data: Any)

Expand source code

class MediaBuyChangeTermConstraints4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['effective_timing'] = 'effective_timing'
    minimum_notice: Annotated[
        duration.Duration | None,
        Field(
            description='Minimum elapsed notice before pause, resume, cancellation, or another operational action may take effect.'
        ),
    ] = None
    earliest_effective_at: AwareDatetime | None = None
    latest_effective_at: AwareDatetime | None = None


    @model_validator(mode='after')
    def _require_portable_bound(self) -> MediaBuyChangeTermConstraints4:
        if not any(getattr(self, name) is not None for name in ('minimum_notice', 'earliest_effective_at', 'latest_effective_at')):
            raise ValueError('at least one portable constraint bound is required')
        return self

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

Class variables

var earliest_effective_at : pydantic.types.AwareDatetime | None

var kind : Literal['effective_timing']

var latest_effective_at : pydantic.types.AwareDatetime | None

var minimum_notice : Duration | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MediaBuyChangeTermId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class MediaBuyChangeTermId(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Za-z0-9_.:-]+$'}
    _json_schema_extra = {
        'description': 'The accepted proposal change_terms[].term_id from which this current-state action projection was derived.',
        'title': 'Media Buy Change Term ID',
    }

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class MediaBuyDelivery (**data: Any)

Expand source code

class MediaBuyDelivery(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buy_id: Annotated[str, Field(description="Seller's media buy identifier")]
    currency: Annotated[
        str | None,
        Field(
            description="ISO 4217 denomination for monetary values in this media-buy delivery row, including totals, package spend, and currency-denominated package rates. Sellers SHOULD populate this field whenever all monetary values in the row share one currency. For AdCP-authored buys it MUST equal the media-buy currency, and every by_package[].currency MUST equal it. For a legacy or externally created mixed-currency buy, omit this field, daily_breakdown, and all monetary or money-derived values from row and window totals; report those values only at package grain with each package's own currency. AdCP does not perform currency conversion.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    status: Annotated[
        Status,
        Field(
            description='Current media buy status. Lifecycle states use the same taxonomy as media-buy-status (`pending_creatives`, `pending_start`, `active`, `paused`, `completed`, `rejected`, `canceled`). In webhook context, reporting_delayed indicates data temporarily unavailable. `pending` is accepted as a legacy alias for pending_start.'
        ),
    ]
    expected_availability: Annotated[
        AwareDatetime | None,
        Field(
            description='When delayed data is expected to be available (only present when status is reporting_delayed)'
        ),
    ] = None
    is_adjusted: Annotated[
        StrictBool | None,
        Field(
            description='Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals.'
        ),
    ] = None
    is_final: Annotated[
        StrictBool | None,
        Field(
            description="Whether this row's delivery data is final for the reporting period. The row does not carry its own `measurement_window` — that lives on each `by_package[*]` entry. Reconciliation joins on per-package `measurement_window`; this row-level flag is a convenience roll-up. Sellers MUST NOT emit `is_final: true` at the row level unless every entry in `by_package` has `is_final: true` for the same `measurement_window` as the buy's `measurement_terms.billing_measurement.measurement_window` (or for the row's natural window when no `billing_measurement.measurement_window` is set). On any disagreement between row-level and package-level finality, package-level is authoritative. When true, the seller considers these numbers closed and is willing to invoice on them subject to `measurement_terms.billing_measurement`. When false, numbers may still move as measurement matures (broadcast C3 → C7) or processing completes (IVT scrubbing, dedup). When absent, the seller does not distinguish provisional from final at the row level — consult per-package `is_final`."
        ),
    ] = None
    finalized_at: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp at which this row became final. Present only when `is_final: true`. Anchors the buyer's reconciliation and (when later defined) dispute-window clocks against the buy's `measurement_terms.billing_measurement`. Computed as the latest `finalized_at` across the row's packages for the reconciliation window."
        ),
    ] = None
    pricing_model: Annotated[
        pricing_model_1.PricingModel | None,
        Field(description='Pricing model used for this media buy'),
    ] = None
    pacing_index: Annotated[
        StrictFloat | None,
        Field(
            description='Aggregate media-buy delivery pace relative to the media-buy pacing plan (1.0 = on track, <1.0 = behind, >1.0 = ahead). This is the authoritative pacing signal for seller-optimized buys; package pacing indexes are subordinate diagnostics.',
            ge=0.0,
        ),
    ] = None
    totals: Totals
    by_package: Annotated[list[ByPackageItem], Field(description='Metrics broken down by package')]
    windows: Annotated[
        list[Window] | None,
        Field(
            description="Per-window delivery slices over the reporting period at the requested time_granularity. Only present when the request set time_granularity and include_window_breakdown: true. Each slice mirrors what reporting_webhook would have delivered for the same window — buyers who missed webhook fires can reconstruct identical data by reading this array. Slice rows are ordered by window_start ascending; consecutive rows are contiguous (each row's window_end equals the next row's window_start) and partition the requested date range at the chosen granularity. For a legacy or external mixed-currency media buy, monetary and money-derived values MUST be omitted from each window totals object and reported only in currency-qualified windows[].by_package rows. Sellers MUST exclude this field when time_granularity is omitted; when set, sellers MUST honor pulls at any granularity in reporting_capabilities.windowed_pull_granularities (otherwise return UNSUPPORTED_GRANULARITY). See snapshot-and-log Rule 4 for the two-paths-parity contract this surface anchors."
        ),
    ] = None
    daily_breakdown: Annotated[
        list[DailyBreakdownItem1] | None,
        Field(
            description="Day-by-day delivery for a media-buy row with one currency. Sellers MUST omit this aggregate breakdown for a legacy or externally created mixed-currency buy because these rows have no package currency field. Sellers MUST also omit this aggregate breakdown when the media buy's packages span more than one reporting timezone; package-level daily_breakdown remains, each in its own product's reporting timezone."
        ),
    ] = 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

Class variables

var by_package : list[ByPackageItem]

var currency : str | None

var daily_breakdown : list[DailyBreakdownItem1] | None

var expected_availability : pydantic.types.AwareDatetime | None

var finalized_at : pydantic.types.AwareDatetime | None

var is_adjusted : bool | None

var is_final : bool | None

var media_buy_id : str

var model_config

var pacing_index : float | None

var pricing_model : PricingModel | None

var status : Status

var totals : Totals

var windows : list[Window] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MediaBuyDeliveryWebhookResult (**data: Any)

Expand source code

class MediaBuyDeliveryWebhookResult(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    notification_type: Annotated[
        NotificationType,
        Field(
            description='Type of delivery-report notification: scheduled = regular periodic update, final = campaign completed, delayed = data not yet available, adjusted = corrected data for the same window, window_update = a wider measurement window supersedes a prior window.'
        ),
    ]
    partial_data: Annotated[
        StrictBool | None,
        Field(
            description='Indicates if any media buys in this webhook have missing or delayed data.'
        ),
    ] = None
    unavailable_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of media buys with reporting_delayed or failed status when partial_data is true.',
            ge=0,
        ),
    ] = None
    sequence_number: Annotated[
        SchemaInt | None,
        Field(
            description='Sequential notification number for this reporting webhook stream.', ge=1
        ),
    ] = None
    next_expected_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp for the next expected notification. Omitted on final notifications.'
        ),
    ] = None
    reporting_period: Annotated[
        ReportingPeriod,
        Field(
            description="Period covered by the delivery report. start and end are instants on the reporting timezone's period boundaries (the products' reporting_capabilities.timezone, echoed in timezone). They fall on UTC midnight only when that timezone is UTC."
        ),
    ]
    currency: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2 and removed in AdCP 4.0. Optional legacy report-wide ISO 4217 currency code. It may be used only when every monetary value in the report has that denomination. A report can contain media buys with different currencies, so buyers MUST NOT interpret this field as an aggregation currency or evidence of currency conversion. Prefer media_buy_deliveries[].currency when present and package-level currency otherwise.',
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    attribution_window: Annotated[
        attribution_window_1.AttributionWindow | None,
        Field(
            description='Attribution methodology and lookback windows used for conversion metrics in this report.'
        ),
    ] = None
    media_buy_deliveries: Annotated[
        list[MediaBuyDelivery],
        Field(
            description='Delivery rows for one or more media buys included in this notification.'
        ),
    ]
    errors: Annotated[
        list[error.Error] | None, Field(description='Task-specific delivery errors or warnings.')
    ] = None
    sandbox: StrictBool | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var attribution_window : AttributionWindow | None

var context : ContextObject | None

var currency : str | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var media_buy_deliveries : list[MediaBuyDelivery]

var model_config

var next_expected_at : pydantic.types.AwareDatetime | None

var notification_type : NotificationType

var partial_data : bool | None

var reporting_period : ReportingPeriod

var sandbox : bool | None

var sequence_number : int | None

var unavailable_count : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MediaBuyFeatures (**data: Any)

Expand source code

class MediaBuyFeatures(AdCPBaseModel):
    __pydantic_extra__: Dict[str, StrictBool]
    model_config = ConfigDict(
        extra='allow',
    )
    inline_creative_management: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='Deprecated 3.x compatibility capability for creatives provided inline in create_media_buy and update_media_buy package payloads. buy_products, accept_proposal, and control_media_buy never accept inline creatives. New integrations use the dedicated creative lifecycle. Removed in 4.0.',
        ),
    ] = None
    property_list_filtering: Annotated[
        StrictBool | None,
        Field(
            description='Honors property_list parameter in get_products to filter results to buyer-approved properties'
        ),
    ] = None
    catalog_management: Annotated[
        StrictBool | None,
        Field(
            description='Supports sync_catalogs task for catalog feed management with platform review and approval'
        ),
    ] = None
    catalog_item_availability_updates: Annotated[
        StrictBool | None,
        Field(
            description='Supports buyer-pushed item_availability_updates and item_availability_queries on sync_catalogs for immediate suppression/restoration and current-state readback in buyer-managed catalogs. Seller declarations may be true only with catalog_management: true; buyer required_features filters may request this feature alone. Requests containing availability operations are synchronous and accept at most 1,000 combined update and query entries. A successful suppress covers selection, dynamic rendering, and cached or pre-generated creatives materialized from the item. Internal lineage MUST retain resolved_account_id, catalog_id, catalog_generation, and item_id. Static creatives supplied or promoted by the buyer without catalog lineage remain outside this automatic guarantee. Suppression persists across feed refreshes and ordinary upserts until restore, expires_at, or catalog deletion. A seller that does not declare true MUST reject availability operations with UNSUPPORTED_FEATURE before lookup or mutation and MUST NOT interpret them as discovery. This does not control seller-owned wholesale inventory or let restore bypass seller controls.'
        ),
    ] = None
    committed_metrics_supported: Annotated[
        StrictBool | None,
        Field(
            description="Seller has per-package snapshot infrastructure for the reporting contract. When true, the seller MUST populate `package.committed_metrics` on committed `create_media_buy` responses where `confirmed_at` is non-null, MUST omit `package.committed_metrics` while `confirmed_at` is null for a provisional buy, and MUST honor append-only mid-flight metric additions via `update_media_buy`. The unified `committed_metrics` array (per the metric-accountability design) covers both standard and vendor-defined metric entries, so a single flag is load-bearing. Buyers filtering on this flag are detecting 'this seller can stamp the reporting contract,' which closes the audit gap from PR #3510 where absence of `committed_metrics` was indistinguishable between 'didn't snapshot' and 'snapshot infrastructure not implemented.'"
        ),
    ] = None
    seller_optimized_budget: Annotated[
        StrictBool | None,
        Field(
            description="Supports the core seller-optimized shared-budget contract for budget_allocation.mode `seller_optimized`: one hard shared total_budget, seller allocation of that total across the buy's packages against budget_allocation.optimization_goals, media-buy-level pacing, and echo of the allocation configuration on buy read surfaces. Sellers declaring true MUST accept eligible explicit-package and proposal executions that use only these core controls and MUST enforce the aggregate budget. Core media-buy pacing: sellers declaring true MUST accept omitted media-buy pacing (which defaults to even when total_budget is present) and pacing `even` on seller-optimized buys; they MAY reject `asap` or `front_loaded` with `UNSUPPORTED_FEATURE` (error.field `pacing`) before any provider mutation, and MUST NOT silently coerce them to `even`. Package-level controls inside a seller-optimized buy are separate capabilities: package budget caps (seller_optimized_package_budgets), package minimum-spend targets (seller_optimized_min_spend_targets), and package pacing (seller_optimized_package_pacing). A seller declaring this feature but not one of those sub-capabilities MUST reject any request that would leave that package control on a seller-optimized buy with `UNSUPPORTED_FEATURE` before any over-subscription validation or provider mutation, and MUST NOT silently drop, soften, or coerce it. Over-subscription validation (`INVALID_REQUEST`) applies only to package controls the seller has declared; see seller_optimized_min_spend_targets. Product combinations may still be rejected when their currencies, optimization capabilities, pricing terms, or delivery constraints are incompatible. Sellers that do not declare this feature MUST reject any request carrying `budget_allocation.mode: 'seller_optimized'` with `UNSUPPORTED_FEATURE` before any provider mutation, and MUST NOT coerce the request to fixed allocation."
        ),
    ] = None
    seller_optimized_package_budgets: Annotated[
        StrictBool | None,
        Field(
            description='Honors package `budget` as an optional hard lifetime package spend cap inside a seller-optimized buy: packages[].budget and new_packages[].budget on create_media_buy and update_media_buy, purchases[].budget on buy_products, package budget controls on control_media_buy, and max_spend_percentage on seller-optimized proposal allocations. The cap is a ceiling, not a reserved or current allocation, and package caps may sum above total_budget. Meaningful only with seller_optimized_budget: true; seller declarations may be true only with seller_optimized_budget: true, while buyer required_features filters may request this feature alone. A seller that declares seller_optimized_budget without this feature MUST reject a request that would leave a package budget on a seller-optimized buy, including an allocation-mode switch that retains fixed-mode package budgets (the buyer clears them with null in the same atomic update), with `UNSUPPORTED_FEATURE` before any over-subscription validation or provider mutation, and MUST NOT issue seller-optimized proposals carrying max_spend_percentage. Does not govern fixed allocation, where package budgets remain required.'
        ),
    ] = None
    seller_optimized_min_spend_targets: Annotated[
        StrictBool | None,
        Field(
            description='Honors package `min_spend_target` as a soft lifetime minimum-spend target inside a seller-optimized buy: packages[].min_spend_target and new_packages[].min_spend_target on create_media_buy and update_media_buy, purchases[].min_spend_target on buy_products, package min_spend_target controls on control_media_buy, and min_spend_target_percentage on seller-optimized proposal allocations. The seller SHOULD attempt to deliver at least the target before allocating incremental spend elsewhere; it is not a billing or delivery guarantee. Meaningful only with seller_optimized_budget: true; seller declarations may be true only with seller_optimized_budget: true, while buyer required_features filters may request this feature alone. Sellers declaring this feature MUST reject package minimum-spend targets summing above total_budget with `INVALID_REQUEST` before mutation, and, when they also declare seller_optimized_package_budgets, MUST likewise reject a min_spend_target above its own package budget. A seller that declares seller_optimized_budget without this feature MUST reject a request carrying a numeric min_spend_target with `UNSUPPORTED_FEATURE` before any over-subscription validation or provider mutation, so an over-subscribed target sent to such a seller yields `UNSUPPORTED_FEATURE`, and MUST NOT issue seller-optimized proposals carrying min_spend_target_percentage.'
        ),
    ] = None
    seller_optimized_package_pacing: Annotated[
        StrictBool | None,
        Field(
            description='Honors package `pacing` as subordinate per-package pacing inside a seller-optimized buy, in addition to the media-buy-level pacing covered by seller_optimized_budget: packages[].pacing and new_packages[].pacing on create_media_buy and update_media_buy, purchases[].pacing on buy_products, package pacing controls on control_media_buy, and allocation pacing on seller-optimized proposals. Package pacing MUST NOT cause delivery to exceed aggregate media-buy pacing. Meaningful only with seller_optimized_budget: true; seller declarations may be true only with seller_optimized_budget: true, while buyer required_features filters may request this feature alone. Package pacing equal to the effective media-buy pacing adds no subordinate constraint and does not require this feature; buyers SHOULD omit package pacing on seller-optimized buys unless this feature is advertised. A seller that declares seller_optimized_budget without this feature MUST reject a request that would leave package pacing differing from media-buy pacing on a seller-optimized buy, including an allocation-mode switch that retains such fixed-mode package pacing (the buyer can align it in the same update), with `UNSUPPORTED_FEATURE` before any provider mutation, and MUST NOT issue seller-optimized proposals carrying allocation pacing. Does not govern package pacing in fixed allocation.'
        ),
    ] = None
    bidding_policy: Annotated[
        bidding_policy_capability.BiddingPolicyCapability | None,
        Field(
            description='Structured support for canonical bidding by authored scope, allocation context, mode, strength, and strength-qualified multi-field combination. Presence does not imply support for both scopes, both allocation modes, or every policy shape. Sellers MUST preserve every advertised semantic exactly and reject unadvertised policies rather than translating them.'
        ),
    ] = 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

Class variables

var bidding_policy : BiddingPolicyCapability | None

var canonical_creatives : bool | None

var catalog_item_availability_updates : bool | None

var catalog_management : bool | None

var committed_metrics_supported : bool | None

var model_config

var property_list_filtering : bool | None

var seller_optimized_budget : bool | None

var seller_optimized_min_spend_targets : bool | None

var seller_optimized_package_budgets : bool | None

var seller_optimized_package_pacing : bool | None

Instance variables

var inline_creative_management : bool | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class MediaBuyStatus (*args, **kwds)

Expand source code

class MediaBuyStatus(StrEnum):
    pending_creatives = 'pending_creatives'
    pending_start = 'pending_start'
    active = 'active'
    paused = 'paused'
    completed = 'completed'
    rejected = 'rejected'
    canceled = 'canceled'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var active

var canceled

var completed

var paused

var pending_creatives

var pending_start

var rejected

class MediaBuyValidAction (*args, **kwds)

Expand source code

class MediaBuyValidAction(StrEnum):
    pause = 'pause'
    resume = 'resume'
    cancel = 'cancel'
    update_name = 'update_name'
    extend_flight = 'extend_flight'
    shorten_flight = 'shorten_flight'
    update_flight_dates = 'update_flight_dates'
    increase_budget = 'increase_budget'
    decrease_budget = 'decrease_budget'
    reallocate_budget = 'reallocate_budget'
    update_budget_allocation = 'update_budget_allocation'
    update_targeting = 'update_targeting'
    update_pacing = 'update_pacing'
    update_bidding = 'update_bidding'
    update_frequency_caps = 'update_frequency_caps'
    replace_creative = 'replace_creative'
    update_creative_assignments = 'update_creative_assignments'
    remove_creative = 'remove_creative'
    add_packages = 'add_packages'
    remove_packages = 'remove_packages'
    update_budget = 'update_budget'
    update_dates = 'update_dates'
    update_packages = 'update_packages'
    sync_creatives = 'sync_creatives'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var add_packages

var cancel

var decrease_budget

var extend_flight

var increase_budget

var pause

var reallocate_budget

var remove_creative

var remove_packages

var replace_creative

var resume

var shorten_flight

var sync_creatives

var update_bidding

var update_budget

var update_budget_allocation

var update_creative_assignments

var update_dates

var update_flight_dates

var update_frequency_caps

var update_name

var update_pacing

var update_packages

var update_targeting

class MediaChannel (*args, **kwds)

Expand source code

class MediaChannel(StrEnum):
    display = 'display'
    olv = 'olv'
    social = 'social'
    search = 'search'
    ctv = 'ctv'
    linear_tv = 'linear_tv'
    radio = 'radio'
    streaming_audio = 'streaming_audio'
    podcast = 'podcast'
    dooh = 'dooh'
    ooh = 'ooh'
    print = 'print'
    cinema = 'cinema'
    email = 'email'
    gaming = 'gaming'
    retail_media = 'retail_media'
    influencer = 'influencer'
    affiliate = 'affiliate'
    product_placement = 'product_placement'
    sponsored_intelligence = 'sponsored_intelligence'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var affiliate

var cinema

var ctv

var display

var dooh

var email

var gaming

var influencer

var linear_tv

var olv

var ooh

var podcast

var print

var product_placement

var radio

var retail_media

var search

var social

var sponsored_intelligence

var streaming_audio

class MediaSubAsset (*args: object, **kwargs: object)

Expand source code

class MediaSubAsset:
    """Removed from ADCP schema. Previously SubAsset with asset_kind='media'."""

    def __init__(self, *args: object, **kwargs: object) -> None:
        raise TypeError(
            "MediaSubAsset was removed from the ADCP schema. There is no direct replacement."
        )

Removed from ADCP schema. Previously SubAsset with asset_kind='media'.

class Member (**data: Any)

Expand source code

class Member(BaseModel):
    """An organization registered in the AAO member directory."""

    model_config = ConfigDict(extra="allow")

    id: str
    slug: str
    display_name: str
    description: str | None = None
    tagline: str | None = None
    logo_url: str | None = None
    logo_light_url: str | None = None
    logo_dark_url: str | None = None
    contact_email: str | None = None
    contact_website: str | None = None
    offerings: list[str] = Field(default_factory=list)
    markets: list[str] = Field(default_factory=list)
    agents: list[dict[str, Any]] = Field(default_factory=list)
    brands: list[dict[str, Any]] = Field(default_factory=list)
    is_public: bool = True
    is_founding_member: bool = False
    featured: bool = False
    si_enabled: bool = False

An organization registered in the AAO member directory.

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 agents : list[dict[str, typing.Any]]

var brands : list[dict[str, typing.Any]]

var contact_email : str | None

var contact_website : str | None

var description : str | None

var display_name : str

var featured : bool

var id : str

var is_founding_member : bool

var is_public : bool

var logo_dark_url : str | None

var logo_light_url : str | None

var logo_url : str | None

var markets : list[str]

var model_config

var offerings : list[str]

var si_enabled : bool

var slug : str

var tagline : str | None

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.

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

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 PixelTrackerMethod (*args, **kwds)

Expand source code

class Method(StrEnum):
    img = 'img'
    js = 'js'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var img

var js

class MetricType (*args, **kwds)

Expand source code

class MetricType(StrEnum):
    overall_performance = 'overall_performance'
    conversion_rate = 'conversion_rate'
    brand_lift = 'brand_lift'
    click_through_rate = 'click_through_rate'
    completion_rate = 'completion_rate'
    viewability = 'viewability'
    brand_safety = 'brand_safety'
    cost_efficiency = 'cost_efficiency'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var brand_lift

var brand_safety

var click_through_rate

var completion_rate

var conversion_rate

var cost_efficiency

var overall_performance

var viewability

class ReportingConsumerMismatchCode (*args, **kwds)

Expand source code

class MismatchCode(StrEnum):
    scope_media_buy_missing = 'scope_media_buy_missing'
    coverage_short = 'coverage_short'
    metric_missing = 'metric_missing'
    schema_nonconformant = 'schema_nonconformant'
    currency_mismatch = 'currency_mismatch'
    period_mismatch = 'period_mismatch'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var coverage_short

var currency_mismatch

var metric_missing

var period_mismatch

var schema_nonconformant

var scope_media_buy_missing

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.

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

• 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 ReportingObligationCounts (**data: Any)

Expand source code

class ObligationCounts(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    total: Annotated[SchemaInt, Field(ge=0)]
    waiting: Annotated[SchemaInt, Field(ge=0)]
    healthy: Annotated[SchemaInt, Field(ge=0)]
    delayed: Annotated[SchemaInt, Field(ge=0)]
    action_required: Annotated[SchemaInt, Field(ge=0)]
    complete: Annotated[SchemaInt, Field(ge=0)]
    consumer_status_pending: Annotated[
        SchemaInt | None,
        Field(
            description="Obligations in this scope whose elapsed expected period has passed its consumer-status deadline — expected_at plus automated_recovery_window_seconds — without a current consumer status from the authenticated caller. A chain with any unsuperseded leaf counts as current whatever that leaf says; only an empty chain is pending. Because it counts obligations, a period the seller omitted entirely has no obligation and is not counted here — the buyer's independently derived denominator, not this field, remains the authority on omitted periods. It is a visibility count over the caller's own silence, never a health input: it MUST NOT change health, any other count, or seller-advertised reliability_statistics, and it overlaps the health counts rather than partitioning them. Required when the seller advertises consumer_status_task.",
            ge=0,
        ),
    ] = 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

Class variables

var action_required : int

var complete : int

var consumer_status_pending : int | None

var delayed : int

var healthy : int

var model_config

var total : int

var waiting : int

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class TmpOffer (**data: Any)

Expand source code

class Offer(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description='Package identifier from the media buy.')]
    seller_agent: Annotated[
        seller_agent_ref.SellerAgentReference | None,
        Field(
            description="Optional echo of the package's seller agent from sync-time metadata. Provided for publisher-side observability so log pipelines can attribute offers to sellers without round-tripping to the media-buy store. Non-authoritative: the binding on the cached AvailablePackage is source of truth. When omitted, the router MAY stamp this field from its cached package→seller map."
        ),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand for this offer. Required when the product allows dynamic brands (brand selected at match time rather than fixed on the package). For single-brand packages, the brand is already known from the media buy.'
        ),
    ] = None
    price: Annotated[
        offer_price.OfferPrice | None,
        Field(
            description='Price for this offer. Only present when the product supports variable pricing. For fixed-price packages, price is already set on the media buy.'
        ),
    ] = None
    summary: Annotated[
        str | None,
        Field(
            description="Buyer-generated description of the offer, for the publisher to judge relevance. E.g., '50% off Goldenfield mayo — recipe integration'. The publisher (or their AI assistant) uses this to decide whether the offer fits the context."
        ),
    ] = None
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest | None,
        Field(
            description='Full creative details, inline. When present, the publisher has everything needed to render. Inline for small creatives (markdown, product card). For large creatives (VAST, video), the manifest references external assets via URLs.'
        ),
    ] = None
    creative_data: Annotated[
        dict[str, str] | None,
        Field(
            description="Optional free-form string enhancements for dynamic creative rendering, such as sponsor labels and promotion codes. The map has no protocol-level key registry or required keys: meanings are package-local, receivers MUST ignore unknown keys, and a missing key MUST NOT make an otherwise renderable offer fail. Required renderable content belongs in creative_manifest assets, so creative_data may complement but never replace a manifest's required assets. This is not ad-server macro substitution or attribution tracking; tracker URLs belong in creative_manifest assets and per-user exposure tracking uses TMPX."
        ),
    ] = 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

Class variables

var brand : BrandReference | None

var creative_data : dict[str, str] | None

var creative_manifest : CreativeManifest | None

var model_config

var package_id : str

var price : OfferPrice | None

var seller_agent : SellerAgentReference | None

var summary : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class OfferPrice (**data: Any)

Expand source code

class OfferPrice(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    amount: Annotated[
        StrictFloat, Field(description='Price amount in the specified currency', ge=0.0)
    ]
    currency: Annotated[
        str | None, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')
    ] = 'USD'
    model: Annotated[Model, Field(description='Pricing model for this offer')]

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

Class variables

var amount : float

var currency : str | None

var model : Model

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Offering (**data: Any)

Expand source code

class Offering(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    offering_id: Annotated[
        str,
        Field(
            description='Unique identifier for this offering. Used by hosts to reference specific offerings in si_get_offering calls.'
        ),
    ]
    name: Annotated[
        str,
        Field(
            description="Human-readable offering name (e.g., 'Winter Sale', 'Free Trial', 'Enterprise Platform')"
        ),
    ]
    description: Annotated[str | None, Field(description="Description of what's being offered")] = (
        None
    )
    tagline: Annotated[
        str | None, Field(description='Short promotional tagline for the offering')
    ] = None
    valid_from: Annotated[
        AwareDatetime | None,
        Field(
            description='When the offering becomes available. If not specified, offering is immediately available.'
        ),
    ] = None
    valid_to: Annotated[
        AwareDatetime | None,
        Field(
            description='When the offering expires. If not specified, offering has no expiration.'
        ),
    ] = None
    checkout_url: Annotated[
        AnyUrl | None,
        Field(
            description="URL for checkout/purchase flow when the brand doesn't support agentic checkout."
        ),
    ] = None
    landing_url: Annotated[
        AnyUrl | None,
        Field(
            description="Landing page URL for this offering. For catalog-driven creatives, this is the per-item click-through destination that platforms map to the ad's link-out URL. Every offering in a catalog should have a landing_url unless the format provides its own destination logic."
        ),
    ] = None
    assets: Annotated[
        list[offering_asset_group.OfferingAssetGroup] | None,
        Field(
            description='Structured asset groups for this offering. Each group carries a typed pool of creative assets (headlines, images, videos, etc.) identified by a group ID that matches format-level vocabulary.'
        ),
    ] = None
    geo_targets: Annotated[
        GeoTargets | None,
        Field(
            description="Geographic scope of this offering. Declares where the offering is relevant — for location-specific offerings such as job vacancies, in-store promotions, or local events. Platforms use this to target geographically appropriate audiences and to filter out offerings irrelevant to a user's location. Uses the same geographic structures as targeting_overlay in create_media_buy."
        ),
    ] = None
    keywords: Annotated[
        list[str] | None,
        Field(
            description='Keywords for matching this offering to user intent. Hosts use these for retrieval/relevance scoring.'
        ),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Categories this offering belongs to (e.g., 'measurement', 'identity', 'programmatic')"
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var assets : list[OfferingAssetGroup] | None

var categories : list[str] | None

var checkout_url : pydantic.networks.AnyUrl | None

var description : str | None

var ext : ExtensionObject | None

var geo_targets : GeoTargets | None

var keywords : list[str] | None

var landing_url : pydantic.networks.AnyUrl | None

var model_config

var name : str

var offering_id : str

var tagline : str | None

var valid_from : pydantic.types.AwareDatetime | None

var valid_to : pydantic.types.AwareDatetime | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class OfferingAssetConstraint (**data: Any)

Expand source code

class OfferingAssetConstraint(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_group_id: Annotated[
        str,
        Field(
            description="The asset group this constraint applies to. Values are canonical-format vocabulary — each declaration chooses its own group IDs (e.g., 'headlines', 'images', 'videos'). Buyers discover them through Product.format_options[], publisher adagents.json formats[], or creative.supported_formats[] according to context."
        ),
    ]
    asset_type: Annotated[
        asset_content_type.AssetContentType,
        Field(description='The expected content type for this group.'),
    ]
    required: Annotated[
        StrictBool | None,
        Field(
            description='Whether this asset group must be present in each offering. Defaults to true.'
        ),
    ] = True
    min_count: Annotated[
        SchemaInt | None, Field(description='Minimum number of items required in this group.', ge=1)
    ] = None
    max_count: Annotated[
        SchemaInt | None, Field(description='Maximum number of items allowed in this group.', ge=1)
    ] = None
    asset_requirements: Annotated[
        asset_requirements_1.AssetRequirements | None,
        Field(
            description='Technical requirements for each item in this group (e.g., max_length for text, min_width/aspect_ratio for images). Applies uniformly to all items in the group.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var asset_group_id : str

var asset_requirements : ImageAssetRequirements | VideoAssetRequirements | AudioAssetRequirements | TextAssetRequirements | MarkdownAssetRequirements | HtmlAssetRequirements | CssAssetRequirements | JavascriptAssetRequirements | VastAssetRequirements | DaastAssetRequirements | UrlAssetRequirements | WebhookAssetRequirements | None

var asset_type : AssetContentType

var ext : ExtensionObject | None

var max_count : int | None

var min_count : int | None

var model_config

var required : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class OfferingAssetGroup (**data: Any)

Expand source code

class OfferingAssetGroup(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_group_id: Annotated[
        str,
        Field(
            description="Identifies the creative role this group fills. Values are defined by each canonical format declaration's offering_asset_constraints — not protocol constants. Discover creative-agent declarations via get_adcp_capabilities creative.supported_formats[] and sales-product declarations via Product.format_options[] (e.g., 'headlines', 'images', or 'videos')."
        ),
    ]
    asset_type: Annotated[
        asset_content_type.AssetContentType,
        Field(description='The content type of all items in this group.'),
    ]
    items: Annotated[
        list[Items],
        Field(
            description='The assets in this group. Each item carries an `asset_type` discriminator that selects the matching asset schema. Note: the group-level `asset_type` declares the expected type; individual items must also self-tag so validators can narrow errors. Intentionally excludes `brief-asset` and `catalog-asset` — those are campaign-input metadata types, not delivery-ready creative assets suitable for a pooled offering group. See core/assets/asset-union.json for the full asset-variant union.',
            min_length=1,
        ),
    ]
    ext: ext_1.ExtensionObject | None = 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

Class variables

var asset_group_id : str

var asset_type : AssetContentType

var ext : ExtensionObject | None

var items : list[TextAsset | ImageAsset | VideoAsset | AudioAsset | UrlAsset | HtmlAsset | MarkdownAsset | VastAsset | DaastAsset | CssAsset | JavascriptAsset | ZipAsset | WebhookAsset]

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingOperationsContact (**data: Any)

Expand source code

class OperationsContact(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
        regex_engine="python-re",
    )
    url: Annotated[
        AnyUrl | None,
        Field(
            description='HTTPS page a human uses to open or track a reporting issue, such as a support portal or status page. Same hardened origin shape as the offering document URIs: never an IP literal, userinfo URL, loopback host, AdCP task endpoint, webhook target, or credentialed link.'
        ),
    ] = None
    email: Annotated[
        EmailStr | None,
        Field(
            description='Monitored operations mailbox for reporting escalations. A role address, not an individual.',
            max_length=254,
        ),
    ] = 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

Class variables

var email : pydantic.networks.EmailStr | None

var model_config

var url : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class OutcomeMeasurement (**data: Any)

Expand source code

class OutcomeMeasurement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        str,
        Field(
            description='Type of measurement',
            examples=['incremental_sales_lift', 'brand_lift', 'foot_traffic'],
        ),
    ]
    attribution: Annotated[
        str,
        Field(
            description='Attribution methodology',
            examples=['deterministic_purchase', 'probabilistic'],
        ),
    ]
    window: Annotated[
        duration.Duration | None,
        Field(
            description='Attribution window as a structured duration (e.g., {"interval": 30, "unit": "days"}).'
        ),
    ] = None
    reporting: Annotated[
        str,
        Field(
            description='Reporting frequency and format',
            examples=['weekly_dashboard', 'real_time_api'],
        ),
    ]

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

Class variables

var attribution : str

var model_config

var reporting : str

var type : str

var window : Duration | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Overlay (**data: Any)

Expand source code

class Overlay(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    id: Annotated[
        str,
        Field(
            description="Identifier for this overlay (e.g., 'play_pause', 'volume', 'publisher_logo', 'carousel_prev', 'carousel_next')"
        ),
    ]
    description: Annotated[
        str | None,
        Field(
            description='Human-readable explanation of what this overlay is and how buyers should account for it'
        ),
    ] = None
    visual: Annotated[
        Visual | None,
        Field(
            description='Optional visual reference for this overlay element. Useful for creative agents compositing previews and for buyers understanding what will appear over their content. Must include at least one of: url, light, or dark.'
        ),
    ] = None
    bounds: Annotated[
        Bounds,
        Field(
            description="Position and size of the overlay relative to the asset's own top-left corner. See 'unit' for coordinate interpretation."
        ),
    ]

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

Class variables

var bounds : Bounds

var description : str | None

var id : str

var model_config

var visual : Visual | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Pacing (*args, **kwds)

Expand source code

class Pacing(StrEnum):
    even = 'even'
    asap = 'asap'
    front_loaded = 'front_loaded'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var asap

var even

var front_loaded

class LegacyPackage (**data: Any)

Expand source code

class Package(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description="Seller's unique identifier for the package")]
    product_id: Annotated[
        str | None,
        Field(
            description="ID of the product this package is based on. For packages created from an explicit create_media_buy package request, sellers MUST echo the request package's product_id on every response package object that represents that requested package."
        ),
    ] = None
    audience_evidence_selections: Annotated[
        list[audience_evidence_selection.AudienceEvidenceSelection] | None,
        Field(
            description='Exact immutable audience-evidence snapshots that affected recommendation, eligibility, or package construction. A confirmed package MUST include a package_construction selection matching every buyer audience_evidence_pin and every snapshot used to satisfy package audience_evidence_requirements; this readback remains mandatory on subsequent package read surfaces. This is decision provenance only; applied targeting remains exclusively in targeting_overlay and targeting_resolution.demographics.',
            min_length=1,
        ),
    ] = None
    budget: Annotated[
        StrictFloat | None,
        Field(
            description='Hard lifetime spend cap for this package in the media-buy currency. Every selected pricing option in an AdCP-authored media buy MUST declare that same currency. In seller-optimized allocation mode this is a ceiling, not a current allocation. May be omitted when the package is bounded only by the shared media-buy total.',
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description='Soft lifetime spend target accepted for this package under seller-optimized budget allocation. This is an allocation preference, not a billing or delivery guarantee.',
            ge=0.0,
        ),
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="The hard package spend ceiling per shared media-buy cap day, in the media buy's currency. Sellers MUST echo this whenever a package daily cap is set. It is a subordinate ceiling, not a reserved or current allocation; the media buy's budget_cap_timezone defines its day boundary.",
            ge=0.0,
        ),
    ] = None
    pacing: pacing_1.Pacing | None = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="ID of the selected pricing option from the product's pricing_options array"
        ),
    ] = None
    bid_price: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy bidding representation. 3.2 sellers normalize accepted legacy input and SHOULD echo bidding instead. Removed in the next major.',
            ge=0.0,
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Package-authored bidding policy, echoed only when the buyer authored a package override. `{automatic:true}` is an explicit automatic-bidding override. Omission means the package inherits media-buy bidding or, when both scopes are absent, uses provider automatic delivery. Monetary fields are denominated in the media-buy currency. Sellers MUST NOT materialize inherited media-buy policy here.'
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description="Breakdown of the effective price for this package. On fixed-price packages, echoes the pricing option's breakdown. On auction packages, shows the clearing price breakdown including any commission or settlement terms."
        ),
    ] = None
    impressions: Annotated[
        StrictFloat | None, Field(description='Impression goal for this package', ge=0.0)
    ] = None
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description='Catalogs this package promotes. Each catalog MUST have a distinct type (e.g., one product catalog, one store catalog). This constraint is enforced at the application level — sellers MUST reject requests containing multiple catalogs of the same type with a validation_error. Echoed from the create_media_buy request.'
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format IDs supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it, including dual-emission cases where `format_option_refs` was the winning selector, so read surfaces preserve the original wire contract. Omitted means the request did not carry legacy format_ids unless the seller cannot reconstruct legacy requests created before this field was persisted.',
        ),
    ] = None
    format_option_refs: Annotated[
        list[format_option_ref.FormatOptionReference] | None,
        Field(
            description='Structured 3.1+ format option references supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it. Publisher-catalog-backed options are identified by `{ scope: "publisher", publisher_domain, format_option_id }`; product-local options are identified by `{ scope: "product", format_option_id }` and resolve only against this package\'s target product. Omitted means the request did not carry format_option_refs unless the seller cannot reconstruct legacy requests created before this field was persisted.',
            min_length=1,
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Direct canonical selector supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it, including informational-echo cases where `format_ids` was the winning selector, so read surfaces preserve the original wire contract.'
        ),
    ] = None
    params: Annotated[
        dict[str, Any] | None,
        Field(
            description='Parameters for the direct canonical selector in `format_kind`, echoed from the create_media_buy request whenever the request included it. Requires `format_kind`; omitted only when the request did not carry direct canonical params or when the seller cannot reconstruct legacy requests created before this field was persisted.'
        ),
    ] = None
    targeting_overlay: Annotated[
        targeting.TargetingOverlay | None,
        Field(
            description='Complete effective targeting accepted for this package, including targeting bound through configured product selection plus package-specific targeting. Sellers MUST echo an applied package frequency_cap independently from any MediaBuy root cap. Sellers MUST also echo placement, property, and collection selection so buyers can audit purchased inventory: placements via placement_selection, collections via collection_selection (the committed concrete selectors, materialized even when the selection was produced through collection_list references).'
        ),
    ] = None
    targeting_resolution: Annotated[
        package_targeting_resolution.PackageTargetingResolution | None,
        Field(
            description="Execution details for the package's accepted targeting. Sellers MUST include targeting_resolution.demographics whenever demographic targeting was requested or applied."
        ),
    ] = None
    measurement_terms: Annotated[
        measurement_terms_1.MeasurementTerms | None,
        Field(
            description="Agreed billing measurement and makegood terms for this package. Reflects what was negotiated — may differ from the buyer's proposal or the product's defaults. When present, these terms are binding for the package's duration."
        ),
    ] = None
    performance_standards: Annotated[
        list[performance_standard.PerformanceStandard] | None,
        Field(
            description='Agreed performance standards for this package. When any entry specifies a vendor, creatives assigned to this package MUST include corresponding tracker_script or tracker_pixel assets from that vendor.',
            min_length=1,
        ),
    ] = None
    committed_metrics: Annotated[
        list[committed_metric.CommittedMetric] | None,
        Field(
            description="The binding reporting contract for this package — what the seller has agreed to populate in delivery reports. Each entry carries an explicit `committed_at` timestamp, so the array also serves as the contract amendment ledger: day-1 commitments share `committed_at = create_media_buy.confirmed_at`; mid-flight additions carry their own timestamps. When `create_media_buy.confirmed_at` is null for a provisional buy, sellers MUST omit `committed_metrics` until commitment. The first response that sets `confirmed_at` MAY include the initial committed-metrics set, and each such entry's `committed_at` MUST equal `confirmed_at`. The `missing_metrics` field on `get_media_buy_delivery` reconciles against this list, filtering to entries where `committed_at < reporting_period.end` (a metric committed mid-flight is only audited from its commitment timestamp forward). Sellers stamp the day-1 set on the `create_media_buy` response; mid-flight additions are appended via `update_media_buy` (append-only — sellers MUST reject attempts to modify or remove existing entries with `validation_error`, suggested code: `IMMUTABLE_FIELD`). Optional in v1; absence means the seller does not provide an audit-grade contract and `missing_metrics` falls back to the product's live `available_metrics` (a known audit gap — buyers SHOULD treat absence as 'no audit-grade contract' rather than 'clean delivery'). Each entry uses an explicit `scope` discriminator: `standard` for entries from the closed `available-metric.json` enum, `vendor` for vendor-defined metrics anchored on a BrandRef. Standard entries are symmetric with `by_package[].metric_values`; vendor entries reconcile to `by_package[].vendor_metric_values`; both use `by_package[].missing_metrics` for gaps. The atomic key remains `(scope, metric_id, qualifier)`, with vendor identity included for vendor scope. Replaces the parallel-array design that shipped briefly in #3510.",
            examples=[
                [
                    {
                        'scope': 'standard',
                        'metric_id': 'impressions',
                        'committed_at': '2026-04-29T10:53:00Z',
                    },
                    {
                        'scope': 'standard',
                        'metric_id': 'spend',
                        'committed_at': '2026-04-29T10:53:00Z',
                    },
                    {
                        'scope': 'standard',
                        'metric_id': 'completed_views',
                        'committed_at': '2026-04-29T10:53:00Z',
                    },
                    {
                        'scope': 'vendor',
                        'vendor': {'domain': 'attentionvendor.example'},
                        'metric_id': 'attention_units',
                        'committed_at': '2026-04-29T10:53:00Z',
                    },
                    {
                        'scope': 'standard',
                        'metric_id': 'viewable_rate',
                        'qualifier': {'viewability_standard': 'mrc'},
                        'committed_at': '2026-05-30T14:22:00Z',
                    },
                ]
            ],
            min_length=1,
        ),
    ] = None
    creative_assignments: Annotated[
        list[creative_assignment.CreativeAssignment] | None,
        Field(
            description='Creative assets assigned to this package, including the committed package-scoped rotation policy. Omitted rotation_mode reads as weighted for backward compatibility; all assignments resolve to one effective mode, and sequential positions are unique within each package-local group.'
        ),
    ] = None
    formats_to_provide: Annotated[
        list[package_format_snapshot.PackageFormatSnapshot] | None,
        Field(
            description='Immutable canonical creative contracts established for this package. Each entry is a PackageFormatSnapshot of the selected effective Product format declaration. A package whose selected format carries tracker_execution_contract MUST retain and return this checklist even after creative coverage is complete; the live Product is never substituted for the package snapshot.',
            min_length=1,
        ),
    ] = None
    formats_pending: Annotated[
        list[package_format_snapshot.PackageFormatSnapshot] | None,
        Field(
            description='PackageFormatSnapshot entries from formats_to_provide that do not yet have creative coverage through sync_creatives or inline assignment. Every entry MUST equal its formats_to_provide snapshot after RFC 8785 canonicalization and, when product_snapshot_digest is present, carry the identical digest. An empty emitted array means every required format is covered. Absence means readiness was not reported.'
        ),
    ] = None
    format_ids_to_provide: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format projection of formats_to_provide retained for older 3.x peers. New sellers emit canonical formats_to_provide declarations.',
        ),
    ] = None
    format_ids_pending: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format projection of formats_pending retained for older 3.x peers. New sellers emit canonical formats_pending declarations. An empty emitted array means every projected requirement is covered. Absence means legacy readiness was not reported and MUST NOT be interpreted as full coverage.',
        ),
    ] = None
    optimization_goals: Annotated[
        list[optimization_goal.OptimizationGoal] | None,
        Field(
            description='Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.',
            min_length=1,
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Flight start date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's start_time. Sellers SHOULD always include the resolved value in responses, even when inherited."
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Flight end date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's end_time. Sellers SHOULD always include the resolved value in responses, even when inherited."
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(
            description='Whether this package is paused by the buyer. Paused packages do not deliver impressions. Defaults to false.'
        ),
    ] = False
    canceled: Annotated[
        StrictBool | None,
        Field(
            description='Whether this package has been canceled. Canceled packages stop delivery and cannot be reactivated. Defaults to false.'
        ),
    ] = False
    cancellation: Annotated[
        Cancellation | None,
        Field(description='Cancellation metadata. Present only when canceled is true.'),
    ] = None
    agency_estimate_number: Annotated[
        str | None,
        Field(
            description="Agency estimate or authorization number for this package. Echoed from the buyer's request. When present on the package, takes precedence over the media buy-level estimate number.",
            max_length=100,
        ),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp for creative upload or change deadline for this package. After this deadline, creative changes are rejected. When absent, the media buy's creative_deadline applies."
        ),
    ] = None
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque package-level correlation data echoed unchanged in responses, webhooks, and read surfaces. Buyers targeting mixed seller populations SHOULD include a per-package correlation value here, commonly context.buyer_ref, so responses from legacy sellers that do not echo product_id can still be mapped back to the requested product or line item. Sellers MUST preserve this object unchanged and MUST NOT parse it for business logic.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

• Package

Class variables

var agency_estimate_number : str | None

var audience_evidence_selections : list[AudienceEvidenceSelection] | None

var bid_price : float | None

var bidding : BiddingPolicy | None

var budget : float | None

var canceled : bool | None

var cancellation : Cancellation | None

var catalogs : list[Catalog] | None

var committed_metrics : list[CommittedMetric1 | CommittedMetric2] | None

var context : ContextObject | None

var creative_assignments : list[CreativeAssignment] | None

var creative_deadline : pydantic.types.AwareDatetime | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var format_ids : list[FormatReferenceStructuredObject] | None

var format_ids_pending : list[FormatReferenceStructuredObject] | None

var format_ids_to_provide : list[FormatReferenceStructuredObject] | None

var format_kind : str | None

var format_option_refs : list[FormatOptionReference1 | FormatOptionReference2] | None

var formats_pending : list[PackageFormatSnapshot18 | PackageFormatSnapshot19 | PackageFormatSnapshot20 | PackageFormatSnapshot21 | PackageFormatSnapshot22 | PackageFormatSnapshot23 | PackageFormatSnapshot24 | PackageFormatSnapshot25 | PackageFormatSnapshot26 | PackageFormatSnapshot27 | PackageFormatSnapshot28 | PackageFormatSnapshot29 | PackageFormatSnapshot30 | PackageFormatSnapshot31 | PackageFormatSnapshot32 | PackageFormatSnapshot33] | None

var formats_to_provide : list[PackageFormatSnapshot18 | PackageFormatSnapshot19 | PackageFormatSnapshot20 | PackageFormatSnapshot21 | PackageFormatSnapshot22 | PackageFormatSnapshot23 | PackageFormatSnapshot24 | PackageFormatSnapshot25 | PackageFormatSnapshot26 | PackageFormatSnapshot27 | PackageFormatSnapshot28 | PackageFormatSnapshot29 | PackageFormatSnapshot30 | PackageFormatSnapshot31 | PackageFormatSnapshot32 | PackageFormatSnapshot33] | None

var impressions : float | None

var measurement_terms : MeasurementTerms | None

var min_spend_target : float | None

var model_config

var optimization_goals : list[OptimizationGoal8 | OptimizationGoal9 | OptimizationGoal10] | None

var pacing : Pacing | None

var package_id : str

var params : dict[str, typing.Any] | None

var paused : bool | None

var performance_standards : list[PerformanceStandard] | None

var price_breakdown : PriceBreakdown | None

var pricing_option_id : str | None

var product_id : str | None

var start_time : pydantic.types.AwareDatetime | None

var targeting_overlay : TargetingOverlay | None

var targeting_resolution : PackageTargetingResolution | None

class MediaBuyPackage (**data: Any)

Expand source code

class Package(IndicatorBearingResourceState):
    model_config = ConfigDict(
        extra='allow',
    )
    indicator_types_evaluated: Annotated[
        list[IndicatorTypesEvaluatedEnum1] | None,
        Field(
            description='Indicator types covered by this snapshot. Required whenever indicators is present. Types omitted from this list remain unknown even when indicators is empty. Every returned indicator.type MUST appear in this list.',
            min_length=1,
        ),
    ] = None
    indicators: Annotated[
        list[Indicator1] | None,
        Field(
            description='Current seller assertions for the indicator types and publisher/placement coverage named by the sibling evaluation fields. Omitted means unknown or not evaluated. A present empty array means evaluated with no current assertion for indicator_types_evaluated in the evaluated scope.'
        ),
    ] = None
    package_id: Annotated[str, Field(description="Seller's package identifier")]
    product_id: Annotated[
        str | None,
        Field(
            description="Product identifier this package is purchased from. For packages created from an explicit create_media_buy package request, sellers MUST echo the request package's product_id on every response package object that represents that requested package."
        ),
    ] = None
    budget: Annotated[
        StrictFloat | None,
        Field(
            description='Hard lifetime package spend cap denominated in media_buy.currency. In seller-optimized mode this is not a current allocation.',
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description='Accepted soft lifetime spend target for this package under seller-optimized allocation.',
            ge=0.0,
        ),
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Current hard package spend ceiling per shared media-buy cap day, denominated in media_buy.currency. It is a subordinate ceiling, not a reserved allocation; media_buy.budget_cap_timezone defines the day boundary.',
            ge=0.0,
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description='Legacy/readback package denomination for buys created outside the canonical 3.2 path. For AdCP-authored media buys this MUST equal media_buy.currency; canonical package budget and BiddingPolicy values always use media_buy.currency. Snapshot currency may still identify externally reported spend denomination.',
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    bid_price: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy bid representation. 3.2 sellers SHOULD normalize and echo package.bidding instead.',
            ge=0.0,
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Package-authored bidding override. `{automatic:true}` explicitly overrides media_buy.bidding with provider automatic delivery. Omitted when this package inherits; sellers MUST NOT copy an inherited block here. Monetary fields use media_buy.currency.'
        ),
    ] = None
    optimization_goals: Annotated[
        list[optimization_goal.OptimizationGoal] | None,
        Field(
            description='Current package objective functions. Currency-bearing execution controls are returned separately in package.bidding or inherited from media_buy.bidding.',
            min_length=1,
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format IDs supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it, including dual-emission cases where another selector won precedence.',
            min_length=1,
        ),
    ] = None
    format_option_refs: Annotated[
        list[format_option_ref.FormatOptionReference] | None,
        Field(
            description='Structured 3.1+ format option references supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it.',
            min_length=1,
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Direct canonical selector supplied for this package on create_media_buy. Sellers SHOULD echo this field whenever the request included it, including informational-echo cases where another selector won precedence.'
        ),
    ] = None
    params: Annotated[
        dict[str, Any] | None,
        Field(
            description='Parameters for the direct canonical selector in `format_kind`, echoed from the create_media_buy request whenever the request included it. Requires `format_kind`.'
        ),
    ] = None
    impressions: Annotated[
        StrictFloat | None,
        Field(description='Goal impression count for impression-based packages', ge=0.0),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Package-level pacing preference. Under seller-optimized allocation this is subordinate to the media-buy aggregate pacing.'
        ),
    ] = None
    targeting_overlay: Annotated[
        targeting.TargetingOverlay | None,
        Field(
            description='Complete effective targeting applied to this package, including configured-product targeting and the most recent package-specific overlay. Sellers SHOULD echo persisted targeting so buyers can verify stored state without replaying requests. Sellers MUST echo geo_places and geo_places_exclude whenever either was persisted, including the exact applied system_version and normalized values, so buyers can audit catalog-backed targeting. Sellers using placement, property-list, or collection-list targeting MUST include the committed inventory selection here. placement_selection mode default SHOULD resolve to mode selected with committed refs when enumerable; collection_selection follows the same rule, materializing the committed selectors even when the selection was produced through collection_list references.'
        ),
    ] = None
    targeting_resolution: Annotated[
        package_targeting_resolution.PackageTargetingResolution | None,
        Field(
            description='Execution details for accepted package targeting. Sellers MUST include targeting_resolution.demographics whenever demographic targeting was requested or applied; its applied predicate and execution fields report the effective booked state.'
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 flight start time for this package. Use to determine whether the package is within its scheduled flight before interpreting delivery status.'
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None, Field(description='ISO 8601 flight end time for this package')
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(description='Whether this package is currently paused by the buyer'),
    ] = None
    canceled: Annotated[
        StrictBool | None,
        Field(
            description='Whether this package has been canceled. Canceled packages stop delivery and cannot be reactivated.'
        ),
    ] = None
    cancellation: Annotated[
        Cancellation1 | None,
        Field(description='Cancellation metadata. Present only when canceled is true.'),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp for creative upload or change deadline for this package. After this deadline, creative changes are rejected. When absent, the media buy's creative_deadline applies."
        ),
    ] = None
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque package-level correlation data echoed unchanged from the create_media_buy package request. Sellers MUST include persisted package context on read surfaces when the package was created through AdCP with context, so buyers can reconcile seller-assigned package_id values with their own line items; this is the legacy-safe fallback when an older seller did not echo product_id on the create response. Sellers MAY omit context for packages created outside AdCP or created without context. Sellers MUST NOT parse this object for business logic.'
        ),
    ] = None
    creative_approvals: Annotated[
        list[CreativeApproval] | None,
        Field(
            description='Approval status for each creative assigned to this package. Absent when no creatives have been assigned.'
        ),
    ] = None
    formats_to_provide: Annotated[
        list[package_format_snapshot.PackageFormatSnapshot] | None,
        Field(
            description='The immutable PackageFormatSnapshot checklist established for this package at booking time. Contract-bearing snapshots remain present after creative coverage is complete so readback, assignment, and serving never fall back to a mutable live Product declaration.',
            min_length=1,
        ),
    ] = None
    formats_pending: Annotated[
        list[package_format_snapshot.PackageFormatSnapshot] | None,
        Field(
            description='PackageFormatSnapshot entries from formats_to_provide that do not yet have creative coverage. Each entry MUST be canonically equal to the corresponding checklist snapshot and, when product_snapshot_digest is present, carry the identical digest. An empty emitted array means all requirements are covered; absence means readiness was not reported.'
        ),
    ] = None
    format_ids_to_provide: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format projection of formats_to_provide retained for older 3.x peers. New sellers emit canonical formats_to_provide declarations.',
        ),
    ] = None
    format_ids_pending: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='**DEPRECATED in 3.2.** Legacy named-format projection of formats_pending retained for older 3.x peers. New sellers emit canonical formats_pending declarations. An empty emitted array means every projected requirement is covered. Absence means legacy readiness was not reported and MUST NOT be interpreted as full coverage.',
        ),
    ] = None
    snapshot_unavailable_reason: Annotated[
        snapshot_unavailable_reason_1.SnapshotUnavailableReason | None,
        Field(
            description='Machine-readable reason the snapshot is omitted. Present only when include_snapshot was true and snapshot is unavailable for this package.'
        ),
    ] = None
    snapshot: Annotated[
        Snapshot | None,
        Field(
            description='Near-real-time delivery snapshot for this package. Only present when include_snapshot was true in the request. Represents the latest available entity-level stats from the platform — not billing-grade data.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

• IndicatorBearingResourceState
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• MediaBuyPackage

Class variables

var bid_price : float | None

var bidding : BiddingPolicy | None

var budget : float | None

var canceled : bool | None

var cancellation : Cancellation1 | None

var context : ContextObject | None

var creative_approvals : list[CreativeApproval] | None

var creative_deadline : pydantic.types.AwareDatetime | None

var currency : str | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var format_ids : list[FormatReferenceStructuredObject] | None

var format_ids_pending : list[FormatReferenceStructuredObject] | None

var format_ids_to_provide : list[FormatReferenceStructuredObject] | None

var format_kind : str | None

var format_option_refs : list[FormatOptionReference1 | FormatOptionReference2] | None

var formats_pending : list[PackageFormatSnapshot18 | PackageFormatSnapshot19 | PackageFormatSnapshot20 | PackageFormatSnapshot21 | PackageFormatSnapshot22 | PackageFormatSnapshot23 | PackageFormatSnapshot24 | PackageFormatSnapshot25 | PackageFormatSnapshot26 | PackageFormatSnapshot27 | PackageFormatSnapshot28 | PackageFormatSnapshot29 | PackageFormatSnapshot30 | PackageFormatSnapshot31 | PackageFormatSnapshot32 | PackageFormatSnapshot33] | None

var formats_to_provide : list[PackageFormatSnapshot18 | PackageFormatSnapshot19 | PackageFormatSnapshot20 | PackageFormatSnapshot21 | PackageFormatSnapshot22 | PackageFormatSnapshot23 | PackageFormatSnapshot24 | PackageFormatSnapshot25 | PackageFormatSnapshot26 | PackageFormatSnapshot27 | PackageFormatSnapshot28 | PackageFormatSnapshot29 | PackageFormatSnapshot30 | PackageFormatSnapshot31 | PackageFormatSnapshot32 | PackageFormatSnapshot33] | None

var impressions : float | None

var indicator_types_evaluated : list[IndicatorTypesEvaluatedEnum1] | None

var indicators : list[Indicator1] | None

var min_spend_target : float | None

var model_config

var optimization_goals : list[OptimizationGoal8 | OptimizationGoal9 | OptimizationGoal10] | None

var pacing : Pacing | None

var package_id : str

var params : dict[str, typing.Any] | None

var paused : bool | None

var product_id : str | None

var snapshot : Snapshot | None

var snapshot_unavailable_reason : SnapshotUnavailableReason | None

var start_time : pydantic.types.AwareDatetime | None

var targeting_overlay : TargetingOverlay | None

var targeting_resolution : PackageTargetingResolution | None

class Package (**data: Any)

Expand source code

class Package(_LegacyPackage, CanonicalBoundaryModel):
    """Canonical package; legacy format identity is absent."""

    if TYPE_CHECKING:  # the removed fields, hidden from the constructor too
        format_ids: _RemovedFormatIds = Field(default=None, init=False)
        format_ids_pending: _RemovedFormatIds = Field(default=None, init=False)
        format_ids_to_provide: _RemovedFormatIds = Field(default=None, init=False)

Canonical package; legacy format identity is absent.

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

• Package
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var format_ids : list[FormatReferenceStructuredObject] | None

var format_ids_pending : list[FormatReferenceStructuredObject] | None

var format_ids_to_provide : list[FormatReferenceStructuredObject] | None

var model_config

Instance variables

var bid_price : float | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

Inherited members

• Package:
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class LegacyPackageRequest (**data: Any)

Expand source code

class PackageRequest(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    product_id: Annotated[
        str,
        Field(
            description="Opaque configured product ID returned by get_products. Selecting it accepts the product's disclosed targeting_resolution, pricing, forecast assumptions, and terms. Sellers MUST echo this value on every response package object that represents this requested package."
        ),
    ]
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format selector retained for older 3.x peers. New buyers MUST NOT emit this field. Sellers MUST normalize every entry through the canonical mapping path before product satisfaction checks; an entry that cannot be normalized is rejected with `UNSUPPORTED_FEATURE` before any equivalence check. When this field coexists with `format_option_refs` or `format_kind` plus `params`, sellers MUST compare the product option sets selected by each resolved route. Legacy parameter compatibility follows the asymmetric v2-narrows-v1 relation defined by canonical formats, not raw object equality. Different format shapes, selected option sets, or incompatible dimensions are rejected with `CONFLICTING_SELECTORS`; sellers MUST NOT silently ignore the legacy projection. Equivalent dual emission remains valid during the 3.x compatibility window. If omitted and no canonical selector is present, all formats supported by the product are active.',
            min_length=1,
        ),
    ] = None
    format_option_refs: Annotated[
        list[format_option_ref.FormatOptionReference] | None,
        Field(
            description='Canonical 3.2 format-option selector. Each reference matches one target product `format_options[]` entry. Publisher-backed options match `{ scope: "publisher", publisher_domain, format_option_id }`; product-local options match `{ scope: "product", format_option_id }`. Sellers reject unresolved options with `UNSUPPORTED_FEATURE` and a field path to the failing entry before comparing co-present routes. New buyers MUST use this route by itself and MUST NOT dual-emit either a direct canonical selector or deprecated `format_ids`. Receivers handling older 3.x multi-route requests MUST resolve every present route, require each route to select the same product option set, and reject disagreement with `CONFLICTING_SELECTORS` before treating `format_option_refs` as authoritative.',
            min_length=1,
        ),
    ] = None
    format_kind: Annotated[
        str | None,
        Field(
            description='Canonical 3.2 direct selector. Names the canonical format shape this package targets when the buyer is not selecting a published `format_option_ref`. Pair with `params` for dimensions, duration, codecs, or other constraints. New buyers MUST NOT combine this route with `format_option_refs` or deprecated `format_ids`. Receivers handling older 3.x multi-route requests MUST equivalence-check every present route before applying precedence and reject disagreement with `CONFLICTING_SELECTORS`. Product satisfaction is directional: broad `{ format_kind: "image" }` does not satisfy a fixed-size product declaration.'
        ),
    ] = None
    params: Annotated[
        dict[str, Any] | None,
        Field(
            description="Parameters for the direct canonical selector in `format_kind`. Shape follows the selected canonical's parameter vocabulary: dimensions (`width`, `height`, `sizes`), duration (`duration_ms_exact`, `duration_ms_range`), codecs, asset-source and slot narrowing, or other canonical-specific constraints. Requires `format_kind`. For fixed-size image selectors, `width` and `height` MUST co-occur; a selector containing only one dimension is schema-invalid. New buyers omit `params` when selecting by `format_option_refs` or `format_ids`; older multi-route requests are accepted only when every route selects the same product option set."
        ),
    ] = None
    budget: Annotated[
        StrictFloat | None,
        Field(
            description="Hard lifetime spend cap for this package in the media buy's currency. Required in fixed allocation mode. Optional in seller-optimized mode; when omitted, the package is bounded by the shared total_budget and any other package constraints. In seller-optimized mode this is a ceiling, not a reserved or current allocation, and requires advertised media_buy.features.seller_optimized_package_budgets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.",
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description="Soft lifetime spend target for this package in the media buy's currency. Only valid with seller-optimized budget allocation. Requires advertised media_buy.features.seller_optimized_min_spend_targets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation. The seller SHOULD attempt to deliver at least this amount before allocating incremental spend elsewhere, but inventory, policy, optimization targets, or other delivery constraints may prevent it. This is not a billing guarantee. Must not exceed the package budget when both are present; a seller advertising both seller_optimized_min_spend_targets and seller_optimized_package_budgets MUST reject a violation with `INVALID_REQUEST`, while a seller missing either capability rejects the undeclared control with UNSUPPORTED_FEATURE before any over-subscription validation.",
            ge=0.0,
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Package pacing, subordinate to media-buy pacing. In seller-optimized mode, pacing that differs from the media-buy pacing requires advertised media_buy.features.seller_optimized_package_pacing; otherwise rejected with UNSUPPORTED_FEATURE.'
        ),
    ] = None
    pricing_option_id: Annotated[
        str,
        Field(
            description="ID of the selected pricing option from the product's pricing_options array"
        ),
    ]
    bid_price: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Use bidding.bid_amount or bidding.max_bid. Legacy normalization: selected pricing_option.max_bid=true maps to bidding.max_bid; otherwise maps to bidding.bid_amount. A package MUST NOT supply both representations.',
            ge=0.0,
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Package-authored bidding policy. This complete block replaces, rather than field-merges with, any media-buy bidding policy for this package. `{automatic:true}` explicitly overrides a media-buy policy with provider automatic bidding; omission inherits the complete media-buy block. Monetary fields use the media-buy currency, while the selected pricing option supplies only the auction unit and MUST declare that same currency. Sellers MUST reject a new bidding block combined with legacy bid_price or legacy monetary optimization-goal targets on the same effective package with AMBIGUOUS_BIDDING_POLICY.'
        ),
    ] = None
    impressions: Annotated[
        StrictFloat | None, Field(description='Impression goal for this package', ge=0.0)
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Optional hard package daily spend ceiling in the media-buy currency. It is subordinate, not a reserved allocation; package caps need not sum to the aggregate cap. Uses the media buy's cap timezone. Requires advertised package budget-capping scope; otherwise rejected with UNSUPPORTED_FEATURE.",
            ge=0.0,
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Flight start date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's start_time. Must fall within the media buy's date range."
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Flight end date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's end_time. Must fall within the media buy's date range."
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(
            description='Whether this package should be created in a paused state. Paused packages do not deliver impressions. Defaults to false.'
        ),
    ] = False
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description='Catalogs this package promotes. Each catalog MUST have a distinct type (e.g., one product catalog, one store catalog). This constraint is enforced at the application level — sellers MUST reject requests containing multiple catalogs of the same type with a validation_error. Makes the package catalog-driven: one budget envelope, platform optimizes across items.'
        ),
    ] = None
    optimization_goals: Annotated[
        list[optimization_goal.OptimizationGoal] | None,
        Field(
            description='Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.',
            min_length=1,
        ),
    ] = None
    targeting_overlay: Annotated[
        targeting_input.TargetingOverlayInput | None,
        Field(
            description="Optional package-specific targeting input with three states per dimension. Omission inherits targeting already bound to the configured product, a non-null value replaces that dimension, and null explicitly suppresses the configured/product default for that dimension. Null cannot remove inherent product scope: sellers reject a clear the product cannot execute rather than silently retaining the default. Non-null fields MUST be declared in the product's overlay_support unless they were already accepted during discovery. The one fixed-inventory restatement exception is placement_selection equal to the product's complete, explicitly enumerated mode: included placement set: that set is an inherent exact match across discovery, create, and update and does not require overlay_support.placement_selection; partial selection still requires a selectable product. Opaque property_list and collection_list references have no equivalent exception because their membership can change independently and cannot be proven equal from the product wire representation. Package readback echoes the complete effective targeting without null dimensions. A supported value with no current inventory returns PRODUCT_UNAVAILABLE rather than a silent substitute or reprice."
        ),
    ] = None
    audience_evidence_requirements: Annotated[
        audience_evidence_requirements_1.AudienceEvidenceRequirements | None,
        Field(
            description='Buyer policy that the selected product and constructed package MUST satisfy using product audience evidence. This remains planning and suitability evidence, not a targeting instruction. Sellers MUST reject an unsatisfied required policy rather than silently drop it, and a confirmed package MUST include every evidence snapshot used to satisfy this policy in audience_evidence_selections with decision_use package_construction.'
        ),
    ] = None
    audience_evidence_pins: Annotated[
        list[audience_evidence_pin.AudienceEvidencePin] | None,
        Field(
            description="Exact immutable evidence snapshots selected by the buyer during discovery. The seller MUST match evidence_id, snapshot_id, version, and content_digest against one published snapshot and MUST reject catalog mutation, snapshot reuse, missing snapshots, or substitutions. Every accepted pin MUST be echoed in the confirmed package's audience_evidence_selections with decision_use package_construction.",
            min_length=1,
        ),
    ] = None
    measurement_terms: Annotated[
        measurement_terms_1.MeasurementTerms | None,
        Field(
            description="Buyer's proposed billing measurement and makegood terms. Overrides product defaults. Seller accepts (echoed on confirmed package), rejects with TERMS_REJECTED, or adjusts. When absent, product's measurement_terms apply."
        ),
    ] = None
    performance_standards: Annotated[
        list[performance_standard.PerformanceStandard] | None,
        Field(
            description="Buyer's proposed performance standards for this package. Overrides product defaults. Seller accepts, rejects with TERMS_REJECTED, or adjusts. When absent, product's performance_standards apply.",
            min_length=1,
        ),
    ] = None
    committed_metrics: Annotated[
        list[CommittedMetrics] | None,
        Field(
            description="Buyer's proposed reporting contract for this package — the metrics the buyer wants the seller to commit to populating in delivery reports. Same negotiation pattern as `measurement_terms` and `performance_standards`: seller accepts (echoes on confirmed package with `committed_at` stamped), rejects with `TERMS_REJECTED` (with explanation of which entries were unworkable), or normalizes (echoes a different but compatible list — buyer can accept by retrying with the normalized terms). When absent, the seller decides what to commit based on the product's `available_metrics` and the buyer's `required_metrics` filter on `get_products`. Each entry uses an explicit `scope` discriminator (`standard` or `vendor`) and identifies the metric — request-side entries do NOT carry `committed_at`; that timestamp is stamped by the seller on accept. Constraints on what the buyer MAY propose: each `scope: standard` entry's `metric_id` MUST be in the product's `available_metrics`, and each `scope: vendor` entry's `(vendor, metric_id)` MUST appear in the product's `vendor_metrics` — sellers SHOULD reject with `TERMS_REJECTED` and reference the offending entry when the proposal exceeds product capability.",
            min_length=1,
        ),
    ] = None
    creative_assignments: Annotated[
        list[creative_assignment.CreativeAssignment] | None,
        Field(
            description='Assign existing library creatives to this package with optional rotation, grouping, weights, and placement targeting. rotation_mode is package-scoped: omission resolves to weighted, and every assignment MUST resolve to the same effective mode. In sequential mode, sequence_position MUST be unique within each package-local group. Sellers reject conflicts with VALIDATION_ERROR before creating the package.',
            min_length=1,
        ),
    ] = None
    creatives: Annotated[
        Sequence[creative_asset.CreativeAsset] | None,
        Field(
            description="Upload creative assets inline and assign to this package. Native localization is not accepted on this path; use sync_creatives before assigning the library creative. When the seller also advertises creative.has_creative_library: true, these creatives enter the seller's creative library and can be reused by creative_id while retained; inline-only sellers may store them as package-scoped assets. Use creative_assignments instead for existing library creatives.",
            max_length=100,
            min_length=1,
        ),
    ] = None
    agency_estimate_number: Annotated[
        str | None,
        Field(
            description='Agency estimate or authorization number for this package. Overrides the media buy-level estimate number when different packages correspond to different agency estimates (e.g., different stations or flights within the same buy).',
            max_length=100,
        ),
    ] = None
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque package-level correlation data echoed unchanged in the package response, webhooks, and read surfaces. Buyers targeting mixed seller populations SHOULD include a per-package correlation value here, commonly context_1.buyer_ref, so responses from legacy sellers that do not echo product_id can still be mapped back to the requested product or line item. Do not use deprecated top-level buyer_ref for v3 correlation.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _validate_format_params(self) -> PackageRequest:
        if self.params is not None and self.format_kind is None:
            raise ValueError('params requires format_kind')
        if self.params is not None and self.format_kind == 'image':
            if ('width' in self.params) != ('height' in self.params):
                raise ValueError('image params width and height must co-occur')
        return self

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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• PackageRequest

Class variables

var agency_estimate_number : str | None

var audience_evidence_pins : list[AudienceEvidencePin] | None

var audience_evidence_requirements : AudienceEvidenceRequirements | None

var bidding : BiddingPolicy | None

var budget : float | None

var catalogs : list[Catalog] | None

var committed_metrics : list[CommittedMetrics1 | CommittedMetrics2] | None

var context : ContextObject | None

var creative_assignments : list[CreativeAssignment] | None

var creatives : collections.abc.Sequence[CreativeAsset] | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var format_kind : str | None

var format_option_refs : list[FormatOptionReference1 | FormatOptionReference2] | None

var impressions : float | None

var measurement_terms : MeasurementTerms | None

var min_spend_target : float | None

var model_config

var optimization_goals : list[OptimizationGoal8 | OptimizationGoal9 | OptimizationGoal10] | None

var pacing : Pacing | None

var params : dict[str, typing.Any] | None

var paused : bool | None

var performance_standards : list[PerformanceStandard] | None

var pricing_option_id : str

var product_id : str

var start_time : pydantic.types.AwareDatetime | None

var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var bid_price : float | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var format_ids : list[FormatReferenceStructuredObject] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class PackageRequest (**data: Any)

Expand source code

class PackageRequest(_LegacyPackageRequest, CanonicalBoundaryModel):
    """Canonical package request preserving beta.3 selector constraints."""

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_ids: _RemovedFormatIds = Field(default=None, init=False)

    creatives: list[CreativeAsset] | None = Field(default=None, min_length=1)

    @model_validator(mode="after")
    def _validate_format_params(self) -> PackageRequest:
        if self.params is not None and self.format_kind is None:
            raise ValueError("params requires format_kind")
        if self.params is not None and self.format_kind == "image":
            if ("width" in self.params) != ("height" in self.params):
                raise ValueError("image params width and height must co-occur")
        return self

Canonical package request preserving beta.3 selector constraints.

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

• PackageRequest
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var creatives : list[CreativeAsset] | None

var model_config

var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Inherited members

• PackageRequest:
  • adcp_major_version
  • bid_price
  • format_ids
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class PackageSignalTargetingGroup (**data: Any)

Expand source code

class PackageSignalTargetingGroup(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    operator: Annotated[
        Operator,
        Field(
            description="How to evaluate the signals in this group. 'any' is an OR include group. 'none' is an exclusion group equivalent to NOT (A OR B OR C)."
        ),
    ]
    signals: Annotated[
        list[package_signal_targeting.PackageSignalTargeting],
        Field(
            description='Signal targeting entries evaluated by this group. Each entry uses the package signal targeting shape, including signal_ref, value expression, and optional pricing, execution-handle, or activation fields.',
            min_length=1,
        ),
    ]

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

Class variables

var model_config

var operator : Operator

var signals : list[PackageSignalTargeting5 | PackageSignalTargeting6 | PackageSignalTargeting7]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PackageSignalTargetingGroups (**data: Any)

Expand source code

class PackageSignalTargetingGroups(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    operator: Annotated[
        Literal['all'],
        Field(
            description="Groups-level operator. Required even though v1 only supports 'all': every child group must be satisfied."
        ),
    ] = 'all'
    groups: Annotated[
        list[package_signal_targeting_group.PackageSignalTargetingGroup],
        Field(
            description="Signal targeting groups to evaluate. Use operator 'any' for include groups and 'none' for exclusion groups.",
            min_length=1,
        ),
    ]

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

Class variables

var groups : list[PackageSignalTargetingGroup]

var model_config

var operator : Literal['all']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class LegacyPackageUpdate (**data: Any)

Expand source code

class PackageUpdate(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description="Seller's ID of package to update")]
    budget: Annotated[
        StrictFloat | None,
        Field(
            description='Updated hard spend cap for this package in the media-buy currency. Every selected pricing option in an AdCP-authored media buy MUST declare that same currency. In seller-optimized mode a number changes the package ceiling and null removes it so only the shared total and other constraints bound the package. null is invalid when the resulting allocation mode is fixed. A number in a resulting seller-optimized buy requires advertised media_buy.features.seller_optimized_package_budgets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.',
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description='Updated soft lifetime spend target for this package. A number is valid only for seller-optimized allocation, requires advertised media_buy.features.seller_optimized_min_spend_targets (otherwise UNSUPPORTED_FEATURE, before any over-subscription validation), and must not exceed the resulting package budget when one exists. null removes the target. Sellers MUST validate the complete post-update state atomically.',
            ge=0.0,
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Updated package pacing, subordinate to media-buy pacing. In a resulting seller-optimized buy, pacing that differs from the media-buy pacing requires advertised media_buy.features.seller_optimized_package_pacing; otherwise rejected with UNSUPPORTED_FEATURE.'
        ),
    ] = None
    bid_price: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Use bidding. A package update MUST NOT supply both a non-null bidding object and bid_price. During migration, bidding:null MAY accompany bid_price to clear the canonical block and set the legacy representation atomically.',
            ge=0.0,
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Replace the complete package-authored bidding policy. An object replaces any prior package block and remains a complete override of the media-buy default. `{automatic:true}` explicitly selects provider automatic bidding at package scope. null clears the package-authored block so the package inherits media-buy bidding; if the media-buy block is also absent, provider automatic delivery applies. Monetary fields use the media-buy currency and require the package pricing option to declare that currency. During legacy migration, null MAY accompany bid_price or monetary optimization-goal targets; only a non-null canonical bidding object conflicts with those representations.'
        ),
    ] = None
    impressions: Annotated[
        StrictFloat | None, Field(description='Updated impression goal for this package', ge=0.0)
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's hard daily cap; null removes it. Numeric changes apply immediately with current-day package spend counted. A cap below that spend pauses the package for the day; the aggregate cap remains independently binding.",
            ge=0.0,
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Updated flight start date/time for this package in ISO 8601 format. Must fall within the media buy's date range."
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Updated flight end date/time for this package in ISO 8601 format. Must fall within the media buy's date range."
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(description='Pause/resume specific package (true = paused, false = active)'),
    ] = None
    canceled: Annotated[
        Literal[True] | None,
        Field(
            description='Cancel this specific package. Cancellation is irreversible — canceled packages stop delivery and cannot be reactivated. When true, package cancellation takes precedence over sibling fields on this package: the seller applies only canceled and cancellation_reason for this package and SHOULD return a structured warning naming ignored sibling fields. Root fields and other package updates still participate in the same atomic update when root canceled is absent. Sellers MAY reject with NOT_CANCELLABLE.'
        ),
    ] = None
    cancellation_reason: Annotated[
        str | None, Field(description='Reason for canceling this package.', max_length=500)
    ] = None
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description='Replace the catalogs this package promotes. Uses replacement semantics — the provided array replaces the current list. Omit to leave catalogs unchanged.',
            min_length=1,
        ),
    ] = None
    optimization_goals: Annotated[
        list[optimization_goal.OptimizationGoal] | None,
        Field(
            description='Replace all optimization goals for this package. Uses replacement semantics — omit to leave goals unchanged.',
            min_length=1,
        ),
    ] = None
    targeting_overlay: Annotated[
        targeting_input.TargetingOverlayInput | None,
        Field(
            description='Per-dimension targeting patch for this package. Omit targeting_overlay, or omit an individual dimension inside it, to leave the corresponding effective targeting unchanged. A non-null dimension replaces its current value; null clears it, including a value inherited from configured-product selection or a product default. Every resulting effective overlay must remain executable by the product. Sellers reject unsupported or partially applicable changes and use REQUOTE_REQUIRED when a change, including a broader inventory set, falls outside the priced envelope. placement_selection is purchased-inventory targeting; mode default restores the product default, null clears the dimension when the product permits it, and successful readback echoes the committed selected set when enumerable. If a patch removes a placement referenced by an existing creative assignment, the seller MUST reject the update unless the same atomic package mutation supplies a compatible complete creative_assignments replacement. Sellers MUST NOT silently delete assignments or retain orphan placement refs.'
        ),
    ] = None
    keyword_targets_add: Annotated[
        list[KeywordTargetsAddItem] | None,
        Field(
            description='Keyword targets to add or update on this package. Upserts by (keyword, match_type) identity: if the pair already exists, its bid_price is updated; if not, a new keyword target is added. Use targeting_overlay.keyword_targets in create_media_buy to set the initial list.',
            min_length=1,
        ),
    ] = None
    keyword_targets_remove: Annotated[
        list[KeywordTargetsRemoveItem] | None,
        Field(
            description='Keyword targets to remove from this package. Removes matching (keyword, match_type) pairs. If a specified pair is not present, sellers SHOULD treat it as a no-op for that entry.',
            min_length=1,
        ),
    ] = None
    negative_keywords_add: Annotated[
        list[NegativeKeywordsAddItem] | None,
        Field(
            description='Negative keywords to add to this package. Appends to the existing negative keyword list — does not replace it. If a keyword+match_type pair already exists, sellers SHOULD treat it as a no-op for that entry. Use targeting_overlay.negative_keywords in create_media_buy to set the initial list.',
            min_length=1,
        ),
    ] = None
    negative_keywords_remove: Annotated[
        list[NegativeKeywordsRemoveItem] | None,
        Field(
            description='Negative keywords to remove from this package. Removes matching keyword+match_type pairs from the existing list. If a specified pair is not present, sellers SHOULD treat it as a no-op for that entry.',
            min_length=1,
        ),
    ] = None
    creative_assignments: Annotated[
        list[creative_assignment.CreativeAssignment] | None,
        Field(
            description='Replace creative assignments for this package with optional rotation, grouping, weights, and placement routing. Uses replacement semantics - omit to leave assignments unchanged. rotation_mode is package-scoped: omission resolves to weighted, and every assignment MUST resolve to the same effective mode. In sequential mode, sequence_position MUST be unique within each package-local group. Sellers reject conflicts with VALIDATION_ERROR before mutation. When the same mutation narrows or clears targeting_overlay.placement_selection, this complete replacement MUST remove or reroute every assignment reference that would otherwise be orphaned; the seller validates both changes atomically.'
        ),
    ] = None
    creatives: Annotated[
        list[creative_asset.CreativeAsset] | None,
        Field(
            description="Replace this package's inline creative assets. Native localization is not accepted on this path; use sync_creatives before assigning the library creative. When the seller also advertises creative.has_creative_library: true, new inline creatives enter the seller's creative library and can be reused by creative_id while retained; inline-only sellers may store them as package-scoped assets. Use creative_assignments instead for existing library creatives.",
            max_length=100,
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

• PackageUpdate

Class variables

var bidding : BiddingPolicy | None

var budget : float | None

var canceled : Literal[True] | None

var cancellation_reason : str | None

var catalogs : list[Catalog] | None

var context : ContextObject | None

var creative_assignments : list[CreativeAssignment] | None

var creatives : list[CreativeAsset] | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var impressions : float | None

var keyword_targets_add : list[KeywordTargetsAddItem] | None

var keyword_targets_remove : list[KeywordTargetsRemoveItem] | None

var min_spend_target : float | None

var model_config

var negative_keywords_add : list[NegativeKeywordsAddItem] | None

var negative_keywords_remove : list[NegativeKeywordsRemoveItem] | None

var optimization_goals : list[OptimizationGoal8 | OptimizationGoal9 | OptimizationGoal10] | None

var pacing : Pacing | None

var package_id : str

var paused : bool | None

var start_time : pydantic.types.AwareDatetime | None

var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Instance variables

var bid_price : float | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class PackageUpdate (**data: Any)

Expand source code

class PackageUpdate(_LegacyPackageUpdate, CanonicalBoundaryModel):
    """Canonical package update; creatives are canonical assets."""

    creatives: list[CreativeAsset] | None = Field(default=None, min_length=1)  # type: ignore[assignment]

Canonical package update; creatives are canonical assets.

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

• PackageUpdate
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var creatives : list[CreativeAsset] | None

var model_config

var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Inherited members

• PackageUpdate:
  • bid_price
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

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.

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

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.

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

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.

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

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 Parameters (**data: Any)

Expand source code

class Parameters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    demographic_system: Annotated[
        demographic_system_1.DemographicSystem | None,
        Field(
            description='Measurement system for the demographic field. Defaults to nielsen when omitted.'
        ),
    ] = None
    demographic: Annotated[
        str,
        Field(
            description='Target demographic code within the specified demographic_system (e.g., P18-49 for Nielsen, ABC1 Adults for BARB)'
        ),
    ]
    min_points: Annotated[
        StrictFloat | None, Field(description='Minimum GRPs/TRPs required', ge=0.0)
    ] = 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

Class variables

var demographic : str

var demographic_system : DemographicSystem | None

var min_points : float | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PaymentTerms (*args, **kwds)

Expand source code

class PaymentTerms(StrEnum):
    net_15 = 'net_15'
    net_30 = 'net_30'
    net_45 = 'net_45'
    net_60 = 'net_60'
    net_90 = 'net_90'
    prepay = 'prepay'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var net_15

var net_30

var net_45

var net_60

var net_90

var prepay

class PerformanceFeedback (**data: Any)

Expand source code

class PerformanceFeedback(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    feedback_id: Annotated[
        str, Field(description='Unique identifier for this performance feedback submission')
    ]
    media_buy_id: Annotated[str, Field(description="Publisher's media buy identifier")]
    package_id: Annotated[
        str | None,
        Field(
            description='Specific package within the media buy (if feedback is package-specific)'
        ),
    ] = None
    creative_id: Annotated[
        str | None, Field(description='Specific creative asset (if feedback is creative-specific)')
    ] = None
    measurement_period: Annotated[
        MeasurementPeriod, Field(description='Time period for performance measurement')
    ]
    performance_index: Annotated[
        StrictFloat,
        Field(
            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
            ge=0.0,
        ),
    ]
    metric_type: Annotated[
        metric_type_1.MetricType | None,
        Field(
            deprecated=True,
            description='**Deprecated as of this minor.** The legacy free-form metric enum that mixes metrics, verification, and attribution into one list. New implementations SHOULD use `metric` (the discriminated `(scope, metric_id, qualifier)` row shape) and populate `metric_type` with a best-effort string for one-minor backwards compatibility. When both `metric` and `metric_type` are present, consumers MUST use `metric` for dispatch. Removed at the next major. See [docs/measurement/taxonomy](https://docs.adcontextprotocol.org/docs/measurement/taxonomy) for why the layered shape replaces the flat enum.',
        ),
    ] = None
    metric: Annotated[
        Metric | Metric7 | None,
        Field(
            description='The metric this feedback row pertains to, using the same `(scope, metric_id, qualifier)` row shape as `committed_metrics` and package-level delivery values (`metric_values` or `vendor_metric_values`). Preferred over the legacy `metric_type` field for new implementations. Brings performance-feedback into the same atomic unit and dispatch model as the rest of the measurement surface — buyer agents reconcile feedback against the contract surface using the row-level join on `(scope, metric_id, qualifier)`. **Optional and may be omitted entirely for holistic feedback** (e.g., a trader flagging a campaign as underperforming without a specific metric in mind — `performance_index` plus the response narrative carry the signal). Senders SHOULD populate `metric` when the feedback is metric-specific so consumers can route it to the right optimization path; senders MAY omit it for general performance feedback.',
            discriminator='scope',
        ),
    ] = None
    feedback_source: Annotated[
        feedback_source_1.FeedbackSource, Field(description='Source of the performance data')
    ]
    vendor: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description="Vendor that produced this feedback. SHOULD be populated when `feedback_source` is `third_party_measurement` or `verification_partner` AND a single attesting vendor exists — without it, the row is unattributed and consumers can't verify authorization, resolve metric definitions, or route disputes. OMIT for blended outputs where no single vendor owns the result: MMM mixes (Nielsen MMM, Analytic Partners, in-house mix models combining multiple vendor inputs), multi-touch attribution outputs that join across vendors, and clean-room outputs (LiveRamp, Habu, AWS Clean Rooms) where the clean room is not the measurement source. For these cases, leave `vendor` absent and use the response's narrative payload to describe provenance. Optional for `buyer_attribution` and `platform_analytics` (those sources are implicit from context). The vendor's `brand.json` `agents[type='measurement']` is the discovery anchor; metric definitions live on the agent's `get_adcp_capabilities.measurement.metrics[]` block. Same identity discipline as `vendor_metric_value.vendor` and `performance-standard.vendor`."
        ),
    ] = None
    status: Annotated[Status, Field(description='Processing status of the performance feedback')]
    submitted_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when feedback was submitted')
    ]
    applied_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when feedback was applied to optimization algorithms'
        ),
    ] = 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

Class variables

var applied_at : pydantic.types.AwareDatetime | None

var creative_id : str | None

var feedback_id : str

var feedback_source : FeedbackSource

var measurement_period : MeasurementPeriod

var media_buy_id : str

var metric : Metric | Metric7 | None

var metric_type : MetricType | None

var model_config

var package_id : str | None

var performance_index : float

var status : Status

var submitted_at : pydantic.types.AwareDatetime

var vendor : BrandReference | None

class Performance (**data: Any)

Expand source code

class PerformanceFeedback(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    feedback_id: Annotated[
        str, Field(description='Unique identifier for this performance feedback submission')
    ]
    media_buy_id: Annotated[str, Field(description="Publisher's media buy identifier")]
    package_id: Annotated[
        str | None,
        Field(
            description='Specific package within the media buy (if feedback is package-specific)'
        ),
    ] = None
    creative_id: Annotated[
        str | None, Field(description='Specific creative asset (if feedback is creative-specific)')
    ] = None
    measurement_period: Annotated[
        MeasurementPeriod, Field(description='Time period for performance measurement')
    ]
    performance_index: Annotated[
        StrictFloat,
        Field(
            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
            ge=0.0,
        ),
    ]
    metric_type: Annotated[
        metric_type_1.MetricType | None,
        Field(
            deprecated=True,
            description='**Deprecated as of this minor.** The legacy free-form metric enum that mixes metrics, verification, and attribution into one list. New implementations SHOULD use `metric` (the discriminated `(scope, metric_id, qualifier)` row shape) and populate `metric_type` with a best-effort string for one-minor backwards compatibility. When both `metric` and `metric_type` are present, consumers MUST use `metric` for dispatch. Removed at the next major. See [docs/measurement/taxonomy](https://docs.adcontextprotocol.org/docs/measurement/taxonomy) for why the layered shape replaces the flat enum.',
        ),
    ] = None
    metric: Annotated[
        Metric | Metric7 | None,
        Field(
            description='The metric this feedback row pertains to, using the same `(scope, metric_id, qualifier)` row shape as `committed_metrics` and package-level delivery values (`metric_values` or `vendor_metric_values`). Preferred over the legacy `metric_type` field for new implementations. Brings performance-feedback into the same atomic unit and dispatch model as the rest of the measurement surface — buyer agents reconcile feedback against the contract surface using the row-level join on `(scope, metric_id, qualifier)`. **Optional and may be omitted entirely for holistic feedback** (e.g., a trader flagging a campaign as underperforming without a specific metric in mind — `performance_index` plus the response narrative carry the signal). Senders SHOULD populate `metric` when the feedback is metric-specific so consumers can route it to the right optimization path; senders MAY omit it for general performance feedback.',
            discriminator='scope',
        ),
    ] = None
    feedback_source: Annotated[
        feedback_source_1.FeedbackSource, Field(description='Source of the performance data')
    ]
    vendor: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description="Vendor that produced this feedback. SHOULD be populated when `feedback_source` is `third_party_measurement` or `verification_partner` AND a single attesting vendor exists — without it, the row is unattributed and consumers can't verify authorization, resolve metric definitions, or route disputes. OMIT for blended outputs where no single vendor owns the result: MMM mixes (Nielsen MMM, Analytic Partners, in-house mix models combining multiple vendor inputs), multi-touch attribution outputs that join across vendors, and clean-room outputs (LiveRamp, Habu, AWS Clean Rooms) where the clean room is not the measurement source. For these cases, leave `vendor` absent and use the response's narrative payload to describe provenance. Optional for `buyer_attribution` and `platform_analytics` (those sources are implicit from context). The vendor's `brand.json` `agents[type='measurement']` is the discovery anchor; metric definitions live on the agent's `get_adcp_capabilities.measurement.metrics[]` block. Same identity discipline as `vendor_metric_value.vendor` and `performance-standard.vendor`."
        ),
    ] = None
    status: Annotated[Status, Field(description='Processing status of the performance feedback')]
    submitted_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when feedback was submitted')
    ]
    applied_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when feedback was applied to optimization algorithms'
        ),
    ] = 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

Class variables

var applied_at : pydantic.types.AwareDatetime | None

var creative_id : str | None

var feedback_id : str

var feedback_source : FeedbackSource

var measurement_period : MeasurementPeriod

var media_buy_id : str

var metric : Metric | Metric7 | None

var metric_type : MetricType | None

var model_config

var package_id : str | None

var performance_index : float

var status : Status

var submitted_at : pydantic.types.AwareDatetime

var vendor : BrandReference | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PixelTrackerAsset (**data: Any)

Expand source code

class PixelTrackerAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['pixel_tracker'],
        Field(
            description='Discriminator identifying this as a renderer-fired pixel tracker asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'pixel_tracker'
    event: Annotated[
        pixel_tracking_event.PixelTrackingEvent,
        Field(
            description="Which event this tracker fires on. The event enum maps its first four measurement values to IAB OpenRTB Native 1.2 event types 1-4 and adds explicit AdCP events for renderer behavior that Native does not assign a standard event type:\n- `impression` (IAB type 1) — fires when the ad is served. Covers both `imptrackers[]` and `jstracker` from the IAB shape, distinguished by `method`.\n- `viewable_mrc_50` (IAB type 2) — IAB MRC viewable, 50% pixels for ≥1 second.\n- `viewable_mrc_100` (IAB type 3) — IAB MRC viewable, 100% pixels for ≥1 second.\n- `viewable_video_50` (IAB type 4) — video-specific viewable, 50% pixels for ≥2 seconds. Native type 4 does not require audio. On video_hosted; ignored on image/html5.\n- `audible_video_complete` (AdCP-defined) — video reached 100% completion with audio on. Native reserves event types 500+ for exchange-specific use and does not assign this event a standard numeric type. Meaningful on non-VAST video formats where audible-complete is measured but VAST `<TrackingEvents>` is not the wire format; VAST formats use `vast_tracker` with `vast_event: complete` plus a separate audible tracker instead.\n- `click` — fires when the user clicks the creative (`link.clicktrackers[]`).\n- `custom` — adopter-defined event for anything not in the standardized enum. MUST also set `custom_event_name`; it can represent Native's exchange-specific 500+ range or another qualified vendor event without assigning an IAB numeric identity."
        ),
    ]
    method: Annotated[
        Method | None,
        Field(
            description="How the tracker URL is invoked at serve time:\n- `img` — fired as an image pixel (HTTP GET with `<img>`-like semantics; no JS execution)\n- `js` — fired as a script include (renderer evaluates the URL's response as JavaScript)\n\nMatches IAB OpenRTB Native 1.2 method enum (1=img, 2=js). `js` MUST only be used by sellers whose renderer supports JavaScript trackers; sellers without JS-tracker support MUST reject `method: js` declarations at sync_creatives time with `CREATIVE_REJECTED` carrying the reason."
        ),
    ] = Method.img
    url: Annotated[
        macro_bearing_url.MacroBearingUrl,
        Field(
            description='Tracker URL fired when `event` occurs. Macro processing and encoding follow an attached occurrence declaration; absent declarations retain the legacy universal-macro path.'
        ),
    ]
    macro_declarations: Annotated[
        list[MacroDeclaration] | None,
        Field(
            description='One declaration per token occurrence in `url`; declaration_id values MUST be unique and locations MUST resolve. When omitted, legacy behavior applies.',
            min_length=1,
        ),
    ] = None
    custom_event_name: Annotated[
        str | None,
        Field(
            description='REQUIRED when `event` is `custom`; otherwise MUST be absent. Adopter-defined event name. When tracker execution is undeclared, an unknown custom event is a forward-compatible probe and the seller silently no-ops instead of rejecting the creative. An effective tracker_execution_contract overrides that legacy fallback: with complete:true an unlisted custom selector is unsupported and rejects compatibility with tracker_contract_mismatch; a listed custom selector is an affirmative accept-and-initiate commitment.'
        ),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance.'
        ),
    ] = 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

Class variables

var asset_type : Literal['pixel_tracker']

var custom_event_name : str | None

var event : PixelTrackingEvent

var macro_declarations : list[MacroDeclaration] | None

var method : Method | None

var model_config

var provenance : Provenance | None

var url : str | MacroBearingUrl3 | MacroBearingUrl4

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PixelTrackerEvent (*args, **kwds)

Expand source code

class PixelTrackingEvent(StrEnum):
    impression = 'impression'
    viewable_mrc_50 = 'viewable_mrc_50'
    viewable_mrc_100 = 'viewable_mrc_100'
    viewable_video_50 = 'viewable_video_50'
    audible_video_complete = 'audible_video_complete'
    click = 'click'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audible_video_complete

var click

var custom

var impression

var viewable_mrc_100

var viewable_mrc_50

var viewable_video_50

class LegacyPlacement (**data: Any)

Expand source code

class Placement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    kind: Annotated[
        Kind,
        Field(
            description='Placement authority discriminator. `publisher_ref` is publisher-catalog identity; `seller_inline` is sales-agent-authored identity.'
        ),
    ]
    placement_id: Annotated[
        str,
        Field(
            description='Placement identifier. For publisher_ref it is scoped by publisher_domain and resolves in adagents.json. For seller_inline it is scoped by seller_agent, or by the enclosing seller and product for legacy rows.'
        ),
    ]
    publisher_domain: Annotated[
        str | None,
        Field(
            description="For publisher_ref, the domain whose adagents.json declares the placement and part of canonical identity. For seller_inline, optional inventory-publisher attribution only; it does not grant the seller authority to mint IDs in that publisher's catalog namespace.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    seller_agent: Annotated[
        seller_agent_ref.SellerAgentReference | None,
        Field(
            description='Sales agent that defines a seller_inline placement. Together with placement_id this is its self-contained identity. New 3.2 sellers SHOULD populate it; legacy product-context inline placements may omit it. Not used for publisher_ref.'
        ),
    ] = None
    name: Annotated[
        str | None,
        Field(
            description='Human-readable name for the placement (e.g., \'Homepage Banner\', \'Article Sidebar\'). Required for `kind: "seller_inline"`. May be omitted for publisher-referenced placements because buyers resolve the name from the publisher declaration identified by `{publisher_domain, placement_id}`.'
        ),
    ] = None
    description: Annotated[
        str | None, Field(description='Detailed description of where and how the placement appears')
    ] = None
    mode: Annotated[
        Mode,
        Field(
            description="Required product-level relationship to this placement. targetable means the buyer may include the publisher-scoped ref in targeting_overlay.placement_selection; a creative may be routed there only after it is purchased. included means fixed product inventory: it cannot be independently selected, but across discovery, create, and update a selected request exactly equal to the product's complete included placement set is an inherent restatement and may be echoed on the package without overlay_support.placement_selection. A product containing any included placement MUST NOT declare overlay_support.placement_selection; partial selection requires a separately selectable product configuration. During the migration window ending 2026-11-25, buyers MAY tolerate legacy products that omit mode and treat them as targetable; after that date buyers SHOULD fail closed."
        ),
    ]
    tags: Annotated[
        list[str] | None,
        Field(
            description="Optional tags for grouping placements within a product (e.g., 'homepage', 'native', 'premium'). When the placement_id comes from the publisher registry, these should align with the registry tags unless the product is narrowing scope."
        ),
    ] = None
    format_ids: Annotated[
        Sequence[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format placement narrowing. Can include concrete, template, or parameterized format IDs. When present on a product placement, this field narrows the product-level `format_ids` contract and MUST NOT introduce formats the product does not accept. Use canonical `format_options`.',
            min_length=1,
        ),
    ] = None
    format_options: Annotated[
        list[product_format_declaration.ProductFormatDeclaration] | None,
        Field(
            description="Canonical seller-side narrowing for this product placement. When present, these declarations are intersected with the product-level format_options and MUST NOT introduce a format outside that product upper bound. For kind publisher_ref, buyers MUST also resolve {publisher_domain, placement_id} in the publisher's adagents.json and intersect the publisher catalog constraint: use the public placement's format_options when present (resolving bare format_option_id references against same-file top-level formats[]), otherwise use applicable top-level formats[] scoped to that placement's properties. Omitting this inline field removes only the seller-inline layer; it does not bypass a publisher placement or property-scoped narrowing. The placement inherits the full product-level set only when no applicable publisher catalog narrowing exists. Unresolved publisher placement or format-option references fail closed. Locale policy participates in the same intersection: when the product policy is absent, a placement may introduce any concrete policy as a narrowing of the unconstrained option; when both are present, every placement accepted_language_range must be contained by a product range under RFC 4647 Basic Filtering (`fr-CA` narrows `fr`; `fr` does not narrow `fr-CA`). Buyers compute effective locale eligibility independently for each placement. Any effective locale-constrained route is canonical-only and has no projecting product or placement format_id.",
            min_length=1,
        ),
    ] = None
    video_placement_types: Annotated[
        list[video_placement_type.VideoPlacementType] | None,
        Field(
            description='Declared video placement types for this product placement, using IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    audio_distribution_types: Annotated[
        list[audio_distribution_type.AudioDistributionType] | None,
        Field(
            description='Declared audio distribution types for this product placement, using IAB Tech Lab/OpenRTB 2.6 audio.feed definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    sponsored_placement_types: Annotated[
        list[sponsored_placement_type.SponsoredPlacementType] | None,
        Field(
            description='Declared sponsored-placement types for this product placement, distinguishing where the catalog-driven retail-media placement renders on the retailer surface. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    social_placement_surfaces: Annotated[
        list[social_placement_surface.SocialPlacementSurface] | None,
        Field(
            description='Declared social-placement surfaces for this product placement, distinguishing the in-app surface where the social placement renders. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    identifiers: Annotated[
        list[Identifier] | None,
        Field(
            description='Optional external inventory identifiers for this placement, using the same {type, value} shape as property identifiers. Externally governed IDs should be authority-prefixed (e.g., space:1234931339, geopath:30961, fcc:73953). Seller-local IDs are opaque values scoped by the surrounding publisher namespace. Useful for DOOH venue and installed-endpoint IDs, broadcast facility IDs, and any channel where placements map to externally registered inventory. For kind: publisher_ref, the effective identifier set is the union of the resolved publisher declaration and this product declaration, de-duplicated by exact (type, value); a product cannot suppress a publisher-declared identifier by omission.',
            min_length=1,
        ),
    ] = None
    dooh_placement_attributes: ProductDoohPlacementAttributes | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> Placement:
        # ``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 (('name',), ('publisher_domain',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'Placement requires at least one of these field groups: name | publisher_domain'
        )

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

• Placement

Class variables

var audio_distribution_types : list[AudioDistributionType] | None

var description : str | None

var dooh_placement_attributes : ProductDoohPlacementAttributes | None

var format_ids : collections.abc.Sequence[FormatReferenceStructuredObject] | None

var format_options : list[ProductFormatDeclaration1 | ProductFormatDeclaration2 | ProductFormatDeclaration3 | ProductFormatDeclaration4 | ProductFormatDeclaration5 | ProductFormatDeclaration6 | ProductFormatDeclaration7 | ProductFormatDeclaration8 | ProductFormatDeclaration9 | ProductFormatDeclaration10 | ProductFormatDeclaration11 | ProductFormatDeclaration12 | ProductFormatDeclaration13 | ProductFormatDeclaration14 | ProductFormatDeclaration15 | ProductFormatDeclaration16] | None

var identifiers : list[Identifier] | None

var kind : Kind

var mode : Mode

var model_config

var name : str | None

var placement_id : str

var publisher_domain : str | None

var seller_agent : SellerAgentReference | None

var social_placement_surfaces : list[SocialPlacementSurface] | None

var sponsored_placement_types : list[SponsoredPlacementType] | None

var tags : list[str] | None

var video_placement_types : list[VideoPlacementType] | None

class Placement (**data: Any)

Expand source code

class Placement(_LegacyPlacement, CanonicalBoundaryModel):
    """Canonical placement; ``format_options`` are canonical declarations."""

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_ids: _RemovedFormatIdSequence = Field(default=None, init=False)

    format_options: list[Format] | None = Field(default=None, min_length=1)  # type: ignore[assignment]

Canonical placement; format_options are canonical declarations.

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

• Placement
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var format_ids : collections.abc.Sequence[FormatReferenceStructuredObject] | None

var format_options : list[Format] | None

var model_config

Inherited members

• Placement:
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class PlacementPresentationDocument (**data: Any)

Expand source code

class PlacementPresentationDocument(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    schema_version: Literal['1.0'] = '1.0'
    canvas: Canvas
    creative_slot: Annotated[
        CreativeSlot,
        Field(
            description='Rectangle into which the selected creative render is fitted and clipped without changing its manifest or renderer.'
        ),
    ]
    decorations: Annotated[
        list[BoxDecoration | TextDecoration | ImageDecoration] | None, Field(max_length=100)
    ] = 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

Class variables

var canvas : Canvas

var creative_slot : CreativeSlot

var decorations : list[BoxDecoration | TextDecoration | ImageDecoration] | None

var model_config

var schema_version : Literal['1.0']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PlacementPresentationReference (**data: Any)

Expand source code

class PlacementPresentationReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    uri: Annotated[
        AnyUrl,
        Field(
            description='Publisher-controlled HTTPS URL for the presentation metadata. Consumers MUST apply the same SSRF, redirect, response-size, timeout, and DNS-rebinding protections used for format_schema fetches.'
        ),
    ]
    digest: Annotated[
        str,
        Field(
            description='SHA-256 content digest. Consumers cache by uri@digest and MUST fail closed on a digest mismatch.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ]
    media_type: Annotated[
        Literal['application/vnd.adcp.placement-presentation+json'],
        Field(description='Media type of the referenced declarative presentation document.'),
    ] = 'application/vnd.adcp.placement-presentation+json'
    schema_version: Annotated[
        Literal['1.0'],
        Field(
            description='Version of /schemas/core/placement-presentation.json used to validate and compose the referenced document.'
        ),
    ] = '1.0'

    @field_validator('uri')
    @classmethod
    def _require_https_uri(cls, value: AnyUrl) -> AnyUrl:
        if value.scheme != 'https':
            raise ValueError('uri must use https')
        return value

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

Class variables

var digest : str

var media_type : Literal['application/vnd.adcp.placement-presentation+json']

var model_config

var schema_version : Literal['1.0']

var uri : pydantic.networks.AnyUrl

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PlacementReference (**data: Any)

Expand source code

class PlacementReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    publisher_domain: Annotated[
        str | None,
        Field(
            description='Domain where the adagents.json declaring a publisher-catalog placement is hosted, or the inventory publisher associated with an inline placement. Omitted only for legacy single-publisher product-context references.',
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    placement_id: Annotated[
        str,
        Field(
            description="Placement ID from the publisher's adagents.json placement catalog, or an inline seller-defined placement ID interpreted within the enclosing seller and product context."
        ),
    ]

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

Class variables

var model_config

var placement_id : str

var publisher_domain : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Policy (**data: Any)

Expand source code

class Policy(PolicySummary):
    """Full governance policy including policy text and calibration exemplars."""

    policy: str
    issuer: dict[str, Any] | None = None
    acceptance_profile: dict[str, Any] | None = None
    content_digest: str | None = None
    canonical_content: dict[str, Any] | None = None
    guidance: str | None = None
    exemplars: PolicyExemplars | None = None
    ext: dict[str, Any] | None = None

Full governance policy including policy text and calibration exemplars.

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

• PolicySummary
• pydantic.main.BaseModel

Class variables

var acceptance_profile : dict[str, typing.Any] | None

var canonical_content : dict[str, typing.Any] | None

var content_digest : str | None

var exemplars : PolicyExemplars | None

var ext : dict[str, typing.Any] | None

var guidance : str | None

var issuer : dict[str, typing.Any] | None

var model_config

var policy : str

class PolicyExemplar (**data: Any)

Expand source code

class PolicyExemplar(BaseModel):
    """A pass/fail scenario used to calibrate governance agent interpretation."""

    model_config = ConfigDict(extra="allow")

    scenario: str
    explanation: str

A pass/fail scenario used to calibrate governance agent interpretation.

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 explanation : str

var model_config

var scenario : str

class PolicyExemplars (**data: Any)

Expand source code

class PolicyExemplars(BaseModel):
    """Collection of pass/fail exemplars for a policy."""

    model_config = ConfigDict(extra="allow")

    pass_: list[PolicyExemplar] = Field(default_factory=list, alias="pass")
    fail: list[PolicyExemplar] = Field(default_factory=list)

Collection of pass/fail exemplars for a policy.

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 fail : list[PolicyExemplar]

var model_config

var pass_ : list[PolicyExemplar]

class PolicyHistory (**data: Any)

Expand source code

class PolicyHistory(BaseModel):
    """Edit history for a policy."""

    model_config = ConfigDict(extra="allow")

    policy_id: str
    total: int
    revisions: list[PolicyRevision] = Field(default_factory=list)

Edit history for a policy.

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 model_config

var policy_id : str

var revisions : list[PolicyRevision]

var total : int

class PolicyRevision (**data: Any)

Expand source code

class PolicyRevision(BaseModel):
    """A single revision in a policy's edit history."""

    model_config = ConfigDict(extra="allow")

    revision_number: int
    editor_name: str
    edit_summary: str
    is_rollback: bool
    rolled_back_to: int | None = None
    created_at: str

A single revision in a policy's edit history.

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 created_at : str

var edit_summary : str

var editor_name : str

var is_rollback : bool

var model_config

var revision_number : int

var rolled_back_to : int | None

class PolicySummary (**data: Any)

Expand source code

class PolicySummary(BaseModel):
    """Summary of a governance policy from the registry."""

    model_config = ConfigDict(extra="allow", populate_by_name=True)

    policy_id: str
    version: str
    name: str
    description: str | None = None
    category: str
    enforcement: str
    jurisdictions: list[str] = Field(default_factory=list)
    region_aliases: dict[str, list[str]] = Field(default_factory=dict)
    policy_categories: list[str] = Field(default_factory=list)
    verticals: list[str] = Field(default_factory=list)
    channels: list[str] | None = None
    governance_domains: list[str] = Field(default_factory=list)
    effective_date: str | None = None
    sunset_date: str | None = None
    source_url: str | None = None
    source_name: str | None = None
    source_type: str | None = None
    review_status: str | None = None
    created_at: str | None = None
    updated_at: str | None = None

Summary of a governance policy from the 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

• pydantic.main.BaseModel

Subclasses

• Policy

Class variables

var category : str

var channels : list[str] | None

var created_at : str | None

var description : str | None

var effective_date : str | None

var enforcement : str

var governance_domains : list[str]

var jurisdictions : list[str]

var model_config

var name : str

var policy_categories : list[str]

var policy_id : str

var region_aliases : dict[str, list[str]]

var review_status : str | None

var source_name : str | None

var source_type : str | None

var source_url : str | None

var sunset_date : str | None

var updated_at : str | None

var version : str

var verticals : list[str]

class PolicyViolationDetails (**data: Any)

Expand source code

class PolicyViolationDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    origin: Annotated[
        Origin | None,
        Field(
            description='Whose policy produced the rejection. Optional so undisclosed seller policies can return only the typed POLICY_VIOLATION code if even origin would reveal sensitive information.'
        ),
    ] = None
    policy_id: Annotated[
        str | None,
        Field(
            description='Shared policy-registry identifier for the violated policy. Use seller_policy_ref instead when the seller is not disclosing a registry policy.'
        ),
    ] = None
    seller_policy_ref: Annotated[
        str | None,
        Field(
            description='Opaque seller-scoped reference that lets support and audit records correlate an undisclosed policy without publishing its rules. This is not a shared policy-registry ID.',
            min_length=1,
        ),
    ] = None
    policy_url: Annotated[
        AnyUrl | None, Field(description='URL where the full policy can be reviewed')
    ] = None
    violated_rules: Annotated[
        list[str] | None, Field(description='Specific rules that were violated')
    ] = None
    category: Annotated[
        str | None,
        Field(
            description="Optional coarse policy category disclosed at the seller's discretion.",
            pattern='^[a-z][a-z0-9_]*$',
        ),
    ] = 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

Class variables

var category : str | None

var model_config

var origin : Origin | None

var policy_id : str | None

var policy_url : pydantic.networks.AnyUrl | None

var seller_policy_ref : str | None

var violated_rules : list[str] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class LegacyPreviewCreativeRequest (**data: Any)

Expand source code

class PreviewCreativeRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    request_type: Annotated[
        RequestType,
        Field(
            description="Preview mode. 'single' previews one creative manifest. 'batch' previews multiple creatives in one call. 'variant' replays a post-flight variant by ID."
        ),
    ]
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest | None,
        Field(
            description='Complete creative manifest with all required assets for the format. In single mode, provide exactly one of creative_manifest or creative_id. Also accepted per item in batch mode.'
        ),
    ] = None
    target_capability_id: Annotated[
        str | None,
        Field(
            description="Canonical preview-operation selector. Identifies one get_adcp_capabilities creative.supported_formats[].capability_id entry whose operations contains preview. In single mode it selects the renderer for this request; in batch mode it is the default for items that omit their own target_capability_id. When omitted, the agent MAY resolve the renderer only if exactly one advertised preview capability satisfies the manifest's canonical declaration; zero matches or multiple matches MUST be rejected with FORMAT_NOT_SUPPORTED rather than choosing nondeterministically. Mutually exclusive with deprecated format_id.",
            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. New requests select an advertised preview renderer with target_capability_id and carry portable format identity in creative_manifest_1.format_kind plus optional creative_manifest_1.format_option_ref.',
        ),
    ] = None
    inputs: Annotated[
        list[Input] | None,
        Field(
            description='Array of input sets for generating multiple preview variants. Each input set defines macros and context values for one preview rendering. Used in single mode.',
            min_length=1,
        ),
    ] = None
    template_id: Annotated[
        str | None,
        Field(description='Specific template ID for custom format rendering. Used in single mode.'),
    ] = None
    quality: Annotated[
        creative_quality.CreativeQuality | None,
        Field(
            description="Render quality. 'draft' produces fast, lower-fidelity renderings. 'production' produces full-quality renderings. In batch mode, sets the default for all requests (individual items can override)."
        ),
    ] = None
    output_format: Annotated[
        preview_output_format.PreviewOutputFormat | None,
        Field(
            description="Output format. 'url' returns preview_url (iframe-embeddable URL), 'html' returns preview_html (raw HTML). In batch mode, sets the default for all requests (individual items can override). Default: 'url'."
        ),
    ] = preview_output_format.PreviewOutputFormat.url
    item_limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of catalog items to render per preview variant. Used in single mode. Creative agents SHOULD default to a reasonable sample when omitted and the catalog is large.',
            ge=1,
        ),
    ] = None
    requests: Annotated[
        list[Request] | None,
        Field(
            description="Array of preview requests (1-50 items). Required when request_type is 'batch'. Each item follows the single request structure.",
            max_length=50,
            min_length=1,
        ),
    ] = None
    variant_id: Annotated[
        str | None,
        Field(
            description="Agent-assigned AdCP served-execution identifier from get_creative_delivery. Required when request_type is 'variant'. It is agent-unique when the source agent advertises creative.supports_revisions; for legacy agents the published scope remains agent plus creative, and callers SHOULD also send creative_id to disambiguate reused values."
        ),
    ] = None
    creative_id: Annotated[
        str | None,
        Field(
            description='Creative-library identifier. In single mode, previews the stored canonical creative without requiring the caller to reconstruct its manifest. Also available as context in variant mode.'
        ),
    ] = None
    allow_async: Annotated[
        StrictBool | None,
        Field(
            description="Opt in to an asynchronous preview response. When true, the creative agent MAY return status 'submitted' with a task_id only when rendering has been handed to a queue or external renderer and will continue after the request connection is released. Active processing on an open connection uses working progress instead. The buyer polls get_task_status for completion. When false or absent, the agent MUST return a synchronous preview response or a terminal protocol error; it MUST NOT return the submitted shape. This field applies to preview_creative only; build_creative already defines its own async lifecycle."
        ),
    ] = False
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for terminal completion/failure notifications when allow_async is true and preview_creative returns a submitted task envelope. Submitted tasks remain pollable through get_task_status whether or not this field is present. If the agent accepts this configuration and returns submitted, it MUST deliver at least the terminal notification; if it cannot honor the webhook, it MUST return a structured error. Presence of this field alone MUST NOT cause asynchronous execution.'
        ),
    ] = 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 allow_async : bool | None

var context : ContextObject | None

var creative_id : str | None

var creative_manifest : CreativeManifest | None

var ext : ExtensionObject | None

var format_id : FormatReferenceStructuredObject | None

var inputs : list[Input] | None

var item_limit : int | None

var model_config

var output_format : PreviewOutputFormat | None

var push_notification_config : PushNotificationConfig | None

var quality : CreativeQuality | None

var request_type : RequestType

var requests : list[Request] | None

var target_capability_id : str | None

var template_id : str | None

var variant_id : str | 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 LegacyPreviewCreativeResponse1 (**data: Any)

Expand source code

class PreviewCreativeResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    response_type: Literal['single'] = 'single'
    previews: Annotated[list[Preview], Field(min_length=1)]
    quality_used: creative_quality_1.CreativeQuality | None = None
    interactive_url: AnyUrl | None = None
    expires_at: AwareDatetime | None = 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.

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 context : ContextObject | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var interactive_url : pydantic.networks.AnyUrl | None

var model_config

var previews : list[Preview]

var quality_used : CreativeQuality | None

var response_type : Literal['single']

class LegacyPreviewCreativeSingleResponse (**data: Any)

Expand source code

class PreviewCreativeResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    response_type: Literal['single'] = 'single'
    previews: Annotated[list[Preview], Field(min_length=1)]
    quality_used: creative_quality_1.CreativeQuality | None = None
    interactive_url: AnyUrl | None = None
    expires_at: AwareDatetime | None = 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.

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 context : ContextObject | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var interactive_url : pydantic.networks.AnyUrl | None

var model_config

var previews : list[Preview]

var quality_used : CreativeQuality | None

var response_type : Literal['single']

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 LegacyPreviewCreativeBatchResponse (**data: Any)

Expand source code

class PreviewCreativeResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    response_type: Literal['batch'] = 'batch'
    results: Annotated[list[Result], Field(min_length=1)]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var response_type : Literal['batch']

var results : list[Result]

class LegacyPreviewCreativeResponse2 (**data: Any)

Expand source code

class PreviewCreativeResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    response_type: Literal['batch'] = 'batch'
    results: Annotated[list[Result], Field(min_length=1)]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var response_type : Literal['batch']

var results : list[Result]

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 LegacyPreviewCreativeResponse3 (**data: Any)

Expand source code

class PreviewCreativeResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    response_type: Literal['variant'] = 'variant'
    variant_id: str
    creative_id: str | None = None
    previews: Annotated[list[Preview3], Field(min_length=1)]
    manifest: creative_manifest_1.CreativeManifest | None = None
    expires_at: AwareDatetime | None = 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.

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 context : ContextObject | None

var creative_id : str | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var manifest : adcp.types._forward_compat._ReadbackCreativeManifest | None

var model_config

var previews : list[Preview3]

var response_type : Literal['variant']

var variant_id : str

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class LegacyPreviewCreativeVariantResponse (**data: Any)

Expand source code

class PreviewCreativeResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    response_type: Literal['variant'] = 'variant'
    variant_id: str
    creative_id: str | None = None
    previews: Annotated[list[Preview3], Field(min_length=1)]
    manifest: creative_manifest_1.CreativeManifest | None = None
    expires_at: AwareDatetime | None = 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.

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 context : ContextObject | None

var creative_id : str | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var manifest : adcp.types._forward_compat._ReadbackCreativeManifest | None

var model_config

var previews : list[Preview3]

var response_type : Literal['variant']

var variant_id : str

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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 LegacyPreviewCreativeResponse4 (**data: Any)

Expand source code

class PreviewCreativeResponse4(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    response_type: Literal['submitted'] = 'submitted'
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = 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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var response_type : Literal['submitted']

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

class LegacyPreviewCreativeSubmittedResponse (**data: Any)

Expand source code

class PreviewCreativeResponse4(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    response_type: Literal['submitted'] = 'submitted'
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = 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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var response_type : Literal['submitted']

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

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 PreviewOutputFormat (*args, **kwds)

Expand source code

class PreviewOutputFormat(StrEnum):
    url = 'url'
    html = 'html'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var html

var url

class OutputFormat (*args, **kwds)

Expand source code

class PreviewOutputFormat(StrEnum):
    url = 'url'
    html = 'html'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var html

var url

class UrlPreviewRender (**data: Any)

Expand source code

class PreviewRender1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    output_format: Annotated[
        Literal['url'], Field(description='Discriminator indicating preview_url is provided')
    ] = 'url'
    preview_url: Annotated[
        AnyUrl,
        Field(
            description='Untrusted URL to an HTML page that renders this piece. Consumers MUST load it only in a cross-origin iframe with an empty sandbox token set and a caller-enforced restrictive CSP. Provider embedding metadata is advisory and MUST NOT loosen that policy.'
        ),
    ]
    role: Annotated[
        str,
        Field(
            description="Semantic role of this rendered piece. Use 'primary' for main content, 'companion' for associated banners, descriptive strings for device variants or custom roles."
        ),
    ]
    dimensions: Annotated[
        Dimensions | None, Field(description='Dimensions for this rendered piece')
    ] = None
    embedding: Annotated[
        Embedding | None,
        Field(description='Optional security and embedding metadata for safe iframe integration'),
    ] = None
    renderer: Annotated[
        preview_renderer_metadata.PreviewRendererMetadata | None,
        Field(
            description='Optional renderer implementation and safety metadata for audit and reproducibility. Authority is still resolved from capability discovery and placement delegation.'
        ),
    ] = 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

Class variables

var dimensions : Dimensions | None

var embedding : Embedding | None

var model_config

var output_format : Literal['url']

var preview_url : pydantic.networks.AnyUrl

var render_id : str

var renderer : PreviewRendererMetadata | None

var role : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class HtmlPreviewRender (**data: Any)

Expand source code

class PreviewRender2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    output_format: Annotated[
        Literal['html'], Field(description='Discriminator indicating preview_html is provided')
    ] = 'html'
    preview_html: Annotated[
        str,
        Field(
            description='Untrusted HTML. Consumers MUST NOT inject it into the host DOM. Render only as iframe srcdoc with an empty sandbox token set and a caller-enforced restrictive CSP; provider embedding metadata is advisory and MUST NOT loosen that policy.'
        ),
    ]
    role: Annotated[
        str,
        Field(
            description="Semantic role of this rendered piece. Use 'primary' for main content, 'companion' for associated banners, descriptive strings for device variants or custom roles."
        ),
    ]
    dimensions: Annotated[
        Dimensions | None, Field(description='Dimensions for this rendered piece')
    ] = None
    embedding: Annotated[
        Embedding | None, Field(description='Optional security and embedding metadata')
    ] = None
    renderer: Annotated[
        preview_renderer_metadata.PreviewRendererMetadata | None,
        Field(
            description='Optional renderer implementation and safety metadata for audit and reproducibility. Authority is still resolved from capability discovery and placement delegation.'
        ),
    ] = 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

Class variables

var dimensions : Dimensions | None

var embedding : Embedding | None

var model_config

var output_format : Literal['html']

var preview_html : str

var render_id : str

var renderer : PreviewRendererMetadata | None

var role : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class BothPreviewRender (**data: Any)

Expand source code

class PreviewRender3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    output_format: Annotated[
        Literal['both'],
        Field(
            description='Discriminator indicating both preview_url and preview_html are provided'
        ),
    ] = 'both'
    preview_url: Annotated[
        AnyUrl,
        Field(
            description='Untrusted URL to an HTML page that renders this piece. Consumers MUST load it only in a cross-origin iframe with an empty sandbox token set and a caller-enforced restrictive CSP. Provider embedding metadata is advisory and MUST NOT loosen that policy.'
        ),
    ]
    preview_html: Annotated[
        str,
        Field(
            description='Untrusted HTML. Consumers MUST NOT inject it into the host DOM. Render only as iframe srcdoc with an empty sandbox token set and a caller-enforced restrictive CSP; provider embedding metadata is advisory and MUST NOT loosen that policy.'
        ),
    ]
    role: Annotated[
        str,
        Field(
            description="Semantic role of this rendered piece. Use 'primary' for main content, 'companion' for associated banners, descriptive strings for device variants or custom roles."
        ),
    ]
    dimensions: Annotated[
        Dimensions | None, Field(description='Dimensions for this rendered piece')
    ] = None
    embedding: Annotated[
        Embedding | None,
        Field(description='Optional security and embedding metadata for safe iframe integration'),
    ] = None
    renderer: Annotated[
        preview_renderer_metadata.PreviewRendererMetadata | None,
        Field(
            description='Optional renderer implementation and safety metadata for audit and reproducibility. Authority is still resolved from capability discovery and placement delegation.'
        ),
    ] = 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

Class variables

var dimensions : Dimensions | None

var embedding : Embedding | None

var model_config

var output_format : Literal['both']

var preview_html : str

var preview_url : pydantic.networks.AnyUrl

var render_id : str

var renderer : PreviewRendererMetadata | None

var role : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PreviewRendererMetadata (**data: Any)

Expand source code

class PreviewRendererMetadata(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    renderer_id: Annotated[
        str, Field(description='Stable implementation identifier.', min_length=1)
    ]
    version: Annotated[
        str,
        Field(
            description='Exact semantic version of the renderer implementation.',
            pattern='^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$',
        ),
    ]
    export: Annotated[
        str,
        Field(
            description='Renderer export or entry-point name used for this render.', min_length=1
        ),
    ]
    rendering_origin: Annotated[
        RenderingOrigin,
        Field(
            description='Informational implementation origin copied from the selected route. It does not grant authority.'
        ),
    ]
    tracking_suppressed: Annotated[
        StrictBool,
        Field(
            description='True only when the produced output cannot initiate impression, click, billing, conversion, viewability, or asset-fetch side effects. Renderers that retain any remote asset URL or navigation MUST emit false.'
        ),
    ]

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

Class variables

var export : str

var model_config

var renderer_id : str

var rendering_origin : RenderingOrigin

var tracking_suppressed : bool

var version : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PriceGuidance (**data: Any)

Expand source code

class PriceGuidance(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    p25: Annotated[
        StrictFloat | None, Field(description='25th percentile of recent winning bids', ge=0.0)
    ] = None
    p50: Annotated[
        StrictFloat | None, Field(description='Median of recent winning bids', ge=0.0)
    ] = None
    p75: Annotated[
        StrictFloat | None, Field(description='75th percentile of recent winning bids', ge=0.0)
    ] = None
    p90: Annotated[
        StrictFloat | None, Field(description='90th percentile of recent winning bids', ge=0.0)
    ] = 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

Class variables

var model_config

var p25 : float | None

var p50 : float | None

var p75 : float | None

var p90 : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PricingCurrency (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class PricingCurrency(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{3}$'}
    _json_schema_extra = {'description': "ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP')"}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class PricingModel (*args, **kwds)

Expand source code

class PricingModel(StrEnum):
    cpm = 'cpm'
    vcpm = 'vcpm'
    cpc = 'cpc'
    cpcv = 'cpcv'
    cpv = 'cpv'
    cpp = 'cpp'
    cpa = 'cpa'
    revenue_share = 'revenue_share'
    flat_rate = 'flat_rate'
    time = 'time'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var cpa

var cpc

var cpcv

var cpm

var cpp

var cpv

var flat_rate

var revenue_share

var time

var vcpm

class PrimaryCountry (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class PrimaryCountry(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{2}$'}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

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.

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

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.

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

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.

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

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 LegacyProduct (**data: Any)

Expand source code

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


    @model_validator(mode='before')
    @classmethod
    def _coerce_publisher_property_models(cls, data: Any) -> Any:
        if isinstance(data, dict) and isinstance(data.get('publisher_properties'), list):
            coerced = []
            changed = False
            for item in data['publisher_properties']:
                if hasattr(item, 'model_dump'):
                    coerced.append(item.model_dump(mode='json', exclude_none=True))
                    changed = True
                else:
                    coerced.append(item)
            if changed:
                data = dict(data)
                data['publisher_properties'] = coerced
        return data
    product_id: Annotated[
        str,
        Field(
            description='Opaque identifier for this buyable product. For a non-custom wholesale product, sellers MUST reuse the ID for the same logical catalog offer within the seller and declared cache_scope across reads and wholesale-feed webhooks; feed and pricing versions communicate temporal catalog mutation, while retirement or replacement may end the identity. Concurrent or request-bound configurations whose effective targeting, disclosed targeting modifications, forecast assumptions, terms, or overlay support differ MUST use distinguishable configured product IDs. For is_custom: true, the ID identifies only the request-specific discovery/refinement lineage and is not stable across independent contexts. Sellers MUST keep every issued configured ID resolvable for its promised lifetime. Pricing variants within one logical product are distinguished by pricing_option_id: a seller MUST mint a new pricing_option_id whenever a binding fixed price, floor, currency, model, or priced applicability changes, and MUST NOT reinterpret an issued option ID at a new price. Selecting product_id plus pricing_option_id in create_media_buy accepts that returned configuration and commercial option.'
        ),
    ]
    name: Annotated[str, Field(description='Human-readable product name')]
    description: Annotated[
        str, Field(description='Detailed description of the product and its inventory')
    ]
    publisher_properties: Annotated[
        list[PublisherProperty],
        Field(
            description="SDK implementers MUST enforce singular-only at runtime: each entry uses the singular `publisher_domain` form; the compact `publisher_domains[]` form is rejected on products. Codegen toolchains (json-schema-to-typescript, quicktype, datamodel-code-generator, openapi-typescript-codegen) often flatten the `allOf + $ref + not.required` restriction below poorly and may drop the rejection constraint silently, emitting an unrestricted type — runtime enforcement is the safety net. Publisher properties covered by this product. Buyers fetch actual property definitions from each publisher's adagents.json and validate agent authorization. Selection patterns mirror the authorization patterns in adagents.json for consistency. The compact `publisher_domains[]` form is reserved for adagents.json `authorized_agents[].publisher_properties[]` so that buy-side traffic-and-pricing flatteners can always treat each entry as exactly one publisher.",
            min_length=1,
        ),
    ]
    channels: Annotated[
        list[channels_1.MediaChannel] | None,
        Field(
            description="Advertising channels this product is sold as. Products inherit from their properties' supported_channels but may narrow the scope. For example, a product covering YouTube properties might be sold as ['ctv'] even though those properties support ['olv', 'social', 'ctv']."
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format compatibility path. Products MUST carry `format_ids`, `format_options`, or both during the 3.x migration window. New products MUST author canonical `format_options[]`; sellers MAY additionally project those declarations to `format_ids` for legacy buyers. When both fields are present they MUST describe the same underlying formats, and buyers MUST prefer `format_options`. Do not author a new product from `format_ids` alone.',
        ),
    ] = None
    format_options: Annotated[
        list[product_format_declaration.ProductFormatDeclaration] | None,
        Field(
            description="Canonical format-option path: one or more inline format declarations the product accepts. Each element narrows a canonical format with parameters, slots, platform_extensions, and optional locale_policy. New 3.2 products MUST carry format_options; a seller MAY additionally project the same declarations to deprecated format_ids for older 3.x peers. A declaration carrying locale_policy is canonical-only because legacy format_ids cannot preserve locale eligibility; no product or placement format_id may project to an effective locale-constrained option.\n\nWhen placements are published, product-level format_options are the union of formats deliverable somewhere in the product and the upper bound for every placement. A placement's effective accepted set is the intersection of every applicable layer: (1) the product format_options; (2) the product placement's inline format_options, when present; and (3) for kind publisher_ref, the named publisher's adagents.json catalog narrowing. Resolve layer 3 by locating the matching placements[] entry: use its format_options when present, resolving bare format_option_id references against that same file's top-level formats[]; otherwise use top-level formats[] applicable to the placement's property_ids/property_tags. An omitted optional layer is unconstrained, but an unresolved publisher placement or format-option reference MUST fail closed. A publisher-referenced placement without inline product format_options therefore does NOT inherit the full product union when the publisher catalog supplies narrower placement or property-scoped acceptance.\n\nMatch publisher-declared options by {publisher_domain, format_option_id}, match product-local options by format_option_id when publisher_domain is omitted, and otherwise match declarations with the same format_kind whose narrower parameters satisfy the broader declaration. A product- or placement-level declaration MUST NOT introduce a format outside the product upper bound. Locale policy follows the same intersection. If the product locale policy is absent, a placement may introduce any concrete policy as a narrowing of an unconstrained option; when both are present, every placement range must be contained by a product range under RFC 4647 Basic Filtering. Locale eligibility is checked independently for every placement where an assignment may serve.\n\nFor a product or package containing multiple included placements, a single creative intended for every placement MUST lie in the intersection of every selected placement's effective set. Distinct per-placement creatives MAY use the union, but the selected creative set MUST cover every included placement; uncovered inventory MUST be rejected or refined, never silently omitted. If a product spans multiple publishers but omits placements[], there is no public routing key for per-placement creatives: its format_options MUST therefore be the common intersection accepted across every selected publisher/property scope. A seller that needs a union of publisher-specific formats MUST publish placements[] with publisher-scoped identities and narrowing. Commercial terms such as price, floor, availability, and deal eligibility are product facts, not format parameters.",
            min_length=1,
        ),
    ] = None
    placements: Annotated[
        list[placement.Placement] | None,
        Field(
            description="Optional array of specific public placements within this product. Product placements declare `kind` to distinguish publisher-catalog placements (`publisher_ref`) from sales-agent-defined placements (`seller_inline`). Publisher references use canonical `{publisher_domain, placement_id}` identity and may omit name because adagents.json resolves it. New seller-inline placements SHOULD carry `seller_agent`; legacy rows without it remain scoped to the enclosing seller and product. A seller-inline publisher_domain is inventory attribution, not authority to mint an ID in that publisher's catalog namespace. Each placement MUST declare mode: targetable or included. Creative assignments route creatives only after placement inventory is purchased.",
            min_length=1,
        ),
    ] = None
    video_placement_types: Annotated[
        list[video_placement_type.VideoPlacementType] | None,
        Field(
            description='Declared video placement types that may be included in this product, using IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. Use on OLV, CTV, and other video products when buyers need to distinguish instream, accompanying-content, interstitial, and standalone/no-content inventory. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `video_placement_types`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    audio_distribution_types: Annotated[
        list[audio_distribution_type.AudioDistributionType] | None,
        Field(
            description='Declared audio distribution types that may be included in this product, using IAB Tech Lab/OpenRTB 2.6 audio.feed definitions with AdCP-native names. Use on radio, streaming-audio, podcast, gaming, and other audio products when buyers need to distinguish music streaming services, FM/AM broadcast, podcasts, catch-up radio, web radio, video-game audio, and text-to-speech inventory without changing the buyer-facing channel or adagents.json property type. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `audio_distribution_types`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    sponsored_placement_types: Annotated[
        list[sponsored_placement_type.SponsoredPlacementType] | None,
        Field(
            description='Declared sponsored-placement types that may be included in this product, distinguishing where catalog-driven retail-media placements render on the retailer surface (sponsored search, sponsored display, or sponsored native). Use on retail-media products when buyers need to distinguish search-keyed, display, and native in-grid sponsored inventory. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `sponsored_placement_types`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    social_placement_surfaces: Annotated[
        list[social_placement_surface.SocialPlacementSurface] | None,
        Field(
            description='Declared social-placement surfaces that may be included in this product, distinguishing the in-app surface where social placements render (feed, stories, short_video, explore, or search). Use on social products when buyers need to distinguish feed, story, short-video, and discovery surfaces. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `social_placement_surfaces`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.',
            min_length=1,
        ),
    ] = None
    delivery_type: delivery_type_1.DeliveryType
    exclusivity: Annotated[
        exclusivity_1.Exclusivity | None,
        Field(
            description="Whether this product offers exclusive access to its inventory. Defaults to 'none' when absent. Most relevant for guaranteed products tied to specific collections or placements."
        ),
    ] = None
    pricing_options: Annotated[
        list[pricing_option.PricingOption],
        Field(
            description="Available pricing models for this product. Fixed prices and auction floors are binding for every later targeting selection permitted by this product's overlay_support; price_guidance remains non-binding. Declaring broad overlay support alongside a binding option is therefore a uniform-price promise, not permission to calculate a different price at create time. A seller with value-dependent rates MUST return a request-specific configured product after rediscovery with concrete targeting, split the inventory into separately priced products, or expose only non-binding guidance until it can issue a binding option. The seller MUST mint a new pricing_option_id whenever a binding price, floor, currency, model, or priced applicability changes. It MUST NOT silently reprice a create request or reuse the selected option ID with different terms.",
            min_length=1,
        ),
    ]
    forecast: Annotated[
        delivery_forecast.DeliveryForecast | None,
        Field(
            description="Forecasted delivery metrics for this product. Concrete discovery targeting scopes the forecast to those effective values. When discovery requested only required_overlay_support for a dimension, the forecast describes the product's discovery/default scope and is not a value-specific forecast for every later selection; buyers rediscover with concrete targeting_overlay values when they need that forecast."
        ),
    ] = None
    outcome_measurement: Annotated[
        outcome_measurement_1.OutcomeMeasurement | None,
        Field(
            deprecated=True,
            description='**Deprecated as of this minor.** Outcome capabilities (incremental sales lift, brand lift, foot traffic, etc.) are now declared via `reporting_capabilities.available_metrics` (the same path used for impressions, conversions, ROAS) with `qualifier.attribution_methodology` and `qualifier.attribution_window` carrying the methodology and window on commit. New implementations SHOULD use the unified pattern; this field is retained for one-minor backwards compatibility and removed at the next major. See `outcome-measurement.json` description for migration guidance.',
        ),
    ] = None
    delivery_measurement: Annotated[
        DeliveryMeasurement | None,
        Field(
            description='Measurement vendors and methodology for delivery metrics. The buyer accepts the declared vendors as the source of truth for the buy. When absent, buyers should apply their own measurement defaults. Senders SHOULD populate `vendors` (structured BrandRef array) for new implementations; the legacy `provider` string field is deprecated and retained for one-minor backwards compatibility.'
        ),
    ] = None
    measurement_terms: Annotated[
        measurement_terms_1.MeasurementTerms | None,
        Field(
            description="Seller's default billing measurement and makegood terms. Declares who counts the billing metric and what remedies apply when thresholds are breached. Buyers may propose different terms at media buy creation — sellers accept, reject (TERMS_REJECTED), or adjust per their policy."
        ),
    ] = None
    performance_standards: Annotated[
        list[performance_standard.PerformanceStandard] | None,
        Field(
            description="Seller's default performance standards for this product: viewability, IVT, completion rate, brand safety, attention score. Buyers may propose different standards at media buy creation. When absent, no structured performance standards apply.",
            min_length=1,
        ),
    ] = None
    cancellation_policy: Annotated[
        cancellation_policy_1.CancellationPolicy | None,
        Field(
            description='Cancellation terms for this product. Declares the minimum notice period required before cancellation takes effect and any penalties for insufficient notice. Relevant for guaranteed delivery products. Buyers accept these terms by creating a media buy against the product.'
        ),
    ] = None
    allowed_actions: Annotated[
        list[product_allowed_action.ProductAllowedAction] | None,
        Field(
            description='Actions buyers may perform on buys created against this product, scoped to statuses and modes. Advisory template — the authoritative per-buy capability is `available_actions[]` on the buy response, which resolves modes against current buy state, account tier, and negotiated terms. Buyers SHOULD use this for pre-flight product selection ("which products let me self-serve cancel within 72hr?") and read `available_actions[]` for runtime decisions. The array is uniquely keyed by `action` — sellers MUST NOT emit two entries with the same `action` value. Absence means the seller has not declared a structured action surface for this product — buyers fall back to `valid_actions[]` on buy responses for the flat string vocabulary.',
            min_length=1,
        ),
    ] = None
    reporting_capabilities: reporting_capabilities_1.ReportingCapabilities
    creative_policy: creative_policy_1.CreativePolicy | None = None
    is_custom: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product is a request-specific configured offer rather than a reusable baseline product. Sellers MUST set true when targeting, disclosed resolution, pricing, forecast assumptions, inventory, or terms are bound for a particular discovery/refinement lineage. Products issued through targeting-aware discovery include expires_at even when exact acceptance omits targeting_resolution. For backward compatibility, is_custom alone does not make expires_at schema-required.'
        ),
    ] = None
    property_targeting_allowed: Annotated[
        StrictBool | None,
        Field(
            description="Whether buyers can select a subset of this product's publisher_properties through targeting_overlay.property_list. When false, the product is fixed inventory: it matches requested property targeting only when its inherent property set already satisfies the request, or when a configured product discloses additional inventory through targeting_resolution."
        ),
    ] = False
    data_provider_signals: Annotated[
        list[data_provider_signal_selector.DataProviderSignalSelector] | None,
        Field(
            deprecated=True,
            description='Deprecated. Legacy/non-selectable metadata for data-provider signals already bundled into or associated with this product. This field does not provide buyer-selectable options, prices, or seller activation handles. Use included_signals for non-selectable product signal metadata, or signal_targeting_options for selectable package-level signal groups.',
        ),
    ] = None
    included_signals: Annotated[
        list[signal_listing.SignalListing] | None,
        Field(
            description="Non-selectable signal metadata for signals already included in, bundled with, or planned into this product. These signals describe what the product is; buyers do not select them in packages[].targeting_overlay.signal_targeting_groups and this field does not imply package-level signal targeting. Use signal_ref scope 'data_provider' or 'signal_source' to reference externally defined signals without redefining their name or value_type. Use signal_ref scope 'product' with name and value_type when the included signal is defined only by this product.",
            min_length=1,
        ),
    ] = None
    signal_targeting_options: Annotated[
        list[product_signal_targeting_option.ProductSignalTargetingOption] | None,
        Field(
            description="Inline seller-offered signals that may be applied to packages for this product at create_media_buy time. Each entry references a named signal definition with signal_ref scope 'product' for a product-local signal option, scope 'data_provider' for an external signal definition published in adagents.json signals[] that the seller is authorized to apply, or scope 'signal_source' for a source-native signal. Product-local options define name and value_type inline; data-provider and signal-source options may omit those fields when the referenced definition or source is authoritative. Use this field when the selectable menu is product-specific, has product-specific pricing or activation handles, is the relevant subset for a brief/refine result, or should be rendered without an additional get_signals call. Wholesale products may omit this field and rely on get_signals for the selectable signal feed. Buyers select eligible signals through packages[].targeting_overlay.signal_targeting_groups when signal_targeting_rules allow; fixed/default entries are applied by the seller and echoed on the package state. Sellers MUST set signal_targeting_allowed to true whenever this field is present. Bundled, non-selectable signal metadata belongs in included_signals; legacy data_provider_signals may appear only for backwards compatibility.",
            min_length=1,
        ),
    ] = None
    signal_targeting_rules: Annotated[
        signal_targeting_rules_1.SignalTargetingRules | None,
        Field(
            description='Composition rules for selecting signals on this product. The selectable signal menu may come from inline signal_targeting_options or from get_signals when a wholesale product omits inline options. This is product-scoped because products may be backed by different ad servers with different Boolean targeting support and group limits.'
        ),
    ] = None
    signal_targeting_allowed: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product has a package-level signal_targeting_groups surface. When false (default), signals are bundled into the product terms and cannot be selected or explicitly echoed as package signal groups. When true, eligible signals from inline signal_targeting_options or from get_signals may be buyer-selected or seller-applied according to signal_targeting_rules and are represented through packages[].targeting_overlay.signal_targeting_groups. Editability is controlled by signal_targeting_rules; fixed/default-only products still set this to true when applied signal groups are echoed.'
        ),
    ] = False
    demographic_targeting: Annotated[
        demographic_targeting_capability.DemographicTargetingCapability | None,
        Field(
            description='Exact demographic execution available for this product. Buyers MUST use this product-scoped declaration, not the seller-wide get_adcp_capabilities rollup, to preflight a demographic predicate.'
        ),
    ] = None
    overlay_support: Annotated[
        targeting_overlay_support.TargetingOverlaySupport | None,
        Field(
            description='Binding product-scoped targeting dimensions the buyer may set independently on packages after discovery. Presence guarantees selectable capability subject to disclosed limits, not inventory or a forecast for every possible value. Targeting satisfied only through inherent product scope does not appear here. Returned products MUST cover every field requested through get_products.required_overlay_support. A later supported selection with no available inventory returns PRODUCT_UNAVAILABLE on create; an update outside the original priced envelope may return REQUOTE_REQUIRED.'
        ),
    ] = None
    media_buy_support: Annotated[
        media_buy_support_1.ProductMediaBuySupport | None,
        Field(
            description='Binding product participation in shared MediaBuy-level controls. This is separate from overlay_support because a root frequency cap aggregates exposures across packages rather than targeting one package. Returned products MUST cover every field requested through required_media_buy_support.'
        ),
    ] = None
    identity: product_identity.ProductIdentity | None = None
    execution_requirements: Annotated[
        list[product_execution_requirement.ProductExecutionRequirement] | None,
        Field(
            description="Experimental (`media_buy.execution_requirements`). Account resources a package on this product needs before `create_media_buy` succeeds. Every entry is required. Account-independent: it does not change `cache_scope` and carries no account resource IDs or names. When present, it plus the `required_connections` of the package's selected format declarations is complete for the kinds in `product-execution-requirement.json`: a seller MUST NOT reject a package that satisfies all of them for lacking an undeclared kind. Absence means undeclared. A declaring seller MUST reject an unmet `event_source` or `catalog` entry on a buyer-supplied `create_media_buy` `packages[]` or `update_media_buy` `new_packages[]` entry, or an update that removes a satisfying binding, with `VALIDATION_ERROR`, `error.field` at the binding, and `error.details` per `error-details/execution-requirement-unmet.json`.",
            min_length=1,
        ),
    ] = None
    targeting_resolution: Annotated[
        product_targeting_resolution.ProductTargetingResolution | None,
        Field(
            description='Discovery-time targeting resolution bound to this configured product. modifications sparsely disclose product-specific differences from get_products.targeting_overlay. Request-level brief interpretation is returned once on GetProductsResponse.targeting_resolution. Exact structured overlay values are not repeated. Selecting product_id accepts the disclosed modifications; product forecast and pricing MUST reflect them.'
        ),
    ] = None
    audience_evidence: Annotated[
        list[audience_evidence_1.AudienceEvidence] | None,
        Field(
            description='Immutable population-level evidence explaining why this inventory may suit an audience. This supports discovery, comparison, and planning only. It does not imply exact demographic targeting, user-level signal membership, or legal-age verification. Sellers MUST publish each distinct snapshot with a new snapshot_id and content_digest.',
            min_length=1,
        ),
    ] = None
    audience_evidence_selections: Annotated[
        list[audience_evidence_selection.AudienceEvidenceSelection] | None,
        Field(
            description='Exact evidence snapshots that satisfied required eligibility or affected seller ranking for this get_products result. When audience_evidence_requirements was supplied and evidence influenced inclusion or rank, sellers MUST return the relevant selections; an absent-evidence match under evidence_presence when_available has no selection. Product selections use decision_use recommendation or eligibility.',
            min_length=1,
        ),
    ] = None
    catalog_types: Annotated[
        list[catalog_type.CatalogType] | None,
        Field(
            description='Catalog types this product supports for catalog-driven campaigns. A sponsored product listing declares ["product"], a job board declares ["job", "offering"]. Buyers match synced catalogs to products via this field.',
            min_length=1,
        ),
    ] = None
    metric_optimization: Annotated[
        MetricOptimization | None,
        Field(
            description="Metric optimization capabilities for this product. Presence indicates the product supports optimization_goals with kind: 'metric'. No event source or conversion tracking setup required — the seller tracks these metrics natively."
        ),
    ] = None
    vendor_metric_optimization: Annotated[
        vendor_metric_optimization_1.VendorMetricOptimization | None,
        Field(
            description="Vendor-attested metric optimization capabilities for this product. Presence indicates the product supports `optimization_goals` with `kind: 'vendor_metric'` — the seller's bidding stack can steer delivery toward a specific vendor's measurement (e.g., DV/IAS/Adelaide attention, Scope3 emissions, Kantar brand lift, retail-media partner metrics). Distinct from `metric_optimization` (seller-native metrics with no vendor binding) and from `reporting_capabilities.vendor_metrics` (which declares what the product can *report* rather than what it can *optimize against*). A product may report a vendor metric without being able to optimize for it. Buyers MUST verify the goal's `(vendor, metric_id)` is in `supported_metrics` AND that the package's `committed_metrics[]` includes a matching `{ scope: 'vendor', vendor, metric_id }` entry — optimization without committed reporting is unverifiable and is rejected at the wire level."
        ),
    ] = None
    max_optimization_goals: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of optimization_goals this product accepts on a package. When absent, no limit is declared. Most social platforms accept only 1 goal — buyers sending arrays longer than this value should expect the seller to use only the highest-priority (lowest priority number) goal.',
            ge=1,
        ),
    ] = None
    measurement_readiness: Annotated[
        measurement_readiness_1.MeasurementReadiness | None,
        Field(
            description="Assessment of whether the buyer's event source setup is sufficient for this product to optimize effectively. Only present when the seller can evaluate the buyer's account context. Buyers should check this before creating media buys with event-based optimization goals."
        ),
    ] = None
    conversion_tracking: Annotated[
        ConversionTracking | None,
        Field(
            description="Conversion event tracking for this product. Presence indicates the product supports optimization_goals with kind: 'event'. Seller-level capabilities (supported event types, UID types, attribution windows) are declared in get_adcp_capabilities."
        ),
    ] = None
    catalog_match: Annotated[
        CatalogMatch | None,
        Field(
            description='When the buyer provides a catalog on get_products, indicates which catalog items are eligible for this product. Only present for products where catalog matching is relevant (e.g., sponsored product listings, job boards, hotel ads).'
        ),
    ] = None
    brief_relevance: Annotated[
        str | None,
        Field(
            description='Explanation of why this product matches the brief (only included when brief is provided)'
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description='Expiration timestamp. Required for request-specific configured products whose targeting resolution, price, forecast, inventory, or terms are time-bound. After this time, a seller that still recognizes the issued configured ID within the authenticated account and referenced discovery/refinement lineage rejects create_media_buy with PRODUCT_EXPIRED and the buyer re-runs get_products. Once the seller no longer retains an expiry tombstone, or whenever the ID belongs to another account or lineage, PRODUCT_NOT_FOUND applies instead; sellers are not required to retain tombstones indefinitely and MUST NOT disclose cross-tenant existence through error choice.'
        ),
    ] = None
    product_card: Annotated[
        ProductCard | None,
        Field(
            description='Optional standard visual card for displaying this product in user interfaces (catalog browsers, dashboards, agent UIs). Distinct from `format` — product_card describes the UI rendering of the product itself, not the ad creative the product accepts. Typed inline; no format_id indirection. Receivers render the card directly from these fields.'
        ),
    ] = None
    product_card_detailed: Annotated[
        ProductCardDetailed | None,
        Field(
            description='Optional detailed card with hero + carousel + structured specifications, for rich product presentation (media-kit-style pages, full product detail views). Distinct from `format` — describes the UI rendering of the product itself, not the ad creative the product accepts. Typed inline; no format_id indirection.'
        ),
    ] = None
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description='Collections available in this product. Each entry references collections declared in an adagents.json by domain and collection ID. Buyers resolve full collection objects from the referenced adagents.json. Product selectors must name explicit collection_ids — the domain-only bulk-grant selector form is for authorization scoping, not product composition.',
            min_length=1,
        ),
    ] = None
    collection_targeting_allowed: Annotated[
        StrictBool | None,
        Field(
            description="Whether buyers can select a subset of this product's collections through targeting_overlay.collection_list or targeting_overlay.collection_selection. When false, the product is a fixed bundle (a collection_selection that exactly restates the complete bundle remains an inherent match); when true, collection selection is a product-scoped overlay capability."
        ),
    ] = False
    list_applications: Annotated[
        list[inventory_list_application.InventoryListApplication] | None,
        Field(
            description='Product-scoped receipts for every effective property- or collection-list targeting reference. Sellers MUST return one receipt per application regardless of response field projection; exclusion applications receive a receipt even when summary.matched is zero, while zero matches for any inclusion application make the product ineligible and it is not returned. Each receipt uses the same pre-list product inventory baseline; pricing and forecast reflect inventory remaining after all effective lists are composed.',
            min_length=1,
        ),
    ] = None
    installments: Annotated[
        list[installment.Installment] | None,
        Field(
            description='Specific installments included in this product. Each installment references its parent through canonical collection_ref when the product spans multiple collections or publisher namespaces; collection_id remains a deprecated single-namespace shorthand. When absent with collections present, the product covers the collections broadly (run-of-collection).'
        ),
    ] = None
    enforced_policies: Annotated[
        list[str] | None,
        Field(
            description='Registry policy IDs the seller enforces for this product. Enforcement level comes from the policy registry. Buyers can filter products by required policies.'
        ),
    ] = None
    acceptance_policy_profile_ids: (
        acceptance_policy_profile_ids_1.AcceptancePolicyProfileIds | None
    ) = None
    trusted_match: Annotated[
        TrustedMatch | None,
        Field(
            description='Trusted Match Protocol capabilities for this product. When present, the product supports real-time contextual and/or identity matching via TMP. Buyers use this to determine what response types the publisher can accept and whether brands can be selected dynamically at match time.'
        ),
    ] = None
    audience_activation: Annotated[
        AudienceActivation | None,
        Field(
            description="How buyer audience data can reach this product's targeting. Absence means undeclared — buyers SHOULD treat it as needs-clarification rather than non-support, except under an audience_activation_methods filter, where sellers MUST exclude undeclared products. Declare when the product accepts buyer audiences. Experimental: sellers declaring this MUST list media_buy.audience_activation in experimental_features on get_adcp_capabilities."
        ),
    ] = None
    material_submission: Annotated[
        MaterialSubmission | None,
        Field(
            description="Instructions for submitting physical creative materials (print, static OOH, cinema). Present only for products requiring physical delivery outside the digital creative assignment flow. Buyer agents MUST validate url and email domains against the seller's known domains (from adagents.json) before submitting materials. Never auto-submit without human confirmation."
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> Product:
        # ``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 (('format_ids',), ('format_options',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'Product requires at least one of these field groups: format_ids | format_options'
        )

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

• Product

Class variables

var acceptance_policy_profile_ids : AcceptancePolicyProfileIds | None

var allowed_actions : list[ProductAllowedAction] | None

var audience_activation : AudienceActivation | None

var audience_evidence : list[AudienceEvidence] | None

var audience_evidence_selections : list[AudienceEvidenceSelection] | None

var audio_distribution_types : list[AudioDistributionType] | None

var brief_relevance : str | None

var cancellation_policy : CancellationPolicy | None

var catalog_match : CatalogMatch | None

var catalog_types : list[CatalogType] | None

var channels : list[MediaChannel] | None

var collection_targeting_allowed : bool | None

var collections : list[CollectionSelector] | None

var conversion_tracking : ConversionTracking | None

var creative_policy : CreativePolicy | None

var data_provider_signals : list[DataProviderSignalSelector1 | DataProviderSignalSelector2 | DataProviderSignalSelector3] | None

var delivery_measurement : DeliveryMeasurement | None

var delivery_type : DeliveryType

var demographic_targeting : DemographicTargetingCapability | None

var description : str

var enforced_policies : list[str] | None

var exclusivity : Exclusivity | None

var execution_requirements : list[ProductExecutionRequirement1 | ProductExecutionRequirement2 | ProductExecutionRequirement3] | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var forecast : DeliveryForecast | None

var format_ids : list[FormatReferenceStructuredObject] | None

var format_options : list[ProductFormatDeclaration1 | ProductFormatDeclaration2 | ProductFormatDeclaration3 | ProductFormatDeclaration4 | ProductFormatDeclaration5 | ProductFormatDeclaration6 | ProductFormatDeclaration7 | ProductFormatDeclaration8 | ProductFormatDeclaration9 | ProductFormatDeclaration10 | ProductFormatDeclaration11 | ProductFormatDeclaration12 | ProductFormatDeclaration13 | ProductFormatDeclaration14 | ProductFormatDeclaration15 | ProductFormatDeclaration16] | None

var identity : ProductIdentity | None

var included_signals : list[SignalListing] | None

var installments : list[Installment] | None

var is_custom : bool | None

var list_applications : list[InventoryListApplication1 | InventoryListApplication2] | None

var material_submission : MaterialSubmission | None

var max_optimization_goals : int | None

var measurement_readiness : MeasurementReadiness | None

var measurement_terms : MeasurementTerms | None

var media_buy_support : ProductMediaBuySupport | None

var metric_optimization : MetricOptimization | None

var model_config

var name : str

var outcome_measurement : OutcomeMeasurement | None

var overlay_support : TargetingOverlaySupport | None

var performance_standards : list[PerformanceStandard] | None

var placements : list[Placement] | None

var pricing_options : list[CpmPricingOption | VcpmPricingOption | CpcPricingOption | CpcvPricingOption | CpvPricingOption | CppPricingOption | CpaPricingOption | RevenueSharePricingOption | FlatRatePricingOption | TimeBasedPricingOption]

var product_card : ProductCard | None

var product_card_detailed : ProductCardDetailed | None

var product_id : str

var property_targeting_allowed : bool | None

var publisher_properties : list[PublisherProperty85 | PublisherProperty86 | PublisherProperty87]

var reporting_capabilities : ReportingCapabilities

var signal_targeting_allowed : bool | None

var signal_targeting_options : list[ProductSignalTargetingOption] | None

var signal_targeting_rules : SignalTargetingRules | None

var social_placement_surfaces : list[SocialPlacementSurface] | None

var sponsored_placement_types : list[SponsoredPlacementType] | None

var targeting_resolution : ProductTargetingResolution | None

var trusted_match : TrustedMatch | None

var vendor_metric_optimization : VendorMetricOptimization | None

var video_placement_types : list[VideoPlacementType] | None

class Product (**data: Any)

Expand source code

class Product(_LegacyProduct, CanonicalBoundaryModel):
    """Canonical product; formats, placements and pricing are canonical."""

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_ids: _RemovedFormatIds = Field(default=None, init=False)

    format_options: list[Format] = Field(  # type: ignore[assignment]
        min_length=1, description="Canonical creative formats accepted by this product."
    )
    placements: list[Placement] | None = Field(default=None, min_length=1)  # type: ignore[assignment]
    pricing_options: list[CanonicalPricingOption] = Field(min_length=1)

Canonical product; formats, placements and pricing are canonical.

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

• Product
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var format_ids : list[FormatReferenceStructuredObject] | None

var format_options : list[Format]

var model_config

var placements : list[Placement] | None

var pricing_options : list[CpmPricingOption | VcpmPricingOption | CpcPricingOption | CpcvPricingOption | CpvPricingOption | CppPricingOption | CpaPricingOption | RevenueSharePricingOption | FlatRatePricingOption | TimeBasedPricingOption]

Instance variables

var data_provider_signals : list[DataProviderSignalSelector1 | DataProviderSignalSelector2 | DataProviderSignalSelector3] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var outcome_measurement : OutcomeMeasurement | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

Inherited members

• Product:
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class ProductAllocation (**data: Any)

Expand source code

class ProductAllocation(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    product_id: Annotated[
        str, Field(description='ID of the product (must reference a product in the products array)')
    ]
    allocation_percentage: Annotated[
        StrictFloat | None,
        Field(
            description='Exact percentage of total budget allocated to this product in a fixed proposal. Percentages across all allocations MUST sum to 100. Must be absent in a seller-optimized proposal.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    min_spend_target_percentage: Annotated[
        StrictFloat | None,
        Field(
            description='Soft minimum-spend target as a percentage of the executed total budget. Only valid in seller-optimized proposals, and sellers MUST NOT emit it unless they advertise media_buy.features.seller_optimized_min_spend_targets. The seller SHOULD attempt to reach it, but it is not a delivery guarantee. Minimum targets across allocations MUST sum to no more than 100.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    max_spend_percentage: Annotated[
        StrictFloat | None,
        Field(
            description='Hard maximum share of the executed total budget that this product may spend. Only valid in seller-optimized proposals, and sellers MUST NOT emit it unless they advertise media_buy.features.seller_optimized_package_budgets. Maximums across allocations MUST collectively permit 100 percent of the budget to be spent.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Recommended subordinate package pacing. On proposal execution this becomes pacing on the derived package and MUST NOT cause delivery to exceed aggregate proposal/media-buy pacing. On a committed proposal it is a firm delivery term. On a seller-optimized proposal, sellers MUST NOT emit it unless they advertise media_buy.features.seller_optimized_package_pacing.'
        ),
    ] = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="Selected pricing option ID from the product's pricing_options array. Required when the containing proposal is committed so create_media_buy executes the exact disclosed commercial terms; optional on legacy draft proposals."
        ),
    ] = None
    rationale: Annotated[
        str | None,
        Field(description='Explanation of why this product and allocation are recommended'),
    ] = None
    sequence: Annotated[
        SchemaInt | None,
        Field(description='Optional ordering hint for multi-line-item plans (1-based)', ge=1),
    ] = None
    tags: Annotated[
        list[str] | None,
        Field(
            description="Categorical tags for this allocation (e.g., 'desktop', 'german', 'mobile') - useful for grouping/filtering allocations by dimension"
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description='Recommended flight start date/time for this allocation in ISO 8601 format. Allows publishers to propose per-flight scheduling within a proposal. When omitted, the allocation applies to the full campaign date range.'
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description='Recommended flight end date/time for this allocation in ISO 8601 format. Allows publishers to propose per-flight scheduling within a proposal. When omitted, the allocation applies to the full campaign date range.'
        ),
    ] = None
    daypart_targets: Annotated[
        list[daypart_target.DaypartTarget] | None,
        Field(
            description="Recommended time windows for this allocation in spot-plan proposals. Each entry's timezone defaults to inventory_local when omitted, and entries MAY use different clocks.",
            min_length=1,
        ),
    ] = None
    forecast: Annotated[
        delivery_forecast.DeliveryForecast | None,
        Field(description='Forecasted delivery metrics for this allocation'),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var allocation_percentage : float | None

var daypart_targets : list[DaypartTarget] | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var forecast : DeliveryForecast | None

var max_spend_percentage : float | None

var min_spend_target_percentage : float | None

var model_config

var pacing : Pacing | None

var pricing_option_id : str | None

var product_id : str

var rationale : str | None

var sequence : int | None

var start_time : pydantic.types.AwareDatetime | None

var tags : list[str] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ProductAllowedAction (**data: Any)

Expand source code

class ProductAllowedAction(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    action: Annotated[
        media_buy_available_action_id.MediaBuyAvailableActionId,
        Field(
            description='The action identifier. Accepts every legacy valid_actions value plus structured-only actions such as update_media_buy_frequency_cap.'
        ),
    ]
    modes: Annotated[
        list[media_buy_action_mode.MediaBuyActionMode],
        Field(
            description='Modes available for this action on this product. A product may declare multiple modes (for example `self_serve` within tolerances, escalating to `requires_approval` outside) — the buy-side `available_actions[<action>].mode` resolves to the singular mode in effect at mutation time. SDKs that see multiple modes MUST NOT assume which one will fire; they must read the resolved `mode` on the buy.',
            min_length=1,
        ),
    ]
    allowed_statuses: Annotated[
        list[media_buy_status.MediaBuyStatus] | None,
        Field(
            description='Media buy statuses in which this action is permitted. When absent, the action is permitted in all non-terminal statuses (`pending_creatives`, `pending_start`, `active`, `paused`).',
            min_length=1,
        ),
    ] = None
    sla: Annotated[
        sla_window.SlaWindow | None,
        Field(
            description='Optional SLA commitment for this action on this product. Absence means no commitment.'
        ),
    ] = None
    constraints: Annotated[
        change_term_constraints.MediaBuyChangeTermConstraints | None,
        Field(
            description='Optional advisory machine-readable bounds buyers can use during product selection. The proposal must restate any binding bounds in commercial_terms.change_terms[].constraints.'
        ),
    ] = None
    terms_ref: Annotated[
        str | None,
        Field(
            description='Optional advisory pointer to published commercial terms governing this product action. It is not a proposal change-term identity and never grants a binding change right; a proposal materializes binding rights under commercial_terms.change_terms[].term_id.'
        ),
    ] = 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

Class variables

var action : MediaBuyValidAction | Literal['update_media_buy_frequency_cap']

var allowed_statuses : list[MediaBuyStatus] | None

var constraints : MediaBuyChangeTermConstraints1 | MediaBuyChangeTermConstraints2 | MediaBuyChangeTermConstraints3 | MediaBuyChangeTermConstraints4 | None

var model_config

var modes : list[MediaBuyActionMode]

var sla : SlaWindow | None

var terms_ref : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ProductCard (**data: Any)

Expand source code

class ProductCard(AdCPBaseModel):
    title: Annotated[bound_value.A2UiBoundValue, Field(description='Product name')]
    price: Annotated[bound_value.A2UiBoundValue, Field(description='Price display string')]
    image: Annotated[bound_value.A2UiBoundValue | None, Field(description='Product image URL')] = (
        None
    )
    description: Annotated[
        bound_value.A2UiBoundValue | None, Field(description='Product description')
    ] = None
    badge: Annotated[
        bound_value.A2UiBoundValue | None, Field(description="Badge text (e.g., 'Best Seller')")
    ] = None
    ctaLabel: Annotated[
        bound_value.A2UiBoundValue | None, Field(description='CTA button label')
    ] = None
    action: Action23 | None = 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

Class variables

var action : Action23 | None

var badge : A2UiBoundValue1 | A2UiBoundValue2 | A2UiBoundValue3 | A2UiBoundValue4 | A2UiBoundValue5 | None

var ctaLabel : A2UiBoundValue1 | A2UiBoundValue2 | A2UiBoundValue3 | A2UiBoundValue4 | A2UiBoundValue5 | None

var description : A2UiBoundValue1 | A2UiBoundValue2 | A2UiBoundValue3 | A2UiBoundValue4 | A2UiBoundValue5 | None

var image : A2UiBoundValue1 | A2UiBoundValue2 | A2UiBoundValue3 | A2UiBoundValue4 | A2UiBoundValue5 | None

var model_config

var price : A2UiBoundValue1 | A2UiBoundValue2 | A2UiBoundValue3 | A2UiBoundValue4 | A2UiBoundValue5

var title : A2UiBoundValue1 | A2UiBoundValue2 | A2UiBoundValue3 | A2UiBoundValue4 | A2UiBoundValue5

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ProductCardDetailed (**data: Any)

Expand source code

class ProductCardDetailed(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    hero_image: Annotated[
        image_asset.ImageAsset | None,
        Field(description='Primary hero image at the top of the detailed view.'),
    ] = None
    carousel_images: Annotated[
        list[image_asset.ImageAsset] | None,
        Field(description='Additional images for a swipeable carousel below the hero.'),
    ] = None
    title: Annotated[str | None, Field(description='Page title (typically the product name).')] = (
        None
    )
    description: Annotated[
        str | None,
        Field(
            description='Full descriptive copy. Markdown allowed in client renderers that support it; otherwise treat as plain text.'
        ),
    ] = None
    specifications: Annotated[
        list[Specification] | None,
        Field(
            description="Structured key/value specifications (e.g., 'Aspect ratio: 9:16', 'Duration: 30s'). Each item is a labeled fact about the product."
        ),
    ] = None
    price_label: Annotated[str | None, Field(description='Formatted price or pricing summary.')] = (
        None
    )
    cta_label: Annotated[str | None, Field(description='Call-to-action button label.')] = None
    reference_assets: Annotated[
        list[product_card_reference_asset.ProductCardReferenceAsset] | None,
        Field(
            description='Typed seller collateral for buyer planning — coverage maps, sample renders, environment photos, media kits. Distinct from hero_image/carousel_images, which are display-oriented.'
        ),
    ] = 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

Class variables

var carousel_images : list[ImageAsset] | None

var cta_label : str | None

var description : str | None

var hero_image : ImageAsset | None

var model_config

var price_label : str | None

var reference_assets : list[ProductCardReferenceAsset] | None

var specifications : list[Specification] | None

var title : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ProductCatalog (**data: Any)

Expand source code

class ProductCatalog(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    feed_url: Annotated[AnyUrl, Field(description='URL to product catalog feed')]
    feed_format: Annotated[FeedFormat | None, Field(description='Format of the product feed')] = (
        None
    )
    categories: Annotated[
        list[str] | None, Field(description='Product categories available in the catalog')
    ] = None
    last_updated: Annotated[
        AwareDatetime | None, Field(description='When the product catalog was last updated')
    ] = None
    update_frequency: Annotated[
        UpdateFrequency | None, Field(description='How frequently the product catalog is updated')
    ] = None
    agentic_checkout: Annotated[
        AgenticCheckout | None, Field(description='Agentic checkout endpoint configuration')
    ] = 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

Class variables

var agentic_checkout : AgenticCheckout | None

var categories : list[str] | None

var feed_format : FeedFormat | None

var feed_url : pydantic.networks.AnyUrl

var last_updated : pydantic.types.AwareDatetime | None

var model_config

var update_frequency : UpdateFrequency | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class LegacyProductFilters (**data: Any)

Expand source code

class ProductFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    delivery_type: delivery_type_1.DeliveryType | None = None
    exclusivity: Annotated[
        exclusivity_1.Exclusivity | None,
        Field(
            description="Filter by exclusivity level. Returns products matching the specified exclusivity (e.g., 'exclusive' returns only sole-sponsorship products)."
        ),
    ] = None
    is_fixed_price: Annotated[
        StrictBool | None,
        Field(
            description='Legacy filter for fixed versus auction pricing availability. true returns options with fixed_price; false returns auction options whose price is established through bid_price. Contingent options such as revenue_share match neither value and MUST be omitted whenever this filter is present. Use pricing_structures to discover contingent pricing. Products with both fixed and auction options match both true and false, but sellers MUST return only entries matching the requested structure.'
        ),
    ] = None
    pricing_structures: Annotated[
        list[pricing_structure.PricingStructure] | None,
        Field(
            description='Filter by how the payable price is determined. fixed selects options with fixed_price, auction selects options established through bid_price, and contingent selects options calculated from a measured business outcome after delivery (currently revenue_share). Products match when at least one pricing option has a requested structure. Sellers MUST return only matching pricing_options entries. When combined with is_fixed_price, both filters apply and the returned entries must satisfy both.',
            min_length=1,
        ),
    ] = None
    pricing_currencies: Annotated[
        list[PricingCurrency] | None,
        Field(
            description='Filter by currencies the buyer can use for the media product transaction, using ISO 4217 currency codes. Products match when they offer at least one product-level pricing_options entry in one of the requested currencies and any seller-applied or otherwise mandatory product-scoped signal charges are satisfiable in one of those currencies or have no incremental price. Mandatory custom signal pricing without currency is not satisfiable for this filter unless the seller can truthfully treat it as having no incremental price. Sellers MUST return only product pricing_options entries whose currency is in this list so buyers can select deterministically from discovery. This filter does not require pruning optional signal or vendor add-on pricing; buyers should avoid optional add-ons priced only in unsupported currencies.',
            min_length=1,
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatReferenceStructuredObject] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2; removed in AdCP 4.0. Filter by legacy named-format references. Use `format_kinds` or `format_option_refs`.',
            min_length=1,
        ),
    ] = None
    format_kinds: Annotated[
        list[str] | None,
        Field(
            description='Filter to products accepting any of these canonical format kinds.',
            min_length=1,
        ),
    ] = None
    format_option_refs: Annotated[
        list[format_option_ref.FormatOptionReference] | None,
        Field(
            description='Filter to products accepting any of these exact publisher- or product-scoped canonical format options.',
            min_length=1,
        ),
    ] = None
    standard_formats_only: Annotated[
        StrictBool | None, Field(description='Only return products accepting IAB standard formats')
    ] = None
    min_exposures: Annotated[
        SchemaInt | None,
        Field(description='Minimum exposures/impressions needed for measurement validity', ge=1),
    ] = None
    start_date: Annotated[
        date | None,
        Field(
            description='Campaign start date (ISO 8601 date format: YYYY-MM-DD) for availability checks'
        ),
    ] = None
    end_date: Annotated[
        date | None,
        Field(
            description='Campaign end date (ISO 8601 date format: YYYY-MM-DD) for availability checks'
        ),
    ] = None
    budget_range: Annotated[
        BudgetRange | None, Field(description='Budget range to filter appropriate products')
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy coverage filter. On compact discovery tasks use criteria.offer_filters.countries. Return products whose inventory covers at least one requested area; this does not impose delivery targeting or require selectable targeting support. Retained get_products handlers MUST preserve the original coverage predicate.',
            min_length=1,
        ),
    ] = None
    regions: Annotated[
        list[Region] | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy coverage filter. On compact discovery tasks use criteria.offer_filters.regions. Return products whose inventory covers at least one requested area; this does not impose delivery targeting or require selectable targeting support. Retained get_products handlers MUST preserve the original coverage predicate.',
            min_length=1,
        ),
    ] = None
    metros: Annotated[
        list[Metro] | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy coverage filter. On compact discovery tasks use criteria.offer_filters.metros. Return products whose inventory covers at least one requested area; this does not impose delivery targeting or require selectable targeting support. Retained get_products handlers MUST preserve the original coverage predicate.',
            min_length=1,
        ),
    ] = None
    channels: Annotated[
        list[channels_1.MediaChannel] | None,
        Field(
            description="Filter by advertising channels (e.g., ['display', 'ctv', 'dooh'])",
            min_length=1,
        ),
    ] = None
    video_placement_types: Annotated[
        list[video_placement_type.VideoPlacementType] | None,
        Field(
            description='Filter product metadata by declared video placement types, using IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. A product matches when its declared array intersects the requested array. This is discovery classification only and does not promise delivery exclusively on a requested type; buyers needing exact placement inventory use targeting_overlay.placement_selection against targetable placements. This filter has set semantics for wholesale feed canonicalization.',
            min_length=1,
        ),
    ] = None
    audio_distribution_types: Annotated[
        list[audio_distribution_type.AudioDistributionType] | None,
        Field(
            description='Filter product metadata by declared audio distribution types, using IAB Tech Lab/OpenRTB 2.6 audio.feed definitions with AdCP-native names. A product matches when its declared array intersects the requested array. This is discovery classification only and does not promise delivery exclusively on a requested type. This filter has set semantics for wholesale feed canonicalization.',
            min_length=1,
        ),
    ] = None
    sponsored_placement_types: Annotated[
        list[sponsored_placement_type.SponsoredPlacementType] | None,
        Field(
            description='Filter retail-media product metadata by declared sponsored-placement types (sponsored search, sponsored display, or sponsored native). A product matches when its declared array intersects the requested array. This is discovery classification only and does not promise delivery exclusively on a requested type. This filter has set semantics for wholesale feed canonicalization.',
            min_length=1,
        ),
    ] = None
    social_placement_surfaces: Annotated[
        list[social_placement_surface.SocialPlacementSurface] | None,
        Field(
            description='Filter social-product metadata by declared placement surfaces (feed, stories, short_video, explore, or search). A product matches when its declared array intersects the requested array. This is discovery classification only and does not promise delivery exclusively on a requested surface; buyers needing an exact public placement use targeting_overlay.placement_selection. This filter has set semantics for wholesale feed canonicalization.',
            min_length=1,
        ),
    ] = None
    required_axe_integrations: Annotated[
        list[AnyUrl] | None,
        Field(
            deprecated=True,
            description='Deprecated: Use trusted_match filter instead. Filter to products executable through specific agentic ad exchanges. URLs are canonical identifiers.',
            min_length=1,
        ),
    ] = None
    trusted_match: Annotated[
        TrustedMatch | None,
        Field(
            description='Filter products by Trusted Match Protocol capabilities. Only products with matching TMP support are returned.'
        ),
    ] = None
    audience_activation_methods: Annotated[
        list[
            AudienceActivationMethods
            | AudienceActivationMethods1
            | AudienceActivationMethods2
            | AudienceActivationMethods3
            | AudienceActivationMethods4
            | AudienceActivationMethods5
        ]
        | None,
        Field(
            description="Filter to products whose audience_activation.methods matches at least one requested entry (OR across entries). Within an entry every specified field must match (AND); omitted optional fields are wildcards; directions matches on non-empty intersection, and a method that omits directions matches any requested directions; vendor matches on domain, plus brand_id when specified. Fields inapplicable to the requested pattern (e.g. transport on a clean_room entry) make that entry unsatisfiable. Sellers MUST exclude products with no audience_activation declaration when this filter is present; exclusions MAY be reported via filter_diagnostics.excluded_by. Experimental: part of the media_buy.audience_activation surface — buyers SHOULD check the seller's experimental_features before filtering on it; sellers that do not list the feature ignore this filter.",
            min_length=1,
        ),
    ] = None
    required_features: Annotated[
        media_buy_features.MediaBuyFeatures | None,
        Field(
            description='Filter to products from sellers supporting specific protocol features. Only features set to true are used for filtering.'
        ),
    ] = None
    required_geo_targeting: Annotated[
        list[RequiredGeoTargetingItem] | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use get_products.required_overlay_support, which is product-scoped and applies consistently to geographic and non-geographic targeting dimensions.',
            min_length=1,
        ),
    ] = None
    signal_targeting: Annotated[
        list[SignalTargetingItem] | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy signal-option eligibility filter. Retained get_products handlers MUST preserve the signal identity, value predicate, and requested include/exclude capability. This does not activate delivery targeting. Native buyers use criteria.targeting_overlay.signal_targeting_groups only for concrete delivery selections, preserving exclusion through group operators; copying targeting_mode into targeting_overlay.signal_targeting does not preserve it.',
            min_length=1,
        ),
    ] = None
    postal_areas: Annotated[
        list[postal_area.PostalArea] | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy coverage filter. On compact discovery tasks use criteria.offer_filters.postal_areas. Return products whose inventory covers at least one requested area; this does not impose delivery targeting or require selectable targeting support. Retained get_products handlers MUST preserve the original coverage predicate.',
            min_length=1,
        ),
    ] = None
    geo_proximity: Annotated[
        list[GeoProximityItem] | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy coverage filter. On compact discovery tasks use criteria.offer_filters.geo_proximity. Return products whose inventory covers at least one requested area; this does not impose delivery targeting or require selectable targeting support. Retained get_products handlers MUST preserve the original coverage predicate.',
            min_length=1,
        ),
    ] = None
    required_performance_standards: Annotated[
        list[performance_standard.PerformanceStandard] | None,
        Field(
            description="Filter to products that can meet the buyer's performance standard requirements. Each entry specifies a metric, minimum threshold, and optionally a required vendor and standard. Products that cannot meet these thresholds or do not support the specified vendors are excluded. Use this to tell the seller upfront: 'I need DoubleVerify for viewability at 70% MRC.'",
            min_length=1,
        ),
    ] = None
    required_metrics: Annotated[
        list[available_metric.AvailableMetric] | None,
        Field(
            description="Filter to products whose `reporting_capabilities.available_metrics` is a superset of these metrics — i.e., products that commit to reporting all listed metrics in delivery responses. Use this for capability-level discovery (e.g., 'I need products that report `completed_views` for a CTV CPCV buy'); guarantee-level requirements with thresholds belong in `required_performance_standards` and `measurement_terms`. Sellers MUST silently exclude products that cannot meet this list (filter-not-fail; do not return an error). Under the container-subsumption rule in `enums/available-metric.json`, `viewability` satisfies numeric leaves such as `viewable_rate`; structured distributions require explicit `viewed_seconds_percentiles` or `viewed_seconds_histogram` declarations. The product's declared `available_metrics` becomes the binding reporting contract carried into the resulting media buy — the same metric vocabulary is used to compute `missing_metrics` on `get_media_buy_delivery`.",
            examples=[
                ['completed_views'],
                ['completed_views', 'completion_rate'],
                ['impressions', 'spend', 'engagements'],
            ],
            min_length=1,
        ),
    ] = None
    required_vendor_metrics: Annotated[
        list[RequiredVendorMetric] | None,
        Field(
            description="Filter to products whose `reporting_capabilities.vendor_metrics` matches these criteria. Each entry pins a `vendor` (matches any metric from that vendor), a `metric_id` (matches the metric across any vendor that uses that identifier), or both (specific vendor's specific metric). A product matches if its declared `vendor_metrics` covers ALL listed entries (AND across entries; pins within an entry are conjunctive). Cross-vendor discovery (e.g., 'I need attention measurement from any vendor that does it') is the buyer agent's responsibility — the agent resolves which vendors offer a category via the vendors' `brand.json` records, then enumerates them as filter entries. AdCP does not carry vendor-side metric metadata (category, methodology, standard alignment) in the filter surface; that lives at the vendor and is queried out-of-band. Sellers MUST silently exclude non-matching products (filter-not-fail; do not return an error) — same convention as the other `required_*` filters.",
            examples=[
                [{'vendor': {'domain': 'attentionvendor.example'}}],
                [
                    {
                        'vendor': {'domain': 'panelmeasurement.example'},
                        'metric_id': 'demographic_reach',
                    }
                ],
                [
                    {'vendor': {'domain': 'attentionvendor.example'}},
                    {'vendor': {'domain': 'secondattentionvendor.example'}},
                ],
            ],
            min_length=1,
        ),
    ] = None
    keywords: Annotated[
        list[Keyword] | None,
        Field(
            deprecated=True,
            description='DEPRECATED legacy product eligibility filter. Retained get_products handlers MUST preserve the requested keyword eligibility and match_type (default broad). This is not an instruction to add package keyword targeting. Native buyers use criteria.targeting_overlay.keyword_targets only when they intend a delivery constraint, or criteria.required_overlay_support.keyword_targets for future selectability.',
            min_length=1,
        ),
    ] = None
    audience_evidence_requirements: Annotated[
        audience_evidence_requirements_1.AudienceEvidenceRequirements | None,
        Field(
            description='Buyer policy for evaluating Product.audience_evidence. In required mode, sellers MUST apply the evidence_presence and admissibility semantics and exclude non-matching products; they MUST NOT ignore an unsupported hard requirement. In preferred mode, sellers use matches for ranking and explain the evidence selected. Buyers SHOULD inspect media_buy.audience_evidence capabilities before sending this object.'
        ),
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(
            description='Vendor-namespaced extension parameters for seller-specific filter criteria not covered by standard fields. Keys MUST be namespaced under a vendor or platform key (e.g., ext.gam, ext.platform_x). Sellers MUST treat all values as untrusted buyer input; do not interpolate into LLM prompts, SQL queries, or system commands without sanitization. Persistent use of an extension key across multiple buyers is a signal to propose standardization.'
        ),
    ] = 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

• ProductFilters

Class variables

var audience_activation_methods : list[AudienceActivationMethods | AudienceActivationMethods1 | AudienceActivationMethods2 | AudienceActivationMethods3 | AudienceActivationMethods4 | AudienceActivationMethods5] | None

var audience_evidence_requirements : AudienceEvidenceRequirements | None

var audio_distribution_types : list[AudioDistributionType] | None

var budget_range : BudgetRange | None

var channels : list[MediaChannel] | None

var countries : list[Country] | None

var delivery_type : DeliveryType | None

var end_date : datetime.date | None

var exclusivity : Exclusivity | None

var ext : ExtensionObject | None

var format_ids : list[FormatReferenceStructuredObject] | None

var format_kinds : list[str] | None

var format_option_refs : list[FormatOptionReference1 | FormatOptionReference2] | None

var geo_proximity : list[GeoProximityItem] | None

var is_fixed_price : bool | None

var keywords : list[Keyword] | None

var metros : list[Metro] | None

var min_exposures : int | None

var model_config

var postal_areas : list[PostalArea] | None

var pricing_currencies : list[PricingCurrency] | None

var pricing_structures : list[PricingStructure] | None

var regions : list[Region] | None

var required_axe_integrations : list[pydantic.networks.AnyUrl] | None

var required_features : MediaBuyFeatures | None

var required_geo_targeting : list[RequiredGeoTargetingItem] | None

var required_metrics : list[AvailableMetric] | None

var required_performance_standards : list[PerformanceStandard] | None

var required_vendor_metrics : list[RequiredVendorMetric] | None

var signal_targeting : list[SignalTargetingItem5 | SignalTargetingItem6 | SignalTargetingItem7] | None

var social_placement_surfaces : list[SocialPlacementSurface] | None

var sponsored_placement_types : list[SponsoredPlacementType] | None

var standard_formats_only : bool | None

var start_date : datetime.date | None

var trusted_match : TrustedMatch | None

var video_placement_types : list[VideoPlacementType] | None

class ProductFilters (**data: Any)

Expand source code

class ProductFilters(_LegacyProductFilters, CanonicalBoundaryModel):
    """Canonical product filters; legacy identity selection is unavailable."""

    if TYPE_CHECKING:  # the removed field, hidden from the constructor too
        format_ids: _RemovedFormatIds = Field(default=None, init=False)

Canonical product filters; legacy identity selection is unavailable.

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

• ProductFilters
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var format_ids : list[FormatReferenceStructuredObject] | None

var model_config

Instance variables

var countries : list[Country] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var geo_proximity : list[GeoProximityItem] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var keywords : list[Keyword] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var metros : list[Metro] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var postal_areas : list[PostalArea] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var regions : list[Region] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var required_axe_integrations : list[pydantic.networks.AnyUrl] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var required_geo_targeting : list[RequiredGeoTargetingItem] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

var signal_targeting : list[SignalTargetingItem5 | SignalTargetingItem6 | SignalTargetingItem7] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

Inherited members

• ProductFilters:
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class ProductDiscoveryProductId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class ProductId(ScalarStr):
    __slots__ = ()
    _constraints = {'min_length': 1}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

Subclasses

• PolicyId

class RequestProposalsProductId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class ProductId(Suggestion):
    pass

A str generated from a JSON Schema string root.

Ancestors

• Suggestion
• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class ProductSignalTargetingOption (**data: Any)

Expand source code

class ProductSignalTargetingOption(SignalListing):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_agent_segment_id: Annotated[
        str | None,
        Field(
            description='Optional opaque resolved-segment or seller execution handle for this signal. Omit when signal_ref plus the value expression is sufficient for the seller to resolve the signal. Include when the seller exposes a distinct runtime or activation handle that buyers must echo in packages[].targeting_overlay.signal_targeting_groups.groups[].signals[].signal_agent_segment_id. Buyers SHOULD echo this handle verbatim rather than reconstructing identity from categorical values; providers MAY namespace handles so cross-provider identity stays legible without a shared taxonomy registry.'
        ),
    ] = None
    activation_status: Annotated[
        ActivationStatus | None,
        Field(
            description="Whether this signal option is ready to select on create_media_buy for the requesting account. 'ready' means the buyer can select it directly. 'requires_activation' means the buyer must activate the signal first or include an activation_key the seller accepts."
        ),
    ] = ActivationStatus.ready
    allowed_targeting_modes: Annotated[
        list[AllowedTargetingMode] | None,
        Field(
            description="How this signal may be used when composing package-level signal targeting groups. 'include' means the signal may appear in an 'any' child group. 'exclude' means the signal may appear in a 'none' child group. Omit when the signal is include-only. This field declares the allowed buy-time group operator; binary package signal entries still use value=true in both include and exclude groups.",
            min_length=1,
        ),
    ] = [AllowedTargetingMode.include]
    default_selected: Annotated[
        StrictBool | None,
        Field(
            description="Whether the seller recommends or preselects this signal when composing this product. Buyers may remove it unless signal_targeting_rules.selection_mode is 'fixed'. When selection_mode is 'fixed', sellers apply default_selected signals even if the buyer omits signal_targeting_groups and MUST echo the applied entries on the resulting package state."
        ),
    ] = False
    selection_group: Annotated[
        str | None,
        Field(
            description='Optional product-defined composability bucket for signal options, such as alternative audience tiers, a key-value targeting plane, or an audience-segment targeting plane. Signals in the same selection_group are expected to be OR-combinable inside one child group for a given targeting mode, subject to signal_targeting_rules. Use different selection_group values when the product requires separate ANDed clauses, such as signal sets backed by different platform targeting primitives that cannot be collapsed into one child group. selection_group is a product-option grouping key, not a reference to one child object in packages[].targeting_overlay.signal_targeting_groups.groups[]. Sellers can use signal_targeting_rules.max_selected_per_group and signal_targeting_rules.selection_group_rules with selection_group to guide and validate storefront composition.'
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Signal pricing options available when this signal is selected on this product. Product-scoped pricing is authoritative for this product; if get_signals exposes a different default rate card, use this product-scoped price when composing the buy. Buyers pass the selected pricing_option_id in packages[].targeting_overlay.signal_targeting_groups.groups[].signals[].pricing_option_id. Omit when the signal is bundled into the product price or has no incremental cost.',
            min_length=1,
        ),
    ] = None
    signal_ref: Annotated[
        signal_ref.SignalRef,
        Field(
            description="Canonical signal reference. Use scope 'product' for a product-local signal defined by this listing; use scope 'data_provider' with data_provider_domain for a signal defined in a data provider's published adagents.json signals[]; use scope 'signal_source' with signal_source_url for a source-native signal."
        ),
    ]

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

• SignalListing
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var activation_status : ActivationStatus | None

var allowed_targeting_modes : list[AllowedTargetingMode] | None

var default_selected : bool | None

var model_config

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var selection_group : str | None

var signal_agent_segment_id : str | None

var signal_ref : SignalRef1 | SignalRef2 | SignalRef3

Inherited members

• SignalListing:
  • model_dump
  • model_dump_json
  • model_summary

class Property (**data: Any)

Expand source code

class Property(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    property_id: Annotated[
        property_id_1.PropertyId | None,
        Field(
            description='Unique identifier for this property (optional). Enables referencing properties by ID instead of repeating full objects.'
        ),
    ] = None
    property_type: Annotated[
        property_type_1.PropertyType, Field(description='Type of advertising property')
    ]
    name: Annotated[str, Field(description='Human-readable property name')]
    identifiers: Annotated[
        list[Identifier], Field(description='Array of identifiers for this property', min_length=1)
    ]
    tags: Annotated[
        list[property_tag.PropertyTag] | None,
        Field(
            description='Tags for categorization and grouping (e.g., network membership, content categories)'
        ),
    ] = None
    supported_channels: Annotated[
        list[channels.MediaChannel] | None,
        Field(
            description="Advertising channels this property supports (e.g., ['display', 'olv', 'social']). Publishers declare which channels their inventory aligns with. Properties may support multiple channels. See the Media Channel Taxonomy for definitions."
        ),
    ] = None
    publisher_domain: Annotated[
        str | None,
        Field(
            description='Domain where adagents.json should be checked for authorization validation. Optional in adagents.json (file location implies domain).'
        ),
    ] = 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

Class variables

var identifiers : list[Identifier]

var model_config

var name : str

var property_id : PropertyId | None

var property_type : PropertyType

var publisher_domain : str | None

var supported_channels : list[MediaChannel] | None

var tags : list[PropertyTag] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PropertyId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class PropertyId(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[a-z0-9_]+$'}
    _json_schema_extra = {
        'description': 'Identifier for a publisher property. Must be lowercase alphanumeric with underscores only.',
        'examples': ['cnn_ctv_app', 'homepage', 'mobile_ios', 'instagram'],
        'title': 'Property ID',
    }

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class PropertyIdentifierTypes (*args, **kwds)

Expand source code

class PropertyIdentifierTypes(StrEnum):
    domain = 'domain'
    subdomain = 'subdomain'
    network_id = 'network_id'
    ios_bundle = 'ios_bundle'
    android_package = 'android_package'
    apple_app_store_id = 'apple_app_store_id'
    google_play_id = 'google_play_id'
    roku_store_id = 'roku_store_id'
    fire_tv_asin = 'fire_tv_asin'
    samsung_app_id = 'samsung_app_id'
    apple_tv_bundle = 'apple_tv_bundle'
    bundle_id = 'bundle_id'
    venue_id = 'venue_id'
    screen_id = 'screen_id'
    openooh_venue_type = 'openooh_venue_type'
    rss_url = 'rss_url'
    apple_podcast_id = 'apple_podcast_id'
    spotify_collection_id = 'spotify_collection_id'
    podcast_guid = 'podcast_guid'
    station_id = 'station_id'
    facility_id = 'facility_id'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var android_package

var apple_app_store_id

var apple_podcast_id

var apple_tv_bundle

var bundle_id

var domain

var facility_id

var fire_tv_asin

var google_play_id

var ios_bundle

var network_id

var openooh_venue_type

var podcast_guid

var roku_store_id

var rss_url

var samsung_app_id

var screen_id

var spotify_collection_id

var station_id

var subdomain

var venue_id

class PropertyList (**data: Any)

Expand source code

class PropertyList(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list_id: Annotated[str, Field(description='Unique identifier for this property list')]
    name: Annotated[str, Field(description='Human-readable name for the list')]
    description: Annotated[str | None, Field(description="Description of the list's purpose")] = (
        None
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns this list. Returned as account_id form (seller-assigned identifier).'
        ),
    ] = None
    base_properties: Annotated[
        list[base_property_source.BasePropertySource] | None,
        Field(
            description="Array of property sources to evaluate. Each entry is a discriminated union: publisher_tags (publisher_domain + tags), publisher_ids (publisher_domain + property_ids), or identifiers (direct identifiers). If omitted, queries the agent's entire property database."
        ),
    ] = None
    filters: Annotated[
        property_list_filters.PropertyListFilters | None,
        Field(description='Dynamic filters applied when resolving the list'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand reference used to automatically apply appropriate rules. Resolved to full brand identity at execution time.'
        ),
    ] = None
    webhook_url: Annotated[
        AnyUrl | None,
        Field(description='URL to receive notifications when the resolved list changes'),
    ] = None
    cache_duration_hours: Annotated[
        SchemaInt | None,
        Field(
            description='Recommended cache duration for resolved list. Consumers should re-fetch after this period.',
            ge=1,
        ),
    ] = 24
    created_at: Annotated[AwareDatetime | None, Field(description='When the list was created')] = (
        None
    )
    updated_at: Annotated[
        AwareDatetime | None, Field(description='When the list was last modified')
    ] = None
    property_count: Annotated[
        SchemaInt | None,
        Field(description='Number of properties in the resolved list (at time of last resolution)'),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for this property list. Present when the requesting account has a billing relationship with the list provider. The buyer passes the selected pricing_option_id in report_usage.',
            min_length=1,
        ),
    ] = 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

Class variables

var account : AccountReference1 | AccountReference2 | None

var base_properties : list[BasePropertySource1 | BasePropertySource2 | BasePropertySource3] | None

var brand : BrandReference | None

var cache_duration_hours : int | None

var created_at : pydantic.types.AwareDatetime | None

var description : str | None

var filters : PropertyListFilters | None

var list_id : str

var model_config

var name : str

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var property_count : int | None

var updated_at : pydantic.types.AwareDatetime | None

var webhook_url : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PropertyListChangedWebhook (**data: Any)

Expand source code

class PropertyListChangedWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Sender-generated key stable across retries of the same webhook event. Governance agents MUST generate a cryptographically random value (UUID v4 recommended) per distinct list-change event and reuse the same key on every retry. Recipients MUST dedupe by this key, scoped to the authenticated sender identity established by the RFC 9421 signing key — keys from different governance agents are independent.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    event: Annotated[Literal['property_list_changed'], Field(description='The event type')] = 'property_list_changed'
    list_id: Annotated[str, Field(description='ID of the property list that changed')]
    list_name: Annotated[str | None, Field(description='Name of the property list')] = None
    change_summary: Annotated[
        ChangeSummary | None, Field(description='Summary of changes to the resolved list')
    ] = None
    resolved_at: Annotated[AwareDatetime, Field(description='When the list was re-resolved')]
    cache_valid_until: Annotated[
        AwareDatetime | None,
        Field(description='When the consumer should refresh from the governance agent'),
    ] = None
    signature: Annotated[
        str,
        Field(
            deprecated=True,
            description='Deprecated 3.x compatibility marker. Property-list webhooks previously required this field but did not define an implementable signature algorithm, signed bytes, or key-discovery contract. RFC 9421 signatures are carried in the Signature and Signature-Input HTTP headers and bind the complete payload through Content-Digest. New 3.2 senders MUST set this field to the literal value `rfc9421`; receivers MUST accept any string from an older 3.x sender and MUST ignore it when authenticating a delivery. The field remains required through 3.x for schema compatibility and is removed in 4.0.',
        ),
    ]
    ext: ext_1.ExtensionObject | None = 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

Class variables

var cache_valid_until : pydantic.types.AwareDatetime | None

var change_summary : ChangeSummary | None

var event : Literal['property_list_changed']

var ext : ExtensionObject | None

var idempotency_key : str

var list_id : str

var list_name : str | None

var model_config

var resolved_at : pydantic.types.AwareDatetime

var signature : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PropertyListFilters (**data: Any)

Expand source code

class PropertyListFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    countries_all: Annotated[
        list[CountriesAllItem] | None,
        Field(
            description='Property must have feature data for ALL listed countries (ISO codes). When omitted, no country restriction is applied.',
            min_length=1,
        ),
    ] = None
    channels_any: Annotated[
        list[channels.MediaChannel] | None,
        Field(
            description='Property must support ANY of the listed channels. When omitted, no channel restriction is applied.',
            min_length=1,
        ),
    ] = None
    property_types: Annotated[
        list[property_type.PropertyType] | None,
        Field(description='Filter to these property types', min_length=1),
    ] = None
    feature_requirements: Annotated[
        list[feature_requirement.FeatureRequirement] | None,
        Field(
            description='Feature-based requirements. Property must pass ALL requirements (AND logic).',
            min_length=1,
        ),
    ] = None
    exclude_identifiers: Annotated[
        list[identifier.Identifier] | None,
        Field(description='Identifiers to always exclude from results', min_length=1),
    ] = 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

Class variables

var channels_any : list[MediaChannel] | None

var countries_all : list[CountriesAllItem] | None

var exclude_identifiers : list[Identifier] | None

var feature_requirements : list[FeatureRequirement] | None

var model_config

var property_types : list[PropertyType] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PropertyListReference (**data: Any)

Expand source code

class PropertyListReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    agent_url: Annotated[AnyUrl, Field(description='URL of the agent managing the property list')]
    list_id: Annotated[
        str, Field(description='Identifier for the property list within the agent', min_length=1)
    ]
    auth_token: Annotated[
        str | None,
        Field(
            description='JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access.'
        ),
    ] = 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

Class variables

var agent_url : pydantic.networks.AnyUrl

var auth_token : str | None

var list_id : str

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PropertyTag (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class PropertyTag(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[a-z0-9_]+$'}
    _json_schema_extra = {
        'description': 'Tag for categorizing publisher properties. Must be lowercase alphanumeric with underscores only.',
        'examples': ['ctv', 'premium', 'news', 'sports', 'meta_network', 'social_media'],
        'title': 'Property Tag',
    }

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class PropertyType (*args, **kwds)

Expand source code

class PropertyType(StrEnum):
    website = 'website'
    mobile_app = 'mobile_app'
    ctv_app = 'ctv_app'
    desktop_app = 'desktop_app'
    dooh = 'dooh'
    podcast = 'podcast'
    radio = 'radio'
    linear_tv = 'linear_tv'
    streaming_audio = 'streaming_audio'
    ai_assistant = 'ai_assistant'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var ai_assistant

var ctv_app

var desktop_app

var dooh

var linear_tv

var mobile_app

var podcast

var radio

var streaming_audio

var website

class Proposal (**data: Any)

Expand source code

class Proposal(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    proposal_id: Annotated[
        str,
        Field(
            description='Unique identifier for this proposal. Used to finalize a draft proposal and to execute a committed proposal via create_media_buy.',
            max_length=255,
        ),
    ]
    name: Annotated[
        str, Field(description='Human-readable name for this media plan proposal', max_length=500)
    ]
    description: Annotated[
        str | None,
        Field(
            description='Explanation of the proposal strategy and what it achieves', max_length=2000
        ),
    ] = None
    allocations: Annotated[
        list[product_allocation.ProductAllocation],
        Field(
            description='Products and budget constraints in this plan. Fixed proposals require allocation_percentage on every entry and percentages MUST sum to 100. Seller-optimized proposals forbid exact allocation_percentage and may instead supply min_spend_target_percentage and max_spend_percentage, each only when the seller advertises the matching package-control capability (seller_optimized_min_spend_targets, seller_optimized_package_budgets). Publishers are responsible for validating cross-entry sums; buyers SHOULD validate them before execution.',
            min_length=1,
        ),
    ]
    budget_allocation: Annotated[
        budget_allocation_1.BudgetAllocation | None,
        Field(
            description='How the executed total budget is allocated across proposal products. Omit for legacy fixed proposals.'
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Recommended aggregate pacing for the executed media-buy budget. On a committed proposal this is part of the firm delivery terms.'
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Aggregate cap bound into this legacy proposal. It is authoritative when the proposal is executed and uses one counter across its packages.'
        ),
    ] = None
    proposal_status: Annotated[
        proposal_status_1.ProposalStatus | None,
        Field(
            description="Lifecycle status of this proposal and the per-proposal source of truth for whether finalization is required before create_media_buy. When absent, the proposal is ready to buy (backward compatible). 'draft' means indicative pricing — finalize via refine before purchasing. 'committed' means firm pricing with inventory reserved until expires_at and executable via create_media_buy."
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When this proposal expires and can no longer be executed. For draft proposals, indicates when indicative pricing becomes stale. For committed proposals, indicates when the inventory hold lapses — the buyer must call create_media_buy before this time.'
        ),
    ] = None
    insertion_order: Annotated[
        insertion_order_1.InsertionOrder | None,
        Field(
            description='Formal insertion order attached to a committed proposal. Present when the seller requires a signed agreement before the media buy can proceed. The buyer references the io_id in io_acceptance on create_media_buy.'
        ),
    ] = None
    total_budget_guidance: Annotated[
        TotalBudgetGuidance | None, Field(description='Optional budget guidance for this proposal')
    ] = None
    brief_alignment: Annotated[
        str | None,
        Field(
            description='Explanation of how this proposal aligns with the campaign brief',
            max_length=2000,
        ),
    ] = None
    forecast: Annotated[
        delivery_forecast.DeliveryForecast | None,
        Field(
            description='Aggregate forecasted delivery metrics for the entire proposal. When both proposal-level and allocation-level forecasts are present, the proposal-level forecast is authoritative for total delivery estimation.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var allocations : list[ProductAllocation]

var brief_alignment : str | None

var budget_allocation : BudgetAllocation1 | BudgetAllocation2 | None

var description : str | None

var expires_at : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var forecast : DeliveryForecast | None

var frequency_cap : MediaBuyFrequencyCap | None

var insertion_order : InsertionOrder | None

var model_config

var name : str

var pacing : Pacing | None

var proposal_id : str

var proposal_status : ProposalStatus | None

var total_budget_guidance : TotalBudgetGuidance | 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.

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

• GetAccountFinancialsResponse1
• GetAccountFinancialsResponse2
• ListAccountChangesResponse
• ListAccountsResponse
• ReportUsageResponse
• SyncAccountsResponse1
• SyncAccountsResponse2
• SyncGovernanceResponse
• AcquireRightsResponse1
• AcquireRightsResponse2
• AcquireRightsResponse3
• AcquireRightsResponse4
• CreativeApprovalResponse1
• CreativeApprovalResponse2
• CreativeApprovalResponse3
• CreativeApprovalResponse4
• GetBrandIdentityResponse1
• GetBrandIdentityResponse2
• GetRightsResponse1
• GetRightsResponse2
• SearchBrandsResponse
• UpdateRightsResponse1
• UpdateRightsResponse2
• VerifyBrandClaimErrorResponse
• VerifyBrandClaimSuccessResponse
• VerifyBrandClaimsErrorResponse
• VerifyBrandClaimsResponseBulk
• CreateCollectionListResponse
• DeleteCollectionListResponse
• GetCollectionListResponse
• ListCollectionListsResponse
• UpdateCollectionListResponse
• ComplyTestControllerResponse
• CalibrateContentResponse1
• CalibrateContentResponse2
• CreateContentStandardsResponse
• GetContentStandardsResponse1
• GetContentStandardsResponse2
• GetMediaBuyArtifactsResponse1
• GetMediaBuyArtifactsResponse2
• ListContentStandardsResponse
• UpdateContentStandardsResponse
• ValidateContentDeliveryResponse1
• ValidateContentDeliveryResponse2
• TasksGetResponse
• TasksListResponse
• GetCreativeDeliveryResponse
• GetCreativeFeaturesResponse1
• GetCreativeFeaturesResponse2
• GetCreativeFeaturesResponse3
• ListCreativeFormatsResponseCreativeAgent
• ListCreativesResponse
• ListTransformersResponseCreativeAgent
• PreviewCreativeResponse1
• PreviewCreativeResponse2
• PreviewCreativeResponse3
• PreviewCreativeResponse4
• SyncCreativesResponse1
• SyncCreativesResponse2
• SyncCreativesResponse3
• ValidateInputResponse
• GetPlanAuditLogsResponse
• SyncPlansResponse
• BuildCreativeResponse1
• BuildCreativeResponse2
• BuildCreativeResponse3
• BuildCreativeResponse4
• BuildCreativeResponse5
• BuildCreativeResponse6
• CreateMediaBuyResponse1
• CreateMediaBuyResponse2
• CreateMediaBuyResponse3
• GetMediaBuyDeliveryResponse
• GetMediaBuysResponse
• GetProductsRejected
• GetProductsResponse
• GetReportingStatusResponse
• ListCreativeFormatsResponse
• LogEventResponse1
• LogEventResponse2
• ProvidePerformanceFeedbackResponse1
• ProvidePerformanceFeedbackResponse2
• SyncAudiencesResponse1
• SyncAudiencesResponse2
• SyncAudiencesResponse3
• SyncCatalogsResponse1
• SyncCatalogsResponse2
• SyncCatalogsResponse3
• SyncEventSourcesResponse1
• SyncEventSourcesResponse2
• SyncReportingReceiptsResponse
• SyncReportingStatusResponse
• UpdateMediaBuyResponse1
• UpdateMediaBuyResponse2
• UpdateMediaBuyResponse3
• CreatePropertyListResponse
• DeletePropertyListResponse
• GetPropertyListResponse
• ListPropertyListsResponse
• UpdatePropertyListResponse
• ValidatePropertyDeliveryResponse
• GetAdcpCapabilitiesResponse
• GetPrincipalResponse
• GetTaskStatusResponse
• ListTasksResponse
• SyncAgentNotificationConfigsResponse
• SyncPrincipalResponse
• ActivateSignalResponse1
• ActivateSignalResponse2
• GetSignalsResponse
• SiGetOfferingResponse
• SiInitiateSessionResponse
• SiSendMessageResponse
• SiTerminateSessionResponse
• ContextMatchResponseRouterPublisher
• IdentityMatchResponseRouterPublisher
• ContextMatchResponseProviderRouter
• IdentityMatchResponseProviderRouter

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.

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

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 Provenance (**data: Any)

Expand source code

class Provenance(AdCPBaseModel):
    digital_source_type: Annotated[
        digital_source_type_1.DigitalSourceType | None,
        Field(
            description='IPTC-aligned classification of AI involvement in producing this content'
        ),
    ] = None
    synthetic_depiction: Annotated[
        StrictBool | None,
        Field(
            description='Assessed declaration of whether the content synthetically depicts a real or fictional person performing or appearing in a way that was generated or materially manipulated rather than captured as depicted. `true` covers both a fully synthetic performer and material manipulation of a real performer; `false` is an assessed declaration that the content does not contain such a depiction. Absence means the content has not been assessed for synthetic depiction. This field does not claim consent, legality, or independent verification, and receivers MUST NOT derive it solely from `digital_source_type`.'
        ),
    ] = None
    ai_tool: Annotated[
        AiTool | None,
        Field(
            description='AI system used to generate or modify this content. Aligns with IPTC 2025.1 AI metadata fields and C2PA claim_generator.'
        ),
    ] = None
    human_oversight: Annotated[
        HumanOversight | None,
        Field(
            description='Level of human involvement in the AI-assisted creation process. Independent of `disclosure.required` — the protocol does not derive disclosure obligations from oversight level. Some regulations include carve-outs for human-edited or human-directed AI output, but those carve-outs have factual prerequisites the schema cannot evaluate. Asserting `edited` or `directed` does not by itself justify `disclosure.required: false`.'
        ),
    ] = None
    declared_by: Annotated[
        DeclaredBy | None,
        Field(
            description='Party declaring this provenance. Identifies who attached the provenance claim, enabling receiving parties to assess trust.'
        ),
    ] = None
    declared_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When this provenance claim was made (ISO 8601). Distinct from created_time, which records when the content itself was produced. A provenance claim may be attached well after content creation, for example when retroactively declaring AI involvement for regulatory compliance.'
        ),
    ] = None
    created_time: Annotated[
        AwareDatetime | None,
        Field(description='When this content was created or generated (ISO 8601)'),
    ] = None
    c2pa: Annotated[
        C2pa | None,
        Field(
            description='C2PA sidecar manifest reference. Links to a detached cryptographic provenance manifest for this content. Note: file-level C2PA bindings break when ad servers transcode, resize, or re-encode assets. For pipelines with intermediaries, consider embedded_provenance as the primary provenance mechanism.'
        ),
    ] = None
    embedded_provenance: Annotated[
        list[EmbeddedProvenanceItem] | None,
        Field(
            description='Provenance metadata embedded within the content stream. Each entry declares one embedding layer: structured provenance data carried inside the content itself, as distinct from sidecar references (c2pa.manifest_url). Embedded provenance survives operations that break sidecar and file-level bindings: ad-server transcoding, CMS ingestion, copy-paste, reformatting, and CDN re-encoding. For ad-tech pipelines where content passes through multiple intermediaries, embedded provenance is the reliable path for provenance that persists from declaration through delivery. This is a declaration by the embedding party. The receiving party (the seller) is the verifier-of-record: it confirms the claim by calling a governance agent it trusts (typically one published in `creative_policy.accepted_verifiers`).',
            min_length=1,
        ),
    ] = None
    watermarks: Annotated[
        list[Watermark] | None,
        Field(
            description='Content watermarks applied to this asset. Each entry declares one watermarking layer: a content modification that encodes an identifier or fingerprint within the asset. Watermarks differ from embedded provenance: a watermark encodes an identifier (who generated it, who owns it), while embedded provenance carries or references a structured provenance record (the full chain of custody). A single asset may carry both. Aligns with C2PA action taxonomy: c2pa.watermarked.bound (watermark linked to a C2PA manifest) and c2pa.watermarked.unbound (watermark independent of any manifest). This is a declaration by the watermarking party. The receiving party (the seller) is the verifier-of-record: it confirms the claim by calling a governance agent it trusts (typically one published in `creative_policy.accepted_verifiers`).',
            min_length=1,
        ),
    ] = None
    disclosure: Annotated[
        Disclosure | None,
        Field(
            description='Regulatory disclosure requirements for this content. Indicates whether AI disclosure is required and under which jurisdictions.'
        ),
    ] = None
    verification: Annotated[
        list[VerificationItem] | None,
        Field(
            description='Third-party verification or detection results for this content. Multiple services may independently evaluate the same content. Provenance is a claim — verification results attached by the declaring party are supplementary. The enforcing party (e.g., seller/publisher) should run its own verification via get_creative_features or calibrate_content.',
            min_length=1,
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var ai_tool : AiTool | None

var c2pa : C2pa | None

var created_time : pydantic.types.AwareDatetime | None

var declared_at : pydantic.types.AwareDatetime | None

var declared_by : DeclaredBy | None

var digital_source_type : DigitalSourceType | None

var disclosure : Disclosure | None

var embedded_provenance : list[EmbeddedProvenanceItem] | None

var ext : ExtensionObject | None

var human_oversight : HumanOversight | None

var model_config

var synthetic_depiction : bool | None

var verification : list[VerificationItem] | None

var watermarks : list[Watermark] | None

class ReferenceRendererProvenance (**data: Any)

Expand source code

class Provenance(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_repository: Annotated[
        AnyUrl,
        Field(
            description='Allowlisted source repository that the npm provenance attestation MUST identify.'
        ),
    ]
    workflow_path: Annotated[
        str,
        Field(
            description='Repository-relative GitHub Actions workflow path that npm provenance buildDefinition.externalParameters.workflow.path MUST identify.',
            pattern='^\\.github/workflows/[A-Za-z0-9._/-]+\\.ya?ml$',
        ),
    ]

    @field_validator('source_repository')
    @classmethod
    def _require_github_source_repository(cls, value: AnyUrl) -> AnyUrl:
        if value.scheme != 'https' or value.host != 'github.com' or value.port != 443:
            raise ValueError('source_repository must use https://github.com/')
        if value.username is not None or value.password is not None:
            raise ValueError('source_repository must not contain credentials')
        return value

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

Class variables

var model_config

var source_repository : pydantic.networks.AnyUrl

var workflow_path : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ProvidePerformanceFeedbackRequest (**data: Any)

Expand source code

class ProvidePerformanceFeedbackRequest(AdcpRequest, AdcpVersionEnvelope, PerformanceFeedbackAssertion):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this logical assertion. MUST be unique per receiving agent to prevent cross-agent correlation; use a fresh UUID v4 for each new assertion. Retries use the same key and payload.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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
• PerformanceFeedbackAssertion
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

class ProvidePerformanceFeedbackByBuyerRefRequest (**data: Any)

Expand source code

class ProvidePerformanceFeedbackRequest(AdcpRequest, AdcpVersionEnvelope, PerformanceFeedbackAssertion):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this logical assertion. MUST be unique per receiving agent to prevent cross-agent correlation; use a fresh UUID v4 for each new assertion. Retries use the same key and payload.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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
• PerformanceFeedbackAssertion
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

class ProvidePerformanceFeedbackByMediaBuyRequest (**data: Any)

Expand source code

class ProvidePerformanceFeedbackRequest(AdcpRequest, AdcpVersionEnvelope, PerformanceFeedbackAssertion):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this logical assertion. MUST be unique per receiving agent to prevent cross-agent correlation; use a fresh UUID v4 for each new assertion. Retries use the same key and payload.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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
• PerformanceFeedbackAssertion
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | 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 ProvidePerformanceFeedbackResponse1 (**data: Any)

Expand source code

class ProvidePerformanceFeedbackResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    success: Literal[True]
    feedback_id: Annotated[str, StringConstraints(min_length=1)] | None = None
    application_status: Literal['accepted', 'applied', 'not_applied'] | None = None
    status_reason: Annotated[str, StringConstraints(max_length=500)] | None = None
    received_at: AwareDatetime | None = None
    applied_at: AwareDatetime | None = None
    sandbox: bool | None = 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.

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 application_status : Literal['accepted', 'applied', 'not_applied'] | None

var applied_at : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var ext : ExtensionObject | None

var feedback_id : str | None

var model_config

var received_at : pydantic.types.AwareDatetime | None

var sandbox : bool | None

var status_reason : str | None

var success : Literal[True]

class ProvidePerformanceFeedbackSuccessResponse (**data: Any)

Expand source code

class ProvidePerformanceFeedbackResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    success: Literal[True]
    feedback_id: Annotated[str, StringConstraints(min_length=1)] | None = None
    application_status: Literal['accepted', 'applied', 'not_applied'] | None = None
    status_reason: Annotated[str, StringConstraints(max_length=500)] | None = None
    received_at: AwareDatetime | None = None
    applied_at: AwareDatetime | None = None
    sandbox: bool | None = 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.

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 application_status : Literal['accepted', 'applied', 'not_applied'] | None

var applied_at : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var ext : ExtensionObject | None

var feedback_id : str | None

var model_config

var received_at : pydantic.types.AwareDatetime | None

var sandbox : bool | None

var status_reason : str | None

var success : Literal[True]

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 ProvidePerformanceFeedbackErrorResponse (**data: Any)

Expand source code

class ProvidePerformanceFeedbackResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 PublishedPostAsset (**data: Any)

Expand source code

class PublishedPostAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['published_post'],
        Field(
            description='Discriminator identifying this as a published-post reference asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'published_post'
    post_url: Annotated[
        AnyUrl | None,
        Field(
            description='Canonical URL for the published post. Preferred when the platform exposes a stable public or authenticated URL.'
        ),
    ] = None
    platform: Annotated[
        str | None,
        Field(
            description="Optional platform or publisher namespace for the referenced post. Informational unless the seller's product declaration or platform extension narrows the accepted values."
        ),
    ] = None
    platform_post_id: Annotated[
        str | None,
        Field(
            description='Optional platform-native post identifier when a URL alone is not stable or not available. Buyers SHOULD include `platform` when using `platform_post_id` without `post_url`, unless the product or format declaration already narrows the platform. Platform-specific identifier semantics belong in platform_extensions; this field is only an opaque reference.'
        ),
    ] = None
    identity_ref: Annotated[
        IdentityRef | None,
        Field(
            description='Optional identity hint for the authoring handle/page/channel that owns the post. Sellers MUST verify authorization from platform state; buyers MUST NOT use this object as proof of authorization.'
        ),
    ] = None
    published_at: Annotated[
        AwareDatetime | None,
        Field(description='When the referenced post was originally published, if known.'),
    ] = None
    reference_authorization: Annotated[
        ReferenceAuthorization | None,
        Field(
            description='Server-emitted, seller-observed authorization state for the referenced post or identity. Sellers MAY return this object on read surfaces. On write requests, sellers MUST ignore buyer-supplied `reference_authorization.status` and other authorization-state claims unless a platform extension explicitly defines a signed proof shape and the seller verifies that proof.'
        ),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this reference asset, overrides manifest-level provenance.'
        ),
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> PublishedPostAsset:
        # ``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 (('post_url',), ('platform_post_id',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'PublishedPostAsset requires at least one of these field groups: post_url | platform_post_id'
        )

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

Class variables

var asset_type : Literal['published_post']

var identity_ref : IdentityRef | None

var model_config

var platform : str | None

var platform_post_id : str | None

var post_url : pydantic.networks.AnyUrl | None

var provenance : Provenance | None

var published_at : pydantic.types.AwareDatetime | None

var reference_authorization : ReferenceAuthorization | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PublisherDesignatedPreviewProvider (**data: Any)

Expand source code

class PublisherDesignatedPreviewProvider(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    agent_url: Annotated[
        AnyUrl,
        Field(
            description='HTTPS URL of the delegated creative-agent endpoint. Buyers call get_adcp_capabilities and preview_creative on this endpoint. They MUST allow only public IPs, pin DNS resolution through connection, refuse redirects, cap time and response size, and attach provider credentials only after exact normalized-origin binding.'
        ),
    ]
    authority: Annotated[
        Literal['publisher_designated'],
        Field(
            description="Explicitly states that authority comes from the publisher-hosted placement declaration. The provider's rendering_origin metadata is informational and remains non-authoritative elsewhere."
        ),
    ] = 'publisher_designated'
    routes: Annotated[list[Route], Field(min_length=1)]

    @field_validator('agent_url')
    @classmethod
    def _require_https_agent_url(cls, value: AnyUrl) -> AnyUrl:
        if value.scheme != 'https':
            raise ValueError('agent_url must use https')
        return value

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

Class variables

var agent_url : pydantic.networks.AnyUrl

var authority : Literal['publisher_designated']

var model_config

var routes : list[Route]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PublisherDomain (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class PublisherDomain(ScalarStr):
    __slots__ = ()
    _constraints = {
        'pattern': '^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
    }

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class PublisherIdentifierTypes (*args, **kwds)

Expand source code

class PublisherIdentifierTypes(StrEnum):
    tag_id = 'tag_id'
    duns = 'duns'
    lei = 'lei'
    seller_id = 'seller_id'
    gln = 'gln'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var duns

var gln

var lei

var seller_id

var tag_id

class PublisherPropertiesAll (**data: Any)

Expand source code

class PublisherPropertySelector1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    publisher_domain: Annotated[
        str | None,
        Field(
            description="Domain where publisher's adagents.json is hosted (e.g., 'cnn.com'). XOR with `publisher_domains` — exactly one MUST be present on each `publisher_properties[]` entry; both-present and neither-present both fail validation.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    publisher_domains: Annotated[
        list[PublisherDomain] | None,
        Field(
            description="Compact form for fanning the same selector across many publishers (e.g., a managed network listing every publisher it represents). Each entry is the domain where that publisher's adagents.json is hosted. Each listed domain MUST be canonicalized to lowercase (the `pattern` already rejects uppercase). Mutually exclusive with `publisher_domain`. Each listed domain counts as explicitly scoped for the `managerdomain` fallback safety rule.",
            min_length=1,
        ),
    ] = None
    selection_type: Annotated[
        Literal['all'],
        Field(
            description='Discriminator indicating all properties from each addressed publisher are included'
        ),
    ] = 'all'

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

Class variables

var model_config

var publisher_domain : str | None

var publisher_domains : list[PublisherDomain] | None

var selection_type : Literal['all']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PublisherPropertiesById (**data: Any)

Expand source code

class PublisherPropertySelector2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    publisher_domain: Annotated[
        str,
        Field(
            description="Domain where publisher's adagents.json is hosted (e.g., 'cnn.com').",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    selection_type: Annotated[
        Literal['by_id'],
        Field(description='Discriminator indicating selection by specific property IDs'),
    ] = 'by_id'
    property_ids: Annotated[
        list[property_id.PropertyId],
        Field(description="Specific property IDs from the publisher's adagents.json", min_length=1),
    ]

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

Class variables

var model_config

var property_ids : list[PropertyId]

var publisher_domain : str

var selection_type : Literal['by_id']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PublisherPropertiesByTag (**data: Any)

Expand source code

class PublisherPropertySelector3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    publisher_domain: Annotated[
        str | None,
        Field(
            description="Domain where publisher's adagents.json is hosted (e.g., 'cnn.com'). XOR with `publisher_domains` — exactly one MUST be present on each `publisher_properties[]` entry; both-present and neither-present both fail validation.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    publisher_domains: Annotated[
        list[PublisherDomain] | None,
        Field(
            description="Compact form for fanning the same tag predicate across many publishers (canonical managed-network shape). Each entry is the domain where that publisher's adagents.json is hosted. Each listed domain MUST be canonicalized to lowercase (the `pattern` already rejects uppercase). Mutually exclusive with `publisher_domain`. Each listed domain counts as explicitly scoped for the `managerdomain` fallback safety rule.",
            min_length=1,
        ),
    ] = None
    selection_type: Annotated[
        Literal['by_tag'], Field(description='Discriminator indicating selection by property tags')
    ] = 'by_tag'
    property_tags: Annotated[
        list[property_tag.PropertyTag],
        Field(
            description="Property tags resolved against each addressed publisher's adagents.json, OR against the parent file's top-level `properties[]` when those properties carry a `publisher_domain` matching the selector. Selector covers all properties carrying any of these tags.",
            min_length=1,
        ),
    ]

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

Class variables

var model_config

var property_tags : list[PropertyTag]

var publisher_domain : str | None

var publisher_domains : list[PublisherDomain] | None

var selection_type : Literal['by_tag']

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.

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

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 QuartileData (**data: Any)

Expand source code

class QuartileData(AdCPBaseModel):
    q1_views: Annotated[StrictFloat | None, Field(description='25% completion views', ge=0.0)] = (
        None
    )
    q2_views: Annotated[StrictFloat | None, Field(description='50% completion views', ge=0.0)] = (
        None
    )
    q3_views: Annotated[StrictFloat | None, Field(description='75% completion views', ge=0.0)] = (
        None
    )
    q4_views: Annotated[StrictFloat | None, Field(description='100% completion views', ge=0.0)] = (
        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

Class variables

var model_config

var q1_views : float | None

var q2_views : float | None

var q3_views : float | None

var q4_views : float | None

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.

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

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 SignalCoverageRange (**data: Any)

Expand source code

class Range(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    min: Annotated[StrictFloat, Field(description='Minimum value, inclusive.')]
    max: Annotated[StrictFloat, Field(description='Maximum value, inclusive.')]

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

Class variables

var max : float

var min : float

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RateLimitedDetails (**data: Any)

Expand source code

class RateLimitedDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        StrictFloat | None, Field(description='Maximum requests allowed in the window')
    ] = None
    remaining: Annotated[
        StrictFloat | None, Field(description='Requests remaining in the current window')
    ] = None
    window_seconds: Annotated[
        StrictFloat | None, Field(description='Duration of the rate-limit window in seconds')
    ] = None
    scope: Annotated[Scope | None, Field(description='What the limit applies to')] = 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

Class variables

var limit : float | None

var model_config

var remaining : float | None

var scope : Scope | None

var window_seconds : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReachUnit (*args, **kwds)

Expand source code

class ReachUnit(StrEnum):
    individuals = 'individuals'
    households = 'households'
    devices = 'devices'
    accounts = 'accounts'
    cookies = 'cookies'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var accounts

var cookies

var custom

var devices

var households

var individuals

class ReportingIssueRecommendedAction (*args, **kwds)

Expand source code

class RecommendedAction(StrEnum):
    wait_for_retry = 'wait_for_retry'
    contact_buyer = 'contact_buyer'
    contact_seller = 'contact_seller'
    contact_provider = 'contact_provider'
    repair_access = 'repair_access'
    update_configuration = 'update_configuration'
    change_reporting_scope = 'change_reporting_scope'
    use_supported_reader = 'use_supported_reader'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var change_reporting_scope

var contact_buyer

var contact_provider

var contact_seller

var repair_access

var update_configuration

var use_supported_reader

var wait_for_retry

class Recovery (*args, **kwds)

Expand source code

class Recovery(StrEnum):
    transient = 'transient'
    correctable = 'correctable'
    terminal = 'terminal'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var correctable

var terminal

var transient

class ReferenceRenderer (**data: Any)

Expand source code

class ReferenceRenderer(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    runtime: Annotated[
        Literal['browser-esm'],
        Field(
            description='Execution contract for the referenced package. browser-esm means a browser-safe ECMAScript module that accepts canonical manifest data and returns an inert presentation without Node.js APIs, ambient credentials, delivery tracking, or undeclared network access. Non-JavaScript clients use a hosted preview_creative provider or display the manifest.'
        ),
    ] = 'browser-esm'
    package: Annotated[
        str,
        Field(
            description='npm package name, scoped or unscoped. The package is resolved from the npm registry; the AdCP registry does not proxy its executable contents.',
            pattern='^(?:@[a-z0-9][a-z0-9._~-]*/)?[a-z0-9][a-z0-9._~-]*$',
        ),
    ]
    version: Annotated[
        str,
        Field(
            description='Exact semantic version. Ranges and tags such as latest are forbidden so the registry entry is reproducible. Package semantic versioning identifies the pinned distribution artifact; it is independent of any one format revision because one package may expose renderers for multiple formats.',
            pattern='^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$',
        ),
    ]
    export: Annotated[
        str,
        Field(
            description="Named package export that implements the renderer contract for this enclosing format entry. Compatibility is bound at the export-to-entry edge, not to matching version labels: registry review and contract fixtures verify that the export implements the entry's input contract. When that input contract changes, the registry MUST rerun those fixtures and MAY retain the existing export and package pin when they still pass. One package version MAY expose different named exports for different formats or input contracts.",
            min_length=1,
        ),
    ]
    format_revision: Annotated[
        str | None,
        Field(
            deprecated=True,
            description="Deprecated compatibility annotation retained for previously published registry entries. Renderer package versions and community format revisions have independent lifecycles, so consumers MUST NOT require this value to equal the enclosing entry's format_revision or use matching values as evidence of compatibility. Registry review and contract fixtures bind the named export to the enclosing format's input contract. New entries SHOULD omit this field.",
            pattern='^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$',
        ),
    ] = None
    integrity: Annotated[
        str,
        Field(
            description='Subresource Integrity value for the exact npm package tarball. Consumers MUST compare this value before loading code, require the provenance subject digest to match the same tarball, and fail closed on mismatch.',
            pattern='^(?:sha256-[A-Za-z0-9+/]{43}=|sha384-[A-Za-z0-9+/]{64}|sha512-[A-Za-z0-9+/]{86}==)$',
        ),
    ]
    provenance: Provenance

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

Class variables

var export : str

var format_revision : str | None

var integrity : str

var model_config

var package : str

var provenance : Provenance

var runtime : Literal['browser-esm']

var version : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RefineProposalsRequest (**data: Any)

Expand source code

class RefineProposalsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    context_id: Annotated[
        str | None,
        Field(
            description='MCP compatibility field: servers ignore this value; A2A uses transport-native Message/Task contextId.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    governance_context: Annotated[str | None, Field(max_length=4096, min_length=1)] = None
    push_notification_config: push_notification_config_1.PushNotificationConfig | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated key required for retry-safe proposal refinement.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    refinements: Annotated[
        list[proposal_refinement.ProposalRefinement] | Refinements,
        Field(
            description='Proposal operations to apply, with at most 25 entries per request. revise creates a draft successor from a draft, committed, or accepted source. finalize MUST target a draft, reserves inventory, and creates a committed successor whose expires_at is the hold deadline. A batch containing finalize MUST contain only finalize entries and is atomic. proposal_id values MUST be unique; results preserve request order.',
            max_length=25,
            min_length=1,
        ),
    ]

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 context_id : str | None

var governance_context : str | None

var idempotency_key : str

var model_config

var push_notification_config : PushNotificationConfig | None

var refinements : list[ProposalRefinement2 | ProposalRefinement3 | ProposalRefinement4 | ProposalRefinement5 | ProposalRefinement6 | ProposalRefinement7 | ProposalRefinement8 | ProposalRefinement9] | Refinements

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 RefinementApplied1 (**data: Any)

Expand source code

class RefinementApplied1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['request'],
        Field(description="Echoes scope 'request' from the corresponding refine entry."),
    ] = 'request'
    status: Annotated[
        Status,
        Field(
            description="'applied': the ask was fulfilled. 'partial': the ask was partially fulfilled — see notes for details. 'unable': the seller could not fulfill the ask — see notes for why."
        ),
    ]
    notes: Annotated[
        str | None,
        Field(
            description="Seller explanation of what was done, what couldn't be done, or why. Recommended when status is 'partial' or 'unable'."
        ),
    ] = 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

Class variables

var model_config

var notes : str | None

var scope : Literal['request']

var status : Status

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RefinementApplied2 (**data: Any)

Expand source code

class RefinementApplied2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['product'],
        Field(description="Echoes scope 'product' from the corresponding refine entry."),
    ] = 'product'
    product_id: Annotated[
        str, Field(description='Echoes product_id from the corresponding refine entry.')
    ]
    status: Annotated[
        Status,
        Field(
            description="'applied': the ask was fulfilled. 'partial': the ask was partially fulfilled — see notes for details. 'unable': the seller could not fulfill the ask — see notes for why."
        ),
    ]
    notes: Annotated[
        str | None,
        Field(
            description="Seller explanation of what was done, what couldn't be done, or why. Recommended when status is 'partial' or 'unable'."
        ),
    ] = 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

Class variables

var model_config

var notes : str | None

var product_id : str

var scope : Literal['product']

var status : Status

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RefinementApplied3 (**data: Any)

Expand source code

class RefinementApplied3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['proposal'],
        Field(description="Echoes scope 'proposal' from the corresponding refine entry."),
    ] = 'proposal'
    proposal_id: Annotated[
        str, Field(description='Echoes proposal_id from the corresponding refine entry.')
    ]
    status: Annotated[
        Status,
        Field(
            description="'applied': the ask was fulfilled. 'partial': the ask was partially fulfilled — see notes for details. 'unable': the seller could not fulfill the ask — see notes for why."
        ),
    ]
    notes: Annotated[
        str | None,
        Field(
            description="Seller explanation of what was done, what couldn't be done, or why. Recommended when status is 'partial' or 'unable'."
        ),
    ] = 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

Class variables

var model_config

var notes : str | None

var proposal_id : str

var scope : Literal['proposal']

var status : Status

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RegistryAcceptancePolicyProfileReference (**data: Any)

Expand source code

class RegistryAcceptancePolicyProfileReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    policy_id: Annotated[str, Field(min_length=1)]
    policy_version: Annotated[str, Field(min_length=1)]
    policy_digest: Annotated[str, Field(pattern='^sha256:[a-f0-9]{64}$')]
    profile_id: Annotated[str, Field(pattern='^[A-Za-z0-9_.:-]+$')]
    profile_version: Annotated[str, Field(min_length=1)]
    profile_digest: Annotated[str, Field(pattern='^sha256:[a-f0-9]{64}$')]

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

Class variables

var model_config

var policy_digest : str

var policy_id : str

var policy_version : str

var profile_digest : str

var profile_id : str

var profile_version : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PreviewRenderingOrigin (*args, **kwds)

Expand source code

class RenderingOrigin(StrEnum):
    platform_native = 'platform_native'
    agent_approximation = 'agent_approximation'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var agent_approximation

var platform_native

class CapabilitiesPreviewRenderingOrigin (*args, **kwds)

Expand source code

class RenderingOrigin(StrEnum):
    platform_native = 'platform_native'
    agent_approximation = 'agent_approximation'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var agent_approximation

var platform_native

class Renders (**data: Any)

Expand source code

class Renders(AdCPBaseModel):
    role: Annotated[
        str,
        Field(
            description="Semantic role of this rendered piece (e.g., 'primary', 'companion', 'mobile_variant')"
        ),
    ]
    parameters_from_format_id: Annotated[
        StrictBool | None,
        Field(
            description='When true, parameters for this render (dimensions and/or duration) are specified in the format_id. Used for template formats that accept parameters. Mutually exclusive with specifying dimensions object explicitly.'
        ),
    ] = None
    dimensions: Annotated[
        Dimensions,
        Field(
            description='Dimensions for this rendered piece. Defaults to pixels when unit is absent.'
        ),
    ]

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

Class variables

var dimensions : Dimensions

var model_config

var parameters_from_format_id : bool | None

var role : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportPlanAdjustmentRequest (**data: Any)

Expand source code

class ReportPlanAdjustmentRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    action: Annotated[
        Action,
        Field(
            description='report is seller-authenticated and creates a non-authoritative record; review is plan-owner-authenticated and accepts or disputes it.'
        ),
    ]
    plan_id: Annotated[str, Field(description='Plan containing the source outcome.', min_length=1)]
    outcome_id: Annotated[
        str | None,
        Field(
            description='Completed outcome whose authoritative commitment is being adjusted.',
            min_length=1,
        ),
    ] = None
    adjustment_id: Annotated[
        str | None, Field(description='Adjustment to accept or dispute. Required for review.')
    ] = None
    decision: Annotated[
        Decision | None,
        Field(
            description='Buyer review decision. Acceptance is blocked while delivery evidence for the governed action is disputed in an open governance period; a historical closed_unresolved period is audit evidence, not a billing determination.'
        ),
    ] = None
    seller_reference: Annotated[
        str | None,
        Field(
            description='Seller resource identifier. Must exactly match the reference retained on the source outcome.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    seller_adjustment_id: Annotated[
        str | None,
        Field(
            description="Stable identifier of the adjustment in the authenticated seller's system.",
            max_length=255,
            min_length=1,
        ),
    ] = None
    adjustment_type: Annotated[
        AdjustmentType | None,
        Field(
            description='Commercial meaning. Verified decommitments restore headroom in every mode; verified refunds and credits restore it only in verified_net_cost mode; makegoods never restore cash headroom.'
        ),
    ] = None
    amount: Annotated[
        Amount | None, Field(description='Positive adjustment amount in the plan currency.')
    ] = None
    reason: Annotated[
        str | None,
        Field(
            description='Human-readable reason retained in the audit trail.',
            max_length=1000,
            min_length=1,
        ),
    ] = None
    effective_at: Annotated[
        AwareDatetime | None, Field(description="When the seller's adjustment became effective.")
    ] = None
    evidence: Annotated[
        Evidence | None,
        Field(
            description='Integrity-bound commercial source record supplied by the seller. Its evidence_type must correspond to adjustment_type.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Caller-generated retry key. Exact replays return the original report or review; reuse with another payload is rejected.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 action : Action

var adjustment_id : str | None

var adjustment_type : AdjustmentType | None

var amount : Amount | None

var context : ContextObject | None

var decision : Decision | None

var effective_at : pydantic.types.AwareDatetime | None

var evidence : Evidence | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var outcome_id : str | None

var plan_id : str

var reason : str | None

var seller_adjustment_id : str | None

var seller_reference : str | 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 ReportPlanAdjustmentResponse (**data: Any)

Expand source code

class ReportPlanAdjustmentResponse(AdcpResponse, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    adjustment_id: Annotated[
        str, Field(description='Governance-agent identifier for the adjustment record.')
    ]
    adjustment_state: Annotated[
        AdjustmentState,
        Field(
            description='reported has seller evidence but no buyer decision; verified was accepted by the plan owner; disputed was rejected by the plan owner. Only verified records can affect net cost or headroom.'
        ),
    ]
    adjustment_type: AdjustmentType
    amount: Amount
    headroom_restored: Annotated[
        StrictFloat,
        Field(
            description='Amount by which current ledger commitment was reduced under the plan accounting mode.',
            ge=0.0,
        ),
    ]
    plan_summary: PlanSummary
    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
    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.

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
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var adjustment_id : str

var adjustment_state : AdjustmentState

var adjustment_type : AdjustmentType

var amount : Amount

var context : ContextObject | None

var ext : ExtensionObject | None

var headroom_restored : float

var model_config

var plan_summary : PlanSummary

var replayed : bool | 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 ReportPlanOutcomeRequest (**data: Any)

Expand source code

class ReportPlanOutcomeRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    plan_id: Annotated[
        str,
        Field(
            description='The plan this outcome is for. The plan is owned by the authenticated buyer that synchronized it; plan_id is an identifier, not an account credential. Completed and failed settlements inherit their commercial binding from the exact approved check tuple.'
        ),
    ]
    check_id: Annotated[
        str | None,
        Field(
            description='The check_id from check_governance. Required for completed and failed outcomes and for buyer delivery observations. A delivery observation names the exact seller delivery check whose canonical statement is being compared.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Buyer-generated unique key for this outcome report. An identical retry returns the cached response without another settlement; reuse with a different canonical payload returns IDEMPOTENCY_CONFLICT. Use a fresh UUID v4 for each distinct report.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    purchase_type: Annotated[
        purchase_type_1.PurchaseType | None,
        Field(
            description="The type of financial commitment this outcome is for. Must equal the original approved intent's purchase_type. Determines which budget allocation (if any) to charge against. Defaults to 'media_buy' when omitted."
        ),
    ] = purchase_type_1.PurchaseType.media_buy
    outcome: Annotated[outcome_type.OutcomeType, Field(description='Outcome type.')]
    seller_response: Annotated[
        SellerResponse | None,
        Field(description="The seller's full response. Required when outcome is 'completed'."),
    ] = None
    delivery: Annotated[
        Delivery | None,
        Field(
            description='Buyer-attributed observation compared with the canonical seller delivery statement identified by check_id. This evidence never overwrites seller evidence or creates a second commitment. A conflict produces an explicit disputed reconciliation state while the operational period is open; the plan owner may close it without asserting final billing truth.'
        ),
    ] = None
    error: Annotated[
        reported_outcome_error.ReportedOutcomeError | None,
        Field(
            description='Buyer-attributed error associated with a failed seller interaction. Required when outcome is failed; classification_source=seller_response_copy preserves what the buyer received without claiming seller-attested provenance.'
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque governance context from the check_governance response. Required with check_id for completed and failed outcomes and buyer delivery observations.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = 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 check_id : str | None

var context : ContextObject | None

var delivery : Delivery | None

var error : ReportedOutcomeError | None

var ext : ExtensionObject | None

var governance_context : str | None

var idempotency_key : str

var model_config

var outcome : OutcomeType

var plan_id : str

var purchase_type : PurchaseType | None

var seller_response : SellerResponse | 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 ReportPlanOutcomeResponse (**data: Any)

Expand source code

class ReportPlanOutcomeResponse(AdcpResponse, AdcpVersionEnvelope):
    @model_validator(mode='before')
    @classmethod
    def _status_to_outcome_state(cls, data: Any) -> Any:
        if isinstance(data, dict) and 'outcome_state' not in data and 'status' in data:
            data = dict(data)
            data['outcome_state'] = data['status']
        return data

    model_config = ConfigDict(
        extra='allow',
    )
    outcome_id: Annotated[str, Field(description='Unique identifier for this outcome record.')]
    outcome_state: Annotated[
        OutcomeState,
        Field(
            description="Outcome state. 'accepted' means state updated with no issues. 'findings' means issues were detected. Renamed from `status` in 3.1 to free the top-level `status` key for the envelope task-status (TaskStatus) under MCP flat-on-the-wire serialization."
        ),
    ]
    committed_budget: Annotated[
        StrictFloat | None,
        Field(
            description="Budget committed from this outcome. Present for 'completed' and 'failed' outcomes."
        ),
    ] = None
    delivery_reconciliation_status: Annotated[
        DeliveryReconciliationStatus | None,
        Field(
            description='Comparison state between the buyer-attributed observation and canonical seller statement. Present for delivery outcomes. A disputed state blocks adjustment verification while the period is open. measurement_variance records a buyer-measured cumulative_spend that differs from the seller statement; it never blocks verification — the higher amount bounds conservative exposure and decommitments instead. closed_unresolved preserves the discrepancy after operational closure without claiming a final billing result.'
        ),
    ] = None
    delivery_period_state: Annotated[
        DeliveryPeriodState | None,
        Field(
            description='Operational state of the governance reporting period. Closure freezes governance evidence for that period but is not billing settlement.'
        ),
    ] = None
    findings: Annotated[
        list[Finding] | None,
        Field(description="Issues detected. Present only when outcome_state is 'findings'."),
    ] = None
    plan_summary: Annotated[
        PlanSummary | None,
        Field(
            description="Updated plan budget state. Present for 'completed' and 'failed' outcomes."
        ),
    ] = 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
    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.

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
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var committed_budget : float | None

var context : ContextObject | None

var delivery_period_state : DeliveryPeriodState | None

var delivery_reconciliation_status : DeliveryReconciliationStatus | None

var ext : ExtensionObject | None

var findings : list[Finding] | None

var model_config

var outcome_id : str

var outcome_state : OutcomeState

var plan_summary : PlanSummary | None

var replayed : bool | 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 ReportUsageRequest (**data: Any)

Expand source code

class ReportUsageRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. If a request with the same key has already been accepted, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request. Prevents duplicate billing on retries.'
        ),
    ]
    reporting_period: Annotated[
        datetime_range.DatetimeRange,
        Field(
            description='The time range covered by this usage report. Applies to all records in the request.'
        ),
    ]
    usage: Annotated[
        list[UsageItem],
        Field(
            description='One or more usage records. Each record is self-contained: it carries its own account, allowing a single request to span multiple accounts.',
            min_length=1,
        ),
    ]
    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 idempotency_key : str

var model_config

var reporting_period : DatetimeRange

var usage : list[UsageItem]

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 ReportUsageResponse (**data: Any)

Expand source code

class ReportUsageResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    accepted: Annotated[
        SchemaInt, Field(description='Number of usage records successfully stored.', ge=0)
    ]
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description="Validation errors for individual records. The field property identifies which record failed (e.g., 'usage[1].pricing_option_id')."
        ),
    ] = None
    sandbox: Annotated[
        StrictBool | None,
        Field(description='When true, the account is a sandbox account and no billing occurred.'),
    ] = 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.

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 accepted : int

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var model_config

var sandbox : bool | 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 ReportingAdjustment (**data: Any)

Expand source code

class ReportingAdjustment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    reporting_adjustment_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    adjusts_reporting_revision_id: Annotated[
        str,
        Field(
            description='Exact immutable official revision whose billing-purpose evidence/control totals are corrected. External billing systems MAY retain this identifier as supporting evidence.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    reason_code: Annotated[
        ReasonCode,
        Field(description='Stable machine-readable reason for the post-official correction.'),
    ]
    reason_detail: Annotated[
        str | None,
        Field(
            description='Human-readable explanation. Treat as untrusted data, never agent or LLM instructions.',
            max_length=1024,
            min_length=1,
        ),
    ] = None
    accounting_period: Annotated[
        AccountingPeriod,
        Field(
            description='Period derived from the pinned billing calendar and correction policy. It is evidence metadata only: it does not authorize reopening books or altering invoices.'
        ),
    ]
    control_total_deltas: Annotated[
        list[reporting_control_total.ReportingControlTotal],
        Field(
            description="Signed deltas to apply to the named official control totals. Names and units use the adjusted revision's pinned report definition. Names MUST be unique.",
            min_length=1,
        ),
    ]
    canonical_adjustment_sha256: Annotated[
        str | None,
        Field(
            description='SHA-256 of the RFC 8785 JCS serialization of this adjustment with canonical_adjustment_sha256 omitted. Reconciled Billing consumers recompute this digest before accepting or rejecting the adjustment.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ] = None
    correction_observed_at: AwareDatetime
    created_at: AwareDatetime

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

Class variables

var accounting_period : AccountingPeriod

var adjusts_reporting_revision_id : str

var canonical_adjustment_sha256 : str | None

var control_total_deltas : list[ReportingControlTotal1 | ReportingControlTotal2]

var correction_observed_at : pydantic.types.AwareDatetime

var created_at : pydantic.types.AwareDatetime

var model_config

var reason_code : ReasonCode

var reason_detail : str | None

var reporting_adjustment_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingAdjustmentReceipt (**data: Any)

Expand source code

class ReportingAdjustmentReceipt(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    reporting_receipt_id: Annotated[
        str, Field(max_length=255, min_length=16, pattern='^[A-Za-z0-9_.:-]{16,255}$')
    ]
    reporting_adjustment_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    adjusts_reporting_revision_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    supersedes_reporting_receipt_id: Annotated[
        str | None,
        Field(
            description='Optional immutable rejected receipt replaced by this new receipt for the same adjustment. Accepted current receipts are terminal.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    status: Status
    observed_adjustment_sha256: Annotated[
        str,
        Field(
            description='Digest recomputed from the adjustment using its canonical evidence rule.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ]
    rejection_codes: Annotated[
        list[ReportingAdjustmentRejectionCode] | None, Field(min_length=1)
    ] = None
    observed_at: AwareDatetime
    received_at: AwareDatetime | None = 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

Class variables

var adjusts_reporting_revision_id : str

var model_config

var observed_adjustment_sha256 : str

var observed_at : pydantic.types.AwareDatetime

var received_at : pydantic.types.AwareDatetime | None

var rejection_codes : list[ReportingAdjustmentRejectionCode] | None

var reporting_adjustment_id : str

var reporting_receipt_id : str

var status : Status

var supersedes_reporting_receipt_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingBucket (**data: Any)

Expand source code

class ReportingBucket(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    protocol: Annotated[
        cloud_storage_protocol.CloudStorageProtocol, Field(description='Cloud storage protocol')
    ]
    bucket: Annotated[
        str,
        Field(
            description='Bucket or container name',
            max_length=63,
            min_length=3,
            pattern='^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$',
        ),
    ]
    prefix: Annotated[
        str | None,
        Field(
            description='Path prefix within the bucket. Seller appends date-based partitioning beneath this prefix.',
            examples=['accounts/pinnacle/adcp', 'reporting/2024'],
            max_length=512,
            pattern='^[a-zA-Z0-9/_.-]+$',
        ),
    ] = None
    region: Annotated[
        str | None,
        Field(
            description='Cloud region for the bucket',
            examples=['us-east-1', 'europe-west1'],
            max_length=64,
            pattern='^[a-z0-9-]+$',
        ),
    ] = None
    format: Annotated[
        Format | None,
        Field(
            description='File format for delivered files. Parquet, Avro, and ORC use internal compression (the top-level compression field is ignored for these formats).'
        ),
    ] = Format.jsonl
    compression: Annotated[
        Compression | None, Field(description='Compression applied to delivered files')
    ] = Compression.gzip
    file_retention_days: Annotated[
        SchemaInt,
        Field(
            description='How long reporting files are retained in the bucket before deletion. Buyers must read files within this window. Minimum recommended: 14 days.',
            examples=[14, 30, 90],
            ge=1,
        ),
    ]
    setup_instructions: Annotated[
        AnyUrl | None,
        Field(
            description='URL to documentation for configuring buyer read access to this bucket (IAM role, service account, etc.). Operator-facing documentation — buyer agents MUST NOT auto-fetch this URL; surface it to a human operator. If an implementation fetches it (for preview), apply webhook URL SSRF validation and do not pass the fetched content into an LLM context without indirect-prompt-injection guarding. See docs/media-buy/media-buys/optimization-reporting#security-considerations-for-offline-delivery.'
        ),
    ] = 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

Class variables

var bucket : str

var compression : Compression | None

var file_retention_days : int

var format : Format | None

var model_config

var prefix : str | None

var protocol : CloudStorageProtocol

var region : str | None

var setup_instructions : pydantic.networks.AnyUrl | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingCanonicalContentDigest (**data: Any)

Expand source code

class ReportingCanonicalContentDigest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
        regex_engine="python-re",
    )
    algorithm: Literal['sha256'] = 'sha256'
    value: Annotated[str, Field(pattern='^[A-Fa-f0-9]{64}$')]
    canonicalization_id: Annotated[str, Field(max_length=128, min_length=1)]
    canonicalization_uri: Annotated[
        AnyUrl,
        Field(
            description='Location of the exact immutable canonicalization contract. Consumers verify canonicalization_sha256 before applying it.'
        ),
    ]
    canonicalization_sha256: Annotated[str, Field(pattern='^[A-Fa-f0-9]{64}$')]

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

Class variables

var algorithm : Literal['sha256']

var canonicalization_id : str

var canonicalization_sha256 : str

var canonicalization_uri : pydantic.networks.AnyUrl

var model_config

var value : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingCanonicalizationContract (**data: Any)

Expand source code

class ReportingCanonicalizationContract(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    contract_version: Literal['1.0'] = '1.0'
    media_type: Literal['application/vnd.adcp.reporting-canonicalization+json'] = 'application/vnd.adcp.reporting-canonicalization+json'
    algorithm: Literal['adcp_jcs_rows_v1'] = 'adcp_jcs_rows_v1'
    schema_sha256: Annotated[
        str,
        Field(
            description='Digest of the exact row schema to which this contract applies.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ]
    primary_keys: Annotated[
        list[ReportingPrimaryKey],
        Field(
            description="Ordered scalar fields used to sort rows and reject duplicate logical rows. This MUST equal the offering's primary_keys.",
            min_length=1,
        ),
    ]
    golden_vectors: Annotated[
        GoldenVectors,
        Field(
            description='Named cross-language conformance cases: exactly one empty_report vector, exactly one ordering_encoding vector, and an optional list of additional vectors.'
        ),
    ]

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

Class variables

var algorithm : Literal['adcp_jcs_rows_v1']

var contract_version : Literal['1.0']

var golden_vectors : GoldenVectors

var media_type : Literal['application/vnd.adcp.reporting-canonicalization+json']

var model_config

var primary_keys : list[ReportingPrimaryKey]

var schema_sha256 : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingCapabilities (**data: Any)

Expand source code

class ReportingCapabilities(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    available_reporting_frequencies: Annotated[
        list[reporting_frequency.ReportingFrequency],
        Field(description='Supported reporting frequency options', min_length=1),
    ]
    expected_delay_minutes: Annotated[
        SchemaInt,
        Field(
            description='Expected delay in minutes before reporting data becomes available (e.g., 240 for 4-hour delay)',
            examples=[240, 300, 1440],
            ge=0,
        ),
    ]
    timezone: Annotated[
        str,
        Field(
            description="Timezone for this product's reporting periods. Use 'UTC' or an IANA timezone (e.g., 'America/New_York'). This explicit reporting clock may equal Account.timezone or differ when the upstream platform reports on a separate boundary, so buyers MUST NOT infer it from Account.timezone. It is the reporting timezone for this product's delivery reporting: get_media_buy_delivery start_date, end_date, and daily_breakdown dates are calendar dates in it, and reporting_period boundaries and daily, weekly, or monthly windows fall on its calendar boundaries. Buyers MUST use this value for daily/monthly report alignment.",
            examples=['UTC', 'America/New_York', 'Europe/London', 'America/Los_Angeles'],
        ),
    ]
    supports_webhooks: Annotated[
        StrictBool,
        Field(description='Whether this product supports webhook-based reporting notifications'),
    ]
    reporting_delivery_offering_ids: Annotated[
        list[reporting_delivery_offering_id.ReportingDeliveryOfferingId] | None,
        Field(
            description='Product-scoped subset of get_adcp_capabilities.media_buy.reporting_delivery.offerings[].offering_id that packages using this product can satisfy. This binds seller-wide managed-delivery offerings to product/package eligibility. An empty array explicitly declares no managed offering; absence means product-level applicability is unknown and MUST NOT be inferred from the seller-wide list. Account, seat, credential, or provider constraints may narrow support further during sync_accounts validation.'
        ),
    ] = None
    available_metrics: Annotated[
        list[available_metric.AvailableMetric],
        Field(
            description="Metrics available in reporting. Impressions and spend are always implicitly included. When a creative format declares reported_metrics, buyers receive the intersection of these product-level metrics and the format's reported_metrics.",
            examples=[
                ['impressions', 'spend', 'clicks', 'completed_views'],
                ['impressions', 'spend', 'conversions'],
            ],
        ),
    ]
    vendor_metrics: Annotated[
        list[VendorMetric] | None,
        Field(
            description="Vendor-defined metrics this product can report, beyond the closed `available_metrics` enum. Each entry is a pointer (`{ vendor, metric_id }`) into the vendor's metric catalog — the canonical definition (standard alignment, accreditations, methodology, unit, human-readable description) lives at the vendor's `get_adcp_capabilities.measurement.metrics[]`, queried once per vendor when needed. Use this for proprietary metrics like attention scores, emissions, panel-based demographics, or platform-native social metrics not yet in the standard enum. Sellers populate values in delivery via `delivery-metrics.json#/properties/vendor_metric_values`. The metric is identified by the tuple `(vendor, metric_id)`; identifiers are namespaced by the vendor, so the same `metric_id` may mean different things in different vendors' vocabularies. Semantic uniqueness key is `(vendor.domain, vendor.brand_id, metric_id)`; sellers MUST de-duplicate before emission and MUST NOT declare the same vendor metric twice. Buyers MAY treat duplicate `(vendor, metric_id)` rows as a seller-side conformance bug. (JSON Schema `uniqueItems` is not used here because BrandRef carries optional fields whose absence/presence would defeat deep-equal — uniqueness is on the semantic key, enforced at build/validation time on the seller side.) Promotion path: when the industry converges on a metric via a published standard, the spec adds it to the closed `available_metrics` enum and the vendor extensions become historical aliases. The `vendor` MAY resolve to the selling party's own `brand.json` — a seller MAY be its own measurement vendor (DOOH sensor networks, retail-media closed loops, walled gardens) provided it publishes the metric in an `agents[type='measurement']` catalog like any other vendor and declares the relationship via `vendor_relationship`; the catalog contract is not relaxed for first-party measurement."
        ),
    ] = None
    supports_creative_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports creative-level metric breakdowns in delivery reporting (by_creative within by_package)'
        ),
    ] = None
    supports_format_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports canonical creative-format breakdowns in GET delivery reporting (by_format within by_package, keyed by format_kind). This is independent from supports_creative_breakdown because a seller may expose aggregate format-grain reporting without exposing individual creative performance.'
        ),
    ] = None
    supports_keyword_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports keyword-level metric breakdowns in delivery reporting (by_keyword within by_package)'
        ),
    ] = None
    supports_geo_breakdown: Annotated[
        geo_breakdown_support.GeographicBreakdownSupport | None,
        Field(
            description='Geographic breakdown support for this product. Declares which geo levels and systems are available for by_geo reporting within by_package.'
        ),
    ] = None
    supports_device_type_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports device type breakdowns in delivery reporting (by_device_type within by_package)'
        ),
    ] = None
    supports_device_platform_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports device platform breakdowns in delivery reporting (by_device_platform within by_package)'
        ),
    ] = None
    supports_audience_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports audience segment breakdowns in delivery reporting (by_audience within by_package)'
        ),
    ] = None
    supports_demographic_breakdown: Annotated[
        demographic_reporting_capability.DemographicReportingCapability | None,
        Field(
            description='Product-scoped demographic breakdown support for by_demographic reporting. Declares reportable age ranges and measurement systems independently from demographic targeting execution.'
        ),
    ] = None
    supports_placement_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports placement breakdowns in delivery reporting (by_placement within by_package)'
        ),
    ] = None
    supports_property_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports property breakdowns in delivery reporting (by_property within by_package).'
        ),
    ] = None
    supports_collection_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports collection breakdowns in delivery reporting (by_collection within by_package).'
        ),
    ] = None
    supports_installment_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports installment breakdowns in delivery reporting (by_installment within by_package).'
        ),
    ] = None
    supports_collection_property_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports collection × property intersection reporting (by_collection_property within by_package).'
        ),
    ] = None
    supports_installment_property_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports installment × property intersection reporting (by_installment_property within by_package).'
        ),
    ] = None
    supports_placement_property_breakdown: Annotated[
        StrictBool | None,
        Field(
            description='Whether this product supports placement × property intersection reporting (by_placement_property within by_package).'
        ),
    ] = None
    supports_spot_breakdown: Annotated[
        spot_reporting_capability.SpotReportingCapability | None,
        Field(
            description='Spot-level as-run airing-log support and metrics available at spot grain for broadcast TV, radio, and other scheduled inventory.'
        ),
    ] = None
    date_range_support: Annotated[
        DateRangeSupport,
        Field(
            description="Whether delivery data can be filtered to arbitrary date ranges. 'date_range' means the platform supports start_date/end_date parameters. 'lifetime_only' means the platform returns campaign lifetime totals and date range parameters are not accepted."
        ),
    ]
    windowed_pull_granularities: Annotated[
        list[reporting_frequency.ReportingFrequency] | None,
        Field(
            description='Granularities at which this product honors per-window pulls on get_media_buy_delivery (via request `time_granularity` + `include_window_breakdown: true`). Closes the GET-side half of the snapshot/log two-paths-parity contract for data-bearing events: a buyer who missed a webhook fire at any granularity listed here can reconstruct an identical payload by polling. Capability-scoped MUST — sellers MUST honor pulls at any granularity declared here, and MUST return UNSUPPORTED_GRANULARITY for pulls outside the set. Sellers MAY emit higher-frequency webhooks than they expose for pull (common where the webhook is a Kafka tap and historical reads go through a warehouse with coarser granularity); buyers see the gap up front via this capability and treat the webhook as primary for those frequencies. Absent or empty means the product only supports cumulative date-range pulls and full per-window recovery via GET is unavailable — see snapshot-and-log Rule 4.',
            examples=[['daily'], ['hourly', 'daily'], ['hourly', 'daily', 'monthly']],
        ),
    ] = None
    measurement_windows: Annotated[
        list[measurement_window.MeasurementWindow] | None,
        Field(
            description='Measurement maturation stages available for this product. Used by any channel where billing-grade data is produced in phases rather than arriving final on day one. Examples: broadcast/linear TV (Live → C3 → C7 DVR accumulation), DOOH (tentative plays → post-IVT/fraud-check final), digital with IVT filtering (raw → GIVT filtered → SIVT filtered), podcast (7-day downloads → 30-day downloads). Each window defines an accumulation period and expected data availability. When present, delivery reports reference a specific window_id. Sellers whose data is final on first delivery typically omit this.',
            min_length=1,
        ),
    ] = 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

Class variables

var available_metrics : list[AvailableMetric]

var available_reporting_frequencies : list[ReportingFrequency]

var date_range_support : DateRangeSupport

var expected_delay_minutes : int

var measurement_windows : list[MeasurementWindow] | None

var model_config

var reporting_delivery_offering_ids : list[ReportingDeliveryOfferingId] | None

var supports_audience_breakdown : bool | None

var supports_collection_breakdown : bool | None

var supports_collection_property_breakdown : bool | None

var supports_creative_breakdown : bool | None

var supports_demographic_breakdown : DemographicReportingCapability | None

var supports_device_platform_breakdown : bool | None

var supports_device_type_breakdown : bool | None

var supports_format_breakdown : bool | None

var supports_geo_breakdown : GeographicBreakdownSupport | None

var supports_installment_breakdown : bool | None

var supports_installment_property_breakdown : bool | None

var supports_keyword_breakdown : bool | None

var supports_placement_breakdown : bool | None

var supports_placement_property_breakdown : bool | None

var supports_property_breakdown : bool | None

var supports_spot_breakdown : SpotReportingCapability | None

var supports_webhooks : bool

var timezone : str

var vendor_metrics : list[VendorMetric] | None

var windowed_pull_granularities : list[ReportingFrequency] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingConsumerStatus (**data: Any)

Expand source code

class ReportingConsumerStatus(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    reporting_status_id: Annotated[
        str,
        Field(
            description='Consumer-issued immutable identity for this status statement. Exact retries reuse the ID and content; changed status uses a new ID and supersedes_reporting_status_id.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    supersedes_reporting_status_id: Annotated[
        str | None,
        Field(
            description="The authenticated consumer's current status leaf replaced by this statement. It must identify the same account, configuration generation, report definition, and period.",
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    delivery_config_id: Annotated[
        str, Field(max_length=64, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,64}$')
    ]
    delivery_config_version: Annotated[SchemaInt, Field(ge=1)]
    report_definition_id: Annotated[
        str,
        Field(
            description='Exact immutable report definition accepted with the configuration generation, preventing unlike reporting promises from sharing a status chain.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    period: Annotated[
        Period,
        Field(
            description='Expected half-open reporting period derived from the accepted configuration generation. This identity works even when the seller omitted the corresponding obligation.'
        ),
    ]
    reporting_obligation_id: Annotated[
        str | None,
        Field(
            description='Seller-issued obligation identity when one was visible. Omitted when the consumer is reporting a missing obligation.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    reporting_revision_id: Annotated[
        str | None,
        Field(
            description='Exact revision successfully consumed or found unreadable. Omitted when no required revision was available.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    observed_revision_content_sha256: Annotated[
        str | None,
        Field(
            description='revision_content_sha256 independently recomputed from the exact consumed Core revision binding. Required for received and content_mismatch, where it proves which exact revision content the consumer read; unlike a Reconciled Billing receipt it carries no materialization evidence, row totals, canonical digest, or billing acceptance.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ] = None
    consumer_status: Annotated[
        ConsumerStatus,
        Field(
            description='received means the exact revision content was successfully consumed; obligation_missing means the independently expected period was absent from the seller ledger; revision_missing means the obligation existed but no required revision was available after expected_at; unreadable means a named revision was advertised but its exact content could not be consumed; content_mismatch means the exact revision content was read but contradicts a fact the accepted configuration generation already fixed, named by the closed mismatch_code. None of these values reconciles billing evidence, and content_mismatch in particular is not a measurement dispute.'
        ),
    ]
    status_as_of: Annotated[
        AwareDatetime,
        Field(
            description='When the consumer established this status. For received, this is when the named revision first became consumable to this consumer; sellers use it as buyer-attributed arrival evidence rather than silently substituting publication time.'
        ),
    ]
    mismatch_code: Annotated[
        MismatchCode | None,
        Field(
            description="Closed reason the consumed revision contradicts the accepted configuration generation. Each value is decidable from the obligation, the pinned report definition, and the revision itself, with no reference to either party's own measurement. scope_media_buy_missing: a media buy frozen in the obligation's media_buy_ids denominator is absent from the revision and is not represented by an explicit zero row, so the revision cannot distinguish zero delivery from an omitted buy. coverage_short: the revision covers fewer packages than the obligation's frozen coverage.covered_package_ids claims. metric_missing: a metric named in the pinned report definition's metrics[].name is absent from the revision. schema_nonconformant: rows do not validate against the reporting profile's pinned schema_uri and schema_sha256. currency_mismatch: a value's unit disagrees with the unit the pinned report definition fixed for that metric, or a control total's unit disagrees with the profile-defined unit for that name. period_mismatch: the revision carries a time dimension declared by the pinned grain whose values fall outside the obligation's half-open period. Precedence when more than one applies: schema_nonconformant is used only when the failure is structural validation against the pinned schema; a metric that is simply absent uses metric_missing even when the pinned schema declares it required. Each names a contract fact already fixed by the accepted generation, never a difference of opinion about counts. Agents dispatch on this value, not on prose."
        ),
    ] = None
    failure_code: Annotated[
        FailureCode | None,
        Field(
            description='Typed reason a named revision was unreadable. Agents dispatch on this value, not prose or provider response bodies.'
        ),
    ] = None
    consumer_commit_ref: Annotated[
        str | None,
        Field(
            description='Optional opaque, non-secret consumer checkpoint, transaction, or load reference. It is operational evidence, not authorization, a credential, a URL, or instructions; receivers compare or display it as inert text and never dereference or execute it.',
            max_length=512,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,512}$',
        ),
    ] = None
    seller_ledger_snapshot_id: Annotated[
        str | None,
        Field(
            description='Optional seller-issued get_reporting_status snapshot on which this statement was based. It is evidence context, not consumer authority over that snapshot.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    seller_ledger_as_of: Annotated[
        AwareDatetime | None,
        Field(
            description='ledger_as_of echoed from seller_ledger_snapshot_id. Present if and only if seller_ledger_snapshot_id is present.'
        ),
    ] = None
    recorded_at: Annotated[
        AwareDatetime | None,
        Field(description='When the seller durably recorded this immutable statement.'),
    ] = 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

Class variables

var consumer_commit_ref : str | None

var consumer_status : ConsumerStatus

var delivery_config_id : str

var delivery_config_version : int

var failure_code : FailureCode | None

var mismatch_code : MismatchCode | None

var model_config

var observed_revision_content_sha256 : str | None

var period : Period

var recorded_at : pydantic.types.AwareDatetime | None

var report_definition_id : str

var reporting_obligation_id : str | None

var reporting_revision_id : str | None

var reporting_status_id : str

var seller_ledger_as_of : pydantic.types.AwareDatetime | None

var seller_ledger_snapshot_id : str | None

var status_as_of : pydantic.types.AwareDatetime

var supersedes_reporting_status_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingDeliveryCapabilities (**data: Any)

Expand source code

class ReportingDeliveryCapabilities(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    supported: Literal[True]
    reliable_reporting_version: Annotated[
        Literal['1.0'] | None,
        Field(
            description='Explicit adoption declaration for the proper-name AdCP 3.2 Reliable Reporting contract. Presence, together with supported: true and the media_buy.reporting_delivery experimental feature gate, is the affirmative machine-readable answer. Absence denotes the earlier experimental managed-reporting shape.'
        ),
    ] = None
    managed_delivery: Annotated[
        StrictBool | None,
        Field(
            description='Tier flag: this seller supports managed file, dataset-share, or warehouse delivery. Offerings whose method names a delivery pattern require this tier. When false or absent, every offering is API-delivered and Core-only.'
        ),
    ] = None
    reconciled_billing: Annotated[
        StrictBool | None,
        Field(
            description='Tier flag: this seller supports canonical-digest verification and authenticated consumer receipts for both report materializations and post-official adjustments through receipt_task. Offerings with reconciliation_mode consumer_receipt and billing-grade canonicalization require this tier.'
        ),
    ] = None
    configuration_task: Literal['sync_accounts'] | None = None
    status_task: Literal['get_reporting_status'] | None = None
    consumer_status_task: Annotated[
        Literal['sync_reporting_status'] | None,
        Field(
            description='Opt-in consumer-status loop during the published migration window, becoming required Core in the next eligible minor after that window. Buyers call this seller-hosted task to record whether each expected reporting period was received, missing, or unreadable. Buyers expose no reverse endpoint, and the status is not a billing receipt.'
        ),
    ] = None
    revision_content_task: Annotated[
        Literal['get_media_buy_delivery'] | None,
        Field(
            description='Reliable Reporting exact-content read: callers select reporting_revision_id and receive immutable revision metadata plus authoritative canonical reporting_rows.'
        ),
    ] = None
    receipt_task: Annotated[
        Literal['sync_reporting_receipts'] | None,
        Field(
            description='Required when reconciled_billing is true: the task consumers call to submit and read back authenticated revision and adjustment receipts.'
        ),
    ] = None
    readiness_notification: Annotated[
        Literal['reporting.delivery_ready'] | None,
        Field(
            description='Optional managed-delivery-only positive-readiness doorbell. It names a materialization at a destination, so Core sellers MUST omit it.'
        ),
    ] = None
    status_notification: Annotated[
        Literal['reporting.status_changed'] | None,
        Field(
            description='Optional tier-independent invalidation doorbell for health transitions in either direction, including clock-driven waiting-to-delayed and delayed-to-action_required. Valid for Core: it names no destination. Polling status_task remains the authoritative recovery path whether or not this is offered.'
        ),
    ] = None
    ledger_notification: Annotated[
        Literal['reporting.ledger_changed'] | None,
        Field(
            description='Optional tier-independent invalidation for every newly committed revision or post-official adjustment, even when health does not change. Receivers repair through get_reporting_status changes_after; polling remains authoritative.'
        ),
    ] = None
    offerings: Annotated[
        list[reporting_delivery_offering.ReportingDeliveryOffering],
        Field(
            description='Atomic supported feed/profile/schedule/finality/method combinations. offering_id values MUST be unique.',
            min_length=1,
        ),
    ]
    automated_recovery_window_seconds: Annotated[
        SchemaInt,
        Field(
            description='Maximum late interval during which a due obligation may remain delayed while automated recovery continues before action_required.',
            ge=0,
        ),
    ]
    status_retention_days: Annotated[
        SchemaInt,
        Field(
            description='Minimum period for which obligation, revision, and materialization metadata remain queryable.',
            ge=1,
        ),
    ]
    consumer_mismatch_escalation_seconds: Annotated[
        SchemaInt | None,
        Field(
            description="Maximum interval after a CONSUMER_STATUS_MISMATCH issue's opened_at during which the seller may keep that issue at a non-escalated recommended_action. After it, the issue MUST be action_required with a contact_ recommended_action naming the diagnosed responsible_party. Declaring it requires operations_contact so the escalation has a destination. Absence means the seller publishes no escalation commitment; it never means an unbounded one.",
            ge=0,
        ),
    ] = None
    operations_contact: Annotated[
        OperationsContact | None,
        Field(
            description='Optional non-secret human escalation path for reporting issues the protocol cannot resolve. It is display metadata for an operator, not an AdCP endpoint: agents MUST NOT dereference, probe, or send protocol traffic to these values, and they carry no authorization. Required when consumer_mismatch_escalation_seconds is advertised.'
        ),
    ] = None
    reliability_statistics: Annotated[
        list[reporting_reliability_statistics.ReportingReliabilityStatistics] | None,
        Field(
            description='Optional evidence-scoped observed performance for advertised offerings. offering_id values MUST be unique and name offerings in this capability block.'
        ),
    ] = None
    resource_retention_days: Annotated[
        SchemaInt | None,
        Field(
            description='Minimum period after publication for which at least one verified exact materialization remains readable to every still-authorized intended consumer.',
            ge=1,
        ),
    ] = None
    supports_webhook_activity: StrictBool | None = None
    authorization_revocation_seconds: Annotated[
        SchemaInt | None,
        Field(
            description="Maximum delay after caller/account authorization ends before seller-controlled transport access, provider grants, and write credentials are revoked. It cannot revoke a buyer's access to data already written into a buyer-owned destination.",
            ge=0,
        ),
    ] = None

    @model_validator(mode='after')
    def _validate_reporting_tiers(self) -> ReportingDeliveryCapabilities:
        if self.reconciled_billing is True and self.managed_delivery is not True:
            raise ValueError('reconciled_billing requires managed_delivery')
        if self.readiness_notification is not None and self.managed_delivery is not True:
            raise ValueError('readiness_notification requires managed_delivery')
        if self.receipt_task is not None and self.reconciled_billing is not True:
            raise ValueError('receipt_task requires reconciled_billing')
        return self

    @model_serializer(mode='wrap')
    def _omit_absent_reporting_promises(
        self, handler: SerializerFunctionWrapHandler
    ) -> dict[str, Any]:
        return {key: value for key, value in handler(self).items() if value is not 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

Class variables

var authorization_revocation_seconds : int | None

var automated_recovery_window_seconds : int

var configuration_task : Literal['sync_accounts'] | None

var consumer_mismatch_escalation_seconds : int | None

var consumer_status_task : Literal['sync_reporting_status'] | None

var ledger_notification : Literal['reporting.ledger_changed'] | None

var managed_delivery : bool | None

var model_config

var offerings : list[ReportingDeliveryOffering]

var operations_contact : OperationsContact | None

var readiness_notification : Literal['reporting.delivery_ready'] | None

var receipt_task : Literal['sync_reporting_receipts'] | None

var reconciled_billing : bool | None

var reliability_statistics : list[ReportingReliabilityStatistics] | None

var reliable_reporting_version : Literal['1.0'] | None

var resource_retention_days : int | None

var revision_content_task : Literal['get_media_buy_delivery'] | None

var status_notification : Literal['reporting.status_changed'] | None

var status_retention_days : int

var status_task : Literal['get_reporting_status'] | None

var supported : Literal[True]

var supports_webhook_activity : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingDeliveryConfiguration (**data: Any)

Expand source code

class ReportingDeliveryConfiguration(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    delivery_config_id: Annotated[
        str,
        Field(
            description='Caller-selected stable identifier, unique within the authenticated caller and account.',
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    delivery_config_version: Annotated[
        SchemaInt,
        Field(
            description='Caller-selected immutable semantic generation. Increment when feed/profile/scope/finality/schedule/method/destination changes; lifecycle fields may change in place.',
            ge=1,
        ),
    ]
    offering_id: Annotated[
        str,
        Field(
            description='Atomic reporting offering advertised by the seller that binds feed, profile, schedule, finality, and delivery support.',
            max_length=128,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,128}$',
        ),
    ]
    active: Annotated[
        StrictBool,
        Field(
            description='Whether new reporting obligations should use this configuration. Inactive configurations remain visible for historical resolution.'
        ),
    ]
    feed_purpose: reporting_delivery_offering.ReportingFeedPurpose
    report_definition_id: Annotated[
        str,
        Field(
            description='Exact immutable semantic definition selected from the offering. This makes the expected obligation identity independently derivable and prevents attribution, timezone, source-mapping, or restatement-policy drift behind a profile label.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    reporting_profile: Annotated[
        str,
        Field(
            description='Versioned semantic profile for the aggregate report, such as media_buy_delivery_v1. It MUST match the selected offering.',
            max_length=128,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,128}$',
        ),
    ]
    scope: Annotated[Scope, Field(description='Media buys covered by this configuration.')]
    coverage_requirement: Annotated[
        CoverageRequirement,
        Field(
            description='Whether every package in the resolved media-buy scope must support the exact selected offering. full fails closed when any package is unsupported or unknown. allow_partial permits publication only for the explicitly covered package denominator; every revision and status response still exposes partial coverage and MUST NOT present covered-subset totals as whole-buy totals.'
        ),
    ]
    required_finality: Annotated[
        reporting_finality.ReportingFinality,
        Field(
            description='Finality the durable path must ultimately provide. Snapshot delivery may still precede an official requirement.'
        ),
    ]
    reconciliation_mode: Annotated[
        reporting_reconciliation_mode.ReportingReconciliationMode,
        Field(
            description='Whether producer-side delivery evidence is sufficient or the selected consumer must submit an authenticated matching receipt. A seller-authoritative billing feed MUST use consumer_receipt.'
        ),
    ]
    authoritative_party: Annotated[
        AuthoritativeParty | None,
        Field(
            description="Reserved: which party's count of this feed is authoritative. seller (the default, and the only value any 3.2 seller accepts) means the seller produces every revision and the consumer may only attest to what it consumed. consumer is reserved for the buyer-deposited billing revision task scoped to a later minor; until that task exists sellers MUST reject it with UNSUPPORTED_FEATURE. Reserving the field now keeps a future buyer-basis billing feed additive instead of breaking the billing-feed constraints. See https://github.com/adcontextprotocol/adcp/issues/7440."
        ),
    ] = AuthoritativeParty.seller
    schedule: reporting_schedule.ReportingSchedule
    method: reporting_delivery_method.ReportingDeliveryMethod | None = None
    revocation_effective_at: Annotated[
        AwareDatetime | None,
        Field(
            description='Optional requested cutoff for deactivation. No new publication may begin after the applied cutoff; historical access is limited to the contracted recovery window.'
        ),
    ] = 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

Class variables

var active : bool

var authoritative_party : AuthoritativeParty | None

var coverage_requirement : CoverageRequirement

var delivery_config_id : str

var delivery_config_version : int

var feed_purpose : ReportingFeedPurpose

var method : ReportingDeliveryMethod1 | ReportingDeliveryMethod2 | ReportingDeliveryMethod3 | None

var model_config

var offering_id : str

var reconciliation_mode : ReportingReconciliationMode

var report_definition_id : str

var reporting_profile : str

var required_finality : ReportingFinality

var revocation_effective_at : pydantic.types.AwareDatetime | None

var schedule : ReportingSchedule

var scope : Scope

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingDeliveryConfigurationState (**data: Any)

Expand source code

class ReportingDeliveryConfigurationState(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    configuration: reporting_delivery_config.ReportingDeliveryConfiguration
    state: ReportingDeliveryConfigLifecycleState
    destination_ref: Annotated[
        str | None,
        Field(
            description='Seller-issued immutable destination-generation reference. It is caller-scoped and reusable across separately authorized account configurations; it is not itself account authority or a bearer grant. Present when and only when the configuration selects a managed-delivery offering; a Core (API-delivered) configuration becomes ready with no destination at all.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    validated_at: AwareDatetime | None = None
    activated_at: AwareDatetime | None = None
    deactivated_at: AwareDatetime | None = None
    publication_stopped_at: Annotated[
        AwareDatetime | None,
        Field(
            description='Applied schedule boundary at or after deactivation. No obligation whose period starts at or after this cutoff is created; earlier obligations remain owed through their SLA and recovery lifecycle.'
        ),
    ] = None
    seller_managed_access_ends_at: Annotated[
        AwareDatetime | None,
        Field(
            description='End of historical access to a producer-hosted share/resource for a still-authorized principal after voluntary deactivation. Inapplicable to data already written into a buyer-owned destination.'
        ),
    ] = None
    current_coverage: Annotated[
        reporting_coverage.ReportingCoverage | None,
        Field(
            description='Current effective product/package coverage for the selected offering and resolved account. This setup-time view may change as media buys or provider capabilities change; each period obligation later freezes its own authoritative coverage.'
        ),
    ] = None
    setup: Annotated[
        Setup | None,
        Field(
            description='Secret-free next step when provider-side authorization or recipient activation cannot be completed automatically.'
        ),
    ] = None
    issues: Annotated[
        list[reporting_status_issue.ReportingStatusIssue] | None, Field(min_length=1)
    ] = 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

Class variables

var activated_at : pydantic.types.AwareDatetime | None

var configuration : ReportingDeliveryConfiguration

var current_coverage : ReportingCoverage | None

var deactivated_at : pydantic.types.AwareDatetime | None

var destination_ref : str | None

var issues : list[ReportingStatusIssue] | None

var model_config

var publication_stopped_at : pydantic.types.AwareDatetime | None

var seller_managed_access_ends_at : pydantic.types.AwareDatetime | None

var setup : Setup | None

var state : ReportingDeliveryConfigLifecycleState

var validated_at : pydantic.types.AwareDatetime | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingDeliveryOffering (**data: Any)

Expand source code

class ReportingDeliveryOffering(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
        regex_engine="python-re",
    )
    offering_id: Annotated[
        str, Field(max_length=128, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,128}$')
    ]
    feed_purpose: ReportingFeedPurpose
    report_definition_id: Annotated[
        str,
        Field(
            description='Immutable semantic definition for metric, grain, attribution, action-report-time, timezone/calendar, source/API mapping, and restatement/finality policy. Configurations and revisions MUST echo this exact value.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    report_definition_uri: Annotated[
        AnyUrl,
        Field(
            description='Retrievable immutable reporting-report-definition.json document on the authenticated seller/provider or AdCP-registry origin.'
        ),
    ]
    report_definition_sha256: Annotated[
        str,
        Field(
            description='Digest of the exact report-definition bytes. SDKs verify this before parsing and cache by digest.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ]
    reporting_profile: Annotated[
        ReportingProfile,
        Field(
            description='Machine-readable semantic and validation contract for delivered rows. The canonicalization_* fields describe the external-materialization canonical-digest contract and are required only for offerings under the reconciled_billing tier; Core and managed-delivery offerings omit those fields but every Core revision still carries the fixed RFC 8785/JCS revision-binding digest.'
        ),
    ]
    schedule: Annotated[
        reporting_schedule_offering.ReportingScheduleOffering,
        Field(
            description='Period and availability SLA this offering can honor. For example, PT1H with snapshot finality explicitly advertises hourly provisional snapshots; a separate P1D official offering advertises daily finalized reporting.'
        ),
    ]
    supported_finality: Annotated[
        list[reporting_finality.ReportingFinality],
        Field(
            description='Finality classes available under this exact report definition, schedule, and delivery method. snapshot is an explicit provisional capability, not inferred from poll frequency. Use separate atomic offerings when snapshot and official schedules or methods differ.',
            min_length=1,
        ),
    ]
    reconciliation_mode: Annotated[
        reporting_reconciliation_mode.ReportingReconciliationMode,
        Field(
            description='Receipt contract included in this atomic offering. Billing offerings MUST require consumer_receipt.'
        ),
    ]
    method: Annotated[
        Method | None,
        Field(
            description='Managed delivery method for this offering. Omit for a Core (API-delivered) offering: rows flow through existing get_media_buy_delivery and reporting_webhook transports and no destination is involved. Present only when the seller advertises managed_delivery.'
        ),
    ] = 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

Class variables

var feed_purpose : ReportingFeedPurpose

var method : Method | None

var model_config

var offering_id : str

var reconciliation_mode : ReportingReconciliationMode

var report_definition_id : str

var report_definition_sha256 : str

var report_definition_uri : pydantic.networks.AnyUrl

var reporting_profile : ReportingProfile

var schedule : ReportingScheduleOffering

var supported_finality : list[ReportingFinality]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingDeliveryReadyWebhook (**data: Any)

Expand source code

class ReportingDeliveryReadyWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Stable across transport retries of this fire; new for a later re-emission.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    notification_id: Annotated[
        str,
        Field(
            description='Stable for this logical materialization-ready event across re-emissions.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    notification_type: Literal['reporting.delivery_ready'] = 'reporting.delivery_ready'
    fired_at: AwareDatetime
    subscriber_id: Annotated[
        str, Field(max_length=64, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,64}$')
    ]
    account_id: Annotated[str, Field(min_length=1)]
    delivery_config_id: Annotated[
        str, Field(max_length=64, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,64}$')
    ]
    delivery_config_version: Annotated[SchemaInt, Field(ge=1)]
    reporting_revision_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_materialization_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    readiness: Readiness
    finality: reporting_finality.ReportingFinality
    data_through: AwareDatetime | None
    feed_purpose: reporting_delivery_offering.ReportingFeedPurpose

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

Class variables

var account_id : str

var data_through : pydantic.types.AwareDatetime | None

var delivery_config_id : str

var delivery_config_version : int

var feed_purpose : ReportingFeedPurpose

var finality : ReportingFinality

var fired_at : pydantic.types.AwareDatetime

var idempotency_key : str

var model_config

var notification_id : str

var notification_type : Literal['reporting.delivery_ready']

var readiness : Readiness

var reporting_materialization_id : str

var reporting_revision_id : str

var subscriber_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingFileCompression (*args, **kwds)

Expand source code

class ReportingFileCompression(StrEnum):
    none = 'none'
    gzip = 'gzip'
    zstd = 'zstd'
    snappy = 'snappy'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var gzip

var none

var snappy

var zstd

class ReportingFileEntry (**data: Any)

Expand source code

class ReportingFileEntry(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    object_ref: reporting_file_object_ref.ReportingFileObjectReference
    native_version_ref: reporting_native_version_ref.ReportingNativeVersionReference | None = None
    size_bytes: Annotated[SchemaInt, Field(ge=0)]
    sha256: Annotated[str, Field(pattern='^[A-Fa-f0-9]{64}$')]
    row_count: Annotated[SchemaInt, Field(ge=0)]
    partition: Annotated[dict[str, str] | None, Field(max_length=32)] = 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

Class variables

var model_config

var native_version_ref : ReportingNativeVersionReference | None

var object_ref : ReportingFileObjectReference

var partition : dict[str, str] | None

var row_count : int

var sha256 : str

var size_bytes : int

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingFileManifest (**data: Any)

Expand source code

class ReportingFileManifest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    manifest_version: Literal['1.0'] = '1.0'
    complete: Literal[True]
    reporting_revision_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_obligation_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_materialization_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    period: Period
    format: Format
    compression: reporting_file_compression.ReportingFileCompression
    files: Annotated[list[reporting_file_entry.ReportingFileEntry], Field(min_length=1)]
    total_size_bytes: Annotated[SchemaInt, Field(ge=0)]
    row_count: Annotated[SchemaInt, Field(ge=0)]
    control_totals: list[reporting_control_total.ReportingControlTotal]
    created_at: AwareDatetime

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

Class variables

var complete : Literal[True]

var compression : ReportingFileCompression

var control_totals : list[ReportingControlTotal1 | ReportingControlTotal2]

var created_at : pydantic.types.AwareDatetime

var files : list[ReportingFileEntry]

var format : Format

var manifest_version : Literal['1.0']

var model_config

var period : Period

var reporting_materialization_id : str

var reporting_obligation_id : str

var reporting_revision_id : str

var row_count : int

var total_size_bytes : int

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingFrequency (*args, **kwds)

Expand source code

class ReportingFrequency(StrEnum):
    hourly = 'hourly'
    daily = 'daily'
    weekly = 'weekly'
    monthly = 'monthly'
    quarterly = 'quarterly'
    post_campaign = 'post_campaign'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var daily

var hourly

var monthly

var post_campaign

var quarterly

var weekly

class AvailableReportingFrequency (*args, **kwds)

Expand source code

class ReportingFrequency(StrEnum):
    hourly = 'hourly'
    daily = 'daily'
    weekly = 'weekly'
    monthly = 'monthly'
    quarterly = 'quarterly'
    post_campaign = 'post_campaign'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var daily

var hourly

var monthly

var post_campaign

var quarterly

var weekly

class ReportingMaterialization (**data: Any)

Expand source code

class ReportingMaterialization(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    reporting_materialization_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_revision_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_obligation_id: Annotated[
        str,
        Field(
            description='Destination-specific obligation this materialization attempts to satisfy.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    delivery_config_id: Annotated[
        str,
        Field(
            description='Durable configuration that requested this materialization.',
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    delivery_config_version: Annotated[SchemaInt, Field(ge=1)]
    destination_ref: Annotated[
        str,
        Field(
            description='Immutable caller-owned destination generation selected by the account-authorized obligation. It may be reused by the same caller across other independently authorized accounts.',
            max_length=255,
            min_length=1,
        ),
    ]
    feed_purpose: reporting_delivery_offering.ReportingFeedPurpose
    method: Method
    transport: Annotated[
        str | None, Field(max_length=64, min_length=1, pattern='^[a-z][a-z0-9_.-]*$')
    ] = None
    attempt: Annotated[SchemaInt, Field(ge=1)]
    status: Annotated[
        Status,
        Field(
            description='Lifecycle of this attempt. pending may transition once to available, delivered, or failed; terminal evidence is immutable. Staleness is evaluated in get_reporting_status health, not stored as a materialization state.'
        ),
    ]
    ready_at: Annotated[
        AwareDatetime | None,
        Field(description='When consumer-path or destination verification completed.'),
    ] = None
    failed_at: AwareDatetime | None = None
    failure_code: Annotated[
        str | None,
        Field(
            description='Stable safe failure classification. MUST NOT include credentials or provider response bodies.',
            max_length=128,
            min_length=1,
            pattern='^[A-Z][A-Z0-9_]*$',
        ),
    ] = None
    resource: reporting_resource.ReportingResource | None = None
    verification: reporting_verification.ReportingVerification | None = None
    created_at: AwareDatetime

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

Class variables

var attempt : int

var created_at : pydantic.types.AwareDatetime

var delivery_config_id : str

var delivery_config_version : int

var destination_ref : str

var failed_at : pydantic.types.AwareDatetime | None

var failure_code : str | None

var feed_purpose : ReportingFeedPurpose

var method : Method

var model_config

var ready_at : pydantic.types.AwareDatetime | None

var reporting_materialization_id : str

var reporting_obligation_id : str

var reporting_revision_id : str

var resource : ReportingResource | None

var status : Status

var transport : str | None

var verification : ReportingVerification | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingObligation (**data: Any)

Expand source code

class ReportingObligation(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    reporting_obligation_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    delivery_config_id: Annotated[
        str, Field(max_length=64, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,64}$')
    ]
    delivery_config_version: Annotated[SchemaInt, Field(ge=1)]
    report_definition_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    feed_purpose: reporting_delivery_offering.ReportingFeedPurpose
    reporting_profile: Annotated[str, Field(max_length=128, min_length=1)]
    account_id: Annotated[str, Field(min_length=1)]
    media_buy_ids: Annotated[
        list[reporting_coverage.ReportingMediaBuyId],
        Field(
            description='Exact frozen media-buy denominator resolved for this period, including buys with zero rows. An empty array is the definitive zero-buy set; omission is never used to mean all, empty, or unknown.'
        ),
    ]
    scope_resolved_at: Annotated[
        AwareDatetime,
        Field(
            description='Instant at which the configured scope was resolved and frozen for this obligation. For all_media_buys, include every caller-authorized account media buy whose effective flight overlaps the half-open period and was known by this cutoff. Later-created or backdated buys do not rewrite this obligation.'
        ),
    ]
    coverage: Annotated[
        reporting_coverage.ReportingCoverage,
        Field(
            description='Immutable effective coverage of the exact selected offering at this period boundary. Delivery health is evaluated separately over the covered denominator.'
        ),
    ]
    period: Period
    expected_at: AwareDatetime
    schedule: Annotated[
        reporting_schedule.ReportingSchedule,
        Field(description='Resolved immutable schedule generation that created this obligation.'),
    ]
    destination_ref: Annotated[
        str | None,
        Field(
            description='Immutable caller-owned destination generation selected by this account-authorized obligation. The account/configuration join—not possession of this reusable reference—authorizes disclosure. Present when and only when the obligation’s configuration selects a managed-delivery offering; Core (API-delivered) obligations omit every destination and materialization field.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    required_finality: reporting_finality.ReportingFinality
    reconciliation_mode: reporting_reconciliation_mode.ReportingReconciliationMode
    reconciliation_status: Annotated[
        ReconciliationStatus,
        Field(
            description='Consumer agreement state for the current required revision. A later superseding revision returns a receipt-required obligation to pending until that revision is accepted.'
        ),
    ]
    health: reporting_health.ReportingHealth
    production_status: Annotated[
        ProductionStatus,
        Field(
            description='Whether any revision has been produced for this obligation. published includes zero-row revisions.'
        ),
    ]
    revision_count: Annotated[
        SchemaInt,
        Field(
            description='Number of revision records for this obligation in the consistent ledger snapshot.',
            ge=0,
        ),
    ]
    consumer_status_count: Annotated[
        SchemaInt | None,
        Field(
            description='Complete number of immutable authenticated consumer status statements associated with this obligation in the ledger snapshot, whether originally joined by reporting_obligation_id or by the exact configuration-generation, report-definition, and period key before the obligation existed. Core status-sync history is counted independently from Reconciled Billing receipts.',
            ge=0,
        ),
    ] = None
    current_consumer_status_id: Annotated[
        str | None,
        Field(
            description='Current unsuperseded consumer status statement associated with this obligation by seller ID or its exact logical period key. Omitted when consumer_status_count is zero.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    adjustment_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of immutable post-official reporting adjustment records for this obligation in the consistent ledger snapshot.',
            ge=0,
        ),
    ] = None
    materialization_count: Annotated[
        SchemaInt | None,
        Field(
            description="Number of materialization records for this obligation's revisions in the consistent ledger snapshot. Present iff the obligation is managed-delivery (destination_ref present).",
            ge=0,
        ),
    ] = None
    successful_materialization_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of available/delivered verified materializations in the consistent ledger snapshot. Present iff the obligation is managed-delivery (destination_ref present).',
            ge=0,
        ),
    ] = None
    receipt_count: Annotated[
        SchemaInt | None,
        Field(
            description='Complete number of authenticated receipts associated with this obligation in the ledger snapshot. Present iff reconciliation_mode is consumer_receipt.',
            ge=0,
        ),
    ] = None
    accepted_receipt_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of accepted receipts. At most one current accepted receipt per consumer and revision contributes to reconciliation_status. Present iff reconciliation_mode is consumer_receipt.',
            ge=0,
        ),
    ] = None
    adjustment_receipt_count: Annotated[
        SchemaInt | None,
        Field(
            description="Number of authenticated receipts for adjustments targeting this obligation's official revision. Reconciled Billing only.",
            ge=0,
        ),
    ] = None
    accepted_adjustment_receipt_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of accepted adjustment receipts. Reconciled Billing buyers do not post an adjustment until their exact digest is accepted.',
            ge=0,
        ),
    ] = None
    pending_adjustment_count: Annotated[
        SchemaInt | None,
        Field(
            description='Number of applicable adjustments without an accepted receipt. Reconciled Billing complete/healthy requires zero.',
            ge=0,
        ),
    ] = None
    issues: list[reporting_status_issue.ReportingStatusIssue]
    resource_retained_until: Annotated[
        AwareDatetime | None,
        Field(
            description='Minimum time through which at least one verified materialization for a completed obligation remains readable. Managed-delivery only; Core revisions are retained per status_retention_days and readable through the existing API transports.'
        ),
    ] = 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

Class variables

var accepted_adjustment_receipt_count : int | None

var accepted_receipt_count : int | None

var account_id : str

var adjustment_count : int | None

var adjustment_receipt_count : int | None

var consumer_status_count : int | None

var coverage : ReportingCoverage

var current_consumer_status_id : str | None

var delivery_config_id : str

var delivery_config_version : int

var destination_ref : str | None

var expected_at : pydantic.types.AwareDatetime

var feed_purpose : ReportingFeedPurpose

var health : ReportingHealth

var issues : list[ReportingStatusIssue]

var materialization_count : int | None

var media_buy_ids : list[ReportingMediaBuyId]

var model_config

var pending_adjustment_count : int | None

var period : Period

var production_status : ProductionStatus

var receipt_count : int | None

var reconciliation_mode : ReportingReconciliationMode

var reconciliation_status : ReconciliationStatus

var report_definition_id : str

var reporting_obligation_id : str

var reporting_profile : str

var required_finality : ReportingFinality

var resource_retained_until : pydantic.types.AwareDatetime | None

var revision_count : int

var schedule : ReportingSchedule

var scope_resolved_at : pydantic.types.AwareDatetime

var successful_materialization_count : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingPeriod (**data: Any)

Expand source code

class ReportingPeriod(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    start: Annotated[AwareDatetime, Field(description='ISO 8601 start timestamp')]
    end: Annotated[AwareDatetime, Field(description='ISO 8601 end timestamp')]
    timezone: Annotated[
        str | None,
        Field(
            description="IANA timezone identifier for the reporting period (e.g., 'America/New_York', 'UTC'). Platforms report in their native timezone."
        ),
    ] = 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

Class variables

var end : pydantic.types.AwareDatetime

var model_config

var start : pydantic.types.AwareDatetime

var timezone : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingReceipt (**data: Any)

Expand source code

class ReportingReceipt(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    reporting_receipt_id: Annotated[
        str, Field(max_length=255, min_length=16, pattern='^[A-Za-z0-9_.:-]{16,255}$')
    ]
    reporting_obligation_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_revision_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_materialization_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    supersedes_reporting_receipt_id: Annotated[
        str | None,
        Field(
            description="Optional immutable rejected receipt replaced by this new receipt. It MUST name the caller's current rejected receipt for this obligation and revision; accepted current receipts are terminal.",
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    status: Status
    verification_profile: reporting_verification_profile.ReportingVerificationProfile
    observed_row_count: Annotated[SchemaInt, Field(ge=0)]
    observed_control_totals: list[reporting_control_total.ReportingControlTotal]
    observed_canonical_content_digest: (
        reporting_canonical_content_digest.ReportingCanonicalContentDigest | None
    ) = None
    observed_manifest_sha256: Annotated[str | None, Field(pattern='^[A-Fa-f0-9]{64}$')] = None
    observed_native_version_ref: (
        reporting_native_version_ref.ReportingNativeVersionReference | None
    ) = None
    consumer_commit_ref: Annotated[
        str | None,
        Field(
            description='Optional non-secret consumer checkpoint, transaction, or load identifier. It is evidence for operations, not authorization or a credential.',
            max_length=512,
            min_length=1,
        ),
    ] = None
    rejection_codes: Annotated[list[RejectionCode] | None, Field(min_length=1)] = None
    observed_at: AwareDatetime
    received_at: AwareDatetime | None = 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

Class variables

var consumer_commit_ref : str | None

var model_config

var observed_at : pydantic.types.AwareDatetime

var observed_canonical_content_digest : ReportingCanonicalContentDigest | None

var observed_control_totals : list[ReportingControlTotal1 | ReportingControlTotal2]

var observed_manifest_sha256 : str | None

var observed_native_version_ref : ReportingNativeVersionReference | None

var observed_row_count : int

var received_at : pydantic.types.AwareDatetime | None

var rejection_codes : list[RejectionCode] | None

var reporting_materialization_id : str

var reporting_obligation_id : str

var reporting_receipt_id : str

var reporting_revision_id : str

var status : Status

var supersedes_reporting_receipt_id : str | None

var verification_profile : ReportingVerificationProfile

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingReconciliationMode (*args, **kwds)

Expand source code

class ReportingReconciliationMode(StrEnum):
    delivery_only = 'delivery_only'
    consumer_receipt = 'consumer_receipt'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var consumer_receipt

var delivery_only

class ReportingReportDefinition (**data: Any)

Expand source code

class ReportingReportDefinition(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    contract_version: Annotated[
        ContractVersion,
        Field(
            description='1.1 adds immutable official closes with adjustments_only correction semantics for Reliable Reporting 1.0. Version 1.0 remains accepted for compatibility with the preceding experimental managed-reporting contract.'
        ),
    ]
    media_type: Literal['application/vnd.adcp.reporting-definition+json'] = 'application/vnd.adcp.reporting-definition+json'
    report_definition_id: Annotated[
        str, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ]
    reporting_profile: Annotated[str, Field(max_length=128, min_length=1)]
    grain: Annotated[str, Field(max_length=128, min_length=1)]
    source: Source
    calendar: Calendar
    metrics: Annotated[list[Metric], Field(min_length=1)]
    dimensions: list[Dimension]
    restatement_policy: RestatementPolicy
    finality_policies: Annotated[
        list[FinalityPolicies | FinalityPolicies1 | FinalityPolicies2], Field(min_length=1)
    ]

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

Class variables

var calendar : Calendar

var contract_version : ContractVersion

var dimensions : list[Dimension]

var finality_policies : list[FinalityPolicies | FinalityPolicies1 | FinalityPolicies2]

var grain : str

var media_type : Literal['application/vnd.adcp.reporting-definition+json']

var metrics : list[Metric]

var model_config

var report_definition_id : str

var reporting_profile : str

var restatement_policy : RestatementPolicy

var source : Source

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingResource (**data: Any)

Expand source code

class ReportingResource(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    resource_ref: Annotated[
        str,
        Field(
            description='Seller-issued opaque reference to this exact authenticated resource descriptor.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    kind: Annotated[
        Kind, Field(description='Shape through which the durable revision is consumed.')
    ]
    location: Annotated[
        str,
        Field(
            description='Non-secret provider-native object, relation, or share identifier. MUST NOT contain an activation URL, signed URL, bearer token, password, private key, or embedded credential.',
            max_length=2048,
            min_length=1,
        ),
    ]
    native_version_ref: reporting_native_version_ref.ReportingNativeVersionReference | None = None
    manifest_version: Annotated[
        Literal['1.0'],
        Field(description='Version of reporting-file-manifest.json used by a manifest resource.'),
    ] = '1.0'
    manifest_sha256: Annotated[
        str | None,
        Field(
            description='SHA-256 over the exact manifest bytes. Consumers verify this before parsing the manifest.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ] = None
    immutability: Annotated[
        Immutability,
        Field(description='How this descriptor selects the exact immutable materialization.'),
    ]
    expires_at: Annotated[
        AwareDatetime,
        Field(
            description='Mandatory finite lower-bound endpoint through which this exact resource remains resolvable; it cannot be earlier than the advertised retention contract.'
        ),
    ]
    reader_compatibility: Annotated[
        list[ReportingReaderCompatibilityItem] | None,
        Field(
            description='Reader features or format constraints required to consume this resource. Readiness verification MUST use a representative supported reader.'
        ),
    ] = 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

Class variables

var expires_at : pydantic.types.AwareDatetime

var immutability : Immutability

var kind : Kind

var location : str

var manifest_sha256 : str | None

var manifest_version : Literal['1.0']

var model_config

var native_version_ref : ReportingNativeVersionReference | None

var reader_compatibility : list[ReportingReaderCompatibilityItem] | None

var resource_ref : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingRevision (**data: Any)

Expand source code

class ReportingRevision(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
        regex_engine="python-re",
    )
    reporting_revision_id: Annotated[
        str,
        Field(
            description='Portable AdCP identity for this immutable report publication. Distinct from package delivery_revision_id and provider-native versions.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    revision_content_sha256: Annotated[
        str,
        Field(
            description='SHA-256 of the immutable RFC 8785 JCS binding object containing reporting_revision_id, row_count, control_totals, and reporting_rows. Reliable Reporting 1.0 Core revisions include it and exact reads return the identical value.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ]
    report_definition_id: Annotated[
        str,
        Field(
            description='Identity or canonical fingerprint of immutable metric, grain, attribution, breakdown, action-definition, profile, and calendar/timezone semantics.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    report_definition_uri: AnyUrl
    report_definition_sha256: Annotated[str, Field(pattern='^[A-Fa-f0-9]{64}$')]
    reporting_profile: Annotated[str, Field(max_length=128, min_length=1)]
    schema_version: Annotated[str, Field(max_length=64, min_length=1)]
    schema_uri: Annotated[
        AnyUrl,
        Field(
            description='Machine-readable schema on the authenticated seller/provider or AdCP-registry origin.'
        ),
    ]
    schema_sha256: Annotated[
        str,
        Field(
            description='Digest of the exact schema bytes used to validate this immutable revision.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ]
    schema_dialect: Annotated[
        Literal['https://json-schema.org/draft/2020-12/schema'],
        Field(description='Closed SDK-bundled dialect; the metaschema is never network-fetched.'),
    ] = 'https://json-schema.org/draft/2020-12/schema'
    schema_ref_policy: Annotated[
        Literal['local_fragment_only'],
        Field(
            description='The fetched schema is self-contained and every $ref is a local # fragment.'
        ),
    ] = 'local_fragment_only'
    account_id: Annotated[str, Field(min_length=1)]
    media_buy_ids: Annotated[
        list[reporting_coverage.ReportingMediaBuyId],
        Field(
            description='Exact frozen media-buy denominator inherited from the obligation, including buys with zero rows. An empty array proves a zero-buy period rather than an unknown denominator.'
        ),
    ]
    coverage: Annotated[
        reporting_coverage.ReportingCoverage,
        Field(
            description='Frozen product/package denominator represented by this logical content. The same coverage follows the revision to every destination.'
        ),
    ]
    period: Annotated[
        Period, Field(description='Half-open reporting interval with its source calendar boundary.')
    ]
    finality: reporting_finality.ReportingFinality
    finality_basis: Annotated[
        FinalityBasis | None,
        Field(
            description='Why an official revision is considered final: an authoritative source signal, a versioned contractual cutoff, or a versioned stabilization rule.'
        ),
    ] = None
    finality_policy_id: Annotated[
        str | None,
        Field(
            description='Immutable policy/version reference that defines the selected finality basis. It MUST be bound by report_definition_id.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    finalized_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When the producer applied the declared finality basis to this official revision.'
        ),
    ] = None
    observed_at: Annotated[
        AwareDatetime,
        Field(description='When the seller obtained or committed this source observation.'),
    ]
    data_through: Annotated[
        AwareDatetime | None,
        Field(
            description='Latest event time conservatively included, or null when precision is unknown.'
        ),
    ]
    data_through_precision: DataThroughPrecision
    supersedes_reporting_revision_id: Annotated[
        str | None,
        Field(
            description='Immediately superseded snapshot revision of the same logical slice. An official revision is terminal and MUST NOT be named here; later corrections use reporting-adjustment records.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    row_count: Annotated[
        SchemaInt,
        Field(
            description='Logical row count, including zero for a successfully evaluated empty report.',
            ge=0,
        ),
    ]
    control_totals: Annotated[
        list[reporting_control_total.ReportingControlTotal],
        Field(
            description='Profile-defined totals computed from the canonical logical revision. Names MUST be unique.'
        ),
    ]
    canonical_content_digest: (
        reporting_canonical_content_digest.ReportingCanonicalContentDigest | None
    ) = None
    created_at: AwareDatetime

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

Class variables

var account_id : str

var canonical_content_digest : ReportingCanonicalContentDigest | None

var control_totals : list[ReportingControlTotal1 | ReportingControlTotal2]

var coverage : ReportingCoverage

var created_at : pydantic.types.AwareDatetime

var data_through : pydantic.types.AwareDatetime | None

var data_through_precision : DataThroughPrecision

var finality : ReportingFinality

var finality_basis : FinalityBasis | None

var finality_policy_id : str | None

var finalized_at : pydantic.types.AwareDatetime | None

var media_buy_ids : list[ReportingMediaBuyId]

var model_config

var observed_at : pydantic.types.AwareDatetime

var period : Period

var report_definition_id : str

var report_definition_sha256 : str

var report_definition_uri : pydantic.networks.AnyUrl

var reporting_profile : str

var reporting_revision_id : str

var revision_content_sha256 : str

var row_count : int

var schema_dialect : Literal['https://json-schema.org/draft/2020-12/schema']

var schema_ref_policy : Literal['local_fragment_only']

var schema_sha256 : str

var schema_uri : pydantic.networks.AnyUrl

var schema_version : str

var supersedes_reporting_revision_id : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingSchedule (**data: Any)

Expand source code

class ReportingSchedule(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
        regex_engine="python-re",
    )
    period_duration: Annotated[
        str,
        Field(
            description='Strictly positive ISO 8601 duration of each reporting period, such as PT15M, P1D, or P1M.',
            pattern='^P(?=.*[1-9])(?=\\d|T)(?:\\d+Y)?(?:\\d+M)?(?:\\d+D)?(?:T(?=\\d)(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$',
        ),
    ]
    alignment: ReportingScheduleAlignment
    period_anchor: Annotated[
        AwareDatetime | None,
        Field(
            description='Required for billing_cycle alignment. This immutable instant anchors the recurring half-open billing periods so producer and consumer derive the same month, quarter, or other contractual cycle.'
        ),
    ] = None
    period_timezone: Annotated[
        str | None,
        Field(
            description='Required IANA timezone for source_timezone and billing_cycle calendar arithmetic. A numeric UTC offset is not sufficient because it does not define DST transitions.',
            max_length=255,
            min_length=1,
        ),
    ] = None
    delivery_sla: Annotated[
        str,
        Field(
            description='Non-negative maximum time after period end before the required revision is due. PT0S means due at period close; expected_at equals the resolved period end plus this duration.',
            pattern='^P(?=\\d|T)(?=.*\\d)(?:\\d+Y)?(?:\\d+M)?(?:\\d+D)?(?:T(?=\\d)(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$',
        ),
    ]

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

Class variables

var alignment : ReportingScheduleAlignment

var delivery_sla : str

var model_config

var period_anchor : pydantic.types.AwareDatetime | None

var period_duration : str

var period_timezone : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingScheduleOffering (**data: Any)

Expand source code

class ReportingScheduleOffering(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
        regex_engine="python-re",
    )
    period_duration: Annotated[
        str,
        Field(
            pattern='^P(?=.*[1-9])(?=\\d|T)(?:\\d+Y)?(?:\\d+M)?(?:\\d+D)?(?:T(?=\\d)(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$'
        ),
    ]
    alignment: reporting_schedule.ReportingScheduleAlignment
    period_anchor_policy: Annotated[
        PeriodAnchorPolicy | None,
        Field(
            description='For billing_cycle only. fixed requires the advertised anchor and timezone; configurable lets each authorized account configuration select them.'
        ),
    ] = None
    period_timezone_policy: Annotated[
        PeriodTimezonePolicy | None,
        Field(
            description="For source_timezone only. fixed advertises one exact upstream IANA timezone; account_resolved requires the seller to resolve and echo the account's upstream reporting timezone during configuration."
        ),
    ] = None
    period_anchor: AwareDatetime | None = None
    period_timezone: Annotated[str | None, Field(max_length=255, min_length=1)] = None
    delivery_sla: Annotated[
        str,
        Field(
            pattern='^P(?=\\d|T)(?=.*\\d)(?:\\d+Y)?(?:\\d+M)?(?:\\d+D)?(?:T(?=\\d)(?:\\d+H)?(?:\\d+M)?(?:\\d+S)?)?$'
        ),
    ]

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

Class variables

var alignment : ReportingScheduleAlignment

var delivery_sla : str

var model_config

var period_anchor : pydantic.types.AwareDatetime | None

var period_anchor_policy : PeriodAnchorPolicy | None

var period_duration : str

var period_timezone : str | None

var period_timezone_policy : PeriodTimezonePolicy | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingStatusIssue (**data: Any)

Expand source code

class ReportingStatusIssue(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    issue_id: Annotated[
        str,
        Field(
            description='Seller-issued stable identifier for this logical issue: re-emissions and later polls of the same unresolved condition reuse it, and resolution retires it, so consumers can project AdCP reporting issues into durable work items. A recurrence after resolution receives a new id.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ]
    code: Code
    severity: ReportingStatusSeverity
    opened_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller first observed this logical condition, carried unchanged across every re-emission until the issue is retired. It anchors the escalation clock advertised as consumer_mismatch_escalation_seconds and lets a consumer age an issue without keeping its own first-seen table. Required when code is CONSUMER_STATUS_MISMATCH.'
        ),
    ] = None
    issue_state: Annotated[
        IssueState | None,
        Field(
            description='Optional seller-maintained lifecycle for this issue_id. open is the default when omitted. acknowledged means a human on responsible_party has taken it up but the condition persists. resolved means the underlying condition no longer holds; a recurrence uses a new issue_id. waived means the parties agreed off-protocol to disregard this exact issue even though its underlying condition may still hold. Only open and acknowledged issues appear in issues[]; retiring an issue removes it from the projection rather than publishing it at resolved or waived, so a reader that treats a nonempty issues[] as degradation stays correct. A CONSUMER_STATUS_MISMATCH waiver follows the bilateral, exact-scope requirements in consumer_mismatch_lifecycle.'
        ),
    ] = None
    external_ref: Annotated[
        str | None,
        Field(
            description="Optional opaque, non-secret correlation string for the party's own tracker — a ticket key, incident ID, or case number. Untrusted display text only. The character class excludes whitespace and the solidus, so the value cannot express a URL or a sentence; receivers compare, store, and display it as inert text and never dereference, resolve, or execute it. It confers no authorization and MUST NOT be used to look up state across accounts or callers.",
            max_length=128,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,128}$',
        ),
    ] = None
    responsible_party: ResponsibleParty
    recommended_action: RecommendedAction
    message: Annotated[
        str | None,
        Field(
            description='Untrusted display text only. SDKs and agents dispatch exclusively on closed code/recommended_action values and never execute embedded links or instructions.',
            max_length=500,
        ),
    ] = None
    reporting_obligation_id: Annotated[
        str | None, Field(max_length=255, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,255}$')
    ] = None
    reporting_status_id: Annotated[
        str | None,
        Field(
            description='Current authenticated consumer status statement that caused this mismatch.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ] = None
    delivery_config_id: Annotated[
        str | None, Field(max_length=64, min_length=1, pattern='^[A-Za-z0-9_.:-]{1,64}$')
    ] = None
    delivery_config_version: Annotated[SchemaInt | None, Field(ge=1)] = None
    feed_purpose: reporting_delivery_offering.ReportingFeedPurpose | None = None
    media_buy_ids: Annotated[
        list[reporting_coverage.ReportingMediaBuyId] | None, Field(min_length=1)
    ] = None
    package_ids: Annotated[
        list[reporting_coverage.ReportingPackageId] | None, Field(min_length=1)
    ] = None
    period_start: AwareDatetime | None = None
    period_end: AwareDatetime | None = None
    expected_at: AwareDatetime | None = 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

Class variables

var code : Code

var delivery_config_id : str | None

var delivery_config_version : int | None

var expected_at : pydantic.types.AwareDatetime | None

var external_ref : str | None

var feed_purpose : ReportingFeedPurpose | None

var issue_id : str

var issue_state : IssueState | None

var media_buy_ids : list[ReportingMediaBuyId] | None

var message : str | None

var model_config

var opened_at : pydantic.types.AwareDatetime | None

var package_ids : list[ReportingPackageId] | None

var period_end : pydantic.types.AwareDatetime | None

var period_start : pydantic.types.AwareDatetime | None

var recommended_action : RecommendedAction

var reporting_obligation_id : str | None

var reporting_status_id : str | None

var responsible_party : ResponsibleParty

var severity : ReportingStatusSeverity

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingVerification (**data: Any)

Expand source code

class ReportingVerification(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    verified_at: Annotated[
        AwareDatetime,
        Field(
            description='When the producer completed verification through the claimed consumer/destination path.'
        ),
    ]
    verification_path: Annotated[
        VerificationPath,
        Field(
            description='Path on which verification succeeded. dataset_share readiness requires representative_consumer; delivered warehouse state requires destination.'
        ),
    ]
    verification_profile: reporting_verification_profile.ReportingVerificationProfile
    row_count: Annotated[
        SchemaInt,
        Field(
            description='Verified row count. Zero explicitly distinguishes an empty committed revision from a missing revision.',
            ge=0,
        ),
    ]
    control_totals: Annotated[
        list[reporting_control_total.ReportingControlTotal],
        Field(
            description='Profile-defined totals recomputed through verification_path. Names MUST be unique.'
        ),
    ]
    canonical_content_digest: (
        reporting_canonical_content_digest.ReportingCanonicalContentDigest | None
    ) = None
    physical_checksums: Annotated[
        list[PhysicalChecksums | PhysicalChecksums1] | None,
        Field(
            description='Method-specific byte/object checksums. Different encodings of the same logical revision normally have different values.',
            min_length=1,
        ),
    ] = None
    native_commit_evidence: Annotated[
        NativeCommitEvidence | None,
        Field(
            description='Provider-native immutable version evidence observed through the named consumer or destination path.'
        ),
    ] = 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

Class variables

var canonical_content_digest : ReportingCanonicalContentDigest | None

var control_totals : list[ReportingControlTotal1 | ReportingControlTotal2]

var model_config

var native_commit_evidence : NativeCommitEvidence | None

var physical_checksums : list[PhysicalChecksums | PhysicalChecksums1] | None

var row_count : int

var verification_path : VerificationPath

var verification_profile : ReportingVerificationProfile

var verified_at : pydantic.types.AwareDatetime

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingVerificationProfile (*args, **kwds)

Expand source code

class ReportingVerificationProfile(StrEnum):
    native_commit = 'native_commit'
    manifest_checksums = 'manifest_checksums'
    canonical_digest = 'canonical_digest'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var canonical_digest

var manifest_checksums

var native_commit

class ReportingWebhook (**data: Any)

Expand source code

class ReportingWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='Webhook endpoint URL for reporting notifications')]
    token: Annotated[
        str | None,
        Field(
            description='Optional client-provided token for webhook validation. Echoed back in webhook payload to validate request authenticity.',
            min_length=16,
        ),
    ] = None
    authentication: Annotated[
        Authentication,
        Field(
            deprecated=True,
            description="Legacy authentication configuration for webhook delivery (A2A-compatible). Opts the receiver into Bearer or HMAC-SHA256 signing. Both schemes are deprecated; the preferred signing profile for new integrations is RFC 9421, where the seller signs with a key published at its brand.json agents[] entry and the buyer verifies against the seller's JWKS — no shared secret crosses the wire (see docs/building/implementation/security.mdx#webhook-callbacks). This field is required in AdCP 3.x; the requirement is removed in AdCP 4.0 when the default RFC 9421 path becomes the only path.",
        ),
    ]
    reporting_frequency: Annotated[
        ReportingFrequency,
        Field(
            description='Frequency for automated reporting delivery. Must be supported by all products in the media buy.'
        ),
    ]
    requested_metrics: Annotated[
        list[available_metric.AvailableMetric] | None,
        Field(
            description="Optional list of metrics to include in webhook notifications. If omitted, all available metrics are included; an empty array has the same meaning as omission (it does not narrow to impressions and spend only). impressions and spend are always included regardless of this list. Must be a subset of the product's available_metrics. Subset evaluation and leaf resolution follow `enums/available-metric.json`: a numeric leaf may be covered by its container, while each structured distribution must be explicitly available. Requesting any nested identity selects its canonical carrier inside the payload's nested object. Same narrowing semantics as get_media_buy_delivery's requested_metrics (which additionally requires at least one entry when present)."
        ),
    ] = 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

Class variables

var model_config

var operation_id : str | None

var reporting_frequency : ReportingFrequency

var requested_metrics : list[AvailableMetric] | None

var token : str | None

var url : pydantic.networks.AnyUrl

Instance variables

var authentication : Authentication

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

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.

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

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 RequestProposalsRequest (**data: Any)

Expand source code

class RequestProposalsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    context_id: Annotated[
        str | None,
        Field(
            description='MCP compatibility field: servers ignore this value; A2A uses transport-native Message/Task contextId.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    governance_context: Annotated[str | None, Field(max_length=4096, min_length=1)] = None
    push_notification_config: push_notification_config_1.PushNotificationConfig | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated key required for retry-safe proposal creation.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    account: Annotated[
        canonical_account_ref.CanonicalAccountReference | None,
        Field(
            description='Alternative brand source for proposal terms. Provide either this natural-key account containing brand and operator or top-level brand, not both.'
        ),
    ] = None
    brand: Annotated[
        brand_key.BrandKey | None,
        Field(
            description='Alternative brand source for proposal terms. Provide either top-level brand or a natural-key account containing brand and operator, not both.'
        ),
    ] = None
    brief: Annotated[
        str,
        Field(
            description='Campaign goal, strategy, and requirements that are not represented in structured criteria.',
            min_length=1,
        ),
    ]
    criteria: product_discovery_criteria.ProductDiscoveryCriteria | None = None
    opportunity: Annotated[
        Opportunity | None,
        Field(
            description='Optional planning-cycle context that the seller associates with every proposal created by this request.'
        ),
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> RequestProposalsRequest:
        # ``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 (('brand',), ('account',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'RequestProposalsRequest requires at least one of these field groups: brand | account'
        )

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 account : CanonicalAccountReference1 | CanonicalAccountReference2 | None

var brand : BrandKey | None

var brief : str

var context : ContextObject | None

var context_id : str | None

var criteria : ProductDiscoveryCriteria | None

var governance_context : str | None

var idempotency_key : str

var model_config

var opportunity : Opportunity | None

var push_notification_config : PushNotificationConfig | 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 DownstreamConnectionRequiredForItem (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class RequiredForItem(ScalarStr):
    __slots__ = ()
    _constraints = {'min_length': 1}
    _json_schema_extra = {
        'examples': ['list_creatives', 'sync_creatives', 'create_media_buy', 'get_media_buy_delivery', 'get_creative_delivery'],
    }

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class RequestSigningRequiredForItem (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class RequiredForItem(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[a-z][a-z0-9_]*$'}

A str generated from a JSON Schema string root.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

Subclasses

• SupportedForItem
• WarnForItem

class RequoteRequiredDetails (**data: Any)

Expand source code

class RequoteRequiredDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    envelope_field: Annotated[
        EnvelopeField | EnvelopeField1 | None,
        Field(
            description='Buyer-visible request field path or paths that breached the accepted commercial envelope. Values MUST NOT name seller-internal objects or identifiers. New emitters SHOULD use the array form even for one path; the scalar form remains valid for compatibility with existing 3.x sellers.'
        ),
    ] = None
    change_term_id: Annotated[
        media_buy_change_term_id.MediaBuyChangeTermId | None,
        Field(
            description='Accepted proposal change term whose typed constraint the request exceeded.'
        ),
    ] = None
    decline_reason: Annotated[
        seller_policy_decline_reason.SellerPolicyDeclineReason | None,
        Field(
            description='Coarse seller-policy dimension that declined the requested shape. Sellers SHOULD populate this when they have a structured reason and disclosure does not expose private thresholds or enforcement controls. When present, it MUST be consistent with the enclosing error.recovery classification.'
        ),
    ] = 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

Class variables

var change_term_id : MediaBuyChangeTermId | None

var decline_reason : SellerPolicyDeclineReason | None

var envelope_field : EnvelopeField | EnvelopeField1 | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ResolvedBrand (**data: Any)

Expand source code

class ResolvedBrand(BaseModel):
    """Brand identity resolved from the AdCP registry."""

    model_config = ConfigDict(extra="allow")

    canonical_id: str
    canonical_domain: str
    brand_name: str
    names: list[dict[str, str]] | None = None
    keller_type: str | None = None
    parent_brand: str | None = None
    house_domain: str | None = None
    house_name: str | None = None
    brand_agent_url: str | None = None
    brand: dict[str, Any] | None = None
    source: str

Brand identity resolved from the AdCP 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

• pydantic.main.BaseModel

Class variables

var brand : dict[str, typing.Any] | None

var brand_agent_url : str | None

var brand_name : str

var canonical_domain : str

var canonical_id : str

var house_domain : str | None

var house_name : str | None

var keller_type : str | None

var model_config

var names : list[dict[str, str]] | None

var parent_brand : str | None

var source : str

class ResolvedProperty (**data: Any)

Expand source code

class ResolvedProperty(BaseModel):
    """Property information resolved from the AdCP registry."""

    model_config = ConfigDict(extra="allow")

    publisher_domain: str
    source: str
    authorized_agents: list[dict[str, Any]]
    properties: list[dict[str, Any]]
    verified: bool

Property information resolved from the AdCP 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

• pydantic.main.BaseModel

Class variables

var authorized_agents : list[dict[str, typing.Any]]

var model_config

var properties : list[dict[str, typing.Any]]

var publisher_domain : str

var source : str

var verified : bool

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.

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

• 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.

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

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 Responsive (**data: Any)

Expand source code

class Responsive(AdCPBaseModel):
    width: StrictBool
    height: StrictBool

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

Class variables

var height : bool

var model_config

var width : bool

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

Class variables

var errors : list[Error]

var kind : Literal['failed']

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RightsPricingOption (**data: Any)

Expand source code

class RightsPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str,
        Field(
            description='Unique identifier for this pricing option. Referenced in acquire_rights and report_usage.'
        ),
    ]
    model: Annotated[
        pricing_model.PricingModel, Field(description='Pricing model (cpm, flat_rate, etc.)')
    ]
    price: Annotated[
        StrictFloat,
        Field(
            description='Price amount. Interpretation depends on model: CPM = cost per 1,000 impressions, flat_rate = fixed cost per period.',
            ge=0.0,
        ),
    ]
    currency: Annotated[str, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')]
    uses: Annotated[
        list[right_use.RightUse],
        Field(
            description='Which rights uses this pricing option covers. A single option can bundle multiple uses (e.g., likeness + voice).',
            min_length=1,
        ),
    ]
    period: Annotated[
        rights_billing_period.RightsBillingPeriod | None,
        Field(description='Billing period for flat_rate and time-based models'),
    ] = None
    impression_cap: Annotated[
        SchemaInt | None,
        Field(description='Maximum impressions included in this pricing option per period', ge=1),
    ] = None
    overage_cpm: Annotated[
        StrictFloat | None,
        Field(description='CPM rate applied to impressions exceeding the impression_cap', ge=0.0),
    ] = None
    description: Annotated[
        str | None, Field(description='Human-readable description of this pricing option')
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var currency : str

var description : str | None

var ext : ExtensionObject | None

var impression_cap : int | None

var model : PricingModel

var model_config

var overage_cpm : float | None

var period : RightsBillingPeriod | None

var price : float

var pricing_option_id : str

var uses : list[RightUse]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RightsTerms (**data: Any)

Expand source code

class RightsTerms(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: str
    amount: Annotated[StrictFloat, Field(ge=0.0)]
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]
    period: rights_billing_period.RightsBillingPeriod | None = None
    uses: list[right_use.RightUse]
    impression_cap: Annotated[SchemaInt | None, Field(ge=1)] = None
    overage_cpm: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    start_date: date | None = None
    end_date: date | None = None
    exclusivity: Annotated[
        Exclusivity | None, Field(description='Exclusivity terms if applicable')
    ] = 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

Class variables

var amount : float

var currency : str

var end_date : datetime.date | None

var exclusivity : Exclusivity | None

var impression_cap : int | None

var model_config

var overage_cpm : float | None

var period : RightsBillingPeriod | None

var pricing_option_id : str

var start_date : datetime.date | None

var uses : list[RightUse]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CapabilitiesPreviewRoute (**data: Any)

Expand source code

class Route(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    capability_id: Annotated[
        str,
        Field(
            description='Agent-local creative.supported_formats[].capability_id accepted by preview_creative.',
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ]
    rendering_origin: Annotated[
        RenderingOrigin,
        Field(
            description="Informational implementation origin. platform_native means the route uses the serving platform's preview machinery; agent_approximation means the agent renders an approximation. Neither value grants authority without a publisher preview_provider delegation."
        ),
    ]

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

Class variables

var capability_id : str

var model_config

var rendering_origin : RenderingOrigin

class PublisherPreviewRoute (**data: Any)

Expand source code

class Route(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    format_option_id: Annotated[
        str,
        Field(
            description='Format option in this adagents.json placement for which the delegation applies. It MUST resolve through the same-file top-level formats[] catalog or an inline placement format declaration.',
            min_length=1,
        ),
    ]
    capability_id: Annotated[
        str,
        Field(
            description="Agent-local preview capability advertised by the delegated provider. The provider's canonical format declaration MUST satisfy the resolved placement format option.",
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ]
    covers_placement_presentation: Annotated[
        StrictBool | None,
        Field(
            description="True only when the publisher delegates both creative rendering and the complete placement-specific frame to this route. When false or omitted, consumers compose any presentation_ref around the provider's creative render."
        ),
    ] = False

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

Class variables

var capability_id : str

var covers_placement_presentation : bool | None

var format_option_id : str

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SchemaVariant

Expand source code

class SchemaVariant(metaclass=_SchemaVariantMeta):
    """Marker for intentional cross-class entity overrides — see module docstring."""

Marker for intentional cross-class entity overrides — see module docstring.

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.

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

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 SellerAgentReference (**data: Any)

Expand source code

class SellerAgentReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    agent_url: Annotated[
        AnyUrl,
        Field(
            description="The seller agent's API endpoint URL as declared in the property publisher's adagents.json `authorized_agents[].url`. MUST use the `https://` scheme. Receivers compare this URL against the `authorized_agents` list using the AdCP URL canonicalization rules — not byte-equality — and reject mismatches with `seller_not_authorized`. See docs/reference/url-canonicalization."
        ),
    ]
    id: Annotated[
        str | None,
        Field(
            description='Reserved for a future registry-assigned stable seller identifier. Not used today — senders MUST NOT populate this field until a registry is defined. When a future release populates both `agent_url` and `id`, `agent_url` remains authoritative and `id` is advisory.',
            min_length=1,
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ] = 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

Class variables

var agent_url : pydantic.networks.AnyUrl

var id : str | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ProductFormatSellerPreference (*args, **kwds)

Expand source code

class SellerPreference(StrEnum):
    preferred = 'preferred'
    accepted = 'accepted'
    discouraged = 'discouraged'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var accepted

var discouraged

var preferred

class Setup (**data: Any)

Expand source code

class Setup(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    url: AnyUrl | None = None
    message: str
    expires_at: AwareDatetime | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var expires_at : pydantic.types.AwareDatetime | None

var message : str

var model_config

var url : pydantic.networks.AnyUrl | None

class CoreSetup (**data: Any)

Expand source code

class Setup(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[
        AnyUrl | None,
        Field(
            description='URL where the human can complete the required action (credit application, legal agreement, add funds).'
        ),
    ] = None
    message: Annotated[str, Field(description="Human-readable description of what's needed.")]
    expires_at: Annotated[
        AwareDatetime | None, Field(description='When this setup link expires.')
    ] = 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

Class variables

var expires_at : pydantic.types.AwareDatetime | None

var message : str

var model_config

var url : pydantic.networks.AnyUrl | None

class SyncAccountsSetup (**data: Any)

Expand source code

class Setup(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    url: AnyUrl | None = None
    message: str
    expires_at: AwareDatetime | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var expires_at : pydantic.types.AwareDatetime | None

var message : str

var model_config

var url : pydantic.networks.AnyUrl | None

class SyncEventSourcesSetup (**data: Any)

Expand source code

class Setup(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    snippet: str | None = None
    snippet_type: Literal['javascript', 'html', 'pixel_url', 'server_only'] | None = None
    instructions: str | None = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var instructions : str | None

var model_config

var snippet : str | None

var snippet_type : Literal['javascript', 'html', 'pixel_url', 'server_only'] | None

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class SiCapabilities (**data: Any)

Expand source code

class SiCapabilities(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    modalities: Annotated[
        Modalities | None, Field(description='Interaction modalities supported')
    ] = None
    components: Annotated[Components | None, Field(description='Visual components supported')] = (
        None
    )
    commerce: Annotated[Commerce | None, Field(description='Commerce capabilities')] = None
    a2ui: Annotated[A2ui | None, Field(description='A2UI (Agent-to-UI) capabilities')] = None
    mcp_apps: Annotated[
        StrictBool | None,
        Field(description='Supports MCP Apps for rendering A2UI surfaces in iframes'),
    ] = False

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

Class variables

var a2ui : A2ui | None

var commerce : Commerce | None

var components : Components | None

var mcp_apps : bool | None

var modalities : Modalities | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SiGetOfferingRequest (**data: Any)

Expand source code

class SiGetOfferingRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    offering_id: Annotated[
        str, Field(description='Offering identifier from the catalog to get details for')
    ]
    intent: Annotated[
        str | None,
        Field(
            description="Optional natural language description of user intent for personalized results (e.g., 'mens size 14 near Cincinnati'). Must be anonymous - no PII."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    include_products: Annotated[
        StrictBool | None, Field(description='Whether to include matching products in the response')
    ] = False
    product_limit: Annotated[
        SchemaInt | None,
        Field(description='Maximum number of matching products to return', ge=1, le=50),
    ] = 5
    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 include_products : bool | None

var intent : str | None

var model_config

var offering_id : str

var product_limit : int | 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 SiGetOfferingResponse (**data: Any)

Expand source code

class SiGetOfferingResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    available: Annotated[
        StrictBool, Field(description='Whether the offering is currently available')
    ]
    offering_token: Annotated[
        str | None,
        Field(
            description="Token to pass to si_initiate_session for session continuity. Brand stores the full query context server-side (products shown, order, context) so they can resolve references like 'the second one' when the session starts."
        ),
    ] = None
    ttl_seconds: Annotated[
        SchemaInt | None,
        Field(
            description='How long this offering information is valid (seconds). Host should re-fetch after TTL expires.',
            ge=0,
        ),
    ] = None
    checked_at: Annotated[
        AwareDatetime | None, Field(description='When this offering information was retrieved')
    ] = None
    offering: Annotated[Offering | None, Field(description='Offering details')] = None
    matching_products: Annotated[
        list[MatchingProduct] | None,
        Field(
            description='Products matching the request context. Only included if include_products was true.'
        ),
    ] = None
    sponsored_context: Annotated[
        si_sponsored_context.SiSponsoredContext | None,
        Field(
            description='Declaration for the sponsored context carried by this offering response. When present, it applies to the returned offering and matching_products package as a whole unless a future extension narrows the declaration to individual items. Hosts MUST either honor the declared context_use and disclosure_obligation or reject the context before using it.'
        ),
    ] = None
    total_matching: Annotated[
        SchemaInt | None,
        Field(
            description='Total number of products matching the context (may be more than returned in matching_products)',
            ge=0,
        ),
    ] = None
    unavailable_reason: Annotated[
        str | None,
        Field(
            description="If not available, why (e.g., 'expired', 'sold_out', 'region_restricted')"
        ),
    ] = None
    alternative_offering_ids: Annotated[
        list[str] | None,
        Field(description='Alternative offerings to consider if this one is unavailable'),
    ] = None
    errors: Annotated[
        list[error.Error] | None, Field(description='Errors during offering lookup')
    ] = 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.

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 alternative_offering_ids : list[str] | None

var available : bool

var checked_at : pydantic.types.AwareDatetime | None

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var matching_products : list[MatchingProduct] | None

var model_config

var offering : Offering | None

var offering_token : str | None

var sponsored_context : SiSponsoredContext | None

var total_matching : int | None

var ttl_seconds : int | None

var unavailable_reason : str | 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 SiIdentity (**data: Any)

Expand source code

class SiIdentity(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    consent_granted: Annotated[
        StrictBool, Field(description='Whether user consented to share identity')
    ]
    consent_timestamp: Annotated[
        AwareDatetime | None, Field(description='When consent was granted (ISO 8601)')
    ] = None
    consent_scope: Annotated[
        list[ConsentScopeEnum] | None, Field(description='What data was consented to share')
    ] = None
    privacy_policy_acknowledged: Annotated[
        PrivacyPolicyAcknowledged | None, Field(description='Brand privacy policy acknowledgment')
    ] = None
    user: Annotated[
        User | None, Field(description='User data (only present if consent_granted is true)')
    ] = None
    anonymous_session_id: Annotated[
        str | None,
        Field(description='Session ID for anonymous users (when consent_granted is false)'),
    ] = 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

Class variables

var anonymous_session_id : str | None

var consent_granted : bool

var consent_scope : list[ConsentScopeEnum] | None

var consent_timestamp : pydantic.types.AwareDatetime | None

var model_config

var privacy_policy_acknowledged : PrivacyPolicyAcknowledged | None

var user : User | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SiInitiateSessionRequest (**data: Any)

Expand source code

class SiInitiateSessionRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    intent: Annotated[
        str,
        Field(
            description='Natural language description of user intent — the conversation handoff from the host describing what the user needs from the brand agent'
        ),
    ]
    context: context_1.ContextObject | None = None
    identity: si_identity.SiIdentity
    media_buy_id: Annotated[
        str | None, Field(description='AdCP media buy ID if session was triggered by advertising')
    ] = None
    placement: Annotated[
        str | None,
        Field(
            description="Where this session was triggered (e.g., 'chatgpt_search', 'claude_chat')"
        ),
    ] = None
    offering_id: Annotated[
        str | None, Field(description='Brand-specific offering identifier to apply')
    ] = None
    supported_capabilities: Annotated[
        si_capabilities.SiCapabilities | None,
        Field(description='What capabilities the host supports'),
    ] = None
    offering_token: Annotated[
        str | None,
        Field(
            description="Token from si_get_offering response for session continuity. Brand uses this to recall what products were shown to the user, enabling natural references like 'the second one' or 'that blue shoe'."
        ),
    ] = None
    sponsored_context_receipt: Annotated[
        si_sponsored_context_receipt.SiSponsoredContextReceipt | None,
        Field(
            description='Host receipt for sponsored context accepted from a prior si_get_offering response or other pre-session context package. This records the accepted context_use, disclosure commitment, paying_principal, and host receipt for audit.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate session creation on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 idempotency_key : str

var identity : SiIdentity

var intent : str

var media_buy_id : str | None

var model_config

var offering_id : str | None

var offering_token : str | None

var placement : str | None

var sponsored_context_receipt : SiSponsoredContextReceipt | None

var supported_capabilities : SiCapabilities | 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 SiInitiateSessionResponse (**data: Any)

Expand source code

class SiInitiateSessionResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    session_id: Annotated[
        str, Field(description='Unique session identifier for subsequent messages')
    ]
    response: Annotated[Response | None, Field(description="Brand agent's initial response")] = None
    negotiated_capabilities: Annotated[
        si_capabilities.SiCapabilities | None,
        Field(description='Intersection of brand and host capabilities for this session'),
    ] = None
    sponsored_context: Annotated[
        si_sponsored_context.SiSponsoredContext | None,
        Field(
            description='Declaration for sponsored context carried by the initial brand-agent response. Hosts MUST either honor the declared context_use and disclosure_obligation or reject the context before presenting, comparing, or otherwise using it.'
        ),
    ] = None
    session_status: Annotated[
        si_session_status.SiSessionStatus,
        Field(
            description='Current session lifecycle state. Returned in initiation, message, and termination responses.'
        ),
    ]
    session_ttl_seconds: Annotated[
        SchemaInt | None,
        Field(
            description='Session inactivity timeout in seconds. After this duration without a message, the brand agent may terminate the session. Hosts SHOULD warn users before timeout when possible.',
            ge=1,
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None, Field(description='Errors during session initiation')
    ] = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var model_config

var negotiated_capabilities : SiCapabilities | None

var response : Response | None

var session_id : str

var session_status : SiSessionStatus

var session_ttl_seconds : int | None

var sponsored_context : SiSponsoredContext | 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 SiSendMessageRequest (**data: Any)

Expand source code

class SiSendMessageRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Each conversational turn is a distinct mutation of session transcript — without this key, a timeout-and-retry produces a duplicate turn and a duplicate model response. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each user turn.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    session_id: Annotated[str, Field(description='Active session identifier')]
    message: Annotated[str | None, Field(description="User's message to the brand agent")] = None
    action_response: Annotated[
        ActionResponse | None,
        Field(description='Response to a previous action_button (e.g., user clicked checkout)'),
    ] = None
    sponsored_context_receipt: Annotated[
        si_sponsored_context_receipt.SiSponsoredContextReceipt | None,
        Field(
            description="Host receipt for sponsored context accepted from a prior SI response in this session. This gives the brand/seller an audit-visible record of the host's accepted use mode and disclosure commitment for that context."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> SiSendMessageRequest:
        # ``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 (('message',), ('action_response',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'SiSendMessageRequest requires at least one of these field groups: message | action_response'
        )

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 action_response : ActionResponse | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var message : str | None

var model_config

var session_id : str

var sponsored_context_receipt : SiSponsoredContextReceipt | None

class SiSendTextMessageRequest (**data: Any)

Expand source code

class SiSendMessageRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Each conversational turn is a distinct mutation of session transcript — without this key, a timeout-and-retry produces a duplicate turn and a duplicate model response. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each user turn.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    session_id: Annotated[str, Field(description='Active session identifier')]
    message: Annotated[str | None, Field(description="User's message to the brand agent")] = None
    action_response: Annotated[
        ActionResponse | None,
        Field(description='Response to a previous action_button (e.g., user clicked checkout)'),
    ] = None
    sponsored_context_receipt: Annotated[
        si_sponsored_context_receipt.SiSponsoredContextReceipt | None,
        Field(
            description="Host receipt for sponsored context accepted from a prior SI response in this session. This gives the brand/seller an audit-visible record of the host's accepted use mode and disclosure commitment for that context."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> SiSendMessageRequest:
        # ``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 (('message',), ('action_response',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'SiSendMessageRequest requires at least one of these field groups: message | action_response'
        )

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 action_response : ActionResponse | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var message : str | None

var model_config

var session_id : str

var sponsored_context_receipt : SiSponsoredContextReceipt | None

class SiSendActionResponseRequest (**data: Any)

Expand source code

class SiSendMessageRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Each conversational turn is a distinct mutation of session transcript — without this key, a timeout-and-retry produces a duplicate turn and a duplicate model response. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each user turn.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    session_id: Annotated[str, Field(description='Active session identifier')]
    message: Annotated[str | None, Field(description="User's message to the brand agent")] = None
    action_response: Annotated[
        ActionResponse | None,
        Field(description='Response to a previous action_button (e.g., user clicked checkout)'),
    ] = None
    sponsored_context_receipt: Annotated[
        si_sponsored_context_receipt.SiSponsoredContextReceipt | None,
        Field(
            description="Host receipt for sponsored context accepted from a prior SI response in this session. This gives the brand/seller an audit-visible record of the host's accepted use mode and disclosure commitment for that context."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> SiSendMessageRequest:
        # ``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 (('message',), ('action_response',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'SiSendMessageRequest requires at least one of these field groups: message | action_response'
        )

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 action_response : ActionResponse | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var message : str | None

var model_config

var session_id : str

var sponsored_context_receipt : SiSponsoredContextReceipt | 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 SiSendMessageResponse (**data: Any)

Expand source code

class SiSendMessageResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    session_id: Annotated[str, Field(description='Session identifier')]
    response: Annotated[Response | None, Field(description="Brand agent's response")] = None
    mcp_resource_uri: Annotated[
        str | None,
        Field(
            description='MCP resource URI for hosts with MCP Apps support (e.g., ui://si/session-abc123)'
        ),
    ] = None
    sponsored_context: Annotated[
        si_sponsored_context.SiSponsoredContext | None,
        Field(
            description='Declaration for sponsored context carried by this brand-agent response. Hosts MUST either honor the declared context_use and disclosure_obligation or reject the context before presenting, comparing, or otherwise using it.'
        ),
    ] = None
    session_status: Annotated[
        si_session_status.SiSessionStatus,
        Field(
            description='Current session status. On a successful response, one of: active, pending_handoff, or complete. Terminated sessions return error codes (SESSION_NOT_FOUND or SESSION_TERMINATED) instead of a success response.'
        ),
    ]
    handoff: Annotated[
        Handoff | None, Field(description='Handoff request when session_status is pending_handoff')
    ] = None
    errors: list[error.Error] | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var handoff : Handoff | None

var mcp_resource_uri : str | None

var model_config

var response : Response | None

var session_id : str

var session_status : SiSessionStatus

var sponsored_context : SiSponsoredContext | 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 SiTerminateSessionRequest (**data: Any)

Expand source code

class SiTerminateSessionRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    session_id: Annotated[str, Field(description='Session identifier to terminate')]
    reason: Annotated[Reason, Field(description='Reason for termination')]
    termination_context: Annotated[
        TerminationContext | None, Field(description='Context for the termination')
    ] = 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 reason : Reason

var session_id : str

var termination_context : TerminationContext | 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 SiTerminateSessionResponse (**data: Any)

Expand source code

class SiTerminateSessionResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    session_id: Annotated[str, Field(description='Terminated session identifier')]
    terminated: Annotated[
        StrictBool, Field(description='Whether session was successfully terminated')
    ]
    session_status: Annotated[
        si_session_status.SiSessionStatus | None,
        Field(
            description="Resulting session state. 'complete' for handoff_transaction/handoff_complete, 'terminated' for user_exit/session_timeout/host_terminated."
        ),
    ] = None
    acp_handoff: Annotated[
        AcpHandoff | None,
        Field(description='ACP checkout handoff data. Present when reason is handoff_transaction.'),
    ] = None
    follow_up: Annotated[FollowUp | None, Field(description='Suggested follow-up actions')] = None
    errors: list[error.Error] | None = 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.

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 acp_handoff : AcpHandoff | None

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var follow_up : FollowUp | None

var model_config

var session_id : str

var session_status : SiSessionStatus | None

var terminated : bool

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 SiUiElement (**data: Any)

Expand source code

class SiUiElement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Type, Field(description='Component type')]
    data: Annotated[dict[str, Any] | None, Field(description='Component-specific data')] = 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

Class variables

var data : dict[str, typing.Any] | None

var model_config

var type : Type

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Signal (**data: Any)

Expand source code

class Signal(SignalListing):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description='Canonical signal reference for this wholesale signal. New events SHOULD use signal_ref.'
        ),
    ] = None
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older clients.',
        ),
    ] = None
    signal_agent_segment_id: Annotated[
        str,
        Field(description='Opaque activation handle returned by the signals agent.', min_length=1),
    ]
    name: Annotated[str, Field(description='Human-readable signal name', min_length=1)]
    description: Annotated[str, Field(description='Detailed signal description', min_length=1)]
    value_type: signal_value_type.SignalValueType | None = None
    categories: Annotated[list[str] | None, Field(min_length=1)] = None
    range: Range | None = None
    signal_type: signal_catalog_type.SignalAvailabilityType
    data_provider: Annotated[str | None, Field(min_length=1)] = None
    coverage_percentage: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    coverage_forecast: Annotated[
        signal_coverage_forecast.SignalCoverageForecast | None,
        Field(
            description='Optional forecast-shaped signal availability guidance using the same wire shape as get_signals.signals[].coverage_forecast. When present, this is authoritative for signal-level discovery coverage.'
        ),
    ] = None
    deployments: Annotated[Sequence[deployment.Deployment], Field(min_length=1)]
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None, Field(min_length=1)
    ] = 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

• SignalListing
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var categories : list[str] | None

var coverage_forecast : SignalCoverageForecast | None

var coverage_percentage : float | None

var data_provider : str | None

var deployments : Sequence[Deployment1 | Deployment2]

var description : str

var model_config

var name : str

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var range : Range | None

var signal_agent_segment_id : str

var signal_id : SignalId8 | SignalId9 | None

var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None

var signal_type : SignalAvailabilityType

var value_type : SignalValueType | None

class GetSignalsSignal (**data: Any)

Expand source code

class Signal(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older Signals Protocol clients.',
        ),
    ] = None
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description="Canonical signal reference. Use scope 'product' for a product-local signal defined by this listing; use scope 'data_provider' with data_provider_domain for a signal defined in a data provider's published adagents.json signals[]; use scope 'signal_source' with signal_source_url for a source-native signal."
        ),
    ] = None
    signal_agent_segment_id: Annotated[
        str,
        Field(
            description='Opaque resolved-segment handle issued by this signal source. Pass this string verbatim to activate_signal.signal_agent_segment_id, and echo it in package signal targeting when the selected product option exposes the same handle. Treat the value as provider-scoped and opaque: providers MAY namespace it so two providers can expose similarly named signals without relying on a shared taxonomy. Do not pass the signal_id object as this handle, and do not reconstruct a segment handle from categorical values when get_signals returned a resolved segment.'
        ),
    ]
    name: Annotated[
        str,
        Field(
            description="Human-readable signal name. Required when signal_ref_1.scope is 'product'. For data_provider and signal_source refs, this is optional contextual display text; the referenced definition or source remains authoritative."
        ),
    ]
    description: Annotated[
        str,
        Field(
            description='Detailed signal description. For data_provider and signal_source refs, this is optional contextual display text and MUST NOT replace the referenced definition.'
        ),
    ]
    value_type: Annotated[
        signal_value_type.SignalValueType | None,
        Field(
            description="The data type of this signal's values. Required when signal_ref_1.scope is 'product'."
        ),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Valid values for categorical signals. Present when value_type is 'categorical'.",
            min_length=1,
        ),
    ] = None
    range: Annotated[
        Range | None,
        Field(description="Valid range for numeric signals. Present when value_type is 'numeric'."),
    ] = None
    signal_type: Annotated[
        signal_catalog_type.SignalAvailabilityType,
        Field(description='Commercial/provenance type of signal (marketplace, custom, owned)'),
    ]
    data_provider: Annotated[
        str | None,
        Field(
            description='Human-readable source name for the signal, when applicable. For data_provider-scoped signals this is the data provider name; for signal_source-scoped signals it may identify the signal source or proprietary origin.'
        ),
    ] = None
    coverage_percentage: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only. If coverage_forecast includes an absent bucket over the same denominator, coverage_percentage SHOULD align with 100 * (1 - absent coverage_rate.mid).',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    coverage_forecast: Annotated[
        signal_coverage_forecast.SignalCoverageForecast | None,
        Field(
            description='Optional forecast-shaped signal availability guidance. When present, this is authoritative for signal-level discovery coverage. Use this to disclose the denominator, bucket semantics, not-present bucket, aggregate present bucket, and per-value coverage distribution for the signal.'
        ),
    ] = None
    deployments: Annotated[
        Sequence[deployment.Deployment], Field(description='Array of deployment targets')
    ]
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options available for this signal when it has an incremental price. The buyer selects one and passes its pricing_option_id in report_usage or package-level signal_targeting_groups for billing verification. Omit when pricing is unavailable to the caller, bundled into the destination product, or has no incremental cost.',
            min_length=1,
        ),
    ] = None
    methodology_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional link to published methodology, media-kit, or data documentation. For data_provider and signal_source refs, this SHOULD match or supplement the referenced definition.'
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='When this definition record was last updated. This indicates freshness of the definition record, not an attestation that the underlying data or model was refreshed at that time.'
        ),
    ] = None
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None,
        Field(description='Restricted attribute categories this signal touches.', min_length=1),
    ] = None
    demographic_predicate: Annotated[
        demographic_predicate_1.DemographicPredicate | None,
        Field(
            description="Projected authoritative demographic meaning for the signal. When projected from another provider, this MUST match the provider's definition exactly. Signal names alone never establish demographic semantics."
        ),
    ] = None
    policy_categories: Annotated[
        list[str] | None,
        Field(description='Policy categories this signal is sensitive for.', min_length=1),
    ] = None
    taxonomy: Annotated[
        Taxonomy | None,
        Field(
            description='Optional taxonomy metadata describing what this signal means in an external audience, content, retail-media, or provider-owned taxonomy.'
        ),
    ] = None
    segmentation_criteria: Annotated[str | None, Field(max_length=500)] = None
    criteria_url: AnyUrl | None = None
    data_sources: Annotated[list[DataSource] | None, Field(min_length=1)] = None
    methodology: Methodology | None = None
    audience_expansion: StrictBool | None = None
    device_expansion: StrictBool | None = None
    refresh_cadence: RefreshCadence | None = None
    lookback_window: RefreshCadence | None = None
    onboarder: Onboarder | None = None
    countries: Annotated[list[Country] | None, Field(min_length=1)] = None
    consent_basis: Annotated[
        list[consent_basis_1.ConsentBasis] | None,
        Field(
            description="Data provider's declared GDPR Article 6 lawful basis or consent basis for the underlying signal definition, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own processing basis for the provider-declared basis.",
            min_length=1,
        ),
    ] = None
    art9_basis: Annotated[
        Art9Basis | None,
        Field(
            description="Data provider's declared GDPR Article 9 basis for the underlying signal definition when special-category data is involved and Article 9 applies, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own Article 9 basis for the provider-declared basis."
        ),
    ] = None
    modeling: Modeling | None = None
    data_subject_rights: Annotated[
        DataSubjectRights | None,
        Field(
            description='Per-signal data-subject-rights routing. This is a contact/routing reference, not a machine-callable AdCP API.'
        ),
    ] = None
    dts_compliant_version: str | None = 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

Class variables

var art9_basis : Art9Basis | None

var audience_expansion : bool | None

var categories : list[str] | None

var consent_basis : list[ConsentBasis] | None

var countries : list[Country] | None

var coverage_forecast : SignalCoverageForecast | None

var coverage_percentage : float | None

var criteria_url : pydantic.networks.AnyUrl | None

var data_provider : str | None

var data_sources : list[DataSource] | None

var data_subject_rights : DataSubjectRights | None

var demographic_predicate : DemographicPredicate | None

var deployments : Sequence[Deployment1 | Deployment2]

var description : str

var device_expansion : bool | None

var dts_compliant_version : str | None

var last_updated : pydantic.types.AwareDatetime | None

var lookback_window : RefreshCadence | None

var methodology : Methodology | None

var methodology_url : pydantic.networks.AnyUrl | None

var model_config

var modeling : Modeling | None

var name : str

var onboarder : Onboarder | None

var policy_categories : list[str] | None

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var range : Range | None

var refresh_cadence : RefreshCadence | None

var restricted_attributes : list[RestrictedAttribute] | None

var segmentation_criteria : str | None

var signal_agent_segment_id : str

var signal_id : SignalId8 | SignalId9 | None

var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None

var signal_type : SignalAvailabilityType

var taxonomy : Taxonomy | None

var value_type : SignalValueType | None

class WholesaleFeedSignal (**data: Any)

Expand source code

class Signal(SignalListing):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description='Canonical signal reference for this wholesale signal. New events SHOULD use signal_ref.'
        ),
    ] = None
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older clients.',
        ),
    ] = None
    signal_agent_segment_id: Annotated[
        str,
        Field(description='Opaque activation handle returned by the signals agent.', min_length=1),
    ]
    name: Annotated[str, Field(description='Human-readable signal name', min_length=1)]
    description: Annotated[str, Field(description='Detailed signal description', min_length=1)]
    value_type: signal_value_type.SignalValueType | None = None
    categories: Annotated[list[str] | None, Field(min_length=1)] = None
    range: Range | None = None
    signal_type: signal_catalog_type.SignalAvailabilityType
    data_provider: Annotated[str | None, Field(min_length=1)] = None
    coverage_percentage: Annotated[
        StrictFloat | None,
        Field(
            deprecated=True,
            description='DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    coverage_forecast: Annotated[
        signal_coverage_forecast.SignalCoverageForecast | None,
        Field(
            description='Optional forecast-shaped signal availability guidance using the same wire shape as get_signals.signals[].coverage_forecast. When present, this is authoritative for signal-level discovery coverage.'
        ),
    ] = None
    deployments: Annotated[Sequence[deployment.Deployment], Field(min_length=1)]
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None, Field(min_length=1)
    ] = 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

• SignalListing
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var categories : list[str] | None

var coverage_forecast : SignalCoverageForecast | None

var coverage_percentage : float | None

var data_provider : str | None

var deployments : Sequence[Deployment1 | Deployment2]

var description : str

var model_config

var name : str

var pricing_options : list[VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11] | None

var range : Range | None

var signal_agent_segment_id : str

var signal_id : SignalId8 | SignalId9 | None

var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None

var signal_type : SignalAvailabilityType

var value_type : SignalValueType | None

Inherited members

• SignalListing:
  • model_dump
  • model_dump_json
  • model_summary

class SignalAvailabilityType (*args, **kwds)

Expand source code

class SignalAvailabilityType(StrEnum):
    marketplace = 'marketplace'
    custom = 'custom'
    owned = 'owned'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var custom

var marketplace

var owned

class SignalCatalogType (*args, **kwds)

Expand source code

class SignalAvailabilityType(StrEnum):
    marketplace = 'marketplace'
    custom = 'custom'
    owned = 'owned'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var custom

var marketplace

var owned

class SignalType (*args, **kwds)

Expand source code

class SignalAvailabilityType(StrEnum):
    marketplace = 'marketplace'
    custom = 'custom'
    owned = 'owned'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var custom

var marketplace

var owned

class SignalCoverageForecast (**data: Any)

Expand source code

class SignalCoverageForecast(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    points: Annotated[
        list[Point],
        Field(
            description='Coverage or availability points. Each point reuses the standard ForecastPoint shape, MUST include a signal dimension, and MUST include metrics.coverage_rate. Use metrics.impressions for count denominators and metrics.coverage_rate for the fraction of the declared scope represented by the point.',
            min_length=1,
        ),
    ]
    forecast_range_unit: Annotated[
        Literal['availability'],
        Field(
            description="How to interpret the points array. Signal coverage forecasts always use 'availability' because the points describe available inventory or population coverage, not spend curves or temporal pacing."
        ),
    ] = 'availability'
    method: Annotated[
        forecast_method.ForecastMethod,
        Field(description='Method used to produce this coverage forecast.'),
    ]
    scope: Annotated[
        Scope,
        Field(
            description='Explicit denominator for the coverage forecast. This identifies the inventory, product, account, or custom universe that coverage_rate values are relative to. Additional seller-specific qualifiers are allowed for scopes such as line item type, ad server, inventory class, country, or flight window.'
        ),
    ]
    bucket_semantics: Annotated[
        BucketSemantics,
        Field(
            description="'exclusive' means the returned signal-value buckets do not overlap with each other. 'overlapping' means one impression or user can appear in multiple returned buckets, so coverage_rate values may sum above 1.0. This field describes overlap among returned buckets; bucket_completeness declares whether the returned buckets cover the full denominator."
        ),
    ]
    bucket_completeness: Annotated[
        BucketCompleteness,
        Field(
            description="'complete' means the returned buckets cover the declared denominator. For complete + exclusive forecasts, count metrics and coverage_rate values can be treated as a full partition, subject to metric additivity rules. 'partial' means omitted denominator share represents undisclosed, other, or unsupported buckets; buyers MUST NOT infer totals by summing returned points."
        ),
    ]
    generated_at: Annotated[
        AwareDatetime | None, Field(description='When this coverage forecast was computed.')
    ] = None
    valid_until: Annotated[
        AwareDatetime | None, Field(description='When this coverage forecast expires.')
    ] = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var bucket_completeness : BucketCompleteness

var bucket_semantics : BucketSemantics

var ext : ExtensionObject | None

var forecast_range_unit : Literal['availability']

var generated_at : pydantic.types.AwareDatetime | None

var method : ForecastMethod

var model_config

var points : list[Point]

var scope : Scope

var valid_until : pydantic.types.AwareDatetime | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SignalDefinitionEnrichment (**data: Any)

Expand source code

class SignalDefinitionEnrichment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None,
        Field(description='Restricted attribute categories this signal touches.', min_length=1),
    ] = None
    demographic_predicate: Annotated[
        demographic_predicate_1.DemographicPredicate | None,
        Field(
            description="Projected authoritative demographic meaning for the signal. When projected from another provider, this MUST match the provider's definition exactly. Signal names alone never establish demographic semantics."
        ),
    ] = None
    policy_categories: Annotated[
        list[str] | None,
        Field(description='Policy categories this signal is sensitive for.', min_length=1),
    ] = None
    taxonomy: Annotated[
        Taxonomy | None,
        Field(
            description='Optional taxonomy metadata describing what this signal means in an external audience, content, retail-media, or provider-owned taxonomy.'
        ),
    ] = None
    segmentation_criteria: Annotated[str | None, Field(max_length=500)] = None
    criteria_url: AnyUrl | None = None
    data_sources: Annotated[list[DataSource] | None, Field(min_length=1)] = None
    methodology: Methodology | None = None
    audience_expansion: StrictBool | None = None
    device_expansion: StrictBool | None = None
    refresh_cadence: RefreshCadence | None = None
    lookback_window: RefreshCadence | None = None
    onboarder: Onboarder | None = None
    countries: Annotated[list[Country] | None, Field(min_length=1)] = None
    consent_basis: Annotated[
        list[consent_basis_1.ConsentBasis] | None,
        Field(
            description="Data provider's declared GDPR Article 6 lawful basis or consent basis for the underlying signal definition, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own processing basis for the provider-declared basis.",
            min_length=1,
        ),
    ] = None
    art9_basis: Annotated[
        Art9Basis | None,
        Field(
            description="Data provider's declared GDPR Article 9 basis for the underlying signal definition when special-category data is involved and Article 9 applies, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own Article 9 basis for the provider-declared basis."
        ),
    ] = None
    modeling: Modeling | None = None
    data_subject_rights: Annotated[
        DataSubjectRights | None,
        Field(
            description='Per-signal data-subject-rights routing. This is a contact/routing reference, not a machine-callable AdCP API.'
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='When this definition record was last updated. This indicates freshness of the definition record, not an attestation that the underlying data or model was refreshed at that time.'
        ),
    ] = None
    dts_compliant_version: str | None = 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

Class variables

var art9_basis : Art9Basis | None

var audience_expansion : bool | None

var consent_basis : list[ConsentBasis] | None

var countries : list[Country] | None

var criteria_url : pydantic.networks.AnyUrl | None

var data_sources : list[DataSource] | None

var data_subject_rights : DataSubjectRights | None

var demographic_predicate : DemographicPredicate | None

var device_expansion : bool | None

var dts_compliant_version : str | None

var last_updated : pydantic.types.AwareDatetime | None

var lookback_window : RefreshCadence | None

var methodology : Methodology | None

var model_config

var modeling : Modeling | None

var onboarder : Onboarder | None

var policy_categories : list[str] | None

var refresh_cadence : RefreshCadence | None

var restricted_attributes : list[RestrictedAttribute] | None

var segmentation_criteria : str | None

var taxonomy : Taxonomy | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SignalFilters (**data: Any)

Expand source code

class SignalFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catalog_types: Annotated[
        list[signal_catalog_type.SignalAvailabilityType] | None,
        Field(description='Filter by catalog type', min_length=1),
    ] = None
    data_providers: Annotated[
        list[str] | None, Field(description='Filter by specific data providers', min_length=1)
    ] = None
    max_cpm: Annotated[
        StrictFloat | None,
        Field(description="Maximum CPM filter. Applies only to signals with model='cpm'.", ge=0.0),
    ] = None
    max_percent: Annotated[
        StrictFloat | None,
        Field(
            description='Maximum percent-of-media rate filter. Signals where all percent_of_media pricing options exceed this value are excluded. Does not account for max_cpm caps.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    min_coverage_percentage: Annotated[
        StrictFloat | None, Field(description='Minimum coverage requirement', ge=0.0, le=100.0)
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(
            description='Vendor-namespaced extension parameters for seller- or platform-specific signal filter criteria not covered by standard fields. Keys MUST be namespaced under a vendor or platform key (e.g., ext.gam, ext.platform_x). Sellers MUST treat all values as untrusted buyer input; avoid unbounded logging or labels, and do not interpolate values into caller-visible error strings, LLM prompts, SQL queries, or system commands without sanitization. Persistent use of an extension key across multiple buyers is a signal to propose standardization.'
        ),
    ] = 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

Class variables

var catalog_types : list[SignalAvailabilityType] | None

var data_providers : list[str] | None

var ext : ExtensionObject | None

var max_cpm : float | None

var max_percent : float | None

var min_coverage_percentage : float | None

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SignalListing (**data: Any)

Expand source code

class SignalListing(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(
            description="Canonical signal reference. Use scope 'product' for a product-local signal defined by this listing; use scope 'data_provider' with data_provider_domain for a signal defined in a data provider's published adagents.json signals[]; use scope 'signal_source' with signal_source_url for a source-native signal."
        ),
    ] = None
    signal_id: Annotated[
        signal_id_1.SignalId | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_ref instead. Legacy SignalId retained for compatibility with older Signals Protocol clients.',
        ),
    ] = None
    name: Annotated[
        str | None,
        Field(
            description="Human-readable signal name. Required when signal_ref.scope is 'product'. For data_provider and signal_source refs, this is optional contextual display text; the referenced definition or source remains authoritative."
        ),
    ] = None
    description: Annotated[
        str | None,
        Field(
            description='Detailed signal description. For data_provider and signal_source refs, this is optional contextual display text and MUST NOT replace the referenced definition.'
        ),
    ] = None
    methodology_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional link to published methodology, media-kit, or data documentation. For data_provider and signal_source refs, this SHOULD match or supplement the referenced definition.'
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description='When this listing record was last updated. This indicates freshness of the listing record, not an attestation that the underlying data or model was refreshed at that time.'
        ),
    ] = None
    value_type: Annotated[
        signal_value_type.SignalValueType | None,
        Field(
            description="The data type of this signal's values. Required when signal_ref.scope is 'product'."
        ),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Valid values for categorical signals. Present when value_type is 'categorical'.",
            min_length=1,
        ),
    ] = None
    range: Annotated[
        Range | None,
        Field(description="Valid range for numeric signals. Present when value_type is 'numeric'."),
    ] = None
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None,
        Field(
            description='Restricted attribute categories this listing touches. Required with demographic_predicate and must include age. For referenced provider/source signals, any projected values must match the authoritative definition.',
            min_length=1,
        ),
    ] = None
    demographic_predicate: Annotated[
        demographic_predicate_1.DemographicPredicate | None,
        Field(
            description='Machine-readable demographic meaning. For product-local signals this listing is authoritative; for data-provider and signal-source refs, any projected value MUST match the referenced authoritative definition. Signal names alone never establish demographic semantics.'
        ),
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> SignalListing:
        # ``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 (('signal_ref',), ('signal_id',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'SignalListing requires at least one of these field groups: signal_ref | signal_id'
        )

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

• ProductSignalTargetingOption
• Signal

Class variables

var categories : list[str] | None

var demographic_predicate : DemographicPredicate | None

var description : str | None

var last_updated : pydantic.types.AwareDatetime | None

var methodology_url : pydantic.networks.AnyUrl | None

var model_config

var name : str | None

var range : Range | None

var restricted_attributes : list[RestrictedAttribute] | None

var signal_id : SignalId8 | SignalId9 | None

var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None

var value_type : SignalValueType | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SignalPricingOption (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class SignalPricingOption(RootModel[vendor_pricing_option.VendorPricingOption]):
    root: Annotated[
        vendor_pricing_option.VendorPricingOption,
        Field(
            description='Deprecated — use vendor-pricing-option.json for new implementations. This alias is retained for backward compatibility.',
            title='Signal Pricing Option',
        ),
    ]

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

-----=

root

The root object of the model.

__pydantic_root_model__

Whether the model is a RootModel.

__pydantic_private__

Private fields in the model.

__pydantic_extra__

Extra fields in the model.

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.root_model.RootModel[Annotated[Union[VendorPricingOption7, VendorPricingOption8, VendorPricingOption9, VendorPricingOption10, VendorPricingOption11], FieldInfo(annotation=NoneType, required=True, title='Vendor Pricing Option', description='A pricing option offered by a vendor agent (signals, creative, governance). Combines pricing_option_id with the pricing model fields. Pass pricing_option_id in report_usage for billing verification. All vendor discovery responses return pricing_options as an array — vendors may offer multiple options (volume tiers, context-specific rates, different models per product line).')]]
• pydantic.root_model.RootModel
• pydantic.main.BaseModel
• typing.Generic

Class variables

var model_config

var root : VendorPricingOption7 | VendorPricingOption8 | VendorPricingOption9 | VendorPricingOption10 | VendorPricingOption11

class SignalTargetingRules (**data: Any)

Expand source code

class SignalTargetingRules(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    resolution_model: Annotated[
        ResolutionModel | None,
        Field(
            description="How selected signal_targeting_options are resolved against the product's inventory. 'direct_targeting' means selected signals are applied as targeting predicates to the package inventory. 'seller_planned' means selected signals are planning inputs that the seller resolves against product-specific inventory, timing, availability, reach, or pacing constraints; buyers SHOULD NOT attempt to decompose the signal selection into lower-level inventory or schedule decisions. Use 'seller_planned' for products such as linear broadcast schedules where the audience definition may be portable but the audience-to-avails plan is seller-resolved."
        ),
    ] = ResolutionModel.direct_targeting
    selection_mode: Annotated[
        SelectionMode | None,
        Field(
            description="Default selection behavior for selectable signals on this product. 'optional' means the buyer may select zero or more signals. 'required' means the buyer must select at least min_selected_signals, or 1 when min_selected_signals is omitted. 'fixed' means the seller applies the default_selected signals and the buyer cannot add or remove them; buyers SHOULD render those entries as read-only and sellers MUST echo them in package targeting_overlay.signal_targeting_groups. Use selection_group_rules for product-scoped products that need different behavior for different groups, such as fixed suppressions plus a required include tier."
        ),
    ] = SelectionMode.optional
    min_selected_signals: Annotated[
        SchemaInt | None,
        Field(
            description="Minimum number of signals the buyer must select when selection_mode is 'required'. If selection_mode is 'required' and this field is omitted, sellers MUST treat the minimum as 1. Defaults to 0 for optional selection.",
            ge=0,
        ),
    ] = None
    max_selected_signals: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of signals the buyer may select for a package. Omit when there is no declared limit beyond the available options.',
            ge=1,
        ),
    ] = None
    max_selected_per_group: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of signal_targeting_options the buyer may select from the same ProductSignalTargetingOption.selection_group. Use 1 for mutually exclusive alternatives within each option group. This limit applies to product option grouping, not to the number of child groups in packages[].targeting_overlay.signal_targeting_groups.',
            ge=1,
        ),
    ] = None
    max_signal_targeting_groups: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of child groups allowed in packages[].targeting_overlay.signal_targeting_groups.groups. Omit when the seller has no declared limit beyond product terms.',
            ge=1,
        ),
    ] = None
    max_signals_per_targeting_group: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of signals allowed in each packages[].targeting_overlay.signal_targeting_groups.groups[].signals array. Omit when the seller has no declared limit beyond product terms.',
            ge=1,
        ),
    ] = None
    selection_group_rules: Annotated[
        list[signal_selection_group_rule.SignalSelectionGroupRule] | None,
        Field(
            description='Optional product-scoped overrides for specific ProductSignalTargetingOption.selection_group values. Use this when one product has mixed behavior, such as fixed seller-applied suppressions, a required pick-one include tier, optional buyer-selected exclusions, or heterogeneous targeting planes that must be represented as separate ANDed clauses. Rules apply only to options whose selection_group matches. When selection_group_rules are present, each packages[].targeting_overlay.signal_targeting_groups child group MUST contain signals from exactly one selection_group and one targeting_mode, and buyers MUST send at most one child group for each (selection_group, targeting_mode) pair. Sellers MUST reject duplicate, mixed, or collapsed groups that combine distinct selection_group_rules into the same child group.',
            min_length=1,
        ),
    ] = 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

Class variables

var max_selected_per_group : int | None

var max_selected_signals : int | None

var max_signal_targeting_groups : int | None

var max_signals_per_targeting_group : int | None

var min_selected_signals : int | None

var model_config

var resolution_model : ResolutionModel | None

var selection_group_rules : list[SignalSelectionGroupRule] | None

var selection_mode : SelectionMode | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Snapshot (**data: Any)

Expand source code

class Snapshot(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    as_of: Annotated[
        AwareDatetime, Field(description='When this snapshot was captured by the platform')
    ]
    staleness_seconds: Annotated[
        SchemaInt,
        Field(
            description='Maximum age of this data in seconds. For example, 3600 means the data may be up to 1 hour old.',
            ge=0,
        ),
    ]
    impressions: Annotated[
        SchemaInt,
        Field(
            description='Lifetime impressions across all assignments. Not scoped to any date range.',
            ge=0,
        ),
    ]
    last_served: Annotated[
        AwareDatetime | None,
        Field(
            description='Last time this creative served an impression. Absent when the creative has never served.'
        ),
    ] = 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

Class variables

var as_of : pydantic.types.AwareDatetime

var impressions : int

var last_served : pydantic.types.AwareDatetime | None

var model_config

var staleness_seconds : int

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SnapshotUnavailableReason (*args, **kwds)

Expand source code

class SnapshotUnavailableReason(StrEnum):
    SNAPSHOT_UNSUPPORTED = 'SNAPSHOT_UNSUPPORTED'
    SNAPSHOT_TEMPORARILY_UNAVAILABLE = 'SNAPSHOT_TEMPORARILY_UNAVAILABLE'
    SNAPSHOT_PERMISSION_DENIED = 'SNAPSHOT_PERMISSION_DENIED'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var SNAPSHOT_PERMISSION_DENIED

var SNAPSHOT_TEMPORARILY_UNAVAILABLE

var SNAPSHOT_UNSUPPORTED

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.

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

Class variables

var direction : SortDirection | None

var field : Field1 | None

var model_config

class ListCreativesSort (**data: Any)

Expand source code

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

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

Class variables

var direction : SortDirection | None

var field : CreativeSortField | None

var model_config

class TasksListSort (**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.

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

Class variables

var direction : SortDirection | None

var field : Field1 | None

var model_config

class ListTasksSort (**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.

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

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.

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

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 Source (*args, **kwds)

Expand source code

class Source(StrEnum):
    producer = 'producer'
    sdk = 'sdk'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var producer

var sdk

class StaleResponseDetails (**data: Any)

Expand source code

class StaleResponseDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    served_from_cache: Annotated[
        Literal[True],
        Field(
            description='Always true for STALE_RESPONSE. Acts as a positive shape sentinel so consumers can validate the details payload matches the code.'
        ),
    ]
    cache_age_seconds: Annotated[
        SchemaInt,
        Field(
            description='Age of the cached payload in seconds at the time of the response. Informational — buyer agents MAY use this to decide whether to immediately retry for fresh data or accept the cached value.',
            ge=0,
        ),
    ]
    freshness_target_seconds: Annotated[
        SchemaInt | None,
        Field(
            description="The seller's freshness target for this surface, in seconds. `cache_age_seconds - freshness_target_seconds` is how far beyond target the cached entry is. Optional — sellers MAY omit when no public freshness contract is declared.",
            ge=0,
        ),
    ] = None
    upstream: Annotated[
        Upstream | None,
        Field(
            description='Identifies the upstream or sub-agent whose fetch failed and triggered cache fallback. When N upstreams are stale, the seller emits N separate STALE_RESPONSE entries (one per upstream) rather than aggregating into a single entry — mirrors the per-asset advisory precedent set by PIXEL_TRACKER_LOSSY_DOWNGRADE.'
        ),
    ] = None
    original_error: Annotated[
        OriginalError | None,
        Field(
            description='Minimal subset of the underlying failure that triggered cache fallback. Sellers MUST NOT include internal stack traces, credentials, or connection strings.'
        ),
    ] = 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

Class variables

var cache_age_seconds : int

var freshness_target_seconds : int | None

var model_config

var original_error : OriginalError | None

var served_from_cache : Literal[True]

var upstream : Upstream | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Status (*args, **kwds)

Expand source code

class Status(StrEnum):
    pending_creatives = 'pending_creatives'
    pending_start = 'pending_start'
    pending = 'pending'
    active = 'active'
    paused = 'paused'
    completed = 'completed'
    rejected = 'rejected'
    canceled = 'canceled'
    failed = 'failed'
    reporting_delayed = 'reporting_delayed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var active

var canceled

var completed

var failed

var paused

var pending

var pending_creatives

var pending_start

var rejected

var reporting_delayed

class MediaBuyDeliveryStatus (*args, **kwds)

Expand source code

class Status(StrEnum):
    pending_creatives = 'pending_creatives'
    pending_start = 'pending_start'
    pending = 'pending'
    active = 'active'
    paused = 'paused'
    completed = 'completed'
    rejected = 'rejected'
    canceled = 'canceled'
    failed = 'failed'
    reporting_delayed = 'reporting_delayed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var active

var canceled

var completed

var failed

var paused

var pending

var pending_creatives

var pending_start

var rejected

var reporting_delayed

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.

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

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 V1CanonicalStructural (**data: Any)

Expand source code

class Structural(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_types: Annotated[
        list[str] | None,
        Field(
            description="Set of asset_type values that must appear in the format's slots (in any order, any count)."
        ),
    ] = None
    vast_versions: Annotated[
        list[str] | None,
        Field(description="VAST version constraints. Strings like '>=4.0', '4.x', '4.2'."),
    ] = None
    daast_versions: list[str] | None = None
    dimensions: Dimensions | None = 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

Class variables

var asset_types : list[str] | None

var daast_versions : list[str] | None

var dimensions : Dimensions | None

var model_config

var vast_versions : list[str] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SyncAccountsRequest (**data: Any)

Expand source code

class SyncAccountsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Natural per-account upsert keys handle resource-level dedup, but the envelope triggers onboarding webhooks, billing setup, and audit events — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    accounts: Annotated[
        list[Accounts | Accounts1],
        Field(
            description='Per-account sync entries. Each entry uses one of two key shapes: the `account` field (AccountRef) for settings-update mode, or the flat `brand` + `operator` + `billing` trio for provisioning mode. An operator_identity settings update MUST carry the latest account revision.',
            max_length=1000,
        ),
    ]
    delete_missing: Annotated[
        StrictBool | None,
        Field(
            description='When true, accounts previously synced by this agent but not included in this request will be deactivated. Scoped to the authenticated agent — does not affect accounts managed by other agents. Use with caution.'
        ),
    ] = False
    dry_run: Annotated[
        StrictBool | None,
        Field(
            description='When true, preview what would change without applying. Returns what would be created/updated/deactivated.'
        ),
    ] = False
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Webhook for async notifications when account status changes (e.g., pending_approval transitions to active).'
        ),
    ] = 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 accounts : list[Accounts | Accounts1]

var context : ContextObject | None

var delete_missing : bool | None

var dry_run : bool | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var push_notification_config : PushNotificationConfig | 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 SyncAccountsResponse1 (**data: Any)

Expand source code

class SyncAccountsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    dry_run: bool | None = None
    accounts: list[Account]
    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.

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 accounts : list[Account]

var context : ContextObject | None

var dry_run : bool | None

var ext : ExtensionObject | None

var model_config

class SyncAccountsSuccessResponse (**data: Any)

Expand source code

class SyncAccountsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    dry_run: bool | None = None
    accounts: list[Account]
    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.

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 accounts : list[Account]

var context : ContextObject | None

var dry_run : bool | None

var ext : ExtensionObject | None

var model_config

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 SyncAccountsErrorResponse (**data: Any)

Expand source code

class SyncAccountsResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 SyncAgentNotificationConfigsRequest (**data: Any)

Expand source code

class SyncAgentNotificationConfigsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description="Client-generated unique key for at-most-once execution. The task mutates the authenticated caller's persistent agent-level subscriber set and may trigger endpoint proof-of-control challenges, so retries MUST reuse the same key and same payload. Use a fresh UUID v4 for each logical replacement.",
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    notification_configs: Annotated[
        list[agent_notification_config.AgentNotificationConfig],
        Field(
            description="Complete desired set of agent-level notification subscribers for the authenticated caller or registry identity. Omit is invalid; send an empty array to remove every subscriber owned by this caller. Each entry registers a URL, the agent-level event types the subscriber wants, and optional legacy auth. Duplicate `subscriber_id` values are rejected within this caller-scoped array. If any entry fails validation or activation proof, the seller rejects the replacement and leaves this caller's previous set unchanged.",
            max_length=16,
        ),
    ]
    dry_run: Annotated[
        StrictBool | None,
        Field(
            description='When true, validate the replacement and report what would be persisted without applying it or sending endpoint proof-of-control 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.

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 dry_run : bool | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var notification_configs : list[AgentNotificationConfig]

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 SyncAgentNotificationConfigsResponse (**data: Any)

Expand source code

class SyncAgentNotificationConfigsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    dry_run: Annotated[
        StrictBool | None,
        Field(description='Whether this was a dry run and no persisted subscriber set changed.'),
    ] = None
    action: Annotated[
        Action,
        Field(
            description="Outcome for the caller-scoped replacement. `updated`: a new subscriber set was persisted for this caller. `unchanged`: the submitted set matched this caller's current set. `cleared`: the submitted empty array removed all subscribers owned by this caller. `failed`: validation, authorization, or endpoint proof failed; the prior caller-scoped set remains unchanged and `errors[]` explains why."
        ),
    ]
    notification_configs: Annotated[
        list[agent_notification_config.AgentNotificationConfig] | None,
        Field(
            description='Current persisted agent-level notification subscribers owned by the authenticated caller after the request. Entries are keyed by `subscriber_id`; `authentication.credentials` is omitted on every entry because credentials are write-only. Present on successful actions and MAY be present on `failed` responses to show the unchanged prior caller-scoped set.',
            max_length=16,
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Operation-level errors and warnings. Present when action is `failed`, and MAY include non-fatal warnings on successful responses.'
        ),
    ] = 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.

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 action : Action

var context : ContextObject | None

var dry_run : bool | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var model_config

var notification_configs : list[AgentNotificationConfig] | 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 SyncAudiencesRequest (**data: Any)

Expand source code

class SyncAudiencesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `audience_id` gives resource-level dedup per audience, but the sync envelope emits audit events and may trigger downstream refreshes — this key prevents those side effects from firing twice on retry. Also serves as a request ID on discovery-only calls (when `audiences` is omitted). MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    account: Annotated[
        account_ref.AccountReference, Field(description='Account to manage audiences for.')
    ]
    audiences: Annotated[
        list[Audience] | None,
        Field(
            description='Audiences to sync (create or update). When omitted, the call is discovery-only and returns all existing audiences on the account without modification.',
            min_length=1,
        ),
    ] = None
    delete_missing: Annotated[
        StrictBool | None,
        Field(
            description='When true, buyer-managed audiences on the account not included in this sync will be removed. Does not affect seller-managed audiences. Do not combine with an omitted audiences array or all buyer-managed audiences will be deleted.'
        ),
    ] = 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.

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 account : AccountReference1 | AccountReference2

var audiences : list[Audience] | None

var context : ContextObject | None

var delete_missing : bool | 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 SyncAudiencesResponse1 (**data: Any)

Expand source code

class SyncAudiencesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    audiences: list[Audience]
    sandbox: bool | None = 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.

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 audiences : list[Audience]

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var sandbox : bool | None

class SyncAudiencesSuccessResponse (**data: Any)

Expand source code

class SyncAudiencesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    audiences: list[Audience]
    sandbox: bool | None = 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.

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 audiences : list[Audience]

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var sandbox : bool | 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 SyncAudiencesErrorResponse (**data: Any)

Expand source code

class SyncAudiencesResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 SyncAudiencesSubmittedResponse (**data: Any)

Expand source code

class SyncAudiencesResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

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 SyncCatalogsInputRequired (**data: Any)

Expand source code

class SyncCatalogsInputRequired(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    reason: Annotated[
        Reason | None,
        Field(
            description='Reason code indicating why buyer input is needed. APPROVAL_REQUIRED: platform requires explicit approval before activating the catalog. FEED_VALIDATION: feed URL returned unexpected format or schema errors. ITEM_REVIEW: platform flagged items for manual review. FEED_ACCESS: platform cannot access the feed URL (authentication, CORS, etc.).'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var reason : Reason | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SyncCatalogsRequest (**data: Any)

Expand source code

class SyncCatalogsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Catalog upserts and item availability transitions can emit audit events or trigger platform work — this key prevents those side effects from firing twice on retry. Also serves as a request ID on discovery-only calls. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    account: Annotated[
        account_ref.AccountReference,
        Field(description='Seller account containing these buyer-managed catalogs.'),
    ]
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description='Array of catalog feeds to sync (create or update). When omitted together with item_availability_updates and item_availability_queries, the call is discovery-only and returns all existing catalogs on the account without modification.',
            max_length=50,
            min_length=1,
        ),
    ] = None
    item_availability_updates: Annotated[
        list[catalog_item_availability_update.CatalogItemAvailabilityUpdate] | None,
        Field(
            description='Immediate suppress or restore operations for items in buyer-managed catalogs. Sellers declaring media_buy.features.catalog_item_availability_updates MUST process these updates synchronously and MUST NOT silently ignore them or return a submitted task. A seller that does not declare the capability MUST reject the request with UNSUPPORTED_FEATURE before lookup or mutation and MUST NOT interpret it as discovery. The combined number of item_availability_updates and item_availability_queries MUST NOT exceed 1,000; excess entries are an operation-level INVALID_REQUEST before lookup or mutation. Each (catalog_id, catalog_generation, item_id) tuple MUST appear at most once in updates; a duplicate is an operation-level INVALID_REQUEST before mutation in every validation mode. For mixed catalog/update requests, the seller MUST validate and stage the entire request against the post-upsert candidate state, then commit catalog and availability changes atomically. It MUST reject before any mutation if synchronous atomic commit is unavailable. A successful suppress acknowledgement means the seller MUST stop selecting or rendering the item and every cached or pre-generated creative it materialized from the item. Seller-internal generation lineage MUST retain resolved_account_id, catalog_id, catalog_generation, and item_id. If the seller cannot enforce that guarantee, it MUST return a failed per-item result. Suppression persists across scheduled feed fetches and catalog upserts until explicit restore, expires_at, or deletion of the containing catalog. Restore removes only an existing buyer-authored overlay or tombstone in the same catalog generation and cannot override seller rejection, withdrawal, policy, rights, or inventory controls. A restore for an absent item without such prior state fails with REFERENCE_NOT_FOUND.',
            max_length=1000,
            min_length=1,
        ),
    ] = None
    item_availability_queries: Annotated[
        list[catalog_item_availability_ref.CatalogItemAvailabilityReference] | None,
        Field(
            description='Read current buyer-authored availability state. Queries require media_buy.features.catalog_item_availability_updates; a seller that does not declare it rejects with UNSUPPORTED_FEATURE before lookup. Any request containing queries is synchronous. In a mixed request the seller validates and stages catalog upserts and availability updates first, evaluates queries against that post-upsert/post-update candidate state, and atomically commits the staged mutations before returning those query results. If the mixed work cannot commit synchronously, it rejects before mutation. The seller returns exactly one item_availability_states entry per query in the same order and echoes request_index and the complete identity. Unknown, inaccessible, stale-generation, and unauthorized references use the normalized REFERENCE_NOT_FOUND shape described by validation_mode. Use a fresh idempotency_key for a current read; a replayed response is a historical snapshot.',
            max_length=1000,
            min_length=1,
        ),
    ] = None
    catalog_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional filter to limit sync scope to specific catalog IDs. When provided, only these catalogs will be created/updated. Other catalogs on the account are unaffected.',
            max_length=50,
            min_length=1,
        ),
    ] = None
    delete_missing: Annotated[
        StrictBool | None,
        Field(
            description='When true, buyer-managed catalogs on the account not included in this sync will be removed. Does not affect seller-managed catalogs. Requires catalogs; item_availability_updates alone cannot define deletion scope.'
        ),
    ] = False
    dry_run: Annotated[
        StrictBool | None,
        Field(
            description='When true, preview catalog create, update, and delete changes without applying them. MUST NOT be combined with item_availability_updates.'
        ),
    ] = False
    validation_mode: Annotated[
        validation_mode_1.ValidationMode | None,
        Field(
            description="Validation strictness for semantically valid-looking catalog and item entries. In strict mode (default), an unknown, inaccessible, unauthorized, or stale-generation catalog/item reference, a known seller-managed catalog, a stale expected_overlay_revision, or another per-entry error fails the entire operation before any catalog or availability mutation. In lenient mode, the seller returns a positionally matched failed result for each such item entry and processes the remaining valid entries. Unknown, inaccessible, unauthorized, and stale-generation references MUST be observationally equivalent: code REFERENCE_NOT_FOUND, message exactly 'Catalog item not found', recovery 'correctable', and no field, suggestion, retry_after, issues, details, or resource metadata. Authorization and lookup MUST use the same externally observable failure path and SHOULD avoid materially distinguishable timing. A known seller-managed catalog may use INVALID_REQUEST only after catalog access is authorized. Request-schema failures, duplicate identity tuples, unsupported capability, batch-limit excess, dry_run conflicts, and mixed requests that cannot commit synchronously and atomically are operation-level failures before lookup or mutation in both modes. A stale revision uses CONFLICT without mutation."
        ),
    ] = validation_mode_1.ValidationMode.strict
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async sync notifications. Publisher will send webhook when sync completes if operation takes longer than immediate response time (common for large feeds requiring platform review).'
        ),
    ] = 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 account : AccountReference1 | AccountReference2

var catalog_ids : list[str] | None

var catalogs : list[Catalog] | None

var context : ContextObject | None

var delete_missing : bool | None

var dry_run : bool | None

var ext : ExtensionObject | None

var idempotency_key : str

var item_availability_queries : list[CatalogItemAvailabilityReference] | None

var item_availability_updates : list[CatalogItemAvailabilityUpdate] | None

var model_config

var push_notification_config : PushNotificationConfig | None

var validation_mode : ValidationMode | 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 SyncCatalogsResponse1 (**data: Any)

Expand source code

class SyncCatalogsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    status: Literal['completed'] | None = None
    dry_run: bool | None = None
    catalogs: list[Catalog]
    item_availability_updates: Annotated[list[catalog_item_availability_update_result_1.CatalogItemAvailabilityUpdateResult], Field(min_length=1, max_length=1000)] | None = None
    item_availability_states: Annotated[list[catalog_item_availability_state_1.CatalogItemAvailabilityState], Field(min_length=1, max_length=1000)] | None = None
    sandbox: bool | None = 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.

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 catalogs : list[Catalog]

var context : ContextObject | None

var dry_run : bool | None

var ext : ExtensionObject | None

var item_availability_states : list[CatalogItemAvailabilityState] | None

var item_availability_updates : list[CatalogItemAvailabilityUpdateResult] | None

var model_config

var sandbox : bool | None

var status : Literal['completed'] | None

class SyncCatalogsSuccessResponse (**data: Any)

Expand source code

class SyncCatalogsResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    status: Literal['completed'] | None = None
    dry_run: bool | None = None
    catalogs: list[Catalog]
    item_availability_updates: Annotated[list[catalog_item_availability_update_result_1.CatalogItemAvailabilityUpdateResult], Field(min_length=1, max_length=1000)] | None = None
    item_availability_states: Annotated[list[catalog_item_availability_state_1.CatalogItemAvailabilityState], Field(min_length=1, max_length=1000)] | None = None
    sandbox: bool | None = 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.

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 catalogs : list[Catalog]

var context : ContextObject | None

var dry_run : bool | None

var ext : ExtensionObject | None

var item_availability_states : list[CatalogItemAvailabilityState] | None

var item_availability_updates : list[CatalogItemAvailabilityUpdateResult] | None

var model_config

var sandbox : bool | None

var status : Literal['completed'] | 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 SyncCatalogsErrorResponse (**data: Any)

Expand source code

class SyncCatalogsResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[Any], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[typing.Any]

var ext : ExtensionObject | None

var model_config

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 SyncCatalogsSubmittedResponse (**data: Any)

Expand source code

class SyncCatalogsResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

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 SyncCatalogsSubmitted (**data: Any)

Expand source code

class SyncCatalogsSubmitted(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['submitted'],
        Field(
            description='Task-level status literal. Discriminates this async envelope from the synchronous success shape, whose catalogs array is issued in-line. See task-status.json for the full task-status enum.'
        ),
    ] = 'submitted'
    task_id: Annotated[
        str,
        Field(
            description='Task handle the buyer uses with get_task_status (or the legacy AdCP tasks/get alias), and that the seller references on push-notification callbacks. This AdCP application-layer handle remains the snake_case task_id in every transport payload and is distinct from any transport-native A2A Task id.'
        ),
    ]
    message: Annotated[
        str | None,
        Field(
            description="Optional human-readable explanation of why the task is submitted — e.g., 'Catalog ingestion queued; typical turnaround 5–15 minutes.' Plain text only. Buyers MUST treat this as untrusted seller input: escape before rendering to HTML UIs, and sanitize or isolate before passing to an LLM prompt context — a hostile seller may inject prompt-injection payloads aimed at the buyer's agent.",
            max_length=2000,
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories, governance observations). Terminal failures belong in the error branch, not here.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal['submitted']

var task_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SyncCatalogsWorking (**data: Any)

Expand source code

class SyncCatalogsWorking(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    percentage: Annotated[
        StrictFloat | None, Field(description='Completion percentage (0-100)', ge=0.0, le=100.0)
    ] = None
    current_step: Annotated[
        str | None,
        Field(
            description="Current step or phase of the operation (e.g., 'Fetching product feed', 'Validating items', 'Platform review')"
        ),
    ] = None
    total_steps: Annotated[
        SchemaInt | None, Field(description='Total number of steps in the operation', ge=1)
    ] = None
    step_number: Annotated[SchemaInt | None, Field(description='Current step number', ge=1)] = None
    catalogs_processed: Annotated[
        SchemaInt | None, Field(description='Number of catalogs processed so far', ge=0)
    ] = None
    catalogs_total: Annotated[
        SchemaInt | None, Field(description='Total number of catalogs to process', ge=0)
    ] = None
    items_processed: Annotated[
        SchemaInt | None,
        Field(description='Total number of catalog items processed across all catalogs', ge=0),
    ] = None
    items_total: Annotated[
        SchemaInt | None,
        Field(description='Total number of catalog items to process across all catalogs', ge=0),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var catalogs_processed : int | None

var catalogs_total : int | None

var context : ContextObject | None

var current_step : str | None

var ext : ExtensionObject | None

var items_processed : int | None

var items_total : int | None

var model_config

var percentage : float | None

var step_number : int | None

var total_steps : int | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class SyncCreativesRequest (**data: Any)

Expand source code

class SyncCreativesRequest(_LegacySyncCreativesRequest, CanonicalBoundaryModel):
    """Canonical creative sync request; creatives are canonical assets."""

    creatives: list[CreativeAsset] = Field(min_length=1)  # type: ignore[assignment]

Canonical creative sync request; creatives are canonical assets.

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

• SyncCreativesRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var creatives : list[CreativeAsset]

var model_config

class LegacySyncCreativesRequest (**data: Any)

Expand source code

class SyncCreativesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference, Field(description='Account that owns these creatives.')
    ]
    creatives: Annotated[
        list[Creative] | None,
        Field(
            description='Array of creative assets to sync (create or update)',
            max_length=100,
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional filter to limit sync scope to specific creative IDs. When provided, only these creatives will be created/updated. Other creatives in the library are unaffected. Useful for partial updates and error recovery.',
            max_length=100,
            min_length=1,
        ),
    ] = None
    assignments: Annotated[
        list[Assignment] | None,
        Field(
            deprecated=True,
            description='Deprecated additive assignment shorthand. Each entry upserts one creative-to-package assignment. Use assignment_operations for explicit assign, unassign, and replace semantics. Standalone creative agents that do not manage media buys ignore this field.',
            min_length=1,
        ),
    ] = None
    assignment_operations: Annotated[
        list[AssignmentOperations] | None,
        Field(
            description='Explicit, ordered assignment mutations. These operations may be sent without creatives to traffic existing creative IDs independently from MediaBuy commercial control. The entire request is atomic under idempotency_key and therefore requires strict validation; lenient partial processing is not permitted.',
            max_length=500,
            min_length=1,
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated idempotency key for safe retries. If a sync fails without a response, resending with the same idempotency_key guarantees at-most-once execution. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    delete_missing: Annotated[
        StrictBool | None,
        Field(
            description='When true, creatives not included in this sync will be archived. Use with caution for full library replacement. Invalid when creative_ids is provided — delete_missing applies to the entire library scope, not a filtered subset.'
        ),
    ] = False
    dry_run: Annotated[
        StrictBool | None,
        Field(
            description="When true, rehearse this sync_creatives operation without applying it. Validates the actual trafficking request in the seller's current context, including library upsert semantics, creative IDs, assignments, account-scoped gates, and seller policies, then returns what would be created/updated/deleted. This is distinct from validate_input, which only validates manifest structure against canonical/product format targets."
        ),
    ] = False
    validation_mode: Annotated[
        validation_mode_1.ValidationMode | None,
        Field(
            description="Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid creatives and reports errors."
        ),
    ] = validation_mode_1.ValidationMode.strict
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async sync notifications. The agent will send a webhook when sync completes if the operation takes longer than immediate response time (typically for large bulk operations or manual approval/HITL).'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> SyncCreativesRequest:
        # ``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 (('creatives',), ('assignments',), ('assignment_operations',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'SyncCreativesRequest requires at least one of these field groups: creatives | assignments | assignment_operations'
        )

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

Subclasses

• SyncCreativesRequest

Class variables

var account : AccountReference1 | AccountReference2

var assignment_operations : list[AssignmentOperations1 | AssignmentOperations2 | AssignmentOperations3] | None

var assignments : list[Assignment] | None

var context : ContextObject | None

var creative_ids : list[str] | None

var creatives : list[Creative] | None

var delete_missing : bool | None

var dry_run : bool | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var push_notification_config : PushNotificationConfig | None

var validation_mode : ValidationMode | 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 SyncCreativesResponse1 (**data: Any)

Expand source code

class SyncCreativesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    dry_run: bool | None = None
    creatives: list[Creative]
    sandbox: bool | None = 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.

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 context : ContextObject | None

var creatives : list[Creative]

var dry_run : bool | None

var ext : ExtensionObject | None

var model_config

var sandbox : bool | None

class SyncCreativesSuccessResponse (**data: Any)

Expand source code

class SyncCreativesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    dry_run: bool | None = None
    creatives: list[Creative]
    sandbox: bool | None = 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.

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 context : ContextObject | None

var creatives : list[Creative]

var dry_run : bool | None

var ext : ExtensionObject | None

var model_config

var sandbox : bool | 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 SyncCreativesErrorResponse (**data: Any)

Expand source code

class SyncCreativesResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 SyncCreativesResponse3 (**data: Any)

Expand source code

class SyncCreativesResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

class SyncCreativesSubmittedResponse (**data: Any)

Expand source code

class SyncCreativesResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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 context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

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 SyncEventSourcesRequest (**data: Any)

Expand source code

class SyncEventSourcesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `event_source_id` gives resource-level dedup per source, but the sync envelope emits audit events and can trigger downstream pixel provisioning — this key prevents those side effects from firing twice on retry. Also serves as a request ID on discovery-only calls (when `event_sources` is omitted). MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    account: Annotated[
        account_ref.AccountReference, Field(description='Account to configure event sources for.')
    ]
    event_sources: Annotated[
        list[EventSource] | None,
        Field(
            description='Event sources to sync (create or update). When omitted, the call is discovery-only and returns all existing event sources on the account without modification.',
            min_length=1,
        ),
    ] = None
    delete_missing: Annotated[
        StrictBool | None,
        Field(description='When true, event sources not included in this sync will be removed'),
    ] = 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.

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 account : AccountReference1 | AccountReference2

var context : ContextObject | None

var delete_missing : bool | None

var event_sources : list[EventSource] | 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 SyncEventSourcesResponse1 (**data: Any)

Expand source code

class SyncEventSourcesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    event_sources: list[EventSource]
    sandbox: bool | None = 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.

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 context : ContextObject | None

var event_sources : list[EventSource]

var ext : ExtensionObject | None

var model_config

var sandbox : bool | None

class SyncEventSourcesSuccessResponse (**data: Any)

Expand source code

class SyncEventSourcesResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    event_sources: list[EventSource]
    sandbox: bool | None = 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.

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 context : ContextObject | None

var event_sources : list[EventSource]

var ext : ExtensionObject | None

var model_config

var sandbox : bool | 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 SyncEventSourcesErrorResponse (**data: Any)

Expand source code

class SyncEventSourcesResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 SyncGovernanceRequest (**data: Any)

Expand source code

class SyncGovernanceRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `account` gives resource-level dedup, but governance changes emit audit events and can trigger reapproval flows — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    accounts: Annotated[
        list[Account],
        Field(
            description='Per-account governance agent configuration. Each entry pairs an account reference with the governance agents for that account.',
            max_length=100,
            min_length=1,
        ),
    ]
    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 accounts : list[Account]

var context : ContextObject | 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 SyncGovernanceResponse (**data: Any)

Expand source code

class SyncGovernanceResponse(AdcpResponse, ResponseArmDispatchMixin, AdcpVersionEnvelope, ProtocolEnvelope):
    """Constructible compatibility base for generated response arms."""

    @classmethod
    def _response_arm_models(cls) -> tuple[type[SyncGovernanceResponse], ...]:
        return (
            SyncGovernanceResponse1,
            SyncGovernanceResponse2,
        )

Constructible compatibility base for generated response arms.

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
• ResponseArmDispatchMixin
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• SyncGovernanceResponse1
• SyncGovernanceResponse2

Class variables

var model_config

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• ResponseArmDispatchMixin:
  • model_validate
  • model_validate_json
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class SyncPlansRequest (**data: Any)

Expand source code

class SyncPlansRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `plan_id` gives resource-level dedup per plan, but the sync envelope emits audit events and can trigger governance reapproval — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    plans: Annotated[list[Plan], Field(description='One or more campaign plans to sync.')]
    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 idempotency_key : str

var model_config

var plans : list[Plan]

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 SyncPlansResponse (**data: Any)

Expand source code

class SyncPlansResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    plans: Annotated[list[Plan], Field(description='Status for each synced plan.')]
    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
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var plans : list[Plan]

var replayed : bool | 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 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.

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 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.

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 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 SyncReportingReceiptsRequest (**data: Any)

Expand source code

class SyncReportingReceiptsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    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
    account: canonical_account_ref.CanonicalAccountReference
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated batch key. Exact retries reuse the key and body.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    receipts: Annotated[
        list[reporting_receipt.ReportingReceipt] | None, Field(max_length=100, min_length=1)
    ] = None
    adjustment_receipts: Annotated[
        list[reporting_adjustment_receipt.ReportingAdjustmentReceipt] | None,
        Field(
            description='Consumer acceptance or rejection of exact post-official adjustments.',
            max_length=100,
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> SyncReportingReceiptsRequest:
        # ``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 (('receipts',), ('adjustment_receipts',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'SyncReportingReceiptsRequest requires at least one of these field groups: receipts | adjustment_receipts'
        )

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 account : CanonicalAccountReference1 | CanonicalAccountReference2

var adcp_major_version : int | None

var adcp_version : str | None

var adjustment_receipts : list[ReportingAdjustmentReceipt] | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var receipts : list[ReportingReceipt] | 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 SyncReportingReceiptsResponse (**data: Any)

Expand source code

class SyncReportingReceiptsResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['completed'],
        Field(
            description='Receipt batches complete synchronously with one result per submitted receipt.'
        ),
    ] = 'completed'
    results: Annotated[
        list[Results20 | Results21 | Results22 | Results23 | Results],
        Field(max_length=100, min_length=1),
    ]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var results : list[Results20 | Results21 | Results22 | Results23 | Results]

var status : Literal['completed']

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 SyncReportingStatusRequest (**data: Any)

Expand source code

class SyncReportingStatusRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='forbid',
    )
    account: canonical_account_ref.CanonicalAccountReference
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated batch key. Exact retries reuse the key and body.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    statuses: Annotated[
        list[reporting_consumer_status.ReportingConsumerStatus],
        Field(
            description='Immutable status updates. New state uses a new reporting_status_id and explicitly supersedes the current status for that expected period. A batch contains at most one update for each logical status chain. content_mismatch entries report a consumed revision that contradicts the accepted configuration generation; they are operational disagreements about contract facts, never measurement disputes.',
            max_length=100,
            min_length=1,
        ),
    ]
    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 account : CanonicalAccountReference1 | CanonicalAccountReference2

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var statuses : list[ReportingConsumerStatus]

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 SyncReportingStatusResponse (**data: Any)

Expand source code

class SyncReportingStatusResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['completed'],
        Field(
            description='Status batches complete synchronously with one result per submitted statement.'
        ),
    ] = 'completed'
    results: Annotated[list[Results | Results26 | Results27], Field(max_length=100, min_length=1)]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var results : list[Results | Results26 | Results27]

var status : Literal['completed']

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 Tags (**data: Any)

Expand source code

class Tags(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    name: Annotated[str, Field(description='Human-readable name for this tag')]
    description: Annotated[str, Field(description='Description of what this tag represents')]

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

• SignalTags

Class variables

var description : str

var model_config

var name : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class TargetingOverlay (**data: Any)

Expand source code

class TargetingOverlay(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    geo_countries: Annotated[
        list[GeoCountry] | None,
        Field(
            description="Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').",
            min_length=1,
        ),
    ] = None
    geo_countries_exclude: Annotated[
        Sequence[GeoCountriesExcludeItem] | None,
        Field(
            description="Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').",
            min_length=1,
        ),
    ] = None
    geo_regions: Annotated[
        list[GeoRegion] | None,
        Field(
            description='Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback.',
            min_length=1,
        ),
    ] = None
    geo_regions_exclude: Annotated[
        Sequence[GeoRegionsExcludeItem] | None,
        Field(
            description='Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome.',
            min_length=1,
        ),
    ] = None
    geo_metros: Annotated[
        list[geo_metro.GeoMetro] | None,
        Field(
            description='Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
            title='Targeting Geo Metros',
        ),
    ] = None
    geo_metros_exclude: Annotated[
        Sequence[GeoMetrosExcludeItem] | None,
        Field(
            description='Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_postal_areas: Annotated[
        list[postal_area.PostalArea] | None,
        Field(
            description='Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_postal_areas_exclude: Annotated[
        Sequence[postal_area.PostalArea] | None,
        Field(
            description='Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_places: Annotated[
        list[geo_place_area.GeographicPlaceArea] | None,
        Field(
            description='Restrict delivery to catalog-backed named places. Values MUST be stable identifiers in the declared system, not display names. Sellers must declare supported systems, countries, and place types in get_adcp_capabilities and reject unsupported entries rather than silently dropping them.',
            min_length=1,
        ),
    ] = None
    geo_places_exclude: Annotated[
        list[geo_place_area.GeographicPlaceArea] | None,
        Field(
            description='Exclude catalog-backed named places. Uses the same identifier-based shape as geo_places. Sellers MUST reject overlap with geo_places for the same country, system, place_type, and value.',
            min_length=1,
        ),
    ] = None
    daypart_targets: Annotated[
        list[daypart_target.DaypartTarget] | None,
        Field(
            description='Restrict delivery to specific time windows. Each entry specifies days of week, an hour range, and an optional timezone that defaults to inventory_local. A concrete IANA zone uses one shared civil-time clock, while inventory_local evaluates each inventory unit in its seller-assigned local timezone. Entries are independent and MAY use different clocks.',
            min_length=1,
        ),
    ] = None
    axe_include_segment: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated: Use TMP provider fields instead. AXE segment ID to include for targeting.',
        ),
    ] = None
    axe_exclude_segment: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated: Use TMP provider fields instead. AXE segment ID to exclude from targeting.',
        ),
    ] = None
    audience_include: Annotated[
        list[str] | None,
        Field(
            description='Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    audience_exclude: Annotated[
        list[str] | None,
        Field(
            description='Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    signal_targeting_groups: Annotated[
        package_signal_targeting_groups.PackageSignalTargetingGroups | None,
        Field(
            description="Basic Boolean grouping for seller-offered signals. v1 supports a required top-level operator 'all' and child groups with operator 'any' for include groups or 'none' for exclusion groups. Example semantics: group 1 any(A, B) plus group 2 none(C, D) means (A OR B) AND NOT (C OR D). Signal entries reference named signal definitions with signal_ref scope 'product' for product-local signal options or scope 'data_provider' for external signals published in adagents.json signals[]. For simple include-only targeting, send one child group with operator 'any'. Sellers SHOULD reject entries that are not available for the product through inline signal_targeting_options or get_signals, are not active for the account, or exceed the product's signal_targeting_allowed/signal_targeting_rules/product terms. Signal targeting limits are product-scoped, not declared in get_adcp_capabilities, because products may be backed by different ad servers. Sellers MUST echo applied signal_targeting_groups on the resulting package state, including fixed/default selections. Sellers MAY return REQUOTE_REQUIRED when a targeting mutation changes commercial terms.",
            title='Targeting Signal Groups',
        ),
    ] = None
    signal_targeting: Annotated[
        list[signal_targeting_1.SignalTargeting] | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_targeting_groups for package-level signal targeting. Legacy flat signal_targeting remains accepted during the SignalRef migration window but cannot express grouped include/exclude composition or product-scoped pricing.',
            min_length=1,
        ),
    ] = None
    demographics: Annotated[
        demographic_targeting_intent.DemographicTargetingIntent | None,
        Field(
            description='Canonical demographic audience targeting intent with optional constraints on how age may be determined. This is distinct from age_restriction: demographics selects an audience, while age_restriction expresses a legal eligibility or verification floor. Fresh create/update targeting MUST compile exactly or be rejected. During get_products, a seller may offer a different configured predicate only through sparse targeting_resolution modifications on a distinguishable product_id; selecting that product accepts the alternative. Sellers never silently broaden, narrow, default, drop, or substitute the basis.'
        ),
    ] = None
    frequency_cap: Annotated[
        frequency_cap_1.FrequencyCap | None, Field(title='Targeting Frequency Cap')
    ] = None
    property_list: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            description="Reference to a property list for targeting specific properties within this product. The package runs on the intersection of the product's publisher_properties and this list. Sellers SHOULD return a validation error if the product has property_targeting_allowed: false.",
            title='Targeting Property List',
        ),
    ] = None
    property_list_exclude: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            description="Reference to a property list whose properties must not carry the buyer's ads. Matched properties are removed from delivery. Use for brand-safety do-not-run lists (apps, sites). Exclude wins on overlap with property_list, and applies regardless of the product's property_targeting_allowed flag. Seller must declare support in get_adcp_capabilities."
        ),
    ] = None
    collection_list: Annotated[
        collection_list_ref.CollectionListReference | None,
        Field(
            description='Reference to a collection list for including specific collections (programs, publications, channels) within this product. The package runs on the intersection of matched collections and this list. Use for inclusion-based collection targeting. Seller must declare support in get_adcp_capabilities.',
            title='Targeting Collection List',
        ),
    ] = None
    collection_list_exclude: Annotated[
        collection_list_ref.CollectionListReference | None,
        Field(
            description="Reference to a collection list for excluding specific collections (programs, publications, channels) from this product. Matched collections must not carry the buyer's ads. Use for brand safety do-not-air lists. Seller must declare support in get_adcp_capabilities."
        ),
    ] = None
    placement_selection: Annotated[
        placement_selection_1.PlacementSelection | None,
        Field(
            description='Purchased placement selection within the product. This constrains package inventory; it is distinct from creative_assignments[].placement_refs, which only route individual creatives within the purchased set. On create, mode selected supplies the complete selected set and mode default uses the product default. In request-side Targeting Input, a non-null value replaces this dimension, omission preserves or inherits it, and null clears it when the product permits that broader inventory set.'
        ),
    ] = None
    collection_selection: Annotated[
        collection_selection_1.CollectionSelection | None,
        Field(
            description="Purchased collection selection within the product. On create, mode selected supplies the complete selected set and mode default uses the product's full bundle. On package readback this is the committed selection sellers MUST echo as concrete selectors, materializing any collection_list composition; collection_list fields remain the buyer-managed list mechanism. In request-side Targeting Input, a non-null value replaces this dimension, omission preserves or inherits it, and null clears it when the product permits that broader inventory set.",
            title='Targeting Collection Selection',
        ),
    ] = None
    age_restriction: Annotated[
        AgeRestriction | None,
        Field(
            description='Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting.'
        ),
    ] = None
    device_platform: Annotated[
        list[device_platform_1.DevicePlatform] | None,
        Field(
            description='Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV.',
            min_length=1,
        ),
    ] = None
    device_platform_exclude: Annotated[
        list[device_platform_1.DevicePlatform] | None,
        Field(
            description='Exclude specific operating-system platforms from delivery. When a platform appears in both device_platform and device_platform_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion.',
            min_length=1,
        ),
    ] = None
    device_type: Annotated[
        list[device_type_1.DeviceType] | None,
        Field(
            description='Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns).',
            min_length=1,
        ),
    ] = None
    device_type_exclude: Annotated[
        list[device_type_1.DeviceType] | None,
        Field(
            description='Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns).',
            min_length=1,
        ),
    ] = None
    browser: Annotated[
        list[browser_family.BrowserFamily] | None,
        Field(
            description='Restrict delivery to specific canonical browser families in the impression delivery and rendering environment, not the post-click landing-page browser. Values MUST NOT be inferred solely from operating system, device, web/mobile-web inventory, or placement. Values in this array use OR semantics. When browser is supplied, families not listed are ineligible: other includes a seller-recognized family that is not explicitly enumerated, while unknown includes a browser the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Browser and device constraints intersect; a seller that cannot enforce the exact combination MUST exclude or explicitly reconfigure the product during discovery and MUST reject it at create or update rather than silently widening delivery. Browser versions and seller-native IDs are intentionally unsupported.',
            min_length=1,
        ),
    ] = None
    browser_exclude: Annotated[
        list[browser_family.BrowserFamily] | None,
        Field(
            description='Exclude specific canonical browser families from delivery. other excludes seller-recognized families that are not explicitly enumerated; unknown excludes browsers the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion.',
            min_length=1,
        ),
    ] = None
    store_catchments: Annotated[
        list[StoreCatchment] | None,
        Field(
            description='Target users within store catchment areas from a synced store catalog. Each entry references a store-type catalog and optionally narrows to specific stores or catchment zones.',
            min_length=1,
        ),
    ] = None
    geo_proximity: Annotated[
        list[GeoProximityItem] | None,
        Field(
            description='Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    language: Annotated[
        list[locale_tag.LanguageTag] | None,
        Field(
            description="Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic.",
            min_length=1,
            title='Targeting Languages',
        ),
    ] = None
    keyword_targets: Annotated[
        list[KeywordTarget] | None,
        Field(
            description='Keyword targeting for search and retail media platforms. Restricts delivery to queries matching the specified keywords. Each keyword is identified by the tuple (keyword, match_type) — the same keyword string with different match types are distinct targets. Sellers SHOULD reject duplicate (keyword, match_type) pairs within a single request. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
            title='Targeting Keywords',
        ),
    ] = None
    negative_keywords: Annotated[
        list[negative_keyword.NegativeKeyword] | None,
        Field(
            description='Keywords to exclude from delivery. Queries matching these keywords will not trigger the ad. Each negative keyword is identified by the tuple (keyword, match_type). Seller must declare support in get_adcp_capabilities.',
            min_length=1,
            title='Targeting Negative Keywords',
        ),
    ] = 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

Class variables

var age_restriction : AgeRestriction | None

var audience_exclude : list[str] | None

var audience_include : list[str] | None

var axe_exclude_segment : str | None

var axe_include_segment : str | None

var browser : list[BrowserFamily] | None

var browser_exclude : list[BrowserFamily] | None

var collection_list : CollectionListReference | None

var collection_list_exclude : CollectionListReference | None

var collection_selection : CollectionSelection1 | CollectionSelection2 | None

var daypart_targets : list[DaypartTarget] | None

var demographics : DemographicTargetingIntent | None

var device_platform : list[DevicePlatform] | None

var device_platform_exclude : list[DevicePlatform] | None

var device_type : list[DeviceType] | None

var device_type_exclude : list[DeviceType] | None

var frequency_cap : FrequencyCap | None

var geo_countries : list[GeoCountry] | None

var geo_countries_exclude : collections.abc.Sequence[GeoCountriesExcludeItem] | None

var geo_metros : list[GeoMetro] | None

var geo_metros_exclude : collections.abc.Sequence[GeoMetrosExcludeItem] | None

var geo_places : list[GeographicPlaceArea] | None

var geo_places_exclude : list[GeographicPlaceArea] | None

var geo_postal_areas : list[PostalArea] | None

var geo_postal_areas_exclude : collections.abc.Sequence[PostalArea] | None

var geo_proximity : list[GeoProximityItem] | None

var geo_regions : list[GeoRegion] | None

var geo_regions_exclude : collections.abc.Sequence[GeoRegionsExcludeItem] | None

var keyword_targets : list[KeywordTarget] | None

var language : list[LanguageTag] | None

var model_config

var negative_keywords : list[NegativeKeyword] | None

var placement_selection : PlacementSelection1 | PlacementSelection2 | None

var property_list : PropertyListReference | None

var property_list_exclude : PropertyListReference | None

var signal_targeting : list[SignalTargeting1 | SignalTargeting2 | SignalTargeting3] | None

var signal_targeting_groups : PackageSignalTargetingGroups | None

var store_catchments : list[StoreCatchment] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class TargetingOverlayInput (**data: Any)

Expand source code

class TargetingOverlayInput(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    geo_countries: Annotated[
        list[GeoCountry] | None,
        Field(
            description="Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').",
            min_length=1,
        ),
    ] = None
    geo_countries_exclude: Annotated[
        list[GeoCountriesExcludeItem] | None,
        Field(
            description="Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').",
            min_length=1,
        ),
    ] = None
    geo_regions: Annotated[
        list[GeoRegion] | None,
        Field(
            description='Restrict delivery to exact canonical ISO 3166-2 subdivisions (states, provinces, regions, departments, or other subdivision categories). Unknown identifiers are invalid. At create or update, sellers MUST reject unsupported identifiers and MUST NOT silently widen, drop, or partially apply the list. During get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome. Exact internal translation preserves accepted identifiers in package readback.',
            min_length=1,
        ),
    ] = None
    geo_regions_exclude: Annotated[
        list[GeoRegionsExcludeItem] | None,
        Field(
            description='Exclude exact canonical ISO 3166-2 subdivisions. Support is independent from geo_regions inclusion support. Unknown identifiers and values also present in geo_regions are invalid. At create or update, sellers MUST reject unsupported identifiers and partial application; during get_products, a seller may instead return a sparse, buyer-reviewable targeting_resolution modification for a valid but unsupported requested outcome.',
            min_length=1,
        ),
    ] = None
    geo_metros: Annotated[
        list[geo_metro.GeoMetro] | None,
        Field(
            description='Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
            title='Targeting Geo Metros',
        ),
    ] = None
    geo_metros_exclude: Annotated[
        list[GeoMetrosExcludeItem] | None,
        Field(
            description='Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_postal_areas: Annotated[
        list[postal_area.PostalArea] | None,
        Field(
            description='Restrict delivery to specific postal areas. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_postal_areas_exclude: Annotated[
        list[postal_area.PostalArea] | None,
        Field(
            description='Exclude specific postal areas from delivery. Prefer the native country + postal system form. The deprecated legacy country-fused postal-system tokens remain accepted for compatibility. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_places: Annotated[
        list[geo_place_area.GeographicPlaceArea] | None,
        Field(
            description='Restrict delivery to catalog-backed named places. Values MUST be stable identifiers in the declared system, not display names. Sellers must declare supported systems, countries, and place types in get_adcp_capabilities and reject unsupported entries rather than silently dropping them.',
            min_length=1,
        ),
    ] = None
    geo_places_exclude: Annotated[
        list[geo_place_area.GeographicPlaceArea] | None,
        Field(
            description='Exclude catalog-backed named places. Uses the same identifier-based shape as geo_places. Sellers MUST reject overlap with geo_places for the same country, system, place_type, and value.',
            min_length=1,
        ),
    ] = None
    daypart_targets: Annotated[
        list[daypart_target.DaypartTarget] | None,
        Field(
            description='Restrict delivery to specific time windows. Each entry specifies days of week, an hour range, and an optional timezone that defaults to inventory_local. A concrete IANA zone uses one shared civil-time clock, while inventory_local evaluates each inventory unit in its seller-assigned local timezone. Entries are independent and MAY use different clocks.',
            min_length=1,
        ),
    ] = None
    axe_include_segment: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated: Use TMP provider fields instead. AXE segment ID to include for targeting.',
        ),
    ] = None
    axe_exclude_segment: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated: Use TMP provider fields instead. AXE segment ID to exclude from targeting.',
        ),
    ] = None
    audience_include: Annotated[
        list[str] | None,
        Field(
            description='Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    audience_exclude: Annotated[
        list[str] | None,
        Field(
            description='Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    signal_targeting_groups: package_signal_targeting_groups.PackageSignalTargetingGroups | None = (
        None
    )
    signal_targeting: Annotated[
        list[signal_targeting_1.SignalTargeting] | None,
        Field(
            deprecated=True,
            description='DEPRECATED. Use signal_targeting_groups for package-level signal targeting. Legacy flat signal_targeting remains accepted during the SignalRef migration window but cannot express grouped include/exclude composition or product-scoped pricing.',
            min_length=1,
        ),
    ] = None
    demographics: demographic_targeting_intent.DemographicTargetingIntent | None = None
    frequency_cap: frequency_cap_1.FrequencyCap | None = None
    property_list: property_list_ref.PropertyListReference | None = None
    property_list_exclude: property_list_ref.PropertyListReference | None = None
    collection_list: collection_list_ref.CollectionListReference | None = None
    collection_list_exclude: collection_list_ref.CollectionListReference | None = None
    placement_selection: placement_selection_1.PlacementSelection | None = None
    collection_selection: collection_selection_1.CollectionSelection | None = None
    age_restriction: targeting.AgeRestriction | None = None
    device_platform: Annotated[
        list[device_platform_1.DevicePlatform] | None,
        Field(
            description='Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV.',
            min_length=1,
        ),
    ] = None
    device_platform_exclude: Annotated[
        list[device_platform_1.DevicePlatform] | None,
        Field(
            description='Exclude specific operating-system platforms from delivery. When a platform appears in both device_platform and device_platform_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion.',
            min_length=1,
        ),
    ] = None
    device_type: Annotated[
        list[device_type_1.DeviceType] | None,
        Field(
            description='Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns).',
            min_length=1,
        ),
    ] = None
    device_type_exclude: Annotated[
        list[device_type_1.DeviceType] | None,
        Field(
            description='Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns).',
            min_length=1,
        ),
    ] = None
    browser: Annotated[
        list[browser_family.BrowserFamily] | None,
        Field(
            description='Restrict delivery to specific canonical browser families in the impression delivery and rendering environment, not the post-click landing-page browser. Values MUST NOT be inferred solely from operating system, device, web/mobile-web inventory, or placement. Values in this array use OR semantics. When browser is supplied, families not listed are ineligible: other includes a seller-recognized family that is not explicitly enumerated, while unknown includes a browser the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Browser and device constraints intersect; a seller that cannot enforce the exact combination MUST exclude or explicitly reconfigure the product during discovery and MUST reject it at create or update rather than silently widening delivery. Browser versions and seller-native IDs are intentionally unsupported.',
            min_length=1,
        ),
    ] = None
    browser_exclude: Annotated[
        list[browser_family.BrowserFamily] | None,
        Field(
            description='Exclude specific canonical browser families from delivery. other excludes seller-recognized families that are not explicitly enumerated; unknown excludes browsers the seller cannot classify into a recognized family. When the same family appears in browser and browser_exclude, exclusion wins. Sellers MUST reject a request they cannot enforce rather than silently dropping the exclusion.',
            min_length=1,
        ),
    ] = None
    store_catchments: Annotated[
        list[StoreCatchment] | None,
        Field(
            description='Target users within store catchment areas from a synced store catalog. Each entry references a store-type catalog and optionally narrows to specific stores or catchment zones.',
            min_length=1,
        ),
    ] = None
    geo_proximity: Annotated[
        list[GeoProximityItem] | None,
        Field(
            description='Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    language: Annotated[
        list[locale_tag.LanguageTag] | None,
        Field(
            description="Restrict to users with specific language preferences using canonical BCP 47 language ranges. Each buyer range is evaluated against a user's language-preference tag with RFC 4647 section 3.3.1 Basic Filtering: 'fr' matches 'fr', 'fr-CA', and 'fr-FR', while 'fr-CA' matches 'fr-CA' and more-specific descendants but not 'fr' or 'fr-FR'. Values use OR logic.",
            min_length=1,
            title='Targeting Languages',
        ),
    ] = None
    keyword_targets: Annotated[
        list[KeywordTarget] | None,
        Field(
            description='Keyword targeting for search and retail media platforms. Restricts delivery to queries matching the specified keywords. Each keyword is identified by the tuple (keyword, match_type) — the same keyword string with different match types are distinct targets. Sellers SHOULD reject duplicate (keyword, match_type) pairs within a single request. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
            title='Targeting Keywords',
        ),
    ] = None
    negative_keywords: Annotated[
        list[negative_keyword.NegativeKeyword] | None,
        Field(
            description='Keywords to exclude from delivery. Queries matching these keywords will not trigger the ad. Each negative keyword is identified by the tuple (keyword, match_type). Seller must declare support in get_adcp_capabilities.',
            min_length=1,
            title='Targeting Negative Keywords',
        ),
    ] = 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

Class variables

var age_restriction : AgeRestriction | None

var audience_exclude : list[str] | None

var audience_include : list[str] | None

var axe_exclude_segment : str | None

var axe_include_segment : str | None

var browser : list[BrowserFamily] | None

var browser_exclude : list[BrowserFamily] | None

var collection_list : CollectionListReference | None

var collection_list_exclude : CollectionListReference | None

var collection_selection : CollectionSelection1 | CollectionSelection2 | None

var daypart_targets : list[DaypartTarget] | None

var demographics : DemographicTargetingIntent | None

var device_platform : list[DevicePlatform] | None

var device_platform_exclude : list[DevicePlatform] | None

var device_type : list[DeviceType] | None

var device_type_exclude : list[DeviceType] | None

var frequency_cap : FrequencyCap | None

var geo_countries : list[GeoCountry] | None

var geo_countries_exclude : list[GeoCountriesExcludeItem] | None

var geo_metros : list[GeoMetro] | None

var geo_metros_exclude : list[GeoMetrosExcludeItem] | None

var geo_places : list[GeographicPlaceArea] | None

var geo_places_exclude : list[GeographicPlaceArea] | None

var geo_postal_areas : list[PostalArea] | None

var geo_postal_areas_exclude : list[PostalArea] | None

var geo_proximity : list[GeoProximityItem] | None

var geo_regions : list[GeoRegion] | None

var geo_regions_exclude : list[GeoRegionsExcludeItem] | None

var keyword_targets : list[KeywordTarget] | None

var language : list[LanguageTag] | None

var model_config

var negative_keywords : list[NegativeKeyword] | None

var placement_selection : PlacementSelection1 | PlacementSelection2 | None

var property_list : PropertyListReference | None

var property_list_exclude : PropertyListReference | None

var signal_targeting : list[SignalTargeting1 | SignalTargeting2 | SignalTargeting3] | None

var signal_targeting_groups : PackageSignalTargetingGroups | None

var store_catchments : list[StoreCatchment] | None

Inherited members

• AdCPBaseModel:
  • 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 TextContent (**data: Any)

Expand source code

class TextAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['text'],
        Field(
            description='Discriminator identifying this as a text asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'text'
    content: Annotated[str, Field(description='Text content')]
    language: Annotated[
        str | None,
        Field(
            description='Optional language claim for this text. In a materialized creative localization variant, localized-creative-asset.json requires this value to use /schemas/core/locale-tag.json and conformance requires exact equality with the enclosing variant locale. General non-localized assets retain the legacy unconstrained string for compatibility.'
        ),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var asset_type : Literal['text']

var content : str

var language : str | None

var model_config

var provenance : Provenance | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class TextSubAsset (*args: object, **kwargs: object)

Expand source code

class TextSubAsset:
    """Removed from ADCP schema. Previously SubAsset with asset_kind='text'."""

    def __init__(self, *args: object, **kwargs: object) -> None:
        raise TypeError(
            "TextSubAsset was removed from the ADCP schema. There is no direct replacement."
        )

Removed from ADCP schema. Previously SubAsset with asset_kind='text'.

class TimeBasedPricingOption (**data: Any)

Expand source code

class TimeBasedPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['time'],
        Field(description='Cost per time unit - rate scales with campaign duration'),
    ] = 'time'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Cost per time unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid per time unit for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    parameters: Annotated[Parameters, Field(description='Time-based pricing parameters')]
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var min_spend_per_package : float | None

var model_config

var parameters : Parameters

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['time']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class TimeUnit (*args, **kwds)

Expand source code

class TimeUnit(StrEnum):
    hour = 'hour'
    day = 'day'
    week = 'week'
    month = 'month'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var day

var hour

var month

var week

class TmpError (**data: Any)

Expand source code

class TmpError(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['error'], Field(description='Message type discriminator for deserialization.')
    ] = 'error'
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the original request')
    ]
    code: Annotated[
        Code,
        Field(
            description="Machine-readable error code. `seller_not_authorized` is returned by providers at sync time when an AvailablePackage declares a `seller_agent.agent_url` that is not present in the `authorized_agents` list of the publisher's adagents.json for a property the package claims to serve."
        ),
    ]
    message: Annotated[
        str | None, Field(description='Human-readable error description for debugging')
    ] = 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

Class variables

var code : Code

var message : str | None

var model_config

var request_id : str

var type : Literal['error']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class IdentityMatchTmpxMacro (**data: Any)

Expand source code

class TmpxMacro(AdCPBaseModel):
    """Deprecated 3.1.8 TMPX macro/value compatibility model."""

    model_config = ConfigDict(
        extra='forbid',
    )
    name: Annotated[
        str,
        Field(max_length=64, min_length=1, pattern='^[A-Z][A-Z0-9_]*$'),
    ]
    value: Annotated[str, Field(max_length=1024, min_length=1)]

Deprecated 3.1.8 TMPX macro/value compatibility model.

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 name : str

var value : str

class ProviderRegistrationTmpxMacro (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class TmpxMacro(ScalarStr):
    """Deprecated 3.1.8 registered macro-name compatibility model."""

    __slots__ = ()
    _constraints = {'max_length': 64, 'min_length': 1, 'pattern': '^[A-Z][A-Z0-9_]*$'}

Deprecated 3.1.8 registered macro-name compatibility model.

Ancestors

• adcp.types._scalar.ScalarStr
• adcp.types._scalar._ScalarRoot
• builtins.str

class CanonicalProposalTotalBudgetGuidance (**data: Any)

Expand source code

class TotalBudgetGuidance(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    min: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    recommended: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    max: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]

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

Class variables

var currency : str

var max : float | None

var min : float | None

var model_config

var recommended : float | None

class LegacyProposalTotalBudgetGuidance (**data: Any)

Expand source code

class TotalBudgetGuidance(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    min: Annotated[StrictFloat | None, Field(description='Minimum recommended budget', ge=0.0)] = (
        None
    )
    recommended: Annotated[
        StrictFloat | None, Field(description='Recommended budget for optimal performance', ge=0.0)
    ] = None
    max: Annotated[
        StrictFloat | None, Field(description='Maximum budget before diminishing returns', ge=0.0)
    ] = None
    currency: Annotated[str | None, Field(description='ISO 4217 currency code')] = 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

Class variables

var currency : str | None

var max : float | None

var min : float | None

var model_config

var recommended : float | None

class RefineProposalsTotalBudgetGuidance (**data: Any)

Expand source code

class TotalBudgetGuidance(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    min: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    recommended: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    max: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]

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

Class variables

var currency : str

var max : float | None

var min : float | None

var model_config

var recommended : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Totals (**data: Any)

Expand source code

class Totals(DeliveryMetrics):
    effective_rate: Annotated[
        StrictFloat | None,
        Field(
            description="Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')",
            ge=0.0,
        ),
    ] = 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

• DeliveryMetrics
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var effective_rate : float | None

var model_config

Inherited members

• DeliveryMetrics:
  • model_dump
  • model_dump_json
  • model_summary

class Transform (*args, **kwds)

Expand source code

class Transform(StrEnum):
    date = 'date'
    divide = 'divide'
    boolean = 'boolean'
    split = 'split'  # type: ignore[assignment]

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var boolean

var date

var divide

var split

class TrustedMatch (**data: Any)

Expand source code

class TrustedMatch(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    context_match: Annotated[
        StrictBool,
        Field(
            description="Whether this product supports Context Match requests. When true, the publisher's TMP router will send context match requests to registered providers for this product's inventory."
        ),
    ]
    identity_match: Annotated[
        StrictBool | None,
        Field(
            description="Whether this product supports Identity Match requests. When true, the publisher's TMP router will send identity match requests to evaluate user eligibility."
        ),
    ] = False
    response_types: Annotated[
        list[response_type.TmpResponseType] | None,
        Field(description='What the publisher can accept back from context match.', min_length=1),
    ] = [response_type.TmpResponseType.activation]
    dynamic_brands: Annotated[
        StrictBool | None,
        Field(
            description="Whether the buyer can select a brand at match time. When false (default), the brand must be specified on the media buy/package. When true, the buyer's offer can include any brand — the publisher applies approval rules at match time. Enables multi-brand agreements where the holding company or buyer agent selects brand based on context."
        ),
    ] = False
    providers: Annotated[
        list[Provider] | None,
        Field(
            description="TMP providers integrated with this product's inventory. Each entry identifies a provider by agent_url (from the registry) and declares what match types it supports for this product. The product-level context_match and identity_match booleans declare what the product supports overall; the per-provider booleans declare which provider handles each match type. Enables buyer discovery: 'find products where a specific provider does context matching.'",
            min_length=1,
        ),
    ] = 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

Class variables

var context_match : bool

var dynamic_brands : bool | None

var identity_match : bool | None

var model_config

var providers : list[Provider] | None

var response_types : list[TmpResponseType] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DurationUnit (*args, **kwds)

Expand source code

class Unit(StrEnum):
    seconds = 'seconds'
    minutes = 'minutes'
    hours = 'hours'
    days = 'days'
    campaign = 'campaign'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var campaign

var days

var hours

var minutes

var seconds

class OverlayUnit (*args, **kwds)

Expand source code

class Unit(StrEnum):
    px = 'px'
    fraction = 'fraction'
    inches = 'inches'
    cm = 'cm'
    mm = 'mm'
    pt = 'pt'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var cm

var fraction

var inches

var mm

var pt

var px

class RealEstateUnit (*args, **kwds)

Expand source code

class Unit(StrEnum):
    sqft = 'sqft'
    sqm = 'sqm'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var sqft

var sqm

class VehicleUnit (*args, **kwds)

Expand source code

class Unit(StrEnum):
    km = 'km'
    mi = 'mi'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var km

var mi

class UnknownFormatAsset (**data: Any)

Expand source code

class UnknownFormatAsset(_BaseIndividualAsset):
    """Fallback arm for individual asset_type values not in the SDK's known set.

    When the AdCP protocol adds a new asset_type before the SDK is updated,
    responses containing that type parse successfully as UnknownFormatAsset
    instead of raising ValidationError for the entire list_creative_formats
    response. Structural fields (asset_id, required) are still validated;
    type-specific fields are preserved in __pydantic_extra__.

    Access extra wire fields via ``asset.__pydantic_extra__ or {}``.

    This type is read-path only. Do not use it in creative manifests or
    emit-side requests — the request path keeps strict Literal validation.
    """

    # extra='allow' is intentionally hardcoded, not inherited from the
    # ADCP_STRICT_VALIDATION env-var policy on AdCPBaseModel. The whole
    # purpose of this fallback arm is to preserve unknown fields from the wire
    # rather than drop or reject them — both behaviors defeat the goal.
    model_config = ConfigDict(extra="allow")
    asset_type: str

Fallback arm for individual asset_type values not in the SDK's known set.

When the AdCP protocol adds a new asset_type before the SDK is updated, responses containing that type parse successfully as UnknownFormatAsset instead of raising ValidationError for the entire list_creative_formats response. Structural fields (asset_id, required) are still validated; type-specific fields are preserved in pydantic_extra.

Access extra wire fields via asset.__pydantic_extra__ or {}.

This type is read-path only. Do not use it in creative manifests or emit-side requests — the request path keeps strict Literal validation.

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

• BaseIndividualAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : str

var model_config

Inherited members

• BaseIndividualAsset:
  • model_dump
  • model_dump_json
  • model_summary

class UnknownGroupAsset (**data: Any)

Expand source code

class UnknownGroupAsset(_BaseGroupAsset):
    """Fallback arm for group asset_type values not in the SDK's known set.

    Same forward-compat guarantee as UnknownFormatAsset but for assets nested
    inside a RepeatableAssetGroup (Assets94.assets). Access extra wire fields
    via ``asset.__pydantic_extra__ or {}``.
    """

    model_config = ConfigDict(extra="allow")
    asset_type: str

Fallback arm for group asset_type values not in the SDK's known set.

Same forward-compat guarantee as UnknownFormatAsset but for assets nested inside a RepeatableAssetGroup (Assets94.assets). Access extra wire fields via asset.__pydantic_extra__ or {}.

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

• BaseGroupAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var asset_type : str

var model_config

Inherited members

• BaseGroupAsset:
  • model_dump
  • model_dump_json
  • model_summary

class UnsupportedRefinementDimensionDetails (**data: Any)

Expand source code

class UnsupportedRefinementDimensionDetails(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    unsupported_dimension: Annotated[
        str,
        Field(
            description='The first typed revision dimension in the request that the seller does not support, named with the supported_dimensions vocabulary.',
            min_length=1,
        ),
    ]
    supported_dimensions: Annotated[
        list[SupportedDimension],
        Field(
            description="The seller's complete supported_dimensions declaration, echoed so the buyer can reconstruct a valid request. An empty array means ask-only refinement."
        ),
    ]

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

Class variables

var model_config

var supported_dimensions : list[SupportedDimension]

var unsupported_dimension : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class UpdateCollectionListRequest (**data: Any)

Expand source code

class UpdateCollectionListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list_id: Annotated[str, Field(description='ID of the collection list to update')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts; optional otherwise.'
        ),
    ] = None
    name: Annotated[str | None, Field(description='New name for the list')] = None
    description: Annotated[str | None, Field(description='New description')] = None
    base_collections: Annotated[
        list[base_collection_source.BaseCollectionSource] | None,
        Field(
            description='Complete replacement for the base collections list (not a patch). Each entry is a discriminated union: distribution_ids (platform-independent identifiers), publisher_collections (publisher_domain + collection_ids), or publisher_genres (publisher_domain + genres).'
        ),
    ] = None
    filters: Annotated[
        collection_list_filters.CollectionListFilters | None,
        Field(description='Complete replacement for the filters (not a patch)'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Update brand reference. Resolved to full brand identity at execution time.'
        ),
    ] = None
    webhook_url: Annotated[
        AnyUrl | None,
        Field(
            description='Update the webhook URL for list change notifications (set to empty string to remove). Governance agents MUST validate this URL against SSRF per docs/building/implementation/security#webhook-url-validation-ssrf.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

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 account : AccountReference1 | AccountReference2 | None

var base_collections : list[BaseCollectionSource1 | BaseCollectionSource2 | BaseCollectionSource3] | None

var brand : BrandReference | None

var context : ContextObject | None

var description : str | None

var ext : ExtensionObject | None

var filters : CollectionListFilters | None

var idempotency_key : str

var list_id : str

var model_config

var name : str | None

var webhook_url : pydantic.networks.AnyUrl | 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 UpdateCollectionListResponse (**data: Any)

Expand source code

class UpdateCollectionListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list: Annotated[
        collection_list.CollectionList, Field(description='The updated collection list')
    ]
    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
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var list : CollectionList

var model_config

var replayed : bool | 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 UpdateContentStandardsRequest (**data: Any)

Expand source code

class UpdateContentStandardsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    standards_id: Annotated[str, Field(description='ID of the standards configuration to update')]
    scope: Annotated[
        Scope | None,
        Field(description='Updated scope for where this standards configuration applies'),
    ] = None
    registry_policy_ids: Annotated[
        list[str] | None,
        Field(
            description='Registry policy IDs to use as the evaluation basis. When provided, the agent resolves policies from the registry and uses their policy text and exemplars as the evaluation criteria.'
        ),
    ] = None
    policies: Annotated[
        list[policy_entry.PolicyEntry] | None,
        Field(
            description='Updated bespoke policies for this content-standards configuration, using the same shape as registry entries. Replaces the existing policies array; use stable policy_ids to track policies across versions. Combines with registry_policy_ids. Bespoke policy_ids MUST be flat (no colons/slashes).',
            min_length=1,
        ),
    ] = None
    calibration_exemplars: Annotated[
        CalibrationExemplars | None,
        Field(
            description='Updated training/test set to calibrate policy interpretation. Use URL references for pages to be fetched and analyzed, or full artifacts for pre-extracted content.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

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 calibration_exemplars : CalibrationExemplars | None

var context : ContextObject | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var policies : list[PolicyEntry] | None

var registry_policy_ids : list[str] | None

var scope : Scope | None

var standards_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 UpdateContentStandardsResponse (**data: Any)

Expand source code

class UpdateContentStandardsResponse(AdcpResponse, ResponseArmDispatchMixin, AdcpVersionEnvelope, ProtocolEnvelope):
    """Constructible compatibility base for generated response arms."""

    @classmethod
    def _response_arm_models(cls) -> tuple[type[UpdateContentStandardsResponse], ...]:
        return (
            UpdateContentStandardsResponse1,
            UpdateContentStandardsResponse2,
        )

Constructible compatibility base for generated response arms.

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
• ResponseArmDispatchMixin
• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Subclasses

• UpdateContentStandardsResponse1
• UpdateContentStandardsResponse2

Class variables

var model_config

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• ResponseArmDispatchMixin:
  • model_validate
  • model_validate_json
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class UpdateContentStandardsResponse1 (**data: Any)

Expand source code

class UpdateContentStandardsResponse1(UpdateContentStandardsResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Annotated[
        Literal[True], Field(description='Indicates the update was applied successfully')
    ]
    standards_id: Annotated[str, Field(description='ID of the updated standards configuration')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var standards_id : str

var success : Literal[True]

class UpdateContentStandardsSuccessResponse (**data: Any)

Expand source code

class UpdateContentStandardsResponse1(UpdateContentStandardsResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Annotated[
        Literal[True], Field(description='Indicates the update was applied successfully')
    ]
    standards_id: Annotated[str, Field(description='ID of the updated standards configuration')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var standards_id : str

var success : Literal[True]

Inherited members

• UpdateContentStandardsResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class UpdateContentStandardsErrorResponse (**data: Any)

Expand source code

class UpdateContentStandardsResponse2(UpdateContentStandardsResponse):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Annotated[Literal[False], Field(description='Indicates the update failed')]
    errors: Annotated[
        list[error.Error], Field(description='Errors that occurred during the update', min_length=1)
    ]
    conflicting_standards_id: Annotated[
        str | None,
        Field(
            description='If scope change conflicts with another configuration, the ID of the conflicting standards'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Constructible compatibility base for generated response arms.

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

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

Class variables

var conflicting_standards_id : str | None

var context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

var success : Literal[False]

Inherited members

• UpdateContentStandardsResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
  • model_validate
  • model_validate_json

class UpdateFrequency (*args, **kwds)

Expand source code

class UpdateFrequency(StrEnum):
    realtime = 'realtime'
    hourly = 'hourly'
    daily = 'daily'
    weekly = 'weekly'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var daily

var hourly

var realtime

var weekly

class UpdateMediaBuyRequest (**data: Any)

Expand source code

class UpdateMediaBuyRequest(_LegacyUpdateMediaBuyRequest, CanonicalBoundaryModel):
    """Canonical update request; both package lists are canonical."""

    packages: list[PackageUpdate] | None = None
    new_packages: list[PackageRequest] | None = Field(  # type: ignore[assignment]
        default=None, min_length=1
    )

Canonical update request; both package lists are canonical.

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

• UpdateMediaBuyRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var new_packages : list[PackageRequest] | None

var packages : list[PackageUpdate] | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class LegacyUpdateMediaBuyRequest (**data: Any)

Expand source code

class UpdateMediaBuyRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque intent authorization for a commitment-increasing media-buy update.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference,
        Field(
            description='Account that owns this media buy. Pass a natural key (brand, operator, optional sandbox) or a seller-assigned account_id from list_accounts. Required for governance checks and account resolution.'
        ),
    ]
    media_buy_id: Annotated[str, Field(description="Seller's ID of the media buy to update")]
    name: Annotated[
        str | None,
        Field(
            description='Replacement human-readable name for this media buy, used for trafficking UI display and operational communication. Sellers that cannot update name mid-flight SHOULD echo the prior unchanged value in the success response rather than silently dropping the field. This display label is not an identifier or financial reference.',
            max_length=255,
            min_length=1,
            pattern='\\S',
        ),
    ] = None
    revision: Annotated[
        SchemaInt | None,
        Field(
            description="Expected current revision for optimistic concurrency. Optional for backward compatibility. When provided, sellers MUST reject the update with CONFLICT if the media buy's current revision does not match, and MUST enforce that comparison atomically with the write. Obtain from get_media_buys or the most recent create/update response.",
            ge=1,
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(description='Pause/resume the entire media buy (true = paused, false = active)'),
    ] = None
    canceled: Annotated[
        Literal[True] | None,
        Field(
            description='Cancel the entire media buy. Cancellation is irreversible — canceled media buys cannot be reactivated. Sellers MAY reject with NOT_CANCELLABLE if the media buy cannot be canceled in its current state.'
        ),
    ] = None
    cancellation_reason: Annotated[
        str | None,
        Field(
            description='Reason for cancellation. Sellers SHOULD store this and return it in subsequent get_media_buys responses.',
            max_length=500,
        ),
    ] = None
    start_time: start_timing.StartTiming | None = None
    end_time: Annotated[
        AwareDatetime | None, Field(description='New end date/time in ISO 8601 format')
    ] = None
    total_budget: Annotated[
        TotalBudget | None,
        Field(
            description='Updated hard aggregate lifetime budget. currency MUST equal the existing media-buy currency; an update does not redenominate a buy. When supplied alone (without packages or new_packages), in fixed mode the seller MUST atomically scale every active package budget in proportion to its current committed budget, rejecting the entire request if any derived budget cannot be accepted. When supplied with packages or new_packages, the amount MUST equal the resulting fixed-mode package sum; the seller applies the explicit package mutations and rejects with VALIDATION_ERROR if the total is inconsistent. In seller-optimized mode this changes the shared pool without converting package caps into allocations. Already-spent amounts still count against the new total.'
        ),
    ] = None
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description='Replace the hard aggregate daily cap; null removes it. Numeric changes apply immediately with current-day spend counted. A cap below that spend pauses delivery for the day. Package caps are unchanged. Requires advertised media_buy scope; otherwise rejected with UNSUPPORTED_FEATURE.',
            ge=0.0,
        ),
    ] = None
    frequency_cap: Annotated[
        media_buy_frequency_cap.MediaBuyFrequencyCap | None,
        Field(
            description='Replace the hard MediaBuy-level frequency cap; null removes it. Changes apply immediately without resetting the shared counter, so prior qualifying exposures in the resulting window continue to count. Every active package must support the resulting cap or the request is rejected atomically with UNSUPPORTED_FEATURE before any change; sellers MUST NOT clamp it. The check applies to the state the request would produce, so null combined with new_packages adds those packages uncapped.'
        ),
    ] = None
    budget_cap_timezone: Annotated[
        str | None,
        Field(
            description='Replace the shared IANA cap-day timezone; null restores the default selected by budget_capping.timezone_basis (Account.timezone or fixed_timezone). Requires buyer_timezone_override. Changes start at the next boundary in the previously effective timezone; numeric cap changes remain immediate.',
            min_length=1,
        ),
    ] = None
    budget_allocation: Annotated[
        budget_allocation_1.BudgetAllocation | None,
        Field(
            description='Updated allocation configuration. Switching between fixed and seller-optimized modes is allowed only when update_budget_allocation is advertised in available_actions and the resulting package constraints are valid. A resulting seller_optimized allocation requires advertised media_buy.features.seller_optimized_budget, and any package budget caps, min_spend_target values, or package pacing it retains require their own advertised sub-capability; otherwise the update is rejected with UNSUPPORTED_FEATURE before any over-subscription validation.'
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Updated aggregate media-buy pacing. Package pacing remains subordinate to this aggregate strategy. When the resulting buy is seller-optimized, a seller declaring media_buy.features.seller_optimized_budget MUST accept `even`; it MAY reject `asap` or `front_loaded` with UNSUPPORTED_FEATURE (error.field `pacing`) before any provider mutation, including a switch to seller-optimized allocation that would retain such pacing, and MUST NOT silently coerce them to `even`. Fixed-allocation semantics are unchanged.'
        ),
    ] = None
    bidding: Annotated[
        bidding_policy.BiddingPolicy | None,
        Field(
            description='Replace the complete media-buy-authored bidding default. An object replaces the prior block; `{automatic:true}` records an explicit automatic policy. null clears it; packages with explicit package.bidding remain explicit, while packages without overrides fall back to provider automatic delivery. Goal binding follows the resulting budget allocation: seller-optimized outcome controls bind to allocation goals, while fixed inherited cost_per requires compatible package result units. Monetary fields use the media-buy currency and all affected pricing options MUST match it. The seller MUST validate all resulting policies atomically before mutation.'
        ),
    ] = None
    packages: Annotated[
        Sequence[package_update.PackageUpdate] | None,
        Field(description='Package-specific updates for existing packages', min_length=1),
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description="Update who receives the invoice for this buy. When provided, the seller invoices this entity instead of the account's default billing_entity. The seller MUST validate the invoice recipient is authorized for this account. When governance_agents are configured, the seller MUST include invoice_recipient in the check_governance request."
        ),
    ] = None
    new_packages: Annotated[
        list[package_request.PackageRequest] | None,
        Field(
            description='New packages to add to this media buy. Uses the same schema as create_media_buy packages. When budget_allocation is omitted or fixed, every new package MUST carry budget and MUST NOT carry min_spend_target. To add a package without a hard cap to an existing seller-optimized buy, include its resulting seller_optimized budget_allocation block in the update so the allocation context is schema-visible. Repeating an unchanged allocation block does not itself switch modes. Sellers that support mid-flight package additions advertise `add_packages` in both `valid_actions[]` (deprecated) and as an entry in `available_actions[]` (authoritative). Sellers that do not support this MUST reject with ACTION_NOT_ALLOWED (preferred) or UNSUPPORTED_FEATURE (legacy). If the buy has a root frequency_cap, every added product must support that exact aggregate cap; otherwise the seller rejects atomically with UNSUPPORTED_FEATURE, leaving the whole update unapplied and preserving the buy and its counter history.',
            min_length=1,
        ),
    ] = None
    reporting_webhook: Annotated[
        reporting_webhook_1.ReportingWebhook | None,
        Field(
            description='Optional webhook configuration for automated reporting delivery. Updates the reporting configuration for this media buy.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async update notifications. Publisher will send webhook when update completes if operation takes longer than immediate response time. This is separate from reporting_webhook which configures ongoing campaign reporting.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated idempotency key for safe retries. If an update fails without a response, resending with the same idempotency_key guarantees the update is applied at most once. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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

Subclasses

• UpdateMediaBuyRequest

Class variables

var account : AccountReference1 | AccountReference2

var bidding : BiddingPolicy | None

var budget_allocation : BudgetAllocation1 | BudgetAllocation2 | None

var budget_cap_timezone : str | None

var canceled : Literal[True] | None

var cancellation_reason : str | None

var context : ContextObject | None

var daily_budget_cap : float | None

var end_time : pydantic.types.AwareDatetime | None

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var governance_context : str | None

var idempotency_key : str

var invoice_recipient : BusinessEntity | None

var media_buy_id : str

var model_config

var name : str | None

var new_packages : list[PackageRequest] | None

var pacing : Pacing | None

var packages : collections.abc.Sequence[PackageUpdate] | None

var paused : bool | None

var push_notification_config : PushNotificationConfig | None

var reporting_webhook : ReportingWebhook | None

var revision : int | None

var start_time : Literal['asap'] | pydantic.types.AwareDatetime | None

var total_budget : TotalBudget | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class UpdateMediaBuyPackagesRequest (**data: Any)

Expand source code

class UpdateMediaBuyRequest(_LegacyUpdateMediaBuyRequest, CanonicalBoundaryModel):
    """Canonical update request; both package lists are canonical."""

    packages: list[PackageUpdate] | None = None
    new_packages: list[PackageRequest] | None = Field(  # type: ignore[assignment]
        default=None, min_length=1
    )

Canonical update request; both package lists are canonical.

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

• UpdateMediaBuyRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var new_packages : list[PackageRequest] | None

var packages : list[PackageUpdate] | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class UpdateMediaBuyPropertiesRequest (**data: Any)

Expand source code

class UpdateMediaBuyRequest(_LegacyUpdateMediaBuyRequest, CanonicalBoundaryModel):
    """Canonical update request; both package lists are canonical."""

    packages: list[PackageUpdate] | None = None
    new_packages: list[PackageRequest] | None = Field(  # type: ignore[assignment]
        default=None, min_length=1
    )

Canonical update request; both package lists are canonical.

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

• UpdateMediaBuyRequest
• AdcpRequest
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• CanonicalBoundaryModel
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var model_config

var new_packages : list[PackageRequest] | None

var packages : list[PackageUpdate] | None

Inherited members

• UpdateMediaBuyRequest:
  • adcp_major_version
  • get_account
  • get_adcp_major_version
  • get_adcp_version
  • get_context
  • get_idempotency_key
  • get_push_notification_config
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class LegacyUpdateMediaBuySuccessResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    status: Literal['completed'] = 'completed'
    media_buy_id: str
    name: Annotated[str, StringConstraints(pattern='\\S', min_length=1, max_length=255)] | None = None
    media_buy_status: media_buy_status_1.MediaBuyStatus | None = None
    revision: Annotated[int, Field(ge=1)]
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')] | None = None
    total_budget: Annotated[float, Field(ge=0)] | None = None
    daily_budget_cap: Annotated[float, Field(ge=0)] | None = None
    frequency_cap: media_buy_frequency_cap_1.MediaBuyFrequencyCap | None = None
    budget_cap_timezone: str | None = None
    budget_allocation: Any | None = None
    pacing: pacing_1.Pacing | None = None
    bidding: Any | None = None
    implementation_date: AwareDatetime | None = None
    invoice_recipient: business_entity_1.BusinessEntity | None = None
    affected_packages: Sequence[package_1.Package] | None = None
    valid_actions: list[media_buy_valid_action_1.MediaBuyValidAction] | None = None
    available_actions: list[media_buy_available_action_1.MediaBuyAvailableAction] | None = None
    warnings: list[warning_1.Warning] | None = None
    sandbox: bool | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

    @model_validator(mode='before')
    @classmethod
    def _normalize_legacy_status(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        raw_status = unwrap_enum_value(data.get('status'))
        media_buy_status = unwrap_enum_value(data.get('media_buy_status'))
        if raw_status is None:
            data = dict(data)
            data['status'] = 'completed'
        elif raw_status == 'completed':
            data = dict(data)
            data['status'] = 'completed'
        elif media_buy_status is None and raw_status in MEDIA_BUY_LEGACY_STATUS_VALUES:
            data = dict(data)
            data['media_buy_status'] = raw_status
            data['status'] = 'completed'
        elif media_buy_status is not None and raw_status == media_buy_status:
            data = dict(data)
            data['status'] = 'completed'
        return data

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

Subclasses

• UpdateMediaBuyResponse1

Class variables

var affected_packages : collections.abc.Sequence[Package] | None

var available_actions : list[MediaBuyAvailableAction] | None

var bidding : typing.Any | None

var budget_allocation : typing.Any | None

var budget_cap_timezone : str | None

var context : ContextObject | None

var currency : str | None

var daily_budget_cap : float | None

var ext : ExtensionObject | None

var frequency_cap : MediaBuyFrequencyCap | None

var implementation_date : pydantic.types.AwareDatetime | None

var invoice_recipient : BusinessEntity | None

var media_buy_id : str

var media_buy_status : MediaBuyStatus | None

var model_config

var name : str | None

var pacing : Pacing | None

var revision : int

var sandbox : bool | None

var status : Literal['completed']

var total_budget : float | None

var valid_actions : list[MediaBuyValidAction] | None

var warnings : list[Warning] | None

Instance variables

var adcp_major_version : int | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

-----=

msg

The deprecation message to be emitted.

wrapped_property

The property instance if the deprecated field is a computed field, or None.

field_name

The name of the field being deprecated.

class UpdateMediaBuyResponse1 (**data: Any)

Expand source code

class UpdateMediaBuyResponse1(_LegacyUpdateMediaBuyResponse1, CanonicalBoundaryModel):
    """Canonical update response preserving the 3.x legacy-status normalizer."""

    affected_packages: Sequence[Package] | None = None

    @model_validator(mode="before")
    @classmethod
    def _normalize_legacy_status(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        raw_status = unwrap_enum_value(data.get("status"))
        media_buy_status = unwrap_enum_value(data.get("media_buy_status"))
        if raw_status is None or raw_status == "completed":
            return {**data, "status": "completed"}
        if media_buy_status is None and raw_status in MEDIA_BUY_LEGACY_STATUS_VALUES:
            return {**data, "media_buy_status": raw_status, "status": "completed"}
        if media_buy_status is not None and raw_status == media_buy_status:
            return {**data, "status": "completed"}
        return data

Canonical update response preserving the 3.x legacy-status normalizer.

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

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

Class variables

var affected_packages : collections.abc.Sequence[Package] | None

var model_config

class UpdateMediaBuySuccessResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse1(_LegacyUpdateMediaBuyResponse1, CanonicalBoundaryModel):
    """Canonical update response preserving the 3.x legacy-status normalizer."""

    affected_packages: Sequence[Package] | None = None

    @model_validator(mode="before")
    @classmethod
    def _normalize_legacy_status(cls, data: Any) -> Any:
        if not isinstance(data, dict):
            return data
        raw_status = unwrap_enum_value(data.get("status"))
        media_buy_status = unwrap_enum_value(data.get("media_buy_status"))
        if raw_status is None or raw_status == "completed":
            return {**data, "status": "completed"}
        if media_buy_status is None and raw_status in MEDIA_BUY_LEGACY_STATUS_VALUES:
            return {**data, "media_buy_status": raw_status, "status": "completed"}
        if media_buy_status is not None and raw_status == media_buy_status:
            return {**data, "status": "completed"}
        return data

Canonical update response preserving the 3.x legacy-status normalizer.

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

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

Class variables

var affected_packages : collections.abc.Sequence[Package] | None

var model_config

Inherited members

• UpdateMediaBuyResponse1:
  • adcp_major_version
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class UpdateMediaBuyErrorResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse2(_LegacyUpdateMediaBuyResponse2, CanonicalBoundaryModel):
    """Canonical update-media-buy error arm."""

Canonical update-media-buy error arm.

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

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

Class variables

var model_config

class LegacyUpdateMediaBuyErrorResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    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.

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

Subclasses

• UpdateMediaBuyResponse2

Class variables

var context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 LegacyUpdateMediaBuySubmittedResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse3(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow', validate_default=True)
    status: Literal[task_status_1.TaskStatus.submitted] = task_status_1.TaskStatus.submitted
    task_id: str
    message: Annotated[str, StringConstraints(max_length=2000)] | None = None
    errors: list[error_1.Error] | None = 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.

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

Subclasses

• UpdateMediaBuyResponse3

Class variables

var context : ContextObject | None

var errors : list[Error] | None

var ext : ExtensionObject | None

var message : str | None

var model_config

var status : Literal[<TaskStatus.submitted: 'submitted'>]

var task_id : str

class UpdateMediaBuyResponse3 (**data: Any)

Expand source code

class UpdateMediaBuyResponse3(_LegacyUpdateMediaBuyResponse3, CanonicalBoundaryModel):
    """Canonical update-media-buy submitted arm."""

Canonical update-media-buy submitted arm.

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

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

Class variables

var model_config

class UpdateMediaBuySubmittedResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse3(_LegacyUpdateMediaBuyResponse3, CanonicalBoundaryModel):
    """Canonical update-media-buy submitted arm."""

Canonical update-media-buy submitted arm.

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

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

Class variables

var model_config

Inherited members

• UpdateMediaBuyResponse3:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
  • model_dump
  • model_dump_json
  • model_summary
• CanonicalBoundaryModel:
  • model_json_schema

class UpdatePropertyListRequest (**data: Any)

Expand source code

class UpdatePropertyListRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list_id: Annotated[str, Field(description='ID of the property list to update')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts; optional otherwise.'
        ),
    ] = None
    name: Annotated[str | None, Field(description='New name for the list')] = None
    description: Annotated[str | None, Field(description='New description')] = None
    base_properties: Annotated[
        list[base_property_source.BasePropertySource] | None,
        Field(
            description='Complete replacement for the base properties list (not a patch). Each entry is a discriminated union: publisher_tags (publisher_domain + tags), publisher_ids (publisher_domain + property_ids), or identifiers (direct identifiers).'
        ),
    ] = None
    filters: Annotated[
        property_list_filters.PropertyListFilters | None,
        Field(description='Complete replacement for the filters (not a patch)'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Update brand reference. Resolved to full brand identity at execution time.'
        ),
    ] = None
    webhook_url: Annotated[
        AnyUrl | None,
        Field(
            description='Update the webhook URL for list change notifications (set to empty string to remove)'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

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 account : AccountReference1 | AccountReference2 | None

var base_properties : list[BasePropertySource1 | BasePropertySource2 | BasePropertySource3] | None

var brand : BrandReference | None

var context : ContextObject | None

var description : str | None

var ext : ExtensionObject | None

var filters : PropertyListFilters | None

var idempotency_key : str

var list_id : str

var model_config

var name : str | None

var webhook_url : pydantic.networks.AnyUrl | 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 UpdatePropertyListResponse (**data: Any)

Expand source code

class UpdatePropertyListResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    list: Annotated[property_list.PropertyList, Field(description='The updated property list')]
    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
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var list : PropertyList

var model_config

var replayed : bool | 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 UpdateRightsRequest (**data: Any)

Expand source code

class UpdateRightsRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque intent authorization for a commitment-increasing rights update.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    rights_id: Annotated[
        str, Field(description='Rights grant identifier from acquire_rights response')
    ]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account context for this update. Used by the brand agent to resolve any governance agent previously bound for this brand+operator pair via sync_governance — update_rights is a modification-phase governance trigger (per `/docs/governance/campaign/specification#spend-commit-invocation`) and the brand agent consults the bound agent when computing the incremental commit delta. When both an inline governance_context token (on the protocol envelope) and a bound governance agent are present, the inline token wins. Pass a natural key (brand, operator, optional sandbox) or a seller-assigned account_id from list_accounts. The estimated_impressions / commit-delta projection rule for governance-aware updates is tracked separately and not yet normative on this task.'
        ),
    ] = None
    end_date: Annotated[
        date | None,
        Field(
            description='New end date for the rights grant (must be >= current end_date). Extending the grant may re-issue generation credentials with updated expiration.'
        ),
    ] = None
    impression_cap: Annotated[
        SchemaInt | None,
        Field(
            description='New impression cap for the grant. Must be >= impressions already delivered.',
            ge=1,
        ),
    ] = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="Switch to a different pricing option from the original get_rights offering. The new option must be compatible with the existing grant's uses and countries."
        ),
    ] = None
    paused: Annotated[
        StrictBool | None,
        Field(
            description='Pause or resume the rights grant. When paused, generation credentials are suspended and creative delivery should stop. When resumed, credentials are re-activated.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(description='Webhook for async update notifications if the update requires approval'),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated idempotency key for safe retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    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 account : AccountReference1 | AccountReference2 | None

var context : ContextObject | None

var end_date : datetime.date | None

var ext : ExtensionObject | None

var governance_context : str | None

var idempotency_key : str

var impression_cap : int | None

var model_config

var paused : bool | None

var pricing_option_id : str | None

var push_notification_config : PushNotificationConfig | None

var rights_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 UrlContent (**data: Any)

Expand source code

class UrlAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['url'],
        Field(
            description='Discriminator identifying this as a URL asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'url'
    url: Annotated[
        macro_bearing_url.MacroBearingUrl,
        Field(
            description='URL reference carrying plain, AdCP, IAB, or declared vendor macro syntax. Buyers preserve token delimiters; the authoritative declaration determines the processing operation and encoding.'
        ),
    ]
    url_type: Annotated[
        url_asset_type.UrlAssetType | None,
        Field(
            description='Mechanism a receiver uses to invoke this URL: `clickthrough` for a user destination, `ad_request` for a third-party display creative request, `tracker_pixel` for an event HTTP request, or `tracker_script` for a script include. SHOULD be present on every URL asset.'
        ),
    ] = None
    macro_declarations: Annotated[
        list[MacroDeclaration] | None,
        Field(
            description='One declaration per token occurrence in `url`; declaration_id values MUST be unique and every location MUST identify an existing occurrence. Absence retains legacy opaque transport behavior.',
            min_length=1,
        ),
    ] = None
    description: Annotated[
        str | None, Field(description='Description of what this URL points to')
    ] = None
    state_id: Annotated[
        str | None,
        Field(
            description='Binding used only when this URL populates a `seller_rendered_stateful_display` `state_click_urls` slot. It MUST match one declared `states[].state_id` (semantic validators resolve it); at most one entry per state. Omit for ordinary URL slots.'
        ),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var asset_type : Literal['url']

var description : str | None

var macro_declarations : list[MacroDeclaration] | None

var model_config

var provenance : Provenance | None

var state_id : str | None

var url : str | MacroBearingUrl3 | MacroBearingUrl4

var url_type : UrlAssetType | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class UrlAssetType (*args, **kwds)

Expand source code

class UrlAssetType(StrEnum):
    clickthrough = 'clickthrough'
    ad_request = 'ad_request'
    tracker_pixel = 'tracker_pixel'
    tracker_script = 'tracker_script'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var ad_request

var clickthrough

var tracker_pixel

var tracker_script

class UrlType (*args, **kwds)

Expand source code

class UrlAssetType(StrEnum):
    clickthrough = 'clickthrough'
    ad_request = 'ad_request'
    tracker_pixel = 'tracker_pixel'
    tracker_script = 'tracker_script'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var ad_request

var clickthrough

var tracker_pixel

var tracker_script

class V1CanonicalGlobPattern (**data: Any)

Expand source code

class V1Pattern(AdCPBaseModel):
    format_id_glob: Annotated[
        str,
        Field(
            description="Glob pattern matched against v1 format_id.id. Examples: 'iab_mrec_300x250', 'iab_leaderboard_*', 'meta_*_reels'."
        ),
    ]

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

Class variables

var format_id_glob : str

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class V1CanonicalStructuralPattern (**data: Any)

Expand source code

class V1Pattern1(AdCPBaseModel):
    structural: Annotated[
        Structural,
        Field(
            description="Structural match against the format's slot shape, asset types, and version constraints."
        ),
    ]

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

Class variables

var model_config

var structural : Structural

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class V1V2CanonicalFormatMappingRegistry (**data: Any)

Expand source code

class V1V2CanonicalFormatMappingRegistry(AdCPBaseModel):
    version: Annotated[
        str, Field(description='Semver of this registry. Bumped on every published change.')
    ]
    last_updated: Annotated[
        date | None, Field(description='ISO date of the last published change.')
    ] = None
    mappings: Annotated[
        list[Mapping],
        Field(
            description='Ordered list of v1 → v2 mappings. SDKs apply mappings in order and use the first match.'
        ),
    ]

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

Class variables

var last_updated : datetime.date | None

var mappings : list[Mapping]

var model_config

var version : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class V1CanonicalV2Projection (**data: Any)

Expand source code

class V2(AdCPBaseModel):
    canonical: Annotated[str, Field(description='v2 canonical format the v1 pattern projects to.')]
    parameters: Annotated[
        dict[str, Any] | None,
        Field(
            description='Optional parameters that narrow the canonical (e.g., width/height, vast_version). When present, become the params on the projected v2 ProductFormatDeclaration. The shape MUST be valid params for the named canonical.'
        ),
    ] = None
    parameter_mappings: Annotated[
        list[ParameterMapping] | None,
        Field(
            description='Machine-readable forwarding rules for parameters carried by a structured v1 format_id. SDKs copy each present source_field to the target_parameter after applying transform; absent source fields leave the target parameter omitted. Static v2.parameters are applied before these forwarded values.',
            min_length=1,
        ),
    ] = 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

Class variables

var canonical : str

var model_config

var parameter_mappings : list[ParameterMapping] | None

var parameters : dict[str, typing.Any] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ValidateContentDeliveryRequest (**data: Any)

Expand source code

class ValidateContentDeliveryRequest(AdcpRequest, AdcpVersionEnvelope):
    standards_id: Annotated[str, Field(description='Standards configuration to validate against')]
    records: Annotated[
        list[Record],
        Field(
            description='Delivery records to validate (max 10,000)', max_length=10000, min_length=1
        ),
    ]
    feature_ids: Annotated[
        list[str] | None,
        Field(description='Specific features to evaluate (defaults to all)', min_length=1),
    ] = None
    include_passed: Annotated[
        StrictBool | None, Field(description='Include passed records in results')
    ] = True
    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 feature_ids : list[str] | None

var include_passed : bool | None

var model_config

var records : list[Record]

var standards_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 ValidateContentDeliveryResponse1 (**data: Any)

Expand source code

class ValidateContentDeliveryResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    summary: Summary
    results: list[Result]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var results : list[Result]

var summary : Summary

class ValidateContentDeliverySuccessResponse (**data: Any)

Expand source code

class ValidateContentDeliveryResponse1(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    summary: Summary
    results: list[Result]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var results : list[Result]

var summary : Summary

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 ValidateContentDeliveryErrorResponse (**data: Any)

Expand source code

class ValidateContentDeliveryResponse2(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(extra='allow')
    errors: list[error_1.Error]
    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.

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 context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

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 ValidateInputRequest (**data: Any)

Expand source code

class ValidateInputRequest(AdcpRequest, AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Optional account scope for seller-specific product validation. Required by sellers that route product declarations by buyer account.'
        ),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Optional brand scope when account is omitted or the seller keys sandbox validation by brand identity.'
        ),
    ] = None
    manifest: Annotated[
        creative_manifest.CreativeManifest, Field(description='Creative manifest to validate.')
    ]
    targets: Annotated[
        list[Targets] | None,
        Field(
            description="Discriminated list of validation targets. Each entry mirrors the `target` shape on `validate-input-result.json` so the request/response wire shapes match exactly. Multi-target requests enable universal-creative scenarios where one manifest targets multiple sellers' format declarations in a single round-trip; the response carries one result per target in the same order.",
            max_length=50,
            min_length=1,
        ),
    ] = 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
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var account : AccountReference1 | AccountReference2 | None

var brand : BrandReference | None

var manifest : CreativeManifest

var model_config

var targets : list[Targets1 | Targets2 | Targets3 | Targets4] | None

Inherited members

• AdcpRequest:
  • get_account
  • get_adcp_major_version
  • get_adcp_version
  • get_context
  • get_idempotency_key
  • get_push_notification_config
• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ValidateInputResponse (**data: Any)

Expand source code

class ValidateInputResponse(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    results: Annotated[
        list[validate_input_result.ValidateInputResult],
        Field(description='Per-target validation results.'),
    ]

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 model_config

var results : list[ValidateInputResult]

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 ValidationMode (*args, **kwds)

Expand source code

class ValidationMode(StrEnum):
    strict = 'strict'
    lenient = 'lenient'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var lenient

var strict

class VastAsset (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class VastAsset(RootModel[VastAsset3 | VastAsset4]):
    root: Annotated[
        VastAsset3 | VastAsset4,
        Field(
            description='VAST (Video Ad Serving Template) tag for third-party video or audio ad serving. Unlike a hosted media asset, a VAST tag carries no single `width`/`height`: a response can return multiple renditions and the player selects one at serve time. Standardized VAST audio support begins at 4.1 and uses MediaFile width and height values of 0; older audio-in-VAST versions are seller-declared legacy interoperability. Dimensional, duration, MIME-type, and codec constraints live on the format/requirements layer, not on this asset.',
            discriminator='delivery_type',
            title='VAST Asset',
        ),
    ]
    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

-----=

root

The root object of the model.

__pydantic_root_model__

Whether the model is a RootModel.

__pydantic_private__

Private fields in the model.

__pydantic_extra__

Extra fields in the model.

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.root_model.RootModel[Union[VastAsset3, VastAsset4]]
• pydantic.root_model.RootModel
• pydantic.main.BaseModel
• typing.Generic

Class variables

var model_config

var root : VastAsset3 | VastAsset4

class UrlVastAsset (**data: Any)

Expand source code

class VastAsset1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['vast'],
        Field(
            description='Discriminator identifying this as a VAST asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'vast'
    vast_version: Annotated[
        VastVersion | None,
        Field(
            description='Exact VAST version declared by the supplied URL response or inline document. Required by the 3.2 canonical `video_vast` and `audio_vast` manifest paths; optional only on the deprecated named-format compatibility path. Receivers MUST NOT relabel or synthesize a newer version merely because the destination accepts it.'
        ),
    ] = None
    macro_declarations: Annotated[
        list[MacroDeclaration] | None,
        Field(
            description='One declaration per exact occurrence in a field carried by this asset. A URL-delivered asset can declare only occurrences in its locator `url`; tokens discovered later in a fetched VAST response require document validation evidence or an inline/snapshotted asset and MUST NOT be guessed from the locator. IAB tokens cite a registry namespace and revision rather than copying the live registry into AdCP.',
            min_length=1,
        ),
    ] = None
    vpaid_enabled: Annotated[
        StrictBool | None,
        Field(description='Whether VPAID (Video Player-Ad Interface Definition) is supported'),
    ] = None
    duration_ms: Annotated[
        SchemaInt | None,
        Field(description='Expected media duration in milliseconds (if known)', ge=0),
    ] = None
    tracking_events: Annotated[
        list[VastTrackingEvent] | None,
        Field(description='Tracking events supported by this VAST tag'),
    ] = None
    captions_url: Annotated[
        AnyUrl | None, Field(description='URL to captions file (WebVTT, SRT, etc.)')
    ] = None
    audio_description_url: Annotated[
        AnyUrl | None,
        Field(description='URL to audio description track for visually impaired users'),
    ] = None
    provenance: Annotated[
        Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None
    delivery_type: Annotated[
        Literal['url'],
        Field(description='Discriminator indicating VAST is delivered via URL endpoint'),
    ] = 'url'
    url: Annotated[
        MacroBearingUrl,
        Field(
            description='URL endpoint returning VAST XML. Macro delimiters remain byte-preserved; declarations distinguish occurrences in this locator URL from occurrences in inline or fetched VAST content.'
        ),
    ]

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

Class variables

var asset_type : Literal['vast']

var audio_description_url : pydantic.networks.AnyUrl | None

var captions_url : pydantic.networks.AnyUrl | None

var delivery_type : Literal['url']

var duration_ms : int | None

var macro_declarations : list[MacroDeclaration] | None

var model_config

var provenance : Provenance | None

var tracking_events : list[VastTrackingEvent] | None

var url : str | MacroBearingUrl1 | MacroBearingUrl2

var vast_version : VastVersion | None

var vpaid_enabled : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class InlineVastAsset (**data: Any)

Expand source code

class VastAsset2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['vast'],
        Field(
            description='Discriminator identifying this as a VAST asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'vast'
    vast_version: Annotated[
        VastVersion | None,
        Field(
            description='Exact VAST version declared by the supplied URL response or inline document. Required by the 3.2 canonical `video_vast` and `audio_vast` manifest paths; optional only on the deprecated named-format compatibility path. Receivers MUST NOT relabel or synthesize a newer version merely because the destination accepts it.'
        ),
    ] = None
    macro_declarations: Annotated[
        list[MacroDeclaration1] | None,
        Field(
            description='One declaration per exact occurrence in a field carried by this asset. A URL-delivered asset can declare only occurrences in its locator `url`; tokens discovered later in a fetched VAST response require document validation evidence or an inline/snapshotted asset and MUST NOT be guessed from the locator. IAB tokens cite a registry namespace and revision rather than copying the live registry into AdCP.',
            min_length=1,
        ),
    ] = None
    vpaid_enabled: Annotated[
        StrictBool | None,
        Field(description='Whether VPAID (Video Player-Ad Interface Definition) is supported'),
    ] = None
    duration_ms: Annotated[
        SchemaInt | None,
        Field(description='Expected media duration in milliseconds (if known)', ge=0),
    ] = None
    tracking_events: Annotated[
        list[VastTrackingEvent] | None,
        Field(description='Tracking events supported by this VAST tag'),
    ] = None
    captions_url: Annotated[
        AnyUrl | None, Field(description='URL to captions file (WebVTT, SRT, etc.)')
    ] = None
    audio_description_url: Annotated[
        AnyUrl | None,
        Field(description='URL to audio description track for visually impaired users'),
    ] = None
    provenance: Annotated[
        Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None
    delivery_type: Annotated[
        Literal['inline'],
        Field(description='Discriminator indicating VAST is delivered as inline XML content'),
    ] = 'inline'
    content: Annotated[str, Field(description='Inline VAST XML content')]

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

Class variables

var asset_type : Literal['vast']

var audio_description_url : pydantic.networks.AnyUrl | None

var captions_url : pydantic.networks.AnyUrl | None

var content : str

var delivery_type : Literal['inline']

var duration_ms : int | None

var macro_declarations : list[MacroDeclaration1] | None

var model_config

var provenance : Provenance | None

var tracking_events : list[VastTrackingEvent] | None

var vast_version : VastVersion | None

var vpaid_enabled : bool | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VastTrackerAsset (**data: Any)

Expand source code

class VastTrackerAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['vast_tracker'],
        Field(
            description='Discriminator identifying this as a VAST tracker asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'vast_tracker'
    vast_event: Annotated[
        vast_tracking_event.VastTrackingEvent,
        Field(
            description='The VAST tracking event this URL fires on. Maps 1:1 to the VAST `Tracking event="..."` attribute inside `TrackingEvents`. MUST NOT be `impression` (belongs in the VAST `Impression` element — model as a `url` asset with `url_type: "tracker_pixel"`), `clickTracking` / `customClick` (belong in `VideoClicks`), `error` (VAST `Error` element), or any of `viewable` / `notViewable` / `viewUndetermined` / `measurableImpression` / `viewableImpression` (children of the VAST `ViewableImpression` element, not `TrackingEvents`).'
        ),
    ]
    url: Annotated[
        macro_bearing_url.MacroBearingUrl,
        Field(
            description='Tracker URL fired for the VAST event. Attached declarations identify each macro occurrence, registry revision, processing actor, and exact encoding profile.'
        ),
    ]
    macro_declarations: Annotated[
        list[MacroDeclaration] | None,
        Field(
            description='Exact tokens in `url` and their resolver/encoding contracts.', min_length=1
        ),
    ] = None
    offset: Annotated[
        str | None,
        Field(
            description='VAST `offset` attribute. Required when `vast_event` is `progress`; ignored otherwise for compatibility with existing 3.x manifests. Format matches the VAST 4.2 XSD `Tracking@offset` pattern: `HH:MM:SS` or `HH:MM:SS.mmm` for absolute time (two-digit hours, minutes 00–59, seconds 00–59), or an integer percentage 0–100 suffixed with `%`. Negative offsets are NOT permitted — the VAST 4.2 XSD pattern does not allow a leading minus.',
            pattern='^(\\d{2}:[0-5]\\d:[0-5]\\d(\\.\\d{3})?|(100|\\d{1,2})%)$',
        ),
    ] = None
    target: Annotated[
        Target | None,
        Field(
            description='Which VAST creative element this tracker scopes to — `linear` for `<Linear>/<TrackingEvents>`, `non_linear` for `<NonLinearAds>/<TrackingEvents>`, `companion` for `<CompanionAds>/<Companion>/<TrackingEvents>`. Defaults to `linear`. Existing 3.x assets remain structurally permissive; a tracker execution contract applies the standards-valid event/target matrix when matching a creative to a product.'
        ),
    ] = Target.linear
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance.'
        ),
    ] = 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

Class variables

var asset_type : Literal['vast_tracker']

var macro_declarations : list[MacroDeclaration] | None

var model_config

var offset : str | None

var provenance : Provenance | None

var target : Target | None

var url : str | MacroBearingUrl3 | MacroBearingUrl4

var vast_event : VastTrackingEvent

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VastTrackingEvent (*args, **kwds)

Expand source code

class VastTrackingEvent(StrEnum):
    impression = 'impression'
    creativeView = 'creativeView'
    loaded = 'loaded'
    start = 'start'
    firstQuartile = 'firstQuartile'
    midpoint = 'midpoint'
    thirdQuartile = 'thirdQuartile'
    complete = 'complete'
    mute = 'mute'
    unmute = 'unmute'
    pause = 'pause'
    resume = 'resume'
    rewind = 'rewind'
    skip = 'skip'
    playerExpand = 'playerExpand'
    playerCollapse = 'playerCollapse'
    fullscreen = 'fullscreen'
    exitFullscreen = 'exitFullscreen'
    progress = 'progress'
    acceptInvitation = 'acceptInvitation'
    adExpand = 'adExpand'
    adCollapse = 'adCollapse'
    minimize = 'minimize'
    overlayViewDuration = 'overlayViewDuration'
    otherAdInteraction = 'otherAdInteraction'
    interactiveStart = 'interactiveStart'
    clickTracking = 'clickTracking'
    customClick = 'customClick'
    close = 'close'
    closeLinear = 'closeLinear'
    error = 'error'
    viewable = 'viewable'
    notViewable = 'notViewable'
    viewUndetermined = 'viewUndetermined'
    measurableImpression = 'measurableImpression'
    viewableImpression = 'viewableImpression'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var acceptInvitation

var adCollapse

var adExpand

var clickTracking

var close

var closeLinear

var complete

var creativeView

var customClick

var error

var exitFullscreen

var firstQuartile

var fullscreen

var impression

var interactiveStart

var loaded

var measurableImpression

var midpoint

var minimize

var mute

var notViewable

var otherAdInteraction

var overlayViewDuration

var pause

var playerCollapse

var playerExpand

var progress

var resume

var rewind

var skip

var start

var thirdQuartile

var unmute

var viewUndetermined

var viewable

var viewableImpression

class TrackingEvent (*args, **kwds)

Expand source code

class VastTrackingEvent(StrEnum):
    impression = 'impression'
    creativeView = 'creativeView'
    loaded = 'loaded'
    start = 'start'
    firstQuartile = 'firstQuartile'
    midpoint = 'midpoint'
    thirdQuartile = 'thirdQuartile'
    complete = 'complete'
    mute = 'mute'
    unmute = 'unmute'
    pause = 'pause'
    resume = 'resume'
    rewind = 'rewind'
    skip = 'skip'
    playerExpand = 'playerExpand'
    playerCollapse = 'playerCollapse'
    fullscreen = 'fullscreen'
    exitFullscreen = 'exitFullscreen'
    progress = 'progress'
    acceptInvitation = 'acceptInvitation'
    adExpand = 'adExpand'
    adCollapse = 'adCollapse'
    minimize = 'minimize'
    overlayViewDuration = 'overlayViewDuration'
    otherAdInteraction = 'otherAdInteraction'
    interactiveStart = 'interactiveStart'
    clickTracking = 'clickTracking'
    customClick = 'customClick'
    close = 'close'
    closeLinear = 'closeLinear'
    error = 'error'
    viewable = 'viewable'
    notViewable = 'notViewable'
    viewUndetermined = 'viewUndetermined'
    measurableImpression = 'measurableImpression'
    viewableImpression = 'viewableImpression'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var acceptInvitation

var adCollapse

var adExpand

var clickTracking

var close

var closeLinear

var complete

var creativeView

var customClick

var error

var exitFullscreen

var firstQuartile

var fullscreen

var impression

var interactiveStart

var loaded

var measurableImpression

var midpoint

var minimize

var mute

var notViewable

var otherAdInteraction

var overlayViewDuration

var pause

var playerCollapse

var playerExpand

var progress

var resume

var rewind

var skip

var start

var thirdQuartile

var unmute

var viewUndetermined

var viewable

var viewableImpression

class VastVersion (*args, **kwds)

Expand source code

class VastVersion(StrEnum):
    field_2_0 = '2.0'
    field_3_0 = '3.0'
    field_4_0 = '4.0'
    field_4_1 = '4.1'
    field_4_2 = '4.2'
    field_4_3 = '4.3'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var field_2_0

var field_3_0

var field_4_0

var field_4_1

var field_4_2

var field_4_3

class VcpmPricingOption (**data: Any)

Expand source code

class VcpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ] = 'vcpm'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['vcpm']

var pricing_option_id : str

class VcpmAuctionPricingOption (**data: Any)

Expand source code

class VcpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ] = 'vcpm'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['vcpm']

var pricing_option_id : str

class VcpmFixedRatePricingOption (**data: Any)

Expand source code

class VcpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ] = 'vcpm'
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        StrictFloat | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        StrictBool | None,
        Field(
            deprecated=True,
            description='DEPRECATED in 3.2 and removed in the next major. Legacy hint used only to normalize package bid_price to bidding.max_bid (true) or bidding.bid_amount (false/absent). New buyers express intent directly in bidding.',
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        StrictFloat | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = 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

Class variables

var currency : str

var eligible_adjustments : list[PriceAdjustmentKind] | None

var fixed_price : float | None

var floor_price : float | None

var max_bid : bool | None

var min_spend_per_package : float | None

var model_config

var price_breakdown : PriceBreakdown | None

var price_guidance : PriceGuidance | None

var pricing_model : Literal['vcpm']

var pricing_option_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VendorErrorCodeRegistry (**data: Any)

Expand source code

class VendorErrorCodeRegistry(AdCPBaseModel):
    vendors: Annotated[
        dict[str, Vendors] | None,
        Field(description='Map of vendor prefix to vendor metadata and codes'),
    ] = 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

Class variables

var model_config

var vendors : dict[str, Vendors] | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CpmVendorPricingOption (**data: Any)

Expand source code

class VendorPricingOption1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    model: Literal['cpm'] = 'cpm'
    cpm: Annotated[StrictFloat, Field(description='Cost per thousand impressions', ge=0.0)]
    currency: Annotated[str, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')]
    ext: ext_1.ExtensionObject | None = 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

• VendorPricingOption7

Class variables

var cpm : float

var currency : str

var ext : ExtensionObject | None

var model : Literal['cpm']

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PercentOfMediaVendorPricingOption (**data: Any)

Expand source code

class VendorPricingOption2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    model: Literal['percent_of_media'] = 'percent_of_media'
    percent: Annotated[
        StrictFloat, Field(description='Percentage of media spend, e.g. 15 = 15%', ge=0.0, le=100.0)
    ]
    max_cpm: Annotated[
        StrictFloat | None,
        Field(
            description='Optional CPM cap. When set, the effective charge is min(percent × media_spend_per_mille, max_cpm).',
            ge=0.0,
        ),
    ] = None
    currency: Annotated[
        str,
        Field(description='ISO 4217 currency code for the resulting charge', pattern='^[A-Z]{3}$'),
    ]
    ext: ext_1.ExtensionObject | None = 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

• VendorPricingOption8

Class variables

var currency : str

var ext : ExtensionObject | None

var max_cpm : float | None

var model : Literal['percent_of_media']

var model_config

var percent : float

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class FlatFeeVendorPricingOption (**data: Any)

Expand source code

class VendorPricingOption3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    model: Literal['flat_fee'] = 'flat_fee'
    amount: Annotated[StrictFloat, Field(description='Fixed charge for the billing period', ge=0.0)]
    period: Annotated[Period, Field(description='Billing period for the flat fee.')]
    currency: Annotated[str, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')]
    ext: ext_1.ExtensionObject | None = 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

• VendorPricingOption9

Class variables

var amount : float

var currency : str

var ext : ExtensionObject | None

var model : Literal['flat_fee']

var model_config

var period : Period

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class PerUnitVendorPricingOption (**data: Any)

Expand source code

class VendorPricingOption4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    model: Literal['per_unit'] = 'per_unit'
    unit: Annotated[
        str,
        Field(
            description="What is counted — e.g. 'format', 'image', 'token', 'variant', 'render', 'evaluation'."
        ),
    ]
    unit_price: Annotated[StrictFloat, Field(description='Cost per one unit', ge=0.0)]
    currency: Annotated[str, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')]
    ext: ext_1.ExtensionObject | None = 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

• VendorPricingOption10

Class variables

var currency : str

var ext : ExtensionObject | None

var model : Literal['per_unit']

var model_config

var unit : str

var unit_price : float

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CustomVendorPricingOption (**data: Any)

Expand source code

class VendorPricingOption5(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    model: Literal['custom'] = 'custom'
    description: Annotated[
        str,
        Field(
            description='Human-readable description of the custom pricing model. Buyers display this to the operator when requesting approval.',
            min_length=1,
        ),
    ]
    metadata: Annotated[
        Metadata,
        Field(
            description="Structured parameters for the custom model. Keys follow lowercase_snake_case. Values may be primitives, arrays, or nested objects. Must be sufficient for a human to understand the pricing basis and for a downstream system to reconstruct the charge. Vendors SHOULD include a `summary_for_operator` string (one or two sentences, suitable for display in a buyer's operator-review UI) so reviewers across vendors see a consistent prompt. Required operator-review fields (approver role, dollar threshold for automatic approval, escalation contact) MAY be surfaced via additional keys the buyer's review surface recognizes."
        ),
    ]
    currency: Annotated[
        str | None,
        Field(
            description='ISO 4217 currency code. Present when the pricing resolves to a monetary charge in a specific currency.',
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = 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

• VendorPricingOption11

Class variables

var currency : str | None

var description : str

var ext : ExtensionObject | None

var metadata : Metadata

var model : Literal['custom']

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VenueBreakdownItem (**data: Any)

Expand source code

class VenueBreakdownItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    venue_id: Annotated[str, Field(description='Venue identifier')]
    venue_name: Annotated[str | None, Field(description='Human-readable venue name')] = None
    venue_type: Annotated[
        str | None,
        Field(description="Venue type (e.g., 'airport', 'transit', 'retail', 'billboard')"),
    ] = None
    impressions: Annotated[
        SchemaInt, Field(description='Impressions delivered at this venue', ge=0)
    ]
    loop_plays: Annotated[SchemaInt | None, Field(description='Loop plays at this venue', ge=0)] = (
        None
    )
    screens_used: Annotated[
        SchemaInt | None, Field(description='Number of screens used at this venue', ge=0)
    ] = 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

Class variables

var impressions : int

var loop_plays : int | None

var model_config

var screens_used : int | None

var venue_id : str

var venue_name : str | None

var venue_type : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimPayload (**data: Any)

Expand source code

class VerifyBrandClaimPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    typ: Annotated[
        Literal['adcp-response-payload+jws'],
        Field(description='Type discriminator preventing cross-profile replay.'),
    ]
    task: Annotated[
        Literal['verify_brand_claim'],
        Field(description='Designated task whose response payload is signed.'),
    ]
    brand_domain: Annotated[
        str,
        Field(
            description='Brand tenant whose policy store produced the answer. The signer MUST derive this from server-side tenant resolution, not caller-supplied request fields.',
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    agent_url: Annotated[
        AnyUrl,
        Field(
            description='Canonical URL of the responding brand agent entry whose response-signing key verifies this envelope.'
        ),
    ]
    request_hash: Annotated[
        str,
        Field(
            description='sha256: prefix plus unpadded base64url SHA-256 of the canonical request-binding object for this call.',
            pattern='^sha256:[A-Za-z0-9_-]{43}$',
        ),
    ]
    iat: Annotated[int, Field(description='Issued-at time as Unix epoch seconds.', ge=0)]
    exp: Annotated[
        int,
        Field(
            description='Expiration time as Unix epoch seconds. Online verifiers reject envelopes after this time, allowing only implementation-defined clock skew.',
            ge=0,
        ),
    ]
    response: VerifyBrandClaimSignedSuccessPayload

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

Class variables

var agent_url : pydantic.networks.AnyUrl

var brand_domain : str

var exp : int

var iat : int

var model_config

var request_hash : str

var response : VerifyBrandClaimSignedSuccessPayload

var task : Literal['verify_brand_claim']

var typ : Literal['adcp-response-payload+jws']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimRequest (**data: Any)

Expand source code

class VerifyBrandClaimRequest(AdcpRequest, AdcpVersionEnvelope):
    claim_type: ClaimType
    claim: dict[str, Any]

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> VerifyBrandClaimRequest:
        # ``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 (('claim_type', 'claim'),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'VerifyBrandClaimRequest requires at least one of these field groups: claim_type+claim'
        )

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 claim : dict[str, typing.Any]

var claim_type : ClaimType

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 VerifyBrandClaimSignedResponse (**data: Any)

Expand source code

class VerifyBrandClaimSignedResponse(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[
        VerifyBrandClaimPayload,
        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.

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

Class variables

var model_config

var payload : VerifyBrandClaimPayload

var protected : str

var signature : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimSignedSuccessPayload (**data: Any)

Expand source code

class VerifyBrandClaimSignedSuccessPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    claim_type: ClaimType
    verification_status: verification_status.VerificationStatus
    details: dict[str, Any] | None = None
    context_note: Annotated[str | None, Field(max_length=500)] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var claim_type : ClaimType

var context : ContextObject | None

var context_note : str | None

var details : dict[str, typing.Any] | None

var ext : ExtensionObject | None

var model_config

var verification_status : VerificationStatus

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimsErrorResponse (**data: Any)

Expand source code

class VerifyBrandClaimsErrorResponse(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[list[error_1.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

• AdcpVersionEnvelope
• ProtocolEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var context : ContextObject | None

var errors : list[Error]

var ext : ExtensionObject | None

var model_config

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimsPayload (**data: Any)

Expand source code

class VerifyBrandClaimsPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    typ: Annotated[
        Literal['adcp-response-payload+jws'],
        Field(description='Type discriminator preventing cross-profile replay.'),
    ]
    task: Annotated[
        Literal['verify_brand_claims'],
        Field(description='Designated task whose response payload is signed.'),
    ]
    brand_domain: Annotated[
        str,
        Field(
            description='Brand tenant whose policy store produced the answer. The signer MUST derive this from server-side tenant resolution, not caller-supplied request fields.',
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    agent_url: Annotated[
        AnyUrl,
        Field(
            description='Canonical URL of the responding brand agent entry whose response-signing key verifies this envelope.'
        ),
    ]
    request_hash: Annotated[
        str,
        Field(
            description='sha256: prefix plus unpadded base64url SHA-256 of the canonical request-binding object for this call.',
            pattern='^sha256:[A-Za-z0-9_-]{43}$',
        ),
    ]
    iat: Annotated[int, Field(description='Issued-at time as Unix epoch seconds.', ge=0)]
    exp: Annotated[
        int,
        Field(
            description='Expiration time as Unix epoch seconds. Online verifiers reject envelopes after this time, allowing only implementation-defined clock skew.',
            ge=0,
        ),
    ]
    response: VerifyBrandClaimsSignedSuccessPayload

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

Class variables

var agent_url : pydantic.networks.AnyUrl

var brand_domain : str

var exp : int

var iat : int

var model_config

var request_hash : str

var response : VerifyBrandClaimsSignedSuccessPayload

var task : Literal['verify_brand_claims']

var typ : Literal['adcp-response-payload+jws']

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimsRequest (**data: Any)

Expand source code

class VerifyBrandClaimsRequest(VerifyBrandClaimsRequestBulk):
    pass

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

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

Class variables

var model_config

Inherited members

• VerifyBrandClaimsRequestBulk:
  • get_account
  • get_adcp_major_version
  • get_adcp_version
  • get_context
  • get_idempotency_key
  • get_push_notification_config
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimsRequestBulk (**data: Any)

Expand source code

class VerifyBrandClaimsRequestBulk(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    claims: Annotated[
        list[ClaimEntry],
        Field(
            description='Ordered list of verification claims. The agent MUST return `results[]` in the same order (positional zip-by-index). Maximum batch size is 100 per call; agents MAY enforce a lower limit and SHOULD advertise it via `get_adcp_capabilities` (see the task page).',
            max_length=100,
            min_length=1,
        ),
    ]

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

Subclasses

• VerifyBrandClaimsRequest

Class variables

var claims : list[ClaimEntry1 | ClaimEntry2 | ClaimEntry3 | ClaimEntry4]

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 VerifyBrandClaimsResponseBulk (**data: Any)

Expand source code

class VerifyBrandClaimsResponseBulk(AdcpResponse, AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    results: Annotated[
        list[ResultEntry],
        Field(
            description="Per-claim results, positionally aligned with the request's claims.",
            min_length=1,
        ),
    ]
    signed_response: Annotated[
        VerifyBrandClaimsSignedResponse,
        Field(
            description='Payload-envelope JWS attesting the canonical bulk success response for verify_brand_claims. The signed payload response MUST match the unsigned task-body fields on this response, excluding signed_response and protocol/version envelope fields.'
        ),
    ]
    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.

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 context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var results : list[ResultEntry]

var signed_response : VerifyBrandClaimsSignedResponse

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 VerifyBrandClaimsSignedResponse (**data: Any)

Expand source code

class VerifyBrandClaimsSignedResponse(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[
        VerifyBrandClaimsPayload,
        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.

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

Class variables

var model_config

var payload : VerifyBrandClaimsPayload

var protected : str

var signature : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VerifyBrandClaimsSignedSuccessPayload (**data: Any)

Expand source code

class VerifyBrandClaimsSignedSuccessPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    results: Annotated[list[ResultEntry], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = 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

Class variables

var context : ContextObject | None

var ext : ExtensionObject | None

var model_config

var results : list[ResultEntry]

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class VersionUnsupportedDetails (**data: Any)

Expand source code

class VersionUnsupportedDetails(AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    supported_versions: Annotated[
        list[SupportedVersion],
        Field(
            description='Release-precision versions the seller speaks. Authoritative — buyers SHOULD select a value from this list and retry.',
            examples=[['3.0', '3.1']],
            min_length=1,
        ),
    ]
    supported_majors: Annotated[
        list[SupportedMajor] | None,
        Field(
            deprecated=True,
            description='DEPRECATED in favor of `supported_versions`. Major versions the seller supports. Servers SHOULD emit both through 3.x; removed in 4.0.',
        ),
    ] = None
    build_version: Annotated[
        str | None,
        Field(
            description="Optional advisory: full semver build identifier of the seller's deployment (MAJOR.MINOR.PATCH plus optional pre-release and build-metadata segments per semver §9–§10), for incident triage. Buyers MUST NOT use this field for negotiation.",
            examples=[
                '3.1.2',
                '3.1.0-beta.3',
                '3.1.2+scope3.deploy.4821',
                '3.1.0-beta.3+sha.a1b2c3d',
            ],
            pattern='^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$',
        ),
    ] = 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

• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var build_version : str | None

var model_config

var supported_majors : list[SupportedMajor] | None

var supported_versions : list[SupportedVersion]

Inherited members

• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class VideoContent (**data: Any)

Expand source code

class VideoAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['video'],
        Field(
            description='Discriminator identifying this as a video asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'video'
    url: Annotated[AnyUrl, Field(description='URL to the video asset')]
    width: Annotated[
        SchemaInt,
        Field(
            description="Width in pixels — the video file's intrinsic native width. Required: a hosted file always has concrete dimensions. (Tag-delivered video carries no width; see the `vast` asset.)",
            ge=1,
        ),
    ]
    height: Annotated[
        SchemaInt,
        Field(
            description="Height in pixels — the video file's intrinsic native height. Required: a hosted file always has concrete dimensions. (Tag-delivered video carries no height; see the `vast` asset.)",
            ge=1,
        ),
    ]
    duration_ms: Annotated[
        SchemaInt | None, Field(description='Video duration in milliseconds', ge=1)
    ] = None
    file_size_bytes: Annotated[SchemaInt | None, Field(description='File size in bytes', ge=1)] = (
        None
    )
    container_format: Annotated[
        str | None, Field(description='Video container format (mp4, webm, mov, etc.)')
    ] = None
    video_codec: Annotated[
        str | None, Field(description='Video codec used (h264, h265, vp9, av1, prores, etc.)')
    ] = None
    video_bitrate_kbps: Annotated[
        SchemaInt | None, Field(description='Video stream bitrate in kilobits per second', ge=1)
    ] = None
    frame_rate: Annotated[
        str | None,
        Field(
            description="Frame rate as string to preserve precision (e.g., '23.976', '29.97', '30')"
        ),
    ] = None
    frame_rate_type: frame_rate_type_1.FrameRateType | None = None
    scan_type: scan_type_1.ScanType | None = None
    color_space: Annotated[ColorSpace | None, Field(description='Color space of the video')] = None
    hdr_format: Annotated[
        HdrFormat | None,
        Field(description="HDR format if applicable, or 'sdr' for standard dynamic range"),
    ] = None
    chroma_subsampling: Annotated[
        ChromaSubsampling | None, Field(description='Chroma subsampling format')
    ] = None
    video_bit_depth: Annotated[VideoBitDepth | None, Field(description='Video bit depth')] = None
    gop_interval_seconds: Annotated[
        StrictFloat | None, Field(description='GOP/keyframe interval in seconds')
    ] = None
    gop_type: gop_type_1.GopType | None = None
    moov_atom_position: moov_atom_position_1.MoovAtomPosition | None = None
    has_audio: Annotated[
        StrictBool | None, Field(description='Whether the video contains an audio track')
    ] = None
    audio_codec: Annotated[
        str | None,
        Field(description='Audio codec used (aac, aac_lc, he_aac, pcm, mp3, ac3, eac3, etc.)'),
    ] = None
    audio_sampling_rate_hz: Annotated[
        SchemaInt | None, Field(description='Audio sampling rate in Hz (e.g., 44100, 48000)')
    ] = None
    audio_channels: Annotated[
        audio_channel_layout.AudioChannelLayout | None,
        Field(description='Audio channel configuration'),
    ] = None
    audio_bit_depth: Annotated[AudioBitDepth | None, Field(description='Audio bit depth')] = None
    audio_bitrate_kbps: Annotated[
        SchemaInt | None, Field(description='Audio bitrate in kilobits per second', ge=1)
    ] = None
    audio_loudness_lufs: Annotated[
        StrictFloat | None, Field(description='Integrated loudness in LUFS')
    ] = None
    audio_true_peak_dbfs: Annotated[
        StrictFloat | None, Field(description='True peak level in dBFS')
    ] = None
    captions_url: Annotated[
        AnyUrl | None, Field(description='URL to captions file (WebVTT, SRT, etc.)')
    ] = None
    transcript_url: Annotated[
        AnyUrl | None, Field(description='URL to text transcript of the video content')
    ] = None
    audio_description_url: Annotated[
        AnyUrl | None,
        Field(description='URL to audio description track for visually impaired users'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var asset_type : Literal['video']

var audio_bit_depth : AudioBitDepth | None

var audio_bitrate_kbps : int | None

var audio_channels : AudioChannelLayout | None

var audio_codec : str | None

var audio_description_url : pydantic.networks.AnyUrl | None

var audio_loudness_lufs : float | None

var audio_sampling_rate_hz : int | None

var audio_true_peak_dbfs : float | None

var captions_url : pydantic.networks.AnyUrl | None

var chroma_subsampling : ChromaSubsampling | None

var color_space : ColorSpace | None

var container_format : str | None

var duration_ms : int | None

var file_size_bytes : int | None

var frame_rate : str | None

var frame_rate_type : FrameRateType | None

var gop_interval_seconds : float | None

var gop_type : GopType | None

var has_audio : bool | None

var hdr_format : HdrFormat | None

var height : int

var model_config

var moov_atom_position : MoovAtomPosition | None

var provenance : Provenance | None

var scan_type : ScanType | None

var transcript_url : pydantic.networks.AnyUrl | None

var url : pydantic.networks.AnyUrl

var video_bit_depth : VideoBitDepth | None

var video_bitrate_kbps : int | None

var video_codec : str | None

var width : int

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ViewThreshold (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class ViewThreshold(ScalarFloat):
    __slots__ = ()
    _constraints = {'ge': 0.0, 'le': 1.0}
    _json_schema_extra = {
        'description': 'Percentage completion threshold (0.0 to 1.0, e.g., 0.5 = 50%)',
    }

A float generated from a JSON Schema number root.

Strict, like the StrictFloat the generator emits for a type: number field: an int or float is accepted, a bool or numeric string is refused, matching the bundled JSON Schema validator.

Ancestors

• adcp.types._scalar.ScalarFloat
• adcp.types._scalar._ScalarRoot
• builtins.float

class WcagLevel (*args, **kwds)

Expand source code

class WcagLevel(StrEnum):
    A = 'A'
    AA = 'AA'
    AAA = 'AAA'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var A

var AA

var AAA

class WebhookContent (**data: Any)

Expand source code

class WebhookAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['webhook'],
        Field(
            description='Discriminator identifying this as a webhook asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'webhook'
    url: Annotated[AnyUrl, Field(description='Webhook URL to call for dynamic content')]
    method: Annotated[http_method.HttpMethod | None, Field(description='HTTP method')] = (
        http_method.HttpMethod.POST
    )
    timeout_ms: Annotated[
        SchemaInt | None,
        Field(description='Maximum time to wait for response in milliseconds', ge=10, le=5000),
    ] = 500
    supported_macros: Annotated[
        list[universal_macro.UniversalMacro | str] | None,
        Field(
            description='Universal macros that can be passed to webhook (e.g., DEVICE_TYPE, COUNTRY). See docs/creative/universal-macros.mdx for full list.'
        ),
    ] = None
    required_macros: Annotated[
        list[universal_macro.UniversalMacro | str] | None,
        Field(description='Universal macros that must be provided for webhook to function'),
    ] = None
    response_type: Annotated[
        webhook_response_type.WebhookResponseType,
        Field(description='Expected content type of webhook response'),
    ]
    security: Annotated[Security, Field(description='Security configuration for webhook calls')]
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var asset_type : Literal['webhook']

var method : HttpMethod | None

var model_config

var provenance : Provenance | None

var required_macros : list[UniversalMacro | str] | None

var response_type : WebhookResponseType

var security : Security

var supported_macros : list[UniversalMacro | str] | None

var timeout_ms : int | None

var url : pydantic.networks.AnyUrl

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

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.

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

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.

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

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

class ResponseType (*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

class WholesaleFeedWebhook (**data: Any)

Expand source code

class WholesaleFeedWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    idempotency_key: Annotated[
        str,
        Field(
            description='Sender-generated key stable across retries of the same webhook 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[
        UUID,
        Field(
            description='Stable identifier for this logical wholesale feed event. MUST equal event.event_id. Re-emissions of the same logical event reuse this value under a new idempotency_key.'
        ),
    ]
    notification_type: Annotated[
        NotificationType,
        Field(
            description='Wholesale feed notification type discriminator. MUST match event.event_type.'
        ),
    ]
    fired_at: Annotated[
        AwareDatetime,
        Field(
            description='ISO 8601 timestamp when the seller initiated this webhook fire. Distinct from event.created_at, which is when the seller observed or recorded the feed change.'
        ),
    ]
    subscriber_id: Annotated[
        str,
        Field(
            description='Identifies which notification_configs[] entry is receiving this fire. Echoed from the registered subscriber_id.',
            max_length=64,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,64}$',
        ),
    ]
    account_id: Annotated[
        str,
        Field(
            description='Seller account identifier for the account scope that registered this webhook through sync_accounts.accounts[].notification_configs[]. Required because wholesale feed webhooks are account-anchored notifications.'
        ),
    ]
    wholesale_feed_version: Annotated[
        str,
        Field(
            description='Opaque post-change version token for the affected wholesale feed. Store it only after applying the event. A stale mirror repairs with its last applied version; uncertain or bulk repair omits the conditional token.'
        ),
    ]
    product_payload_view: Annotated[
        ProductPayloadView | None,
        Field(
            description='Product representation selected by the receiving notification config. Present on product.* fires; canonical uses canonical_product/canonical_pricing_options and legacy uses product/pricing_options.'
        ),
    ] = None
    previous_wholesale_feed_version: Annotated[
        str | None,
        Field(
            description='Opaque version token for the affected wholesale feed before this change, when the seller can cheaply provide it. Receivers MAY use this to detect obvious gaps, but MUST NOT require it.'
        ),
    ] = None
    cache_scope: Annotated[
        CacheScope,
        Field(
            description='Cache layer affected by this change. MUST equal event.payload.applies_to.scope. Mirrors the cache_scope returned by list_products / get_signals for the affected wholesale feed.'
        ),
    ]
    event: Annotated[
        wholesale_feed_event.WholesaleFeedEvent,
        Field(
            description='The actual product, signal, or bulk-change event. Consumers MAY apply this payload to their local mirror. Before any binding action, or when ordering/gap checks fail, consumers MUST reconcile through list_products / get_signals.'
        ),
    ]
    ext: ext_1.ExtensionObject | None = 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

Class variables

var account_id : str

var cache_scope : CacheScope

var event : WholesaleFeedEvent1 | WholesaleFeedEvent2 | WholesaleFeedEvent3 | WholesaleFeedEvent4 | WholesaleFeedEvent5 | WholesaleFeedEvent6 | WholesaleFeedEvent7 | WholesaleFeedEvent8 | WholesaleFeedEvent9

var ext : ExtensionObject | None

var fired_at : pydantic.types.AwareDatetime

var idempotency_key : str

var model_config

var notification_id : uuid.UUID

var notification_type : NotificationType

var previous_wholesale_feed_version : str | None

var product_payload_view : ProductPayloadView | None

var subscriber_id : str

var wholesale_feed_version : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ZipAsset (**data: Any)

Expand source code

class ZipAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_type: Annotated[
        Literal['zip'],
        Field(
            description='Discriminator identifying this as a zip-bundled asset. See /schemas/creative/asset-types for the registry.'
        ),
    ] = 'zip'
    url: Annotated[AnyUrl, Field(description='URL where the zip archive is hosted. Must be HTTPS.')]
    max_file_size_kb: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum file size in kilobytes. Receivers should reject zips exceeding this.',
            ge=0,
        ),
    ] = None
    entry_point: Annotated[
        str | None,
        Field(
            description="Relative path to the entry file within the zip (typically 'index.html'). Receivers default to 'index.html' if absent."
        ),
    ] = None
    allowed_inner_extensions: Annotated[
        list[str] | None,
        Field(
            description="File extensions permitted inside the zip (e.g., ['html', 'css', 'js', 'png', 'jpg', 'svg', 'webp', 'json', 'woff2']). Receivers may reject zips containing other extensions."
        ),
    ] = None
    backup_image_url: Annotated[
        AnyUrl | None,
        Field(
            description='Fallback image URL for environments that cannot render the bundled creative (e.g., non-HTML5 endpoints, ad blockers). Recommended for HTML5 banners.'
        ),
    ] = None
    digest: Annotated[
        str | None,
        Field(
            description='Optional SHA-256 content digest of the zip archive (sha256:<hex>) for integrity verification. Lets receivers detect tampered or stale archives.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ] = None
    accessibility: Annotated[
        Accessibility | None,
        Field(description='Self-declared accessibility properties for this opaque creative'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = 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

Class variables

var accessibility : Accessibility | None

var allowed_inner_extensions : list[str] | None

var asset_type : Literal['zip']

var backup_image_url : pydantic.networks.AnyUrl | None

var digest : str | None

var entry_point : str | None

var max_file_size_kb : int | None

var model_config

var provenance : Provenance | None

var url : pydantic.networks.AnyUrl

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary