Module `adcp.types.domains.media_buy`

Types the AdCP media_buy schemas declare.

Importing from the domain says which variant you mean, where the flat adcp.types namespace can only bind one class per name:

from adcp.types.domains.media_buy import <Type>

A type this domain declares in more than one schema is not here: import it from its own schema's module, adcp.types.domains.media_buy.<schema>. Nothing here is renamed.

Auto-generated from the generated domain tree. DO NOT EDIT MANUALLY. Generation date: 2026-10-04 18:45:11 UTC

Sub-modules

adcp.types.domains.media_buy.accept_proposal_async_response_input_required
adcp.types.domains.media_buy.accept_proposal_async_response_submitted
adcp.types.domains.media_buy.accept_proposal_async_response_working
adcp.types.domains.media_buy.accept_proposal_request
adcp.types.domains.media_buy.accept_proposal_response
adcp.types.domains.media_buy.acceptance_context
adcp.types.domains.media_buy.acceptance_policy_catalog
adcp.types.domains.media_buy.acceptance_policy_profile
adcp.types.domains.media_buy.acceptance_policy_profile_ref
adcp.types.domains.media_buy.acceptance_policy_requirement
adcp.types.domains.media_buy.acceptance_policy_rule
adcp.types.domains.media_buy.build_creative_async_response_input_required
adcp.types.domains.media_buy.build_creative_async_response_submitted
adcp.types.domains.media_buy.build_creative_async_response_working
adcp.types.domains.media_buy.build_creative_request
adcp.types.domains.media_buy.build_creative_response
adcp.types.domains.media_buy.buy_products_async_response_input_required
adcp.types.domains.media_buy.buy_products_async_response_submitted
adcp.types.domains.media_buy.buy_products_async_response_working
adcp.types.domains.media_buy.buy_products_request
adcp.types.domains.media_buy.buy_products_response
adcp.types.domains.media_buy.change_term
adcp.types.domains.media_buy.change_term_constraints
adcp.types.domains.media_buy.commercial_terms
adcp.types.domains.media_buy.control_media_buy_async_response_input_required
adcp.types.domains.media_buy.control_media_buy_async_response_submitted
adcp.types.domains.media_buy.control_media_buy_async_response_working
adcp.types.domains.media_buy.control_media_buy_request
adcp.types.domains.media_buy.control_media_buy_response
adcp.types.domains.media_buy.create_media_buy_async_response_input_required
adcp.types.domains.media_buy.create_media_buy_async_response_submitted
adcp.types.domains.media_buy.create_media_buy_async_response_working
adcp.types.domains.media_buy.create_media_buy_request
adcp.types.domains.media_buy.create_media_buy_response
adcp.types.domains.media_buy.decline_proposals_async_response_input_required
adcp.types.domains.media_buy.decline_proposals_async_response_submitted
adcp.types.domains.media_buy.decline_proposals_async_response_working
adcp.types.domains.media_buy.decline_proposals_request
adcp.types.domains.media_buy.decline_proposals_response
adcp.types.domains.media_buy.get_media_buy_delivery_request
adcp.types.domains.media_buy.get_media_buy_delivery_response
adcp.types.domains.media_buy.get_media_buys_request
adcp.types.domains.media_buy.get_media_buys_response
adcp.types.domains.media_buy.get_products_async_response_input_required
adcp.types.domains.media_buy.get_products_async_response_submitted
adcp.types.domains.media_buy.get_products_async_response_working
adcp.types.domains.media_buy.get_products_rejected
adcp.types.domains.media_buy.get_products_request
adcp.types.domains.media_buy.get_products_response
adcp.types.domains.media_buy.get_products_targeting_resolution
adcp.types.domains.media_buy.get_reporting_status_request
adcp.types.domains.media_buy.get_reporting_status_response
adcp.types.domains.media_buy.legacy_purchase_continuation_input
adcp.types.domains.media_buy.list_creative_formats_request
adcp.types.domains.media_buy.list_creative_formats_response
adcp.types.domains.media_buy.list_products_request
adcp.types.domains.media_buy.list_products_response
adcp.types.domains.media_buy.log_event_request
adcp.types.domains.media_buy.log_event_response
adcp.types.domains.media_buy.media_buy_commitment_response
adcp.types.domains.media_buy.media_buy_delivery_webhook_result
adcp.types.domains.media_buy.outcome_target
adcp.types.domains.media_buy.package_control
adcp.types.domains.media_buy.package_request
adcp.types.domains.media_buy.package_update
adcp.types.domains.media_buy.product_discovery_criteria
adcp.types.domains.media_buy.product_fields
adcp.types.domains.media_buy.product_purchase
adcp.types.domains.media_buy.product_purchase_input
adcp.types.domains.media_buy.product_refinement
adcp.types.domains.media_buy.proposal_budget_constraint
adcp.types.domains.media_buy.proposal_decline
adcp.types.domains.media_buy.proposal_refinement
adcp.types.domains.media_buy.provide_performance_feedback_request
adcp.types.domains.media_buy.provide_performance_feedback_response
adcp.types.domains.media_buy.refine_proposals_async_response_input_required
adcp.types.domains.media_buy.refine_proposals_async_response_submitted
adcp.types.domains.media_buy.refine_proposals_async_response_working
adcp.types.domains.media_buy.refine_proposals_request
adcp.types.domains.media_buy.refine_proposals_response
adcp.types.domains.media_buy.request_proposals_async_response_input_required
adcp.types.domains.media_buy.request_proposals_async_response_submitted
adcp.types.domains.media_buy.request_proposals_async_response_working
adcp.types.domains.media_buy.request_proposals_request
adcp.types.domains.media_buy.request_proposals_response
adcp.types.domains.media_buy.sync_audiences_request
adcp.types.domains.media_buy.sync_audiences_response
adcp.types.domains.media_buy.sync_catalogs_async_response_input_required
adcp.types.domains.media_buy.sync_catalogs_async_response_submitted
adcp.types.domains.media_buy.sync_catalogs_async_response_working
adcp.types.domains.media_buy.sync_catalogs_request
adcp.types.domains.media_buy.sync_catalogs_response
adcp.types.domains.media_buy.sync_event_sources_request
adcp.types.domains.media_buy.sync_event_sources_response
adcp.types.domains.media_buy.sync_reporting_receipts_request
adcp.types.domains.media_buy.sync_reporting_receipts_response
adcp.types.domains.media_buy.sync_reporting_status_request
adcp.types.domains.media_buy.sync_reporting_status_response
adcp.types.domains.media_buy.update_media_buy_async_response_input_required
adcp.types.domains.media_buy.update_media_buy_async_response_submitted
adcp.types.domains.media_buy.update_media_buy_async_response_working
adcp.types.domains.media_buy.update_media_buy_request
adcp.types.domains.media_buy.update_media_buy_response

Classes

class AcceptProposalInputRequired (**data: Any)

Expand source code

class AcceptProposalInputRequired(CompactTaskInputRequired):
    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

CompactTaskInputRequired
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

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

Expand source code

class AcceptProposalResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['completed'] = 'completed'
    media_buy_id: Annotated[str, Field(min_length=1)]
    name: Annotated[
        str | None,
        Field(
            description='Persisted human-readable MediaBuy name for trafficking UI display and operational communication. The seller MUST echo a buyer-supplied request name unchanged; when the seller seeded a new MediaBuy name from an already-valid proposal.name, it MUST return that value unchanged here. Existing named MediaBuys return the stored value on amendment or cancellation commitments. This operational metadata is 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
    revision: Annotated[SchemaInt, Field(ge=1)]
    media_buy_status: media_buy_status_1.MediaBuyStatus | None = None
    confirmed_at: AwareDatetime | None = None
    accepted_proposal: AcceptedProposal
    purchase_bindings: Annotated[
        list[PurchaseBinding],
        Field(
            description='Execution identities assigned to the immutable purchases. purchase_index is the zero-based position in accepted_proposal.commercial_terms.purchases and disambiguates repeated product IDs.',
            min_length=1,
        ),
    ]
    available_actions: list[canonical_media_buy_action.CanonicalMediaBuyAction]
    warnings: Annotated[
        list[Warning] | None,
        Field(
            description='Non-blocking observations about this completed commitment. The MediaBuy was still created or amended exactly as represented. Continuing conditions also appear as indicators on get_media_buys.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

AcceptProposalResponse5

Class variables

var accepted_proposal : AcceptedProposal
var available_actions : list[CanonicalMediaBuyAction1 | CanonicalMediaBuyAction2 | CanonicalMediaBuyAction3]
var confirmed_at : pydantic.types.AwareDatetime | None
var context : ContextObject | None
var ext : ExtensionObject | None
var media_buy_id : str
var media_buy_status : MediaBuyStatus | None
var model_config
var name : str | None
var purchase_bindings : list[PurchaseBinding]
var replayed : Literal[True] | None
var revision : int
var status : Literal['completed']
var warnings : list[Warning] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalResponse2 (**data: Any)

Expand source code

class AcceptProposalResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['failed'] = 'failed'
    errors: Annotated[list[error.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

AcceptProposalResponse6

Class variables

var context : ContextObject | None
var errors : list[Error]
var ext : ExtensionObject | None
var model_config
var replayed : Literal[True] | None
var status : Literal['failed']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalResponse3 (**data: Any)

Expand source code

class AcceptProposalResponse3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['submitted'] = 'submitted'
    task_id: Annotated[str, Field(min_length=1)]
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

AcceptProposalResponse7

Class variables

var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var message : str | None
var model_config
var replayed : Literal[True] | None
var status : Literal['submitted']
var task_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalResponse4 (**data: Any)

Expand source code

class AcceptProposalResponse4(AdCPBaseModel):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalResponse5 (**data: Any)

Expand source code

class AcceptProposalResponse5(AdcpResponse, AcceptProposalResponse1, AcceptProposalResponse4):
    pass

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
AcceptProposalResponse1
AcceptProposalResponse4
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
AcceptProposalResponse1:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalResponse6 (**data: Any)

Expand source code

class AcceptProposalResponse6(AdcpResponse, AcceptProposalResponse2, AcceptProposalResponse4):
    pass

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AcceptProposalResponse2
AcceptProposalResponse4
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
AcceptProposalResponse2:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalResponse7 (**data: Any)

Expand source code

class AcceptProposalResponse7(AdcpResponse, AcceptProposalResponse3, AcceptProposalResponse4):
    pass

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AcceptProposalResponse3
AcceptProposalResponse4
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
AcceptProposalResponse3:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalSubmitted (**data: Any)

Expand source code

class AcceptProposalSubmitted(CompactTaskSubmitted):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class AcceptProposalWorking (**data: Any)

Expand source code

class AcceptProposalWorking(CompactTaskWorking):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskWorking
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskWorking:
- 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class AcceptancePolicyRequirement1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['category_declaration'] = 'category_declaration'
    declaration: Annotated[str | None, Field(min_length=1)] = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var declaration : str | None
var description : str | None
var kind : Literal['category_declaration']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement10 (**data: Any)

Expand source code

class AcceptancePolicyRequirement10(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['disclosure'] = 'disclosure'
    format: Annotated[str | None, Field(min_length=1)] = None
    placement: Annotated[str | None, Field(min_length=1)] = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var format : str | None
var kind : Literal['disclosure']
var model_config
var placement : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement11 (**data: Any)

Expand source code

class AcceptancePolicyRequirement11(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['targeting_restriction'] = 'targeting_restriction'
    restricted_attributes: Annotated[
        list[restricted_attribute.RestrictedAttribute] | None, Field(min_length=1)
    ] = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var kind : Literal['targeting_restriction']
var model_config
var restricted_attributes : list[RestrictedAttribute] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement12 (**data: Any)

Expand source code

class AcceptancePolicyRequirement12(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['creative_restriction'] = 'creative_restriction'
    description: Annotated[str, Field(min_length=1)]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str
var kind : Literal['creative_restriction']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement13 (**data: Any)

Expand source code

class AcceptancePolicyRequirement13(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['destination_restriction'] = 'destination_restriction'
    description: Annotated[str, Field(min_length=1)]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str
var kind : Literal['destination_restriction']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement14 (**data: Any)

Expand source code

class AcceptancePolicyRequirement14(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['format_restriction'] = 'format_restriction'
    format_ids: Annotated[
        list[FormatId] | None,
        Field(
            deprecated=True,
            description='Deprecated in AdCP 3.2 and removed in AdCP 4.0. This named-format restriction is retained for 3.x compatibility; new policies identify canonical format options in description or an extension until a registry-stable format-option identity is standardized.',
            min_length=1,
        ),
    ] = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var format_ids : list[FormatId] | None
var kind : Literal['format_restriction']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement15 (**data: Any)

Expand source code

class AcceptancePolicyRequirement15(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['time_restriction'] = 'time_restriction'
    starts_at: AwareDatetime | None = None
    ends_at: AwareDatetime | None = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var ends_at : pydantic.types.AwareDatetime | None
var kind : Literal['time_restriction']
var model_config
var starts_at : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement16 (**data: Any)

Expand source code

class AcceptancePolicyRequirement16(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['transparency_reporting'] = 'transparency_reporting'
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var kind : Literal['transparency_reporting']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement17 (**data: Any)

Expand source code

class AcceptancePolicyRequirement17(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['custom'] = 'custom'
    id: Annotated[str, Field(pattern='^[a-z][a-z0-9_.:-]*$')]
    description: Annotated[str, Field(min_length=1)]
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str
var ext : ExtensionObject | None
var id : str
var kind : Literal['custom']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement2 (**data: Any)

Expand source code

class AcceptancePolicyRequirement2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['advertiser_verification'] = 'advertiser_verification'
    verification_scheme: Annotated[str | None, Field(min_length=1)] = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var kind : Literal['advertiser_verification']
var model_config
var verification_scheme : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement3 (**data: Any)

Expand source code

class AcceptancePolicyRequirement3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['advertiser_eligibility'] = 'advertiser_eligibility'
    criteria: Annotated[
        list[Criterion],
        Field(
            description='Stable criteria such as domestic_entity, citizen_or_resident, official_election_authority, or eligible_agency.',
            min_length=1,
        ),
    ]
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var criteria : list[Criterion]
var description : str | None
var kind : Literal['advertiser_eligibility']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement4 (**data: Any)

Expand source code

class AcceptancePolicyRequirement4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['funding_restriction'] = 'funding_restriction'
    criteria: Annotated[
        list[Criterion],
        Field(
            description='Stable restrictions such as no_foreign_funding or sponsor_identity_required.',
            min_length=1,
        ),
    ]
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var criteria : list[Criterion]
var description : str | None
var kind : Literal['funding_restriction']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement5 (**data: Any)

Expand source code

class AcceptancePolicyRequirement5(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['certification'] = 'certification'
    credential: Annotated[str | None, Field(min_length=1)] = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var credential : str | None
var description : str | None
var kind : Literal['certification']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement6 (**data: Any)

Expand source code

class AcceptancePolicyRequirement6(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['license'] = 'license'
    credential: Annotated[str | None, Field(min_length=1)] = None
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var credential : str | None
var description : str | None
var kind : Literal['license']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement7 (**data: Any)

Expand source code

class AcceptancePolicyRequirement7(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['prior_authorization'] = 'prior_authorization'
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var kind : Literal['prior_authorization']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement8 (**data: Any)

Expand source code

class AcceptancePolicyRequirement8(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['account_setup'] = 'account_setup'
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var kind : Literal['account_setup']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcceptancePolicyRequirement9 (**data: Any)

Expand source code

class AcceptancePolicyRequirement9(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['sales_assisted'] = 'sales_assisted'
    description: Annotated[str | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var kind : Literal['sales_assisted']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class Action11(StrEnum):
    include = 'include'
    omit = 'omit'
    finalize = 'finalize'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var finalize
var include
var omit

class Action9 (*args, **kwds)

Expand source code

class Action9(StrEnum):
    include = 'include'
    omit = 'omit'
    finalize = 'finalize'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var finalize
var include
var omit

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

Expand source code

class AdvertiserJurisdiction(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

DeliveryJurisdiction

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

Expand source code

class AffectedPackageId(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 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class AllowedStatus(StrEnum):
    pending_creatives = 'pending_creatives'
    pending_start = 'pending_start'
    active = 'active'
    paused = 'paused'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var active
var paused
var pending_creatives
var pending_start

class Alternatives (**data: Any)

Expand source code

class Alternatives(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    count: Annotated[
        SchemaInt,
        Field(
            description="Number of draft alternatives requested. The protocol maximum is 10. Buyers MUST NOT exceed a seller's lower advertised proposal_refinement.max_alternatives; sellers reject an excessive count at task level with VALIDATION_ERROR rather than clamping it.",
            ge=2,
            le=10,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var count : int
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ArtifactWebhook (**data: Any)

Expand source code

class ArtifactWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='Webhook endpoint URL for artifact delivery')]
    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.",
        ),
    ]
    delivery_mode: Annotated[
        DeliveryMode,
        Field(
            description="How artifacts are delivered. 'realtime' pushes artifacts as impressions occur. 'batched' aggregates artifacts and pushes periodically (see batch_frequency)."
        ),
    ]
    batch_frequency: Annotated[
        BatchFrequency | None,
        Field(
            description="For batched delivery, how often to push artifacts. Required when delivery_mode is 'batched'."
        ),
    ] = None
    sampling_rate: Annotated[
        StrictFloat | None,
        Field(
            description='Fraction of impressions to include (0-1). 1.0 = all impressions, 0.1 = 10% sample. Default: 1.0',
            ge=0.0,
            le=1.0,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authentication : Authentication
var batch_frequency : BatchFrequency | None
var delivery_mode : DeliveryMode
var model_config
var sampling_rate : float | None
var token : str | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AttributionWindow (**data: Any)

Expand source code

class AttributionWindow(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    post_click: Annotated[
        duration.Duration | None, Field(description='Post-click attribution window to apply.')
    ] = None
    post_view: Annotated[
        duration.Duration | None, Field(description='Post-view attribution window to apply.')
    ] = None
    model: Annotated[
        attribution_model.AttributionModel | None,
        Field(
            description='Attribution model to use. When omitted, the seller applies their default model.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model : AttributionModel | None
var model_config
var post_click : Duration | None
var post_view : Duration | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AudienceType (*args, **kwds)

Expand source code

class AudienceType(StrEnum):
    crm = 'crm'
    suppression = 'suppression'
    lookalike_seed = 'lookalike_seed'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var crm
var lookalike_seed
var suppression

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

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var credentials : str
var model_config
var schemes : list[AuthenticationScheme]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BatchFrequency (*args, **kwds)

Expand source code

class BatchFrequency(StrEnum):
    hourly = 'hourly'
    daily = 'daily'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var daily
var hourly

class BuildCreativeInputRequired (**data: Any)

Expand source code

class BuildCreativeInputRequired(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    reason: Annotated[
        Reason | None, Field(description='Reason code indicating why input is needed')
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Optional validation errors or warnings explaining why input is required.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var model_config
var reason : Reason | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 BuildCreativeResponse1 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 BuildCreativeResponse2 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 BuildCreativeResponse3 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 BuildCreativeResponse4 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 BuildCreativeResponse5 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 BuildCreativeResponse6 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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[]
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 BuildCreativeSubmitted (**data: Any)

Expand source code

class BuildCreativeSubmitted(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['submitted'],
        Field(
            description='Task-level status literal. Discriminates this async envelope from the synchronous success shapes, whose creative_manifest or creative_manifests are 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., 'Generative build queued; typical turnaround 3–5 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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 BuildCreativeWorking (**data: Any)

Expand source code

class BuildCreativeWorking(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., 'generating_assets', 'resolving_macros', 'rendering_preview')"
        ),
    ] = 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
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class BuyProductsInputRequired(CompactTaskInputRequired):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskInputRequired
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskInputRequired:
- 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 BuyProductsResponse1 (**data: Any)

Expand source code

class BuyProductsResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['completed'] = 'completed'
    media_buy_id: Annotated[str, Field(min_length=1)]
    name: Annotated[
        str | None,
        Field(
            description='Persisted human-readable MediaBuy name for trafficking UI display and operational communication. The seller MUST echo a buyer-supplied request name unchanged; when the seller seeded a new MediaBuy name from an already-valid proposal.name, it MUST return that value unchanged here. Existing named MediaBuys return the stored value on amendment or cancellation commitments. This operational metadata is 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
    revision: Annotated[SchemaInt, Field(ge=1)]
    media_buy_status: media_buy_status_1.MediaBuyStatus | None = None
    confirmed_at: AwareDatetime | None = None
    accepted_proposal: AcceptedProposal
    purchase_bindings: Annotated[
        list[PurchaseBinding],
        Field(
            description='Execution identities assigned to the immutable purchases. purchase_index is the zero-based position in accepted_proposal.commercial_terms.purchases and disambiguates repeated product IDs.',
            min_length=1,
        ),
    ]
    available_actions: list[canonical_media_buy_action.CanonicalMediaBuyAction]
    warnings: Annotated[
        list[Warning] | None,
        Field(
            description='Non-blocking observations about this completed commitment. The MediaBuy was still created or amended exactly as represented. Continuing conditions also appear as indicators on get_media_buys.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

BuyProductsResponse5

Class variables

var accepted_proposal : AcceptedProposal
var available_actions : list[CanonicalMediaBuyAction1 | CanonicalMediaBuyAction2 | CanonicalMediaBuyAction3]
var confirmed_at : pydantic.types.AwareDatetime | None
var context : ContextObject | None
var ext : ExtensionObject | None
var media_buy_id : str
var media_buy_status : MediaBuyStatus | None
var model_config
var name : str | None
var purchase_bindings : list[PurchaseBinding]
var replayed : Literal[True] | None
var revision : int
var status : Literal['completed']
var warnings : list[Warning] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BuyProductsResponse2 (**data: Any)

Expand source code

class BuyProductsResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['failed'] = 'failed'
    errors: Annotated[list[error.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

BuyProductsResponse6

Class variables

var context : ContextObject | None
var errors : list[Error]
var ext : ExtensionObject | None
var model_config
var replayed : Literal[True] | None
var status : Literal['failed']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BuyProductsResponse3 (**data: Any)

Expand source code

class BuyProductsResponse3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['submitted'] = 'submitted'
    task_id: Annotated[str, Field(min_length=1)]
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

BuyProductsResponse7

Class variables

var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var message : str | None
var model_config
var replayed : Literal[True] | None
var status : Literal['submitted']
var task_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BuyProductsResponse4 (**data: Any)

Expand source code

class BuyProductsResponse4(AdCPBaseModel):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BuyProductsResponse5 (**data: Any)

Expand source code

class BuyProductsResponse5(AdcpResponse, BuyProductsResponse1, BuyProductsResponse4):
    pass

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
BuyProductsResponse1
BuyProductsResponse4
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
BuyProductsResponse1:
- model_dump
- model_dump_json
- model_summary

class BuyProductsResponse6 (**data: Any)

Expand source code

class BuyProductsResponse6(AdcpResponse, BuyProductsResponse2, BuyProductsResponse4):
    pass

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
BuyProductsResponse2
BuyProductsResponse4
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
BuyProductsResponse2:
- model_dump
- model_dump_json
- model_summary

class BuyProductsResponse7 (**data: Any)

Expand source code

class BuyProductsResponse7(AdcpResponse, BuyProductsResponse3, BuyProductsResponse4):
    pass

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
BuyProductsResponse3
BuyProductsResponse4
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
BuyProductsResponse3:
- model_dump
- model_dump_json
- model_summary

class BuyProductsSubmitted (**data: Any)

Expand source code

class BuyProductsSubmitted(CompactTaskSubmitted):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class BuyProductsWorking (**data: Any)

Expand source code

class BuyProductsWorking(CompactTaskWorking):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskWorking
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

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

Expand source code

class ByAudienceItem(DeliveryMetrics):
    audience_id: Annotated[
        str,
        Field(
            description="Audience segment identifier. For 'synced' source, matches audience_id from sync_audiences. For other sources, seller-defined."
        ),
    ]
    audience_source: Annotated[
        audience_source_1.AudienceSource,
        Field(
            description='Origin of the audience segment (synced, platform, third_party, lookalike, retargeting, unknown)'
        ),
    ]
    audience_name: Annotated[
        str | None, Field(description='Human-readable audience segment name')
    ] = None
    impressions: Any
    spend: Any

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var audience_id : str
var audience_name : str | None
var audience_source : AudienceSource
var impressions : Any
var model_config
var spend : Any

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class ByDemographicItem (**data: Any)

Expand source code

class ByDemographicItem(DeliveryMetrics):
    demographic: Annotated[
        str,
        Field(
            description="Demographic code in the declared system's notation (for example, P25-54 for Nielsen).",
            min_length=1,
            pattern='\\S',
        ),
    ]
    demographic_system: Annotated[
        demographic_system_1.DemographicSystem,
        Field(description='Measurement system that defines the demographic code.'),
    ]
    age: Annotated[
        demographic_age_range.DemographicAgeRange | None,
        Field(
            description="Canonical age interval represented by this row. Required by protocol semantics for age ranges requested through reporting_dimensions.demographic.age_ranges and for intervals declared in the product's demographic reporting capability."
        ),
    ] = None
    impressions: Any
    spend: Any

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var age : DemographicAgeRange | None
var demographic : str
var demographic_system : DemographicSystem
var impressions : Any
var model_config
var spend : Any

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class ByDevicePlatformItem (**data: Any)

Expand source code

class ByDevicePlatformItem(DeliveryMetrics):
    device_platform: Annotated[
        device_platform_1.DevicePlatform, Field(description='Operating system platform')
    ]
    impressions: Any
    spend: Any

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var device_platform : DevicePlatform
var impressions : Any
var model_config
var spend : Any

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class ByDeviceTypeItem (**data: Any)

Expand source code

class ByDeviceTypeItem(DeliveryMetrics):
    device_type: Annotated[
        device_type_1.DeviceType,
        Field(description='Device form factor (desktop, mobile, tablet, ctv, dooh, unknown)'),
    ]
    impressions: Any
    spend: Any

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var device_type : DeviceType
var impressions : Any
var model_config
var spend : Any

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class ByFormatItem (**data: Any)

Expand source code

class ByFormatItem(DeliveryMetrics):
    format_kind: Annotated[
        str,
        Field(
            description='Canonical creative format kind aggregated by this row. This identifies creative shape, not duration or other format-option parameters.'
        ),
    ]
    impressions: Any
    spend: Any

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var format_kind : str
var impressions : Any
var model_config
var spend : Any

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class ByPackageItem1 (**data: Any)

Expand source code

class ByPackageItem1(DeliveryMetrics):
    package_id: Annotated[str, Field(description="Seller's package identifier")]
    currency: Annotated[
        str | None,
        Field(
            description="ISO 4217 denomination for this package window's monetary values. Required by the runtime currency-coherence rule when neither the parent media-buy row nor deprecated response-wide field supplies a currency and this package window contains monetary values; otherwise it MUST match the row or response currency when present.",
            pattern='^[A-Z]{3}$',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str | None
var model_config
var package_id : str

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class BySpotItem (**data: Any)

Expand source code

class BySpotItem(DeliveryMetrics):
    spot_id: Annotated[
        str,
        Field(
            description='Stable seller-scoped identifier for this scheduled spot occurrence. Reused across measurement-window updates and available to later preemption or makegood workflows. Distinct from creative_id.',
            min_length=1,
        ),
    ]
    creative_id: Annotated[
        str | None,
        Field(
            description="Optional identifier for the creative that aired in this spot occurrence, matching the package's creative asset or assignment. For library-backed sellers this is the sync_creatives identifier; inline-only sellers use the packages[].creatives creative_id.",
            min_length=1,
        ),
    ] = None
    aired_at: Annotated[
        AwareDatetime,
        Field(
            description='RFC 3339 timestamp when the spot actually aired. Its presence proves an airing; it is not inferred from impressions.'
        ),
    ]
    network: Annotated[
        str | None,
        Field(
            description="Optional network or syndicated service name, for example 'USA Network' or 'Westwood One'.",
            min_length=1,
        ),
    ] = None
    station: Annotated[
        str | None,
        Field(
            description="Optional station identifier or call sign, for example 'WABC-TV' or 'WNYC-FM'.",
            min_length=1,
        ),
    ] = None
    daypart: Annotated[
        str | None,
        Field(
            description="Optional seller-defined daypart label, for example 'prime_time' or 'morning_drive'.",
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var aired_at : pydantic.types.AwareDatetime
var creative_id : str | None
var daypart : str | None
var model_config
var network : str | None
var spot_id : str
var station : str | None

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class Cancellation (**data: Any)

Expand source code

class Cancellation(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    canceled_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when this media buy was canceled.')
    ]
    canceled_by: Annotated[
        canceled_by_1.CanceledBy, Field(description='Which party initiated the cancellation.')
    ]
    reason: Annotated[
        str | None, Field(description='Reason the media buy was canceled.', max_length=500)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var canceled_at : pydantic.types.AwareDatetime
var canceled_by : CanceledBy
var model_config
var reason : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Cancellation1 (**data: Any)

Expand source code

class Cancellation1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    canceled_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when this package was canceled.')
    ]
    canceled_by: Annotated[
        canceled_by_1.CanceledBy,
        Field(description='Which party initiated the package cancellation.'),
    ]
    reason: Annotated[
        str | None, Field(description='Reason the package was canceled.', max_length=500)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var canceled_at : pydantic.types.AwareDatetime
var canceled_by : CanceledBy
var model_config
var reason : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CancellationTerms (**data: Any)

Expand source code

class CancellationTerms(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    effective_at: AwareDatetime
    fee: Fee | None = None
    reason: Annotated[str | None, Field(max_length=500, min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var effective_at : pydantic.types.AwareDatetime
var fee : Fee | None
var model_config
var reason : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class CatalogItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of catalog_item entries to return. When omitted, the seller returns its automatic default set.',
            ge=1,
        ),
    ] = None
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CatalogItemRef (**data: Any)

Expand source code

class CatalogItemRef(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    catalog_type: str | None = None
    item_id: str

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalog_type : str | None
var item_id : str
var model_config

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ChangeKind (*args, **kwds)

Expand source code

class ChangeKind(StrEnum):
    amendment = 'amendment'
    cancellation = 'cancellation'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var amendment
var cancellation

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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class CommittedMetrics1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['standard'],
        Field(description='Standard metric from the closed `available-metric.json` enum.'),
    ] = 'standard'
    metric_id: Annotated[
        available_metric.AvailableMetric,
        Field(
            description="Identifier for the standard metric. MUST be present in the product's `reporting_capabilities.available_metrics`."
        ),
    ]
    qualifier: Annotated[
        Qualifier | None,
        Field(
            description='Disambiguator — same shape as on the response-side `committed_metrics`. Required when the buyer wants to pin a specific measurement path: `viewability_standard` for MRC vs GroupM viewability; `completion_source` for seller- vs vendor-attested `completion_rate`; `attribution_methodology` for how attribution was computed (deterministic_purchase, probabilistic, panel_based, modeled); `attribution_window` for the time window over which outcomes are attributed. See response-side description for full semantics.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var metric_id : AvailableMetric
var model_config
var qualifier : Qualifier | None
var scope : Literal['standard']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CommittedMetrics2 (**data: Any)

Expand source code

class CommittedMetrics2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['vendor'],
        Field(description='Vendor-defined metric, identified by the tuple `(vendor, metric_id)`.'),
    ] = 'vendor'
    vendor: Annotated[
        brand_ref.BrandReference,
        Field(
            description="Vendor that defines and computes this metric. The vendor's `brand.json` `agents[type='measurement']` is the canonical anchor."
        ),
    ]
    metric_id: Annotated[
        vendor_metric_id.VendorMetricId,
        Field(
            description="Identifier for the metric within the vendor's vocabulary. MUST be present in the product's `reporting_capabilities.vendor_metrics` for the same vendor."
        ),
    ]
    methodology_version: Annotated[
        str | None,
        Field(
            description="Optional buyer-proposed pin of the vendor's `measurement.metrics[].methodology_version`. The seller accepts by echoing it on the confirmed package's `committed_metrics` entry, normalizes to the version it can actually deliver, or rejects with `TERMS_REJECTED`. Opaque string — equality comparison only."
        ),
    ] = None
    qualifier: Annotated[
        Qualifier | None,
        Field(
            description='Optional disambiguator for vendor metrics committed under more than one methodology or window — same closed key set as standard-scope entries.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var methodology_version : str | None
var metric_id : VendorMetricId
var model_config
var qualifier : Qualifier | None
var scope : Literal['vendor']
var vendor : BrandReference

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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class Condition(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$'}

A str generated from a JSON Schema string root.

Ancestors

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

class Constraints (**data: Any)

Expand source code

class Constraints(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    total_budget: Annotated[
        proposal_budget_constraint.ProposalBudgetConstraint | None,
        Field(
            description='Inclusive bounds checked against commercial_terms.total_budget. Satisfied only when commercial_terms.total_budget is present, its currency matches, and its amount falls within every supplied bound.'
        ),
    ] = None
    cpm: Annotated[
        Cpm | None,
        Field(
            description='Hard ceiling on fixed CPM rates. Satisfied only when every entry of commercial_terms.purchases carries pricing with pricing_model cpm or vcpm, a matching currency, and a fixed_price no greater than max. Auction-priced, missing, or non-CPM pricing on any purchase leaves the constraint unsatisfied.'
        ),
    ] = None
    impressions: Annotated[
        Impressions | None,
        Field(
            description='Hard minimum contracted impression volume. Satisfied only when every entry of commercial_terms.purchases carries impressions and their sum is at least min.'
        ),
    ] = None
    flight: Annotated[
        Flight | None,
        Field(
            description='Hard flight-window bounds checked against commercial_terms.start_time and end_time. start_no_later_than is satisfied only by a concrete start_time at or before the bound; an asap start is unverifiable and therefore unsatisfied. end_no_earlier_than is satisfied only by an end_time at or after the bound.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var cpm : Cpm | None
var flight : Flight | None
var impressions : Impressions | None
var model_config
var total_budget : ProposalBudgetConstraint | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Constraints1 (**data: Any)

Expand source code

class Constraints1(Constraints):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Constraints
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Constraints:
- model_dump
- model_dump_json
- model_summary

class Constraints2 (**data: Any)

Expand source code

class Constraints2(Constraints):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Constraints
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Constraints:
- model_dump
- model_dump_json
- model_summary

class Constraints3 (**data: Any)

Expand source code

class Constraints3(Constraints):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Constraints
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Constraints:
- model_dump
- model_dump_json
- model_summary

class Constraints4 (**data: Any)

Expand source code

class Constraints4(Constraints):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Constraints
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Constraints:
- model_dump
- model_dump_json
- model_summary

class Constraints5 (**data: Any)

Expand source code

class Constraints5(Constraints):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Constraints
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Constraints:
- model_dump
- model_dump_json
- model_summary

class Constraints6 (**data: Any)

Expand source code

class Constraints6(Constraints):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Constraints
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Constraints:
- model_dump
- model_dump_json
- model_summary

class Constraints7 (**data: Any)

Expand source code

class Constraints7(Constraints):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Constraints
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Constraints:
- model_dump
- model_dump_json
- model_summary

class ControlMediaBuyInputRequired (**data: Any)

Expand source code

class ControlMediaBuyInputRequired(CompactTaskInputRequired):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskInputRequired
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskInputRequired:
- 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 ControlMediaBuyResponse1 (**data: Any)

Expand source code

class ControlMediaBuyResponse1(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['completed'] = 'completed'
    media_buy_id: Annotated[str, Field(min_length=1)]
    revision: Annotated[SchemaInt, Field(ge=1)]
    media_buy_status: media_buy_status_1.MediaBuyStatus | None = None
    implementation_date: AwareDatetime | None = None
    affected_package_ids: list[AffectedPackageId] | None = None
    available_actions: list[canonical_media_buy_action.CanonicalMediaBuyAction] | None = None
    warnings: Annotated[
        list[Warning] | None,
        Field(
            description='Non-blocking observations about this completed control. The control was still applied exactly as represented. Continuing conditions also appear as indicators on get_media_buys.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

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

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

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

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

Ancestors

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

Class variables

var affected_package_ids : list[AffectedPackageId] | None
var available_actions : list[CanonicalMediaBuyAction1 | CanonicalMediaBuyAction2 | CanonicalMediaBuyAction3] | None
var context : ContextObject | None
var ext : ExtensionObject | None
var implementation_date : pydantic.types.AwareDatetime | None
var media_buy_id : str
var media_buy_status : MediaBuyStatus | None
var model_config
var replayed : Literal[True] | None
var revision : int
var status : Literal['completed']
var warnings : list[Warning] | None

Inherited members

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

class ControlMediaBuyResponse2 (**data: Any)

Expand source code

class ControlMediaBuyResponse2(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['failed'] = 'failed'
    errors: Annotated[list[error.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

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

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

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

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

Ancestors

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

Class variables

var context : ContextObject | None
var errors : list[Error]
var ext : ExtensionObject | None
var model_config
var replayed : Literal[True] | None
var status : Literal['failed']

Inherited members

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

class ControlMediaBuyResponse3 (**data: Any)

Expand source code

class ControlMediaBuyResponse3(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['submitted'] = 'submitted'
    task_id: Annotated[str, Field(min_length=1)]
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
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 replayed : Literal[True] | None
var status : Literal['submitted']
var task_id : str

Inherited members

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

class ControlMediaBuySubmitted (**data: Any)

Expand source code

class ControlMediaBuySubmitted(CompactTaskSubmitted):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class ControlMediaBuyWorking (**data: Any)

Expand source code

class ControlMediaBuyWorking(CompactTaskWorking):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskWorking
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskWorking:
- model_dump
- model_dump_json
- model_summary

class Coverage (*args, **kwds)

Expand source code

class Coverage(StrEnum):
    partial = 'partial'
    complete = 'complete'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var complete
var partial

class Cpm (**data: Any)

Expand source code

class Cpm(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    max: Annotated[StrictFloat, Field(gt=0.0)]
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var max : float
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateMediaBuyInputRequired (**data: Any)

Expand source code

class CreateMediaBuyInputRequired(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    reason: Annotated[
        Reason | None, Field(description='Reason code indicating why input is needed')
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Optional validation errors or warnings for debugging purposes. Helps explain why input is required.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var model_config
var reason : Reason | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 CreateMediaBuyResponse1 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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 CreateMediaBuyResponse2 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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

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 CreateMediaBuyResponse3 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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[]
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 CreateMediaBuySubmitted (**data: Any)

Expand source code

class CreateMediaBuySubmitted(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, which carries media-buy lifecycle state in `media_buy_status`. 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 media_buy_id 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., 'Awaiting IO signature from sales team; typical turnaround 2–4 hours.' 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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 CreateMediaBuyWorking (**data: Any)

Expand source code

class CreateMediaBuyWorking(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')
    ] = 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
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agent_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 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.

Important

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

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

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

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

Ancestors

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

Expand source code

class Criterion(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

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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class DailyBreakdownItem1(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 media buy'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', ge=0.0)]
    spend: Annotated[StrictFloat, Field(description='Daily spend', ge=0.0)]
    conversions: Annotated[StrictFloat | None, Field(description='Daily conversions', ge=0.0)] = (
        None
    )
    conversion_value: Annotated[
        StrictFloat | None, Field(description='Daily conversion value', ge=0.0)
    ] = None
    commissionable_value: Annotated[
        StrictFloat | None,
        Field(
            description='Daily settled conversion value eligible for revenue-share commission',
            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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class DeclineProposalsInputRequired(CompactTaskInputRequired):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskInputRequired
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskInputRequired:
- 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 DeclineProposalsResponse1 (**data: Any)

Expand source code

class DeclineProposalsResponse1(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    results: Annotated[list[Results], Field(min_length=1)]
    status: Literal['submitted'] = 'submitted'
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
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 replayed : Literal[True] | None
var results : list[Results1 | Results2]
var status : Literal['submitted']
var task_id : str | None

Inherited members

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

class DeclineProposalsResponse2 (**data: Any)

Expand source code

class DeclineProposalsResponse2(AdcpResponse, CompactTaskSubmitted):
    model_config = ConfigDict(
        extra='forbid',
    )
    results: Annotated[list[Results3] | None, Field(min_length=1)] = None
    status: Literal['submitted'] = 'submitted'
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

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

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

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

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

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
CompactTaskSubmitted
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 replayed : Literal[True] | None
var results : list[Results4 | Results5] | None
var status : Literal['submitted']
var task_id : str | None

Inherited members

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

class DeclineProposalsSubmitted (**data: Any)

Expand source code

class DeclineProposalsSubmitted(CompactTaskSubmitted):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class DeclineProposalsWorking (**data: Any)

Expand source code

class DeclineProposalsWorking(CompactTaskWorking):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

CompactTaskWorking
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskWorking:
- model_dump
- model_dump_json
- model_summary

class DeliveryConfigGeneration (**data: Any)

Expand source code

class DeliveryConfigGeneration(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    delivery_config_id: Annotated[str, Field(max_length=64, min_length=1)]
    delivery_config_version: Annotated[SchemaInt, Field(ge=1)]
    feed_purpose: reporting_delivery_offering.ReportingFeedPurpose

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var delivery_config_id : str
var delivery_config_version : int
var feed_purpose : ReportingFeedPurpose
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Expand source code

class DeliveryConfigId(ScalarStr):
    __slots__ = ()
    _constraints = {'max_length': 64, 'min_length': 1, 'pattern': '^[A-Za-z0-9_.:-]{1,64}$'}

A str generated from a JSON Schema string root.

Ancestors

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

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

Expand source code

class DeliveryJurisdiction(AdvertiserJurisdiction):
    pass

A str generated from a JSON Schema string root.

Ancestors

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

class DeliveryMode (*args, **kwds)

Expand source code

class DeliveryMode(StrEnum):
    realtime = 'realtime'
    batched = 'batched'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var batched
var realtime

class Demographic (**data: Any)

Expand source code

class Demographic(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    age_ranges: Annotated[
        list[demographic_age_range.DemographicAgeRange] | None,
        Field(
            description="Optional canonical age ranges to return as distinct rows. Copying an applied targeting predicate here requests aligned reporting only when the reporting capability supports that exact predicate. Omit to request the product's declared native demographic breakdown.",
            min_length=1,
        ),
    ] = None
    limit: Annotated[
        SchemaInt | None,
        Field(description='Maximum number of demographic entries to return. Defaults to 25.', ge=1),
    ] = 25
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var age_ranges : list[DemographicAgeRange] | None
var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DevicePlatform (**data: Any)

Expand source code

class DevicePlatform(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of entries to return. When omitted, all entries are returned (the enum is small and bounded).',
            ge=1,
        ),
    ] = None
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc
    cursor: Annotated[
        str | None,
        Field(
            description="Opaque cursor from a previous response's by_device_platform_pagination to fetch the next page of a truncated by_device_platform breakdown. Omit for the first page. limit, sort_by, and sort_direction MUST be repeated unchanged across paged requests for the same logical query."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeviceType (**data: Any)

Expand source code

class DeviceType(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of entries to return. When omitted, all entries are returned (the enum is small and bounded).',
            ge=1,
        ),
    ] = None
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc
    cursor: Annotated[
        str | None,
        Field(
            description="Opaque cursor from a previous response's by_device_type_pagination to fetch the next page of a truncated by_device_type breakdown. Omit for the first page. limit, sort_by, and sort_direction MUST be repeated unchanged across paged requests for the same logical query."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Dimension (*args, **kwds)

Expand source code

class Dimension(StrEnum):
    voice = 'voice'
    theme = 'theme'
    best_of_n = 'best_of_n'
    transformer_config = 'transformer_config'
    custom = 'custom'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var best_of_n
var custom
var theme
var transformer_config
var voice

class Disposition (*args, **kwds)

Expand source code

class Disposition(StrEnum):
    allowed = 'allowed'
    conditional = 'conditional'
    prohibited = 'prohibited'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var allowed
var conditional
var prohibited

class Estimate (**data: Any)

Expand source code

class Estimate(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    items_total: Annotated[int, Field(ge=0)] | None = None
    items_to_produce: Annotated[int, Field(ge=0)] | None = None
    conditions_total: Annotated[int, Field(ge=1)] | None = None
    variants_per_item: Annotated[int, Field(ge=1)] | None = None
    leaves_total: Annotated[int, Field(ge=0)] | None = None
    currency: Annotated[str, StringConstraints(pattern='^[A-Z]{3}$')]
    cost_low: Annotated[float, Field(ge=0)]
    cost_high: Annotated[float, Field(ge=0)]
    cost_expected: Annotated[float, Field(ge=0)] | None = None
    basis: Literal['fixed', 'estimated_units', 'cpm_deferred']
    per_leaf: list[PerLeaf] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var basis : Literal['fixed', 'estimated_units', 'cpm_deferred']
var conditions_total : int | None
var cost_expected : float | None
var cost_high : float
var cost_low : float
var currency : str
var items_to_produce : int | None
var items_total : int | None
var leaves_total : int | None
var model_config
var per_leaf : list[PerLeaf] | None
var variants_per_item : int | None

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class Eval (**data: Any)

Expand source code

class Eval(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    features: list[creative_feature_result_1.CreativeFeatureResult] | None = None
    ranked_against: Annotated[int, Field(ge=1)] | None = None
    calls_used: Annotated[int, Field(ge=0)] | None = None
    seconds_used: Annotated[float, Field(ge=0)] | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var calls_used : int | None
var ext : ExtensionObject | None
var features : list[CreativeFeatureResult] | None
var model_config
var ranked_against : int | None
var seconds_used : float | None

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ExcludedBy (**data: Any)

Expand source code

class ExcludedBy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    count: Annotated[
        SchemaInt,
        Field(
            description='Number of products excluded by this filter, interpreted per the parent `semantics` field.',
            ge=0,
        ),
    ]
    values: Annotated[
        list[str | dict[str, Any]] | None,
        Field(
            description='Optional list of the specific filter values that contributed to exclusions, when meaningful. For `required_metrics`: the metric names that excluded products (strings). For `required_vendor_metrics`: the vendor/metric pin entries (objects). Item shape is filter-specific; the schema admits string OR object items. Buyers without filter-specific knowledge SHOULD treat as opaque.'
        ),
    ] = None
    notes: Annotated[
        str | None,
        Field(
            description="Optional human-readable note about why this filter narrowed the set (e.g., 'no products in this brief support DV viewability at the requested threshold')."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var count : int
var model_config
var notes : str | None
var values : list[str | dict[str, typing.Any]] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Extensions (**data: Any)

Expand source code

class Extensions(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    extends: Annotated[
        str,
        Field(
            description='Canonical concept this extension extends (e.g., `tracking`, `cta_vocabulary`, `destinations`, `placement`).'
        ),
    ]
    fields: Annotated[
        dict[str, Any],
        Field(
            description='JSON Schema fragment declaring the additional fields this extension contributes.'
        ),
    ]
    version: Annotated[
        str | None,
        Field(
            description='Semantic version of the extension definition. Distinct from the digest — version is human-readable; digest is the integrity check.'
        ),
    ] = None
    description: str | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var description : str | None
var extends : str
var fields : dict[str, typing.Any]
var model_config
var version : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Fee (**data: Any)

Expand source code

class Fee(TotalBudget):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

TotalBudget
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

TotalBudget:
- model_dump
- model_dump_json
- model_summary

class Field1 (*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 Fields (*args, **kwds)

Expand source code

class Fields(StrEnum):
    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'
    overlay_support = 'overlay_support'
    media_buy_support = 'media_buy_support'
    installments = 'installments'
    is_custom = 'is_custom'
    product_card = 'product_card'
    product_card_detailed = 'product_card_detailed'
    enforced_policies = 'enforced_policies'
    trusted_match = 'trusted_match'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var conversion_tracking
var creative_policy
var data_provider_signals
var delivery_measurement
var enforced_policies
var format_ids
var included_signals
var installments
var is_custom
var media_buy_support
var metric_optimization
var outcome_measurement
var overlay_support
var product_card
var product_card_detailed
var signal_targeting_options
var trusted_match

class FilterDiagnostics (**data: Any)

Expand source code

class FilterDiagnostics(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    semantics: Annotated[
        Semantics | None,
        Field(
            description="How `excluded_by[*].count` values are computed across multiple filters. `only`: counts products that would have been included if not for THIS filter alone (deterministic; the right value for 'which filter killed my result set' triage — recommended when feasible). `any`: counts products excluded by ANY filter (so multiple filters' counts may overlap and sum to more than `total_candidates`). `approximate`: sellers SHOULD use this when their pipeline can't cleanly attribute exclusions to a single filter. Buyers SHOULD inspect `semantics` before doing arithmetic on counts."
        ),
    ] = None
    total_candidates: Annotated[
        SchemaInt | None,
        Field(
            description='Number of products the seller considered before applying `filters`. Baseline for interpreting per-filter exclusion counts. Approximate — sellers MAY return a sampled or capped count when their candidate pool is large. Optional; sellers whose baseline candidate set size is sensitive (revealing market posture or competitive density) MAY omit this while still emitting `excluded_by`.',
            ge=0,
        ),
    ] = None
    excluded_by: Annotated[
        dict[str, ExcludedBy] | None,
        Field(
            description="Per-filter exclusion counts, keyed by the filter property name as it appears in the request's `filters` object (e.g., `pricing_currencies`, `required_metrics`, `required_vendor_metrics`, `required_geo_targeting`, `budget_range`). Values are objects carrying `count` and optional filter-specific detail. Only filters that actually narrowed the set need appear here; absence of a key means that filter did not exclude anything (or was not in the request)."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var excluded_by : dict[str, ExcludedBy] | None
var model_config
var semantics : Semantics | None
var total_candidates : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Flight (**data: Any)

Expand source code

class Flight(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    start_no_later_than: AwareDatetime | None = None
    end_no_earlier_than: AwareDatetime | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var end_no_earlier_than : pydantic.types.AwareDatetime | None
var model_config
var start_no_later_than : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Format (**data: Any)

Expand source code

class Format(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of format rows to return. When omitted, all rows are returned because the canonical format-kind vocabulary is small and bounded.',
            ge=1,
        ),
    ] = None
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Expand source code

class FormatId(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 Geo (**data: Any)

Expand source code

class Geo(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    geo_level: Annotated[
        geo_level_1.GeographicTargetingLevel,
        Field(description='Geographic granularity level for the breakdown'),
    ]
    system: Annotated[
        metro_system.MetroAreaSystem
        | postal_system.PostalCodeSystem
        | legacy_postal_system.CountryFusedPostalCodeSystem
        | None,
        Field(
            description="Optional classification system for metro or postal_area levels. Metro uses metro-system values (e.g., 'nielsen_dma'); native postal_area uses country-local postal-system values with country (e.g., country 'US', system 'zip'); deprecated legacy postal_area requests may use legacy-postal-system values such as 'us_zip'. Omit to request the level without selecting a specific system."
        ),
    ] = None
    country: Annotated[
        str | None,
        Field(
            description='ISO 3166-1 alpha-2 country code. Required for native postal_area requests; omitted for legacy postal_area and non-postal geo requests.',
            pattern='^[A-Z]{2}$',
        ),
    ] = None
    limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of geo entries to return. Defaults to 25. When truncated, by_geo_truncated is true in the response.',
            ge=1,
        ),
    ] = 25
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var country : str | None
var geo_level : GeographicTargetingLevel
var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None
var system : MetroAreaSystem | PostalCodeSystem | CountryFusedPostalCodeSystem | None

Inherited members

AdCPBaseModel:
- 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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(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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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(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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 GetProductsInputRequired (**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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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 GetProductsRejected (**data: Any)

Expand source code

class GetProductsRejected(AdcpVersionEnvelope, ProtocolEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    status: Annotated[
        Literal['rejected'],
        Field(
            description='Task-level business-outcome discriminator. The request was understood and processed, but the seller declined to offer products.'
        ),
    ] = 'rejected'
    reason: Annotated[
        str,
        Field(
            description="Buyer-facing market explanation for the decline. MAY be sanitized to protect confidential seller rules; for example, 'The requested budget is below the minimum for this inventory' rather than naming the internal rule, candidate products, inventory identifiers, or upstream partners that caused the decision. Plain text only.",
            max_length=2000,
            min_length=1,
        ),
    ]
    suggestions: Annotated[
        list[Suggestion] | None,
        Field(
            description='Actionable alternatives the buyer can try, such as changing budget, dates, or channel. If present, the buyer MAY submit a revised brief, but the suggestions do not guarantee acceptance. If absent, the seller is not offering a protocol-level alternative for this brief.',
            max_length=20,
            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.

Important

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

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

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

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

Ancestors

Class variables

var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var reason : str
var status : Literal['rejected']
var suggestions : list[Suggestion] | None

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

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

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

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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 GetProductsResponse (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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 GetProductsSubmitted (**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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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 GetProductsWorking (**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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 Goal (**data: Any)

Expand source code

class Goal(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['metric'] = 'metric'
    metric: Annotated[
        forecastable_metric.ForecastableMetric,
        Field(
            description='Delivery metric to plan for, in the same vocabulary forecast points report.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var kind : Literal['metric']
var metric : ForecastableMetric
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Goal1 (**data: Any)

Expand source code

class Goal1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['event'] = 'event'
    event_type: Annotated[
        event_type_1.EventType,
        Field(
            description='Conversion event to plan for, in the same vocabulary forecast points report.'
        ),
    ]
    custom_event_name: Annotated[
        str | None,
        Field(
            description="Required when event_type is 'custom'. Platform-specific name for the custom event.",
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var custom_event_name : str | None
var event_type : EventType
var kind : Literal['event']
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class HistoryItem (**data: Any)

Expand source code

class HistoryItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    revision: Annotated[
        SchemaInt, Field(description='Revision number after this change was applied.', ge=1)
    ]
    timestamp: Annotated[AwareDatetime, Field(description='When this change occurred.')]
    actor: Annotated[
        str | None,
        Field(
            description='Identity of who made the change — derived from authentication context, not caller-provided. Format is seller-defined (e.g., agent URL, user email, API key label).'
        ),
    ] = None
    action: Annotated[
        str,
        Field(
            description='What happened. Standard actions: created, activated, paused, resumed, canceled, rejected, completed, updated_budget, updated_dates, updated_packages, package_canceled, package_paused, package_resumed. Sellers MAY use additional platform-specific actions (e.g., creative_approved, targeting_updated) — use ext on the history entry for structured metadata about custom actions.'
        ),
    ]
    summary: Annotated[
        str | None,
        Field(
            description="Human-readable summary of the change (e.g., 'Budget increased from $5,000 to $7,500 on pkg_abc').",
            max_length=500,
        ),
    ] = None
    package_id: Annotated[
        str | None,
        Field(description='Package affected, when the change targeted a specific package.'),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : str
var actor : str | None
var ext : ExtensionObject | None
var model_config
var package_id : str | None
var revision : int
var summary : str | None
var timestamp : pydantic.types.AwareDatetime

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Impressions (**data: Any)

Expand source code

class Impressions(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    min: Annotated[StrictFloat, Field(gt=0.0)]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var min : float
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class IncompleteItem3 (**data: Any)

Expand source code

class IncompleteItem3(IncompleteItem):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

IncompleteItem
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

IncompleteItem:
- model_dump
- model_dump_json
- model_summary

class IncompleteItem5 (**data: Any)

Expand source code

class IncompleteItem5(IncompleteItem):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

IncompleteItem
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

IncompleteItem:
- model_dump
- model_dump_json
- model_summary

class IncompleteItem6 (**data: Any)

Expand source code

class IncompleteItem6(IncompleteItem):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

IncompleteItem
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

IncompleteItem:
- model_dump
- model_dump_json
- model_summary

class IncompleteItem7 (**data: Any)

Expand source code

class IncompleteItem7(IncompleteItem):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

IncompleteItem
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

IncompleteItem:
- model_dump
- model_dump_json
- model_summary

class Indicator (**data: Any)

Expand source code

class Indicator(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        IndicatorTypesEvaluatedEnum,
        Field(
            description="A seller-asserted material risk or optimization opportunity that currently warrants buyer attention on an AdCP resource relationship. AdCP standardizes the broad meaning of each value for the protocol release; it does not standardize or version the seller's detection methodology or prescribe a universal remedy.",
            title='Indicator Type',
        ),
    ]
    detected_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller first detected the current uninterrupted occurrence of this indicator. Keep this value stable while the condition remains present. If the condition clears and is later detected again, use the new detection time. Optional because some upstream platforms expose current assessments without an original detection timestamp.'
        ),
    ] = None
    scope: Annotated[
        list[indicator_scope.IndicatorScope] | None,
        Field(
            description='Optional narrower publisher or placement scope within the enclosing media buy, package, or package–creative assignment. Omit only when the seller evaluated and asserts the indicator across the whole enclosing resource/relationship. When partial indicators_evaluated_scope is declared, every returned indicator MUST include scope and every entry MUST fall within that coverage. This is scope, not source: the responding seller remains the source.',
            min_length=1,
        ),
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(
            description='Seller- or provider-specific detail such as scores, thresholds, evaluation windows, methodology identifiers, or upstream attribution. Core consumers must not need ext to understand the broad meaning of type.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var detected_at : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var model_config
var scope : list[IndicatorScope] | None
var type : IndicatorTypesEvaluatedEnum

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Indicator1 (**data: Any)

Expand source code

class Indicator1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        IndicatorTypesEvaluatedEnum1,
        Field(
            description="A seller-asserted material risk or optimization opportunity that currently warrants buyer attention on an AdCP resource relationship. AdCP standardizes the broad meaning of each value for the protocol release; it does not standardize or version the seller's detection methodology or prescribe a universal remedy.",
            title='Indicator Type',
        ),
    ]
    detected_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller first detected the current uninterrupted occurrence of this indicator. Keep this value stable while the condition remains present. If the condition clears and is later detected again, use the new detection time. Optional because some upstream platforms expose current assessments without an original detection timestamp.'
        ),
    ] = None
    scope: Annotated[
        list[indicator_scope.IndicatorScope] | None,
        Field(
            description='Optional narrower publisher or placement scope within the enclosing media buy, package, or package–creative assignment. Omit only when the seller evaluated and asserts the indicator across the whole enclosing resource/relationship. When partial indicators_evaluated_scope is declared, every returned indicator MUST include scope and every entry MUST fall within that coverage. This is scope, not source: the responding seller remains the source.',
            min_length=1,
        ),
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(
            description='Seller- or provider-specific detail such as scores, thresholds, evaluation windows, methodology identifiers, or upstream attribution. Core consumers must not need ext to understand the broad meaning of type.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var detected_at : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var model_config
var scope : list[IndicatorScope] | None
var type : IndicatorTypesEvaluatedEnum1

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Indicator2 (**data: Any)

Expand source code

class Indicator2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        IndicatorTypesEvaluatedEnum2,
        Field(
            description="A seller-asserted material risk or optimization opportunity that currently warrants buyer attention on an AdCP resource relationship. AdCP standardizes the broad meaning of each value for the protocol release; it does not standardize or version the seller's detection methodology or prescribe a universal remedy.",
            title='Indicator Type',
        ),
    ]
    detected_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller first detected the current uninterrupted occurrence of this indicator. Keep this value stable while the condition remains present. If the condition clears and is later detected again, use the new detection time. Optional because some upstream platforms expose current assessments without an original detection timestamp.'
        ),
    ] = None
    scope: Annotated[
        list[indicator_scope.IndicatorScope] | None,
        Field(
            description='Optional narrower publisher or placement scope within the enclosing media buy, package, or package–creative assignment. Omit only when the seller evaluated and asserts the indicator across the whole enclosing resource/relationship. When partial indicators_evaluated_scope is declared, every returned indicator MUST include scope and every entry MUST fall within that coverage. This is scope, not source: the responding seller remains the source.',
            min_length=1,
        ),
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(
            description='Seller- or provider-specific detail such as scores, thresholds, evaluation windows, methodology identifiers, or upstream attribution. Core consumers must not need ext to understand the broad meaning of type.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var detected_at : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var model_config
var scope : list[IndicatorScope] | None
var type : IndicatorTypesEvaluatedEnum2

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class IndicatorTypesEvaluatedEnum (*args, **kwds)

Expand source code

class IndicatorTypesEvaluatedEnum(StrEnum):
    creative_fatigue = 'creative_fatigue'
    creative_quality_opportunity = 'creative_quality_opportunity'
    creative_diversity_low = 'creative_diversity_low'
    audience_saturation = 'audience_saturation'
    inventory_shortfall_forecast = 'inventory_shortfall_forecast'
    pacing_risk = 'pacing_risk'
    budget_constrained = 'budget_constrained'
    budget_constrained_1 = 'budget_constrained'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audience_saturation
var budget_constrained
var budget_constrained_1
var creative_diversity_low
var creative_fatigue
var creative_quality_opportunity
var inventory_shortfall_forecast
var pacing_risk

class IndicatorTypesEvaluatedEnum1 (*args, **kwds)

Expand source code

class IndicatorTypesEvaluatedEnum1(StrEnum):
    creative_fatigue = 'creative_fatigue'
    creative_quality_opportunity = 'creative_quality_opportunity'
    creative_diversity_low = 'creative_diversity_low'
    audience_saturation = 'audience_saturation'
    inventory_shortfall_forecast = 'inventory_shortfall_forecast'
    pacing_risk = 'pacing_risk'
    budget_constrained = 'budget_constrained'
    creative_diversity_low_1 = 'creative_diversity_low'
    audience_saturation_1 = 'audience_saturation'
    inventory_shortfall_forecast_1 = 'inventory_shortfall_forecast'
    pacing_risk_1 = 'pacing_risk'
    budget_constrained_1 = 'budget_constrained'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audience_saturation
var audience_saturation_1
var budget_constrained
var budget_constrained_1
var creative_diversity_low
var creative_diversity_low_1
var creative_fatigue
var creative_quality_opportunity
var inventory_shortfall_forecast
var inventory_shortfall_forecast_1
var pacing_risk
var pacing_risk_1

class IndicatorTypesEvaluatedEnum2 (*args, **kwds)

Expand source code

class IndicatorTypesEvaluatedEnum2(StrEnum):
    creative_fatigue = 'creative_fatigue'
    creative_quality_opportunity = 'creative_quality_opportunity'
    creative_diversity_low = 'creative_diversity_low'
    audience_saturation = 'audience_saturation'
    inventory_shortfall_forecast = 'inventory_shortfall_forecast'
    pacing_risk = 'pacing_risk'
    budget_constrained = 'budget_constrained'
    creative_fatigue_1 = 'creative_fatigue'
    creative_quality_opportunity_1 = 'creative_quality_opportunity'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var audience_saturation
var budget_constrained
var creative_diversity_low
var creative_fatigue
var creative_fatigue_1
var creative_quality_opportunity
var creative_quality_opportunity_1
var inventory_shortfall_forecast
var pacing_risk

class Input (**data: Any)

Expand source code

class Input(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    name: str
    macros: dict[str, str] | None = None
    context_description: str | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_description : str | None
var macros : dict[str, str] | None
var model_config
var name : str

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class Input2 (**data: Any)

Expand source code

class Input2(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    name: str
    macros: dict[str, str] | None = None
    context_description: str | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_description : str | None
var macros : dict[str, str] | None
var model_config
var name : str

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class ItemIssue (**data: Any)

Expand source code

class ItemIssue(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    item_id: str
    status: catalog_item_status_1.CatalogItemStatus
    reasons: list[str] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var item_id : str
var model_config
var reasons : list[str] | None
var status : CatalogItemStatus

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class KeepMode (*args, **kwds)

Expand source code

class KeepMode(StrEnum):
    keep_all = 'keep_all'
    keep_one = 'keep_one'
    keep_some = 'keep_some'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var keep_all
var keep_one
var keep_some

class Keyword (**data: Any)

Expand source code

class Keyword(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        SchemaInt | None,
        Field(
            description='Maximum number of keyword entries to return. When omitted, the seller returns its automatic default set.',
            ge=1,
        ),
    ] = None
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class KeywordTargetsAddItem (**data: Any)

Expand source code

class KeywordTargetsAddItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to target', min_length=1)]
    match_type: match_type_1.MatchType
    bid_price: Annotated[
        StrictFloat | None,
        Field(
            description="Per-keyword bid price. Inherits currency and max_bid interpretation from the package's pricing option.",
            ge=0.0,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var bid_price : float | None
var keyword : str
var match_type : MatchType
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class KeywordTargetsRemoveItem (**data: Any)

Expand source code

class KeywordTargetsRemoveItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to stop targeting', min_length=1)]
    match_type: match_type_1.MatchType

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var keyword : str
var match_type : MatchType
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 ListCreativeFormatsResponse (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 ListProductsResponse1 (**data: Any)

Expand source code

class ListProductsResponse1(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    outcome: Annotated[
        Literal['listed'],
        Field(
            description='Whether this response carries a product page or confirms that the selected feed has not changed.'
        ),
    ] = 'listed'
    products: list[canonical_product.CanonicalProduct]
    next_cursor: Annotated[
        str | None,
        Field(
            description='Cursor for the next page. Omitted when this is the last page.',
            min_length=1,
        ),
    ] = None
    feed_version: Annotated[
        str,
        Field(
            description='Opaque version of the selected offer feed. For wholesale webhook consumers this is the same scope-keyed token carried as wholesale_feed_version on product.* and wholesale_feed.bulk_change notifications.'
        ),
    ]
    pricing_version: Annotated[
        str | None, Field(description='Opaque version of the selected pricing layer.')
    ] = None
    cache_scope: CacheScope
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description='Usable partial response with explicitly missing product-list scopes.',
            min_length=1,
        ),
    ] = None
    replayed: Literal[True] | 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_scope : CacheScope
var context : ContextObject | None
var ext : ExtensionObject | None
var feed_version : str
var incomplete : list[IncompleteItem] | None
var model_config
var next_cursor : str | None
var outcome : Literal['listed']
var pricing_version : str | None
var products : list[CanonicalProduct]
var replayed : Literal[True] | None

Inherited members

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

class ListProductsResponse2 (**data: Any)

Expand source code

class ListProductsResponse2(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    outcome: Annotated[
        Literal['unchanged'],
        Field(
            description='Whether this response carries a product page or confirms that the selected feed has not changed.'
        ),
    ] = 'unchanged'
    products: list[canonical_product.CanonicalProduct] | None = None
    next_cursor: Annotated[
        str | None,
        Field(
            description='Cursor for the next page. Omitted when this is the last page.',
            min_length=1,
        ),
    ] = None
    feed_version: Annotated[
        str,
        Field(
            description='Opaque version of the selected offer feed. For wholesale webhook consumers this is the same scope-keyed token carried as wholesale_feed_version on product.* and wholesale_feed.bulk_change notifications.'
        ),
    ]
    pricing_version: Annotated[
        str | None, Field(description='Opaque version of the selected pricing layer.')
    ] = None
    cache_scope: CacheScope
    incomplete: Annotated[
        list[IncompleteItem3] | None,
        Field(
            description='Usable partial response with explicitly missing product-list scopes.',
            min_length=1,
        ),
    ] = None
    replayed: Literal[True] | 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_scope : CacheScope
var context : ContextObject | None
var ext : ExtensionObject | None
var feed_version : str
var incomplete : list[IncompleteItem3] | None
var model_config
var next_cursor : str | None
var outcome : Literal['unchanged']
var pricing_version : str | None
var products : list[CanonicalProduct] | None
var replayed : Literal[True] | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdCPBaseModel:
- 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 LogEventResponse2 (**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.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 Loss (*args, **kwds)

Expand source code

class Loss(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 Losses (**data: Any)

Expand source code

class Losses(AdCPBaseModel):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MatchBreakdown (**data: Any)

Expand source code

class MatchBreakdown(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    id_type: match_id_type_1.MatchIdType
    submitted: Annotated[int, Field(ge=0)]
    matched: Annotated[int, Field(ge=0)]
    match_rate: Annotated[float, Field(ge=0, le=1)]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var id_type : MatchIdType
var match_rate : float
var matched : int
var model_config
var submitted : int

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class MaxSpend (**data: Any)

Expand source code

class MaxSpend(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    amount: Annotated[
        StrictFloat,
        Field(
            description='Maximum aggregate vendor_cost to incur on this call, in `currency`.',
            ge=0.0,
        ),
    ]
    currency: Annotated[
        str, Field(description='ISO 4217 currency; MUST match the rate card.', pattern='^[A-Z]{3}$')
    ]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var amount : float
var currency : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Important

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

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

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

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

Ancestors

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

Inherited members

IndicatorBearingResourceState:
- 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : 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 MediaBuyChangeTermConstraints1 (**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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var kind : Literal['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 MediaBuyChangeTermConstraints2 (**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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 MediaBuyChangeTermConstraints3 (**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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var kind : Literal['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 MediaBuyChangeTermConstraints4 (**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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class MediaBuyCommitmentResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['completed'] = 'completed'
    media_buy_id: Annotated[str, Field(min_length=1)]
    name: Annotated[
        str | None,
        Field(
            description='Persisted human-readable MediaBuy name for trafficking UI display and operational communication. The seller MUST echo a buyer-supplied request name unchanged; when the seller seeded a new MediaBuy name from an already-valid proposal.name, it MUST return that value unchanged here. Existing named MediaBuys return the stored value on amendment or cancellation commitments. This operational metadata is 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
    revision: Annotated[SchemaInt, Field(ge=1)]
    media_buy_status: media_buy_status_1.MediaBuyStatus | None = None
    confirmed_at: AwareDatetime | None = None
    accepted_proposal: AcceptedProposal
    purchase_bindings: Annotated[
        list[PurchaseBinding],
        Field(
            description='Execution identities assigned to the immutable purchases. purchase_index is the zero-based position in accepted_proposal.commercial_terms.purchases and disambiguates repeated product IDs.',
            min_length=1,
        ),
    ]
    available_actions: list[canonical_media_buy_action.CanonicalMediaBuyAction]
    warnings: Annotated[
        list[Warning] | None,
        Field(
            description='Non-blocking observations about this completed commitment. The MediaBuy was still created or amended exactly as represented. Continuing conditions also appear as indicators on get_media_buys.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accepted_proposal : AcceptedProposal
var available_actions : list[CanonicalMediaBuyAction1 | CanonicalMediaBuyAction2 | CanonicalMediaBuyAction3]
var confirmed_at : pydantic.types.AwareDatetime | None
var context : ContextObject | None
var ext : ExtensionObject | None
var media_buy_id : str
var media_buy_status : MediaBuyStatus | None
var model_config
var name : str | None
var purchase_bindings : list[PurchaseBinding]
var replayed : Literal[True] | None
var revision : int
var status : Literal['completed']
var warnings : list[Warning] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MediaBuyCommitmentResponse2 (**data: Any)

Expand source code

class MediaBuyCommitmentResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['failed'] = 'failed'
    errors: Annotated[list[error.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var errors : list[Error]
var ext : ExtensionObject | None
var model_config
var replayed : Literal[True] | None
var status : Literal['failed']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MediaBuyCommitmentResponse3 (**data: Any)

Expand source code

class MediaBuyCommitmentResponse3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    status: Literal['submitted'] = 'submitted'
    task_id: Annotated[str, Field(min_length=1)]
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var message : str | None
var model_config
var replayed : Literal[True] | None
var status : Literal['submitted']
var task_id : str

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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Expand source code

class Mode(StrEnum):
    execute = 'execute'
    estimate = 'estimate'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var estimate
var execute

class Money (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var amount : float
var currency : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class NegativeKeywordsAddItem (**data: Any)

Expand source code

class NegativeKeywordsAddItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to exclude', min_length=1)]
    match_type: match_type_1.MatchType

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var keyword : str
var match_type : MatchType
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class NegativeKeywordsRemoveItem (**data: Any)

Expand source code

class NegativeKeywordsRemoveItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    keyword: Annotated[str, Field(description='The keyword to stop excluding', min_length=1)]
    match_type: match_type_1.MatchType

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var keyword : str
var match_type : MatchType
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action_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 OutcomeTarget (**data: Any)

Expand source code

class OutcomeTarget(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    goal: Annotated[
        Goal | Goal1,
        Field(
            description='The outcome to plan against: a seller-tracked delivery metric or an advertiser conversion event.',
            discriminator='kind',
        ),
    ]
    volume: Annotated[
        StrictFloat | None,
        Field(
            description="Desired total volume of the goal's metric or event across the planned flight. Alone, the seller solves for budget and answers with total_budget_guidance and a forecast. With cost_per, the seller plans toward the volume at the cost: under a cap it SHOULD keep the buyer's amount and forecast the lower volume it can deliver, unless no volume can be planned at that amount; under a target the ask is plannable when the seller can forecast the volume around it.",
            gt=0.0,
        ),
    ] = None
    cost_per: outcome_target_cost_per.OutcomeTargetCostPer | None = None

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

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cost_per : OutcomeTargetCostPer | None
var goal : Goal | Goal1
var model_config
var volume : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Important

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

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

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

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

Ancestors

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

Inherited members

IndicatorBearingResourceState:
- model_dump
- model_dump_json
- model_summary

class PackageControl (**data: Any)

Expand source code

class PackageControl(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    package_id: Annotated[str, Field(min_length=1)]
    budget: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's hard lifetime spend cap. 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
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's subordinate hard daily cap; null removes it. Numeric changes apply immediately with package spend already incurred in the shared current cap day counted.",
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description="Replace this package's soft minimum-spend target. A number is valid only for seller-optimized allocation and requires advertised media_buy.features.seller_optimized_min_spend_targets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.",
            ge=0.0,
        ),
    ] = None
    impressions: Annotated[StrictFloat | None, Field(ge=0.0)] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Replace 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
    bidding: bidding_policy.BiddingPolicy | None = None
    paused: StrictBool | None = None
    canceled: Annotated[
        Literal[True] | None,
        Field(
            description='Exercise an already-accepted unilateral package cancellation right. If seller agreement is required, refine the accepted proposal with change_kind amendment; cancellation proposals terminate the whole MediaBuy.'
        ),
    ] = None
    cancellation_reason: Annotated[str | None, Field(max_length=500, min_length=1)] = None
    targeting_overlay: Annotated[
        targeting_input.TargetingOverlayInput | None,
        Field(
            description='Per-dimension targeting patch. Omission preserves the current dimension, a non-null value replaces it, and null clears it. The resulting effective targeting must remain within the accepted commercial envelope and is read back without null dimensions.'
        ),
    ] = None
    catalog_ids: Annotated[
        list[CatalogId] | None,
        Field(
            description="Replace the package's promoted catalogs with references previously managed through sync_catalogs.",
            min_length=1,
        ),
    ] = None
    keyword_targets_add: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    keyword_targets_remove: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    negative_keywords_add: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    negative_keywords_remove: Annotated[
        list[keyword_target.KeywordTarget] | None, Field(min_length=1)
    ] = None
    optimization_goals: Annotated[
        list[canonical_optimization_goal.CanonicalOptimizationGoal] | None, Field(min_length=1)
    ] = None

    @model_validator(mode='after')
    def _require_schema_required_group(self) -> PackageControl:
        # ``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 (('budget',), ('daily_budget_cap',), ('min_spend_target',), ('impressions',), ('pacing',), ('bidding',), ('paused',), ('canceled',), ('targeting_overlay',), ('catalog_ids',), ('keyword_targets_add',), ('keyword_targets_remove',), ('negative_keywords_add',), ('negative_keywords_remove',), ('optimization_goals',),):
            if all(name in self.model_fields_set for name in group):
                return self
        raise ValueError(
            'PackageControl requires at least one of these field groups: budget | daily_budget_cap | min_spend_target | impressions | pacing | bidding | paused | canceled | targeting_overlay | catalog_ids | keyword_targets_add | keyword_targets_remove | negative_keywords_add | negative_keywords_remove | optimization_goals'
        )

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var bidding : BiddingPolicy | None
var budget : float | None
var canceled : Literal[True] | None
var cancellation_reason : str | None
var catalog_ids : list[CatalogId] | None
var daily_budget_cap : float | None
var impressions : float | None
var keyword_targets_add : list[KeywordTarget] | None
var keyword_targets_remove : list[KeywordTarget] | None
var min_spend_target : float | None
var model_config
var negative_keywords_add : list[KeywordTarget] | None
var negative_keywords_remove : list[KeywordTarget] | None
var optimization_goals : list[CanonicalOptimizationGoal1 | CanonicalOptimizationGoal2 | CanonicalOptimizationGoal3] | None
var pacing : Pacing | None
var package_id : str
var paused : bool | None
var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

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.

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

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

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

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.

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PartialFailure (**data: Any)

Expand source code

class PartialFailure(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    event_id: str
    code: str
    message: str

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var code : str
var event_id : str
var message : str
var model_config

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class PerLeaf (**data: Any)

Expand source code

class PerLeaf(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    catalog_item_ref: dict[str, Any] | None = None
    variant_axis_value: Any | None = None
    pricing_option_id: str | None = None
    cost_low: Annotated[float, Field(ge=0)] | None = None
    cost_high: Annotated[float, Field(ge=0)] | None = None
    consumption_estimate: creative_consumption_1.CreativeConsumption | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalog_item_ref : dict[str, typing.Any] | None
var consumption_estimate : CreativeConsumption | None
var cost_high : float | None
var cost_low : float | None
var model_config
var pricing_option_id : str | None
var variant_axis_value : typing.Any | None

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class Period (**data: Any)

Expand source code

class Period(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    start: AwareDatetime
    end: AwareDatetime

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var end : pydantic.types.AwareDatetime
var model_config
var start : pydantic.types.AwareDatetime

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Placement (**data: Any)

Expand source code

class Placement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        SchemaInt | None,
        Field(description='Maximum number of entries to return. Defaults to 25.', ge=1),
    ] = 25
    sort_by: Annotated[
        sort_metric.SortMetric | None,
        Field(
            description="Metric to sort breakdown rows by, in `sort_direction` order (descending by default). Falls back to 'spend' when the seller does not report the requested metric at this breakdown's row grain; on fallback the sort direction resets to 'desc'. Rows lacking a value for the applied sort metric order last regardless of direction. The applied sort is echoed in the response."
        ),
    ] = sort_metric.SortMetric.spend
    sort_direction: Annotated[
        sort_direction_1.SortDirection | None,
        Field(
            description="Direction for sort_by ordering. Defaults to 'desc' (largest first). 'asc' enables bottom-N queries (e.g., the 25 worst placements by viewable_rate) that cannot be recovered from a truncated descending pull. Sellers MUST apply the requested direction to the applied sort metric — direction has no availability fallback."
        ),
    ] = sort_direction_1.SortDirection.desc
    cursor: Annotated[
        str | None,
        Field(
            description="Opaque cursor from a previous response's by_placement_pagination to fetch the next page of a truncated by_placement breakdown. Omit for the first page. limit, sort_by, and sort_direction MUST be repeated unchanged across paged requests for the same logical query."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var limit : int | None
var model_config
var sort_by : SortMetric | None
var sort_direction : SortDirection | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PolicyRef (**data: Any)

Expand source code

class PolicyRef(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    policy_id: Annotated[str, Field(min_length=1)]
    version: Annotated[str, Field(min_length=1)]
    content_digest: Annotated[
        str,
        Field(
            description="SHA-256 digest of the referenced policy entry's RFC 8785 JCS serialization with acceptance_profile omitted.",
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var content_digest : str
var model_config
var policy_id : str
var version : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Preview (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var expires_at : pydantic.types.AwareDatetime
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 Preview2 (**data: Any)

Expand source code

class Preview2(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    preview_id: str
    renders: Annotated[list[preview_render_1.PreviewRender], Field(min_length=1)]
    input: Input

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var input : Input
var model_config
var preview_id : str
var renders : list[PreviewRender1 | PreviewRender2 | PreviewRender3]

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class Preview3 (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class Preview4 (**data: Any)

Expand source code

class Preview4(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    preview_id: str
    format_id: format_id_1.FormatReferenceStructuredObject | None = None
    capability_id: Annotated[str, StringConstraints(pattern='^[a-zA-Z0-9_-]+$')] | None = None
    renders: Annotated[list[preview_render_1.PreviewRender], Field(min_length=1)]
    input: Input2

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var capability_id : str | None
var format_id : FormatReferenceStructuredObject | None
var input : Input2
var model_config
var preview_id : str
var renders : list[PreviewRender1 | PreviewRender2 | PreviewRender3]

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class PreviewInput (**data: Any)

Expand source code

class PreviewInput(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    name: Annotated[
        str,
        Field(
            description="Human-readable name for this input set (e.g., 'Sunny morning on mobile', 'Evening podcast ad')"
        ),
    ]
    macros: Annotated[
        dict[str, str] | None, Field(description='Macro values to use for this preview variant')
    ] = 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.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_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 ProductDiscoveryCriteria (**data: Any)

Expand source code

class ProductDiscoveryCriteria(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    product_ids: Annotated[
        list[ProductId] | None,
        Field(
            description='Exact seller-issued products to retrieve or use as proposal candidates.',
            min_length=1,
        ),
    ] = None
    offer_filters: Annotated[
        product_offer_filters.ProductOfferFilters | None,
        Field(
            description='Hard commercial and product-characteristic filters. Every returned product MUST satisfy them. These fields do not become package delivery targeting.'
        ),
    ] = None
    targeting_overlay: Annotated[
        targeting.TargetingOverlay | None,
        Field(
            description='Concrete delivery constraints the buyer expects to carry into create_media_buy. Returned product pricing and forecasts MUST reflect the effective targeting. A product that cannot apply the request exactly is omitted or returned as a distinct configured product with sparse Product.targeting_resolution modifications; absence of that resolution means exact acceptance.'
        ),
    ] = None
    media_buy_frequency_cap: Annotated[
        media_buy_frequency_cap_1.MediaBuyFrequencyCap | None,
        Field(
            description='Concrete aggregate max-impression cap expected at the MediaBuy root. Every returned product must participate in one shared counter for this exact value. Proposals carry it in commercial_terms.frequency_cap.'
        ),
    ] = None
    required_overlay_support: Annotated[
        targeting_overlay_requirements.TargetingOverlayRequirements | None,
        Field(
            description='Minimum product-scoped targeting dimensions the buyer must be able to select independently on packages later. This requests capability, not current values, value-specific availability, a forecast for every later value, or one product per value.'
        ),
    ] = None
    required_media_buy_support: Annotated[
        media_buy_support_requirements.ProductMediaBuySupportRequirements | None,
        Field(
            description='Minimum product participation in shared MediaBuy-level controls. For frequency caps, every returned product is promising composability in one aggregate seller counter for each requested per unit.'
        ),
    ] = None
    outcome_target: Annotated[
        outcome_target_1.OutcomeTarget | None,
        Field(
            description='Reverse-forecast planning input for sellers declaring media_buy.outcome_target: a goal plus a volume, a cost target, or both, answered on proposals. Inert on list_products for every seller. See outcome-target.json.'
        ),
    ] = None
    acceptance_context: Annotated[
        acceptance_context_1.AcceptanceContext | None,
        Field(
            description='Structured campaign and advertiser facts for coarse acceptance-policy matching. A matching product is not a guarantee of final acceptance.'
        ),
    ] = None
    catalog: catalog_selection.CatalogSelection | None = None
    policy_ids: Annotated[list[PolicyId] | None, Field(min_length=1)] = None
    ext: dict[str, Any] | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var acceptance_context : AcceptanceContext | None
var catalog : CatalogSelection | None
var ext : dict[str, typing.Any] | None
var media_buy_frequency_cap : MediaBuyFrequencyCap | None
var model_config
var offer_filters : ProductOfferFilters | None
var outcome_target : OutcomeTarget | None
var policy_ids : list[PolicyId] | None
var product_ids : list[ProductId] | None
var required_media_buy_support : ProductMediaBuySupportRequirements | None
var required_overlay_support : TargetingOverlayRequirements | None
var targeting_overlay : TargetingOverlay | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductDiscoveryTargetingResolution (**data: Any)

Expand source code

class ProductDiscoveryTargetingResolution(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    brief_targeting: Annotated[
        targeting.TargetingOverlay,
        Field(
            description="Structured delivery constraints the seller resolved from explicit hard targeting in the brief. This is the seller's literal interpretation, not a counteroffer: products that cannot honor it are omitted. Sellers MUST emit this confirmation when the interpretation materially affects product eligibility, pricing, or forecasting; otherwise it is a best practice. Unchanged structured targeting_overlay values are not repeated."
        ),
    ]
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var brief_targeting : TargetingOverlay
var ext : ExtensionObject | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductPurchase (**data: Any)

Expand source code

class ProductPurchase(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    product_id: Annotated[str, Field(min_length=1)]
    pricing_option_id: Annotated[str, Field(min_length=1)]
    pricing: Annotated[
        canonical_pricing_option.CanonicalPricingOption | None,
        Field(
            description='Resolved selected pricing terms. Optional on buy_products input, where pricing_option_id plus the versioned feed identifies the offer; required inside accepted commercial_terms. Its pricing_option_id MUST match the sibling field.'
        ),
    ] = None
    format_option_refs: Annotated[
        list[format_option_ref.FormatOptionReference] | None,
        Field(
            description='Canonical format options selected from the published product offer. Legacy named-format identifiers are not accepted.',
            min_length=1,
        ),
    ] = None
    catalog_ids: Annotated[
        list[CatalogId] | None,
        Field(
            description='Previously synchronized account catalog IDs promoted by this selection. Callers manage catalog bodies through sync_catalogs rather than inlining them here.',
            min_length=1,
        ),
    ] = None
    budget: Annotated[
        StrictFloat | None,
        Field(
            description='Hard spend cap for this selection in the media-buy currency. In seller-optimized allocation it is an optional ceiling, not a reserved 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
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Optional hard daily spend ceiling for this purchase. It is subordinate to the media-buy aggregate daily cap and is not a reserved daily allocation. Its day boundary is the media buy's budget_cap_timezone.",
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description='Soft lifetime spend target for seller-optimized allocation. Requires advertised media_buy.features.seller_optimized_min_spend_targets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.',
            ge=0.0,
        ),
    ] = None
    impressions: Annotated[
        StrictFloat | None, Field(ge=0.0, title='Product Purchase Impressions')
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description='Resolved package flight start. On direct-purchase input, omission inherits the MediaBuy start; accepted proposal snapshots carry the resolved timestamp.'
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description='Resolved package flight end. On direct-purchase input, omission inherits the MediaBuy end; accepted proposal snapshots carry the resolved timestamp.'
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Purchase pacing, subordinate to media-buy pacing. In seller-optimized allocation, pacing that differs from the media-buy pacing requires advertised media_buy.features.seller_optimized_package_pacing; otherwise rejected with UNSUPPORTED_FEATURE.'
        ),
    ] = None
    bidding: bidding_policy.BiddingPolicy | None = None
    targeting_overlay: Annotated[
        targeting.TargetingOverlay | None,
        Field(
            description="Resolved effective buyer-selected targeting, including compatible wholesale signal selections, applied within the product's published targeting contract. Cleared dimensions are omitted; null is invalid in an accepted snapshot."
        ),
    ] = None
    optimization_goals: Annotated[
        list[canonical_optimization_goal.CanonicalOptimizationGoal] | None, Field(min_length=1)
    ] = None
    audience_evidence_requirements: Annotated[
        product_audience_evidence_requirements.ProductAudienceEvidenceRequirements | None,
        Field(
            description='Buyer evidence-admissibility policy carried into the accepted purchase snapshot.',
            title='Product Purchase Audience Evidence Requirements',
        ),
    ] = None
    audience_evidence_pins: Annotated[
        list[audience_evidence_pin.AudienceEvidencePin] | None,
        Field(
            description='Exact immutable audience-evidence snapshots selected for package construction.',
            min_length=1,
        ),
    ] = None
    agency_estimate_number: Annotated[
        str | None,
        Field(
            description='Package-level agency estimate or authorization reference.', max_length=100
        ),
    ] = None
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque buyer package correlation preserved in the accepted snapshot and readback.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None
    measurement_terms: Annotated[
        canonical_measurement_terms.CanonicalMeasurementTerms | None,
        Field(
            description='Published or negotiated billing-measurement and makegood terms for this purchase. Direct buyers may omit this to inherit the product default; accepted proposal snapshots preserve the resolved terms.',
            title='Product Purchase Measurement Terms',
        ),
    ] = None
    performance_standards: Annotated[
        list[canonical_performance_standard.CanonicalPerformanceStandard] | None,
        Field(
            description='Published or negotiated metric thresholds and measurement vendors. Direct buyers may omit this to inherit the product defaults; accepted proposal snapshots preserve every applicable standard.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agency_estimate_number : str | None
var audience_evidence_pins : list[AudienceEvidencePin] | None
var audience_evidence_requirements : ProductAudienceEvidenceRequirements | None
var bidding : BiddingPolicy | None
var budget : float | None
var catalog_ids : list[CatalogId] | None
var context : ContextObject | None
var daily_budget_cap : float | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var format_option_refs : list[FormatOptionReference1 | FormatOptionReference2] | None
var impressions : float | None
var measurement_terms : CanonicalMeasurementTerms | None
var min_spend_target : float | None
var model_config
var optimization_goals : list[CanonicalOptimizationGoal1 | CanonicalOptimizationGoal2 | CanonicalOptimizationGoal3] | None
var pacing : Pacing | None
var performance_standards : list[CanonicalPerformanceStandard] | None
var pricing : CanonicalPricingOption | None
var pricing_option_id : str
var product_id : str
var start_time : pydantic.types.AwareDatetime | None
var targeting_overlay : TargetingOverlay | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductPurchaseInput (**data: Any)

Expand source code

class ProductPurchaseInput(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    product_id: Annotated[str, Field(min_length=1)]
    pricing_option_id: Annotated[str, Field(min_length=1)]
    pricing: Annotated[
        canonical_pricing_option.CanonicalPricingOption | None,
        Field(
            description='Resolved selected pricing terms. Optional on buy_products input, where pricing_option_id plus the versioned feed identifies the offer; required inside accepted commercial_terms. Its pricing_option_id MUST match the sibling field.'
        ),
    ] = None
    format_option_refs: Annotated[
        list[format_option_ref.FormatOptionReference] | None,
        Field(
            description='Canonical format options selected from the published product offer. Legacy named-format identifiers are not accepted.',
            min_length=1,
        ),
    ] = None
    catalog_ids: Annotated[
        list[CatalogId] | None,
        Field(
            description='Previously synchronized account catalog IDs promoted by this selection. Callers manage catalog bodies through sync_catalogs rather than inlining them here.',
            min_length=1,
        ),
    ] = None
    budget: Annotated[
        StrictFloat | None,
        Field(
            description='Hard spend cap for this selection in the media-buy currency. In seller-optimized allocation it is an optional ceiling, not a reserved 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
    daily_budget_cap: Annotated[
        StrictFloat | None,
        Field(
            description="Optional hard daily spend ceiling for this purchase. It is subordinate to the media-buy aggregate daily cap and is not a reserved daily allocation. Its day boundary is the media buy's budget_cap_timezone.",
            ge=0.0,
        ),
    ] = None
    min_spend_target: Annotated[
        StrictFloat | None,
        Field(
            description='Soft lifetime spend target for seller-optimized allocation. Requires advertised media_buy.features.seller_optimized_min_spend_targets; otherwise rejected with UNSUPPORTED_FEATURE before any over-subscription validation.',
            ge=0.0,
        ),
    ] = None
    impressions: Annotated[
        StrictFloat | None, Field(ge=0.0, title='Product Purchase Impressions')
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description='Resolved package flight start. On direct-purchase input, omission inherits the MediaBuy start; accepted proposal snapshots carry the resolved timestamp.'
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description='Resolved package flight end. On direct-purchase input, omission inherits the MediaBuy end; accepted proposal snapshots carry the resolved timestamp.'
        ),
    ] = None
    pacing: Annotated[
        pacing_1.Pacing | None,
        Field(
            description='Purchase pacing, subordinate to media-buy pacing. In seller-optimized allocation, pacing that differs from the media-buy pacing requires advertised media_buy.features.seller_optimized_package_pacing; otherwise rejected with UNSUPPORTED_FEATURE.'
        ),
    ] = None
    bidding: bidding_policy.BiddingPolicy | None = None
    targeting_overlay: Annotated[
        targeting_input.TargetingOverlayInput | None,
        Field(
            description="Per-dimension targeting input. Omission inherits the selected product's configured/default dimension, a non-null value replaces it, and null explicitly suppresses it. A clear cannot remove inherent product scope."
        ),
    ] = None
    optimization_goals: Annotated[
        list[canonical_optimization_goal.CanonicalOptimizationGoal] | None, Field(min_length=1)
    ] = None
    audience_evidence_requirements: Annotated[
        product_audience_evidence_requirements.ProductAudienceEvidenceRequirements | None,
        Field(
            description='Buyer evidence-admissibility policy carried into the accepted purchase snapshot.',
            title='Product Purchase Audience Evidence Requirements',
        ),
    ] = None
    audience_evidence_pins: Annotated[
        list[audience_evidence_pin.AudienceEvidencePin] | None,
        Field(
            description='Exact immutable audience-evidence snapshots selected for package construction.',
            min_length=1,
        ),
    ] = None
    agency_estimate_number: Annotated[
        str | None,
        Field(
            description='Package-level agency estimate or authorization reference.', max_length=100
        ),
    ] = None
    context: Annotated[
        context_1.ContextObject | None,
        Field(
            description='Opaque buyer package correlation preserved in the accepted snapshot and readback.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None
    measurement_terms: Annotated[
        canonical_measurement_terms.CanonicalMeasurementTerms | None,
        Field(
            description='Published or negotiated billing-measurement and makegood terms for this purchase. Direct buyers may omit this to inherit the product default; accepted proposal snapshots preserve the resolved terms.',
            title='Product Purchase Measurement Terms',
        ),
    ] = None
    performance_standards: Annotated[
        list[canonical_performance_standard.CanonicalPerformanceStandard] | None,
        Field(
            description='Published or negotiated metric thresholds and measurement vendors. Direct buyers may omit this to inherit the product defaults; accepted proposal snapshots preserve every applicable standard.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agency_estimate_number : str | None
var audience_evidence_pins : list[AudienceEvidencePin] | None
var audience_evidence_requirements : ProductAudienceEvidenceRequirements | None
var bidding : BiddingPolicy | None
var budget : float | None
var catalog_ids : list[CatalogId] | None
var context : ContextObject | None
var daily_budget_cap : float | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var format_option_refs : list[FormatOptionReference1 | FormatOptionReference2] | None
var impressions : float | None
var measurement_terms : CanonicalMeasurementTerms | None
var min_spend_target : float | None
var model_config
var optimization_goals : list[CanonicalOptimizationGoal1 | CanonicalOptimizationGoal2 | CanonicalOptimizationGoal3] | None
var pacing : Pacing | None
var performance_standards : list[CanonicalPerformanceStandard] | None
var pricing : CanonicalPricingOption | None
var pricing_option_id : str
var product_id : str
var start_time : pydantic.types.AwareDatetime | None
var targeting_overlay : TargetingOverlayInput | TargetingOverlay | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Expand source code

class ProductRefinementRequests(RootModel[list[ProductRefinementRequests1]]):
    root: Annotated[
        list[ProductRefinementRequests1],
        Field(
            description='Change requests for iterating on product discovery results and proposals.',
            min_length=1,
            title='Product Refinement Requests',
        ),
    ]

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[Annotated[Union[ProductRefinementRequests2, ProductRefinementRequests3, ProductRefinementRequests4], FieldInfo(annotation=NoneType, required=True, discriminator='scope')]]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : list[ProductRefinementRequests2 | ProductRefinementRequests3 | ProductRefinementRequests4]

class ProductRefinementRequests2 (**data: Any)

Expand source code

class ProductRefinementRequests2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[Literal['request'], Field(description='Change scoped to the overall request.')] = 'request'
    ask: Annotated[
        str, Field(description='What the buyer is asking for at the request level.', min_length=1)
    ]

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var ask : str
var model_config
var scope : Literal['request']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductRefinementRequests3 (**data: Any)

Expand source code

class ProductRefinementRequests3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[Literal['product'], Field(description='Change scoped to a specific product.')] = 'product'
    product_id: Annotated[
        str,
        Field(description='Product ID from a previous product-discovery response.', min_length=1),
    ]
    action: Annotated[Action | None, Field(description='Requested product-level action.')] = (
        Action.include
    )
    ask: Annotated[
        str | None, Field(description='What the buyer is asking for on this product.', min_length=1)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Action | None
var ask : str | None
var model_config
var product_id : str
var scope : Literal['product']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductRefinementRequests4 (**data: Any)

Expand source code

class ProductRefinementRequests4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['proposal'], Field(description='Change scoped to a specific proposal.')
    ] = 'proposal'
    proposal_id: Annotated[
        str,
        Field(description='Proposal ID from a previous product-discovery response.', min_length=1),
    ]
    action: Annotated[Action11 | None, Field(description='Requested proposal-level action.')] = (
        Action11.include
    )
    ask: Annotated[
        str | None,
        Field(description='What the buyer is asking for on this proposal.', min_length=1),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Action11 | None
var ask : str | None
var model_config
var proposal_id : str
var scope : Literal['proposal']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductResponseField (*args, **kwds)

Expand source code

class ProductResponseField(StrEnum):
    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'

Enum where members are also (and must be) strings

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 delivery_type
var demographic_targeting
var description
var exclusivity
var execution_requirements
var expires_at
var forecast
var format_options
var identity
var list_applications
var max_optimization_goals
var measurement_terms
var media_buy_support
var name
var overlay_support
var performance_standards
var placements
var pricing_options
var product_id
var publisher_properties
var reporting_capabilities
var signal_targeting_allowed
var signal_targeting_rules
var social_placement_surfaces
var sponsored_placement_types
var targeting_resolution
var video_placement_types

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

Expand source code

class ProductResponseFields(RootModel[list[ProductResponseField]]):
    root: Annotated[
        list[ProductResponseField],
        Field(
            description='Canonical product fields a buyer requests from list_products. Required product_id and name fields are always returned. list_applications also overrides projection whenever a property or collection list is in the effective targeting because it is the decision receipt for seller-specific list matching. targeting_resolution and expires_at override projection whenever the seller returns modifications, as does collection_targeting_allowed whenever returned overlay_support declares collection_list. Legacy named-format fields remain available only through get_products.',
            min_length=1,
            title='Product Response Fields',
        ),
    ]

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

Class variables

var model_config
var root : list[ProductResponseField]

class Proposal2 (**data: Any)

Expand source code

class Proposal2(Proposal):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Proposal
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Proposal:
- model_dump
- model_dump_json
- model_summary

class Proposal3 (**data: Any)

Expand source code

class Proposal3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(max_length=255, min_length=1)]
    proposal_kind: ProposalKind
    parent_proposal_id: Annotated[
        str,
        Field(
            description="Immediate predecessor this snapshot was forked from. Every proposal produced by refine_proposals carries it, equal to the request's source proposal_id, so negotiation lineage is reconstructible from proposals alone.",
            max_length=255,
            min_length=1,
        ),
    ]
    media_buy_id: Annotated[str | None, Field(min_length=1)] = None
    opportunity_id: Annotated[
        str | None,
        Field(
            description='Buyer planning cycle associated with this proposal. Revisions inherit it; it does not participate in proposal identity.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]{1,255}$',
        ),
    ] = None
    base_media_buy_revision: Annotated[SchemaInt | None, Field(ge=1)] = None
    proposal_status: Annotated[
        Literal['committed'],
        Field(
            description='draft is indicative and unreserved; committed has firm terms with inventory reserved until expires_at; accepted is the historical snapshot attached to a MediaBuy.',
            title='Proposal Status',
        ),
    ] = 'committed'
    accepted_at: AwareDatetime | None = None
    expires_at: Annotated[
        AwareDatetime,
        Field(
            description='For a draft, the indicative-terms freshness deadline. For a committed proposal, the inventory-hold deadline.'
        ),
    ]
    name: Annotated[str, Field(max_length=500, min_length=1)]
    description: Annotated[str | None, Field(max_length=2000)] = None
    brief_alignment: Annotated[str | None, Field(max_length=2000)] = None
    commercial_terms: commercial_terms_1.CommercialTerms
    terms_digest: Annotated[
        str,
        Field(
            description='Base64url SHA-256 digest of the RFC 8785 JCS serialization of commercial_terms, prefixed with sha256:.',
            pattern='^sha256:[A-Za-z0-9_-]{43}$',
        ),
    ]
    insertion_order: insertion_order_1.InsertionOrder | None = None
    total_budget_guidance: Annotated[
        TotalBudgetGuidance | None,
        Field(
            description="Optional budget guidance for this proposal — the planning answer to criteria.outcome_target and to open-budget briefs. commercial_terms.total_budget remains the concrete figure the plan is priced at; this band expresses the seller's recommended range around it. When criteria.outcome_target carries cost_per, the cost answer is commercial_terms.bidding.cost_per and this band's currency equals cost_per.currency."
        ),
    ] = None
    forecast: Annotated[
        canonical_delivery_forecast.CanonicalDeliveryForecast | None,
        Field(
            description="Aggregate forecasted delivery for the proposal. For outcome_target requests, points carry the goal's metric or event key in metrics; with cost_per, that is the goal volume planned under the commercial_terms.bidding policy, and currency equals cost_per.currency."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Proposal6

Class variables

var accepted_at : pydantic.types.AwareDatetime | None
var base_media_buy_revision : int | None
var brief_alignment : str | None
var commercial_terms : CommercialTerms
var description : str | None
var expires_at : pydantic.types.AwareDatetime
var forecast : CanonicalDeliveryForecast | None
var insertion_order : InsertionOrder | None
var media_buy_id : str | None
var model_config
var name : str
var opportunity_id : str | None
var parent_proposal_id : str
var proposal_id : str
var proposal_kind : ProposalKind
var proposal_status : Literal['committed']
var terms_digest : str
var total_budget_guidance : TotalBudgetGuidance | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Proposal4 (**data: Any)

Expand source code

class Proposal4(Proposal):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Proposal
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Proposal:
- model_dump
- model_dump_json
- model_summary

class Proposal5 (**data: Any)

Expand source code

class Proposal5(Proposal):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Proposal
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Proposal:
- model_dump
- model_dump_json
- model_summary

class Proposal6 (**data: Any)

Expand source code

class Proposal6(Proposal3):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

Proposal3
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

Proposal3:
- model_dump
- model_dump_json
- model_summary

class ProposalBudgetConstraint (**data: Any)

Expand source code

class ProposalBudgetConstraint(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    min: 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}$')]

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

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var max : float | None
var min : float | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalDecline (**data: Any)

Expand source code

class ProposalDecline(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[
        str,
        Field(
            description='Immutable proposal ID returned by request_proposals or refine_proposals.',
            max_length=255,
            min_length=1,
        ),
    ]
    reason: proposal_decline_reason.ProposalDeclineReason
    detail: Annotated[
        str | None,
        Field(
            description='Optional short, non-identifying explanation. MUST NOT identify a competitor or disclose sensitive campaign information.',
            max_length=500,
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var detail : str | None
var model_config
var proposal_id : str
var reason : ProposalDeclineReason

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalKind (*args, **kwds)

Expand source code

class ProposalKind(StrEnum):
    new_media_buy = 'new_media_buy'
    media_buy_update = 'media_buy_update'
    media_buy_cancellation = 'media_buy_cancellation'

Enum where members are also (and must be) strings

Ancestors

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

Class variables

var media_buy_cancellation
var media_buy_update
var new_media_buy

class ProposalRefinement2 (**data: Any)

Expand source code

class ProposalRefinement2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['finalize'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'finalize'
    change_kind: Annotated[
        ChangeKind | None,
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = ChangeKind.amendment
    constraints: Annotated[
        Constraints | None,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ] = None
    product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ] = None
    alternatives: Annotated[
        Alternatives | None,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ] = None
    ask: Annotated[
        str | None,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ] = None
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria | None,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ] = None
    remove_media_buy_frequency_cap: Annotated[
        Literal[True] | None,
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['finalize']
var alternatives : Alternatives | None
var ask : str | None
var change_kind : ChangeKind | None
var constraints : Constraints | None
var criteria : ProductDiscoveryCriteria | None
var model_config
var product_changes : ProductChangeMap | None
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalRefinement3 (**data: Any)

Expand source code

class ProposalRefinement3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['revise'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'revise'
    change_kind: Annotated[
        ChangeKind | None,
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = ChangeKind.amendment
    constraints: Annotated[
        Constraints1,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ]
    product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ] = None
    alternatives: Annotated[
        Alternatives | None,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ] = None
    ask: Annotated[
        str | None,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ] = None
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria | None,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ] = None
    remove_media_buy_frequency_cap: Annotated[
        Literal[True] | None,
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['revise']
var alternatives : Alternatives | None
var ask : str | None
var change_kind : ChangeKind | None
var constraints : Constraints1
var criteria : ProductDiscoveryCriteria | None
var model_config
var product_changes : ProductChangeMap | None
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalRefinement4 (**data: Any)

Expand source code

class ProposalRefinement4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['revise'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'revise'
    change_kind: Annotated[
        ChangeKind | None,
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = ChangeKind.amendment
    constraints: Annotated[
        Constraints2 | None,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ] = None
    product_changes: Annotated[
        product_change_map.ProductChangeMap,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ]
    alternatives: Annotated[
        Alternatives | None,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ] = None
    ask: Annotated[
        str | None,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ] = None
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria | None,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ] = None
    remove_media_buy_frequency_cap: Annotated[
        Literal[True] | None,
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['revise']
var alternatives : Alternatives | None
var ask : str | None
var change_kind : ChangeKind | None
var constraints : Constraints2 | None
var criteria : ProductDiscoveryCriteria | None
var model_config
var product_changes : ProductChangeMap
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalRefinement5 (**data: Any)

Expand source code

class ProposalRefinement5(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['revise'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'revise'
    change_kind: Annotated[
        ChangeKind | None,
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = ChangeKind.amendment
    constraints: Annotated[
        Constraints3 | None,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ] = None
    product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ] = None
    alternatives: Annotated[
        Alternatives,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ]
    ask: Annotated[
        str | None,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ] = None
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria | None,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ] = None
    remove_media_buy_frequency_cap: Annotated[
        Literal[True] | None,
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['revise']
var alternatives : Alternatives
var ask : str | None
var change_kind : ChangeKind | None
var constraints : Constraints3 | None
var criteria : ProductDiscoveryCriteria | None
var model_config
var product_changes : ProductChangeMap | None
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalRefinement6 (**data: Any)

Expand source code

class ProposalRefinement6(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['revise'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'revise'
    change_kind: Annotated[
        ChangeKind | None,
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = ChangeKind.amendment
    constraints: Annotated[
        Constraints4 | None,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ] = None
    product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ] = None
    alternatives: Annotated[
        Alternatives | None,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ] = None
    ask: Annotated[
        str,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ]
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria | None,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ] = None
    remove_media_buy_frequency_cap: Annotated[
        Literal[True] | None,
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

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

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

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

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['revise']
var alternatives : Alternatives | None
var ask : str
var change_kind : ChangeKind | None
var constraints : Constraints4 | None
var criteria : ProductDiscoveryCriteria | None
var model_config
var product_changes : ProductChangeMap | None
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalRefinement7 (**data: Any)

Expand source code

class ProposalRefinement7(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['revise'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'revise'
    change_kind: Annotated[
        ChangeKind | None,
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = ChangeKind.amendment
    constraints: Annotated[
        Constraints5 | None,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ] = None
    product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ] = None
    alternatives: Annotated[
        Alternatives | None,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ] = None
    ask: Annotated[
        str | None,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ] = None
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ]
    remove_media_buy_frequency_cap: Annotated[
        Literal[True] | None,
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['revise']
var alternatives : Alternatives | None
var ask : str | None
var change_kind : ChangeKind | None
var constraints : Constraints5 | None
var criteria : ProductDiscoveryCriteria
var model_config
var product_changes : ProductChangeMap | None
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalRefinement8 (**data: Any)

Expand source code

class ProposalRefinement8(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['revise'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'revise'
    change_kind: Annotated[
        ChangeKind | None,
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = ChangeKind.amendment
    constraints: Annotated[
        Constraints6 | None,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ] = None
    product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ] = None
    alternatives: Annotated[
        Alternatives | None,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ] = None
    ask: Annotated[
        str | None,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ] = None
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria | None,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ] = None
    remove_media_buy_frequency_cap: Annotated[
        Literal[True],
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['revise']
var alternatives : Alternatives | None
var ask : str | None
var change_kind : ChangeKind | None
var constraints : Constraints6 | None
var criteria : ProductDiscoveryCriteria | None
var model_config
var product_changes : ProductChangeMap | None
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProposalRefinement9 (**data: Any)

Expand source code

class ProposalRefinement9(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    action: Annotated[
        Literal['revise'],
        Field(
            description='revise creates a new draft snapshot with changed commercial terms. finalize MUST target a draft; it creates a new committed snapshot without changing terms and reserves inventory until its expires_at.'
        ),
    ] = 'revise'
    change_kind: Annotated[
        Literal['cancellation'],
        Field(
            description='Desired successor proposal. cancellation is valid only when the source proposal is accepted and attached to a non-terminal MediaBuy.'
        ),
    ] = 'cancellation'
    constraints: Annotated[
        Constraints7 | None,
        Field(
            description='Hard requirements for every revised proposal. Keys are echoed in unsatisfied_constraints on partial or unable results. A draft that fails any present constraint MUST NOT be returned as revised: the result is partial or unable with reason_code constraint_unsatisfiable — which takes precedence over every other reason code — and the failing keys in unsatisfied_constraints.'
        ),
    ] = None
    product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Product IDs mapped to membership actions checked against commercial_terms.purchases. include requires presence; omit requires absence. The verbs match legacy get_products refinement.'
        ),
    ] = None
    alternatives: Annotated[
        Alternatives | None,
        Field(
            description='Request drafts with distinct commercial terms by count. Every returned alternative MUST carry distinct commercial_terms and therefore a unique terms_digest; diversity preferences remain in ask.'
        ),
    ] = None
    ask: Annotated[
        str | None,
        Field(
            description='What the buyer is asking for on this proposal, or the cancellation reason for action revise. The seller returns a new draft proposal snapshot; this text never directly mutates the source proposal or MediaBuy.',
            min_length=1,
        ),
    ] = None
    criteria: Annotated[
        product_discovery_criteria.ProductDiscoveryCriteria | None,
        Field(
            description='Structured discovery changes for action revise. Each present field replaces that criterion from the source proposal; omitted fields inherit. Concrete targeting, future targeting support, and offer filters belong here rather than being repeated in ask.'
        ),
    ] = None
    remove_media_buy_frequency_cap: Annotated[
        Literal[True] | None,
        Field(
            description='Request a revised draft whose commercial terms omit the existing MediaBuy frequency cap. Omission inherits it. To replace it, provide criteria.media_buy_frequency_cap instead.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Literal['revise']
var alternatives : Alternatives | None
var ask : str | None
var change_kind : Literal['cancellation']
var constraints : Constraints7 | None
var criteria : ProductDiscoveryCriteria | None
var model_config
var product_changes : ProductChangeMap | None
var proposal_id : str
var remove_media_buy_frequency_cap : Literal[True] | None

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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 ProvidePerformanceFeedbackResponse2 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 PurchaseContinuation (**data: Any)

Expand source code

class PurchaseContinuation(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['listed_purchase'] = 'listed_purchase'
    product_ids: Annotated[
        list[ProductId],
        Field(
            description='Exact products the coordinator promoted and re-read through account-scoped list_products before returning this result. The set MUST match products[].product_id.',
            min_length=1,
        ),
    ]
    cache_scope: Literal['account'] = 'account'
    feed_version: Annotated[
        str,
        Field(
            description='Real seller-issued account-scoped feed fence obtained by re-reading the promoted products through list_products.',
            min_length=1,
        ),
    ]
    pricing_version: Annotated[
        str | None,
        Field(
            description='Real seller-issued pricing fence from the same account-scoped list_products response, when the seller versions pricing independently.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var cache_scope : Literal['account']
var feed_version : str
var kind : Literal['listed_purchase']
var model_config
var pricing_version : str | None
var product_ids : list[ProductId]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PurchaseContinuation1 (**data: Any)

Expand source code

class PurchaseContinuation1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    kind: Literal['legacy_create'] = 'legacy_create'
    continuation_token: Annotated[
        str,
        Field(
            description='Opaque, short-lived coordinator token bound to the caller principal, account, and complete observed product/pricing payload. It is not a seller-issued feed fence.',
            min_length=16,
        ),
    ]
    continuation_expires_at: Annotated[
        AwareDatetime,
        Field(description='Absolute expiry of the single-use compatibility continuation.'),
    ]
    source_adcp_version: Annotated[
        SourceAdcpVersion,
        Field(
            description='Established AdCP version actually negotiated with the peer. This provenance is required; the coordinator MUST NOT infer stronger guarantees from the label.'
        ),
    ]
    product_ids: Annotated[
        list[ProductId],
        Field(
            description='Exact products bound to this continuation. A follow-up MUST select a non-empty subset and MUST NOT substitute an ID from another discovery result.',
            min_length=1,
        ),
    ]
    losses: Annotated[
        list[Loss] | Losses,
        Field(
            description='Guarantees that the established create_media_buy continuation cannot provide. The coordinator MUST fail before mutation unless the caller explicitly accepts every listed loss.',
            min_length=2,
        ),
    ]
    requires_explicit_acceptance: Literal[True]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var continuation_expires_at : pydantic.types.AwareDatetime
var continuation_token : str
var kind : Literal['legacy_create']
var losses : list[Loss] | Losses
var model_config
var product_ids : list[ProductId]
var requires_explicit_acceptance : Literal[True]
var source_adcp_version : SourceAdcpVersion

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PurchaseContinuation2 (**data: Any)

Expand source code

class PurchaseContinuation2(PurchaseContinuation):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

PurchaseContinuation
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

PurchaseContinuation:
- model_dump
- model_dump_json
- model_summary

class PurchaseContinuation3 (**data: Any)

Expand source code

class PurchaseContinuation3(PurchaseContinuation1):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

PurchaseContinuation1
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

PurchaseContinuation1:
- model_dump
- model_dump_json
- model_summary

class PurchaseContinuation4 (**data: Any)

Expand source code

class PurchaseContinuation4(PurchaseContinuation):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

PurchaseContinuation
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

PurchaseContinuation:
- model_dump
- model_dump_json
- model_summary

class PurchaseContinuation5 (**data: Any)

Expand source code

class PurchaseContinuation5(PurchaseContinuation1):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

PurchaseContinuation1
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

PurchaseContinuation1:
- model_dump
- model_dump_json
- model_summary

class PurchaseContinuation6 (**data: Any)

Expand source code

class PurchaseContinuation6(PurchaseContinuation):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

PurchaseContinuation
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

PurchaseContinuation:
- model_dump
- model_dump_json
- model_summary

class PurchaseContinuation7 (**data: Any)

Expand source code

class PurchaseContinuation7(PurchaseContinuation1):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

PurchaseContinuation1
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

PurchaseContinuation1:
- model_dump
- model_dump_json
- model_summary

class Qualifier (**data: Any)

Expand source code

class Qualifier(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    viewability_standard: viewability_standard_1.ViewabilityStandard | None = None
    completion_source: completion_source_1.CompletionSource | None = None
    attribution_methodology: attribution_methodology_1.AttributionMethodology | None = None
    attribution_window: duration.Duration | None = None
    lift_dimension: lift_dimension_1.LiftDimension | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var attribution_methodology : AttributionMethodology | None
var attribution_window : Duration | None
var completion_source : CompletionSource | None
var lift_dimension : LiftDimension | None
var model_config
var viewability_standard : ViewabilityStandard | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Refine1 (**data: Any)

Expand source code

class Refine1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['request'],
        Field(
            description='Change scoped to the overall request — direction for the selection as a whole.'
        ),
    ] = 'request'
    ask: Annotated[
        str,
        Field(
            description="What the buyer is asking for at the request level (e.g., 'more video options and less display', 'suggest how to combine these products').",
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var ask : str
var model_config
var scope : Literal['request']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Refine2 (**data: Any)

Expand source code

class Refine2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[Literal['product'], Field(description='Change scoped to a specific product.')] = 'product'
    product_id: Annotated[
        str, Field(description='Product ID from a previous get_products response.', min_length=1)
    ]
    action: Annotated[
        Action | None,
        Field(
            description="'include' (default): return this product with updated pricing and data. 'omit': exclude this product from the response. 'more_like_this': find additional products similar to this one (the original is also returned). Optional — when omitted, the seller treats the entry as action: 'include'."
        ),
    ] = Action.include
    ask: Annotated[
        str | None,
        Field(
            description="What the buyer is asking for on this product. For 'include': specific changes to request (e.g., 'add 16:9 format'). For 'more_like_this': what 'similar' means (e.g., 'same audience but video format'). Ignored when action is 'omit'.",
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Action | None
var ask : str | None
var model_config
var product_id : str
var scope : Literal['product']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Refine3 (**data: Any)

Expand source code

class Refine3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    scope: Annotated[
        Literal['proposal'], Field(description='Change scoped to a specific proposal.')
    ] = 'proposal'
    proposal_id: Annotated[
        str, Field(description='Proposal ID from a previous get_products response.', min_length=1)
    ]
    action: Annotated[
        Action9 | None,
        Field(
            description="'include' (default): return this proposal with updated allocations and pricing. 'omit': exclude this proposal from the response. 'finalize': request firm pricing and inventory hold. New callers use refine_proposals with action revise for a draft successor or action finalize for a committed held successor; terminal feedback is available through decline_proposals.\n\nLegacy finalize is exclusive within the parent `refine[]` array: see the array-level description for the finalize-exclusivity rule (mixing finalize with non-finalize entries is rejected) and multi-finalize atomicity contract."
        ),
    ] = Action9.include
    ask: Annotated[
        str | None,
        Field(
            description="What the buyer is asking for on this proposal (e.g., 'shift more budget toward video', 'reduce total by 10%'). Ignored when action is omit.",
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var action : Action9 | None
var ask : str | None
var model_config
var proposal_id : str
var scope : Literal['proposal']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RefineProposalsInputRequired (**data: Any)

Expand source code

class RefineProposalsInputRequired(CompactTaskInputRequired):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

CompactTaskInputRequired
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskInputRequired:
- 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 RefineProposalsResponse1 (**data: Any)

Expand source code

class RefineProposalsResponse1(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    results: Annotated[
        list[Results8] | Results,
        Field(
            description="Ordered results. If any result is finalized, every result MUST be finalized; a finalize batch either creates every requested hold or none. Every returned proposal carries parent_proposal_id equal to the result's source_proposal_id, making negotiation lineage reconstructible from the proposals alone.",
            min_length=1,
        ),
    ]
    products: Annotated[
        list[canonical_product.CanonicalProduct],
        Field(
            description="Canonical products needed to evaluate the resulting terms. For revised or partial results whose effective criteria contain property or collection lists, each affected product MUST carry fresh list_applications receipts from the revision's product reevaluation. Finalization changes no terms and MAY repeat the receipts already bound to the source proposal rather than reevaluating them."
        ),
    ]
    status: Literal['completed'] = 'completed'
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_version : str | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var message : str | None
var model_config
var products : list[CanonicalProduct]
var replayed : Literal[True] | None
var results : list[Results9 | Results10 | Results11 | Results12] | Results
var status : Literal['completed']
var task_id : str | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RefineProposalsResponse2 (**data: Any)

Expand source code

class RefineProposalsResponse2(AdcpResponse, CompactTaskSubmitted):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    results: Annotated[
        list[Results14] | Results | None,
        Field(
            description="Ordered results. If any result is finalized, every result MUST be finalized; a finalize batch either creates every requested hold or none. Every returned proposal carries parent_proposal_id equal to the result's source_proposal_id, making negotiation lineage reconstructible from the proposals alone.",
            min_length=1,
        ),
    ] = None
    products: Annotated[
        list[canonical_product.CanonicalProduct] | None,
        Field(
            description="Canonical products needed to evaluate the resulting terms. For revised or partial results whose effective criteria contain property or collection lists, each affected product MUST carry fresh list_applications receipts from the revision's product reevaluation. Finalization changes no terms and MAY repeat the receipts already bound to the source proposal rather than reevaluating them."
        ),
    ] = None
    status: Status | None = None
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_version : str | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var message : str | None
var model_config
var products : list[CanonicalProduct] | None
var replayed : Literal[True] | None
var results : list[Results15 | Results16 | Results17 | Results18] | Results | None
var status : Status | None
var task_id : str | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class RefineProposalsSubmitted (**data: Any)

Expand source code

class RefineProposalsSubmitted(CompactTaskSubmitted):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class RefineProposalsWorking (**data: Any)

Expand source code

class RefineProposalsWorking(CompactTaskWorking):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

CompactTaskWorking
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskWorking:
- 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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var 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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var 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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var 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 Refinements (**data: Any)

Expand source code

class Refinements(AdCPBaseModel):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RegionAliase (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class RegionAliase(Jurisdiction):
    pass

A str generated from a JSON Schema string root.

Ancestors

Jurisdiction
adcp.types._scalar.ScalarStr
adcp.types._scalar._ScalarRoot
builtins.str

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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var 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 ReportingCommitment (**data: Any)

Expand source code

class ReportingCommitment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    purchase_index: Annotated[SchemaInt, Field(ge=0)]
    metrics: Annotated[
        list[canonical_reporting_commitment.CanonicalReportingCommitment], Field(min_length=1)
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var metrics : list[CanonicalReportingCommitment1 | CanonicalReportingCommitment2]
var model_config
var purchase_index : int

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportingDimensions (**data: Any)

Expand source code

class ReportingDimensions(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catalog_item: Annotated[
        CatalogItem | None,
        Field(
            description='Request a negotiated catalog_item breakdown. Omitting this key preserves the automatic behavior — sellers return catalog_item rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.'
        ),
    ] = None
    creative: Annotated[
        Creative | None,
        Field(
            description='Request a negotiated creative breakdown. Omitting this key preserves the automatic behavior — sellers return creative rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.'
        ),
    ] = None
    keyword: Annotated[
        Keyword | None,
        Field(
            description='Request a negotiated keyword breakdown. Omitting this key preserves the automatic behavior — sellers return keyword rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.'
        ),
    ] = None
    geo: Annotated[
        Geo | None,
        Field(
            description='Request geographic breakdown. Check reporting_capabilities.supports_geo_breakdown for available levels and systems.'
        ),
    ] = None
    device_type: Annotated[
        DeviceType | None, Field(description='Request device type breakdown.')
    ] = None
    device_platform: Annotated[
        DevicePlatform | None, Field(description='Request device platform breakdown.')
    ] = None
    format: Annotated[
        Format | None,
        Field(
            description='Request delivery broken down by canonical creative format kind. This dimension is negotiated on the GET path. Reporting webhook configuration does not negotiate or guarantee dimensional breakdowns, although a webhook payload may carry the same fields as an extension.'
        ),
    ] = None
    audience: Annotated[
        Audience | None, Field(description='Request audience segment breakdown.')
    ] = None
    demographic: Annotated[
        Demographic | None,
        Field(
            description="Request delivery broken down by demographic. Check the product's reporting_capabilities.supports_demographic_breakdown independently from demographic_targeting. When age_ranges is present, every requested range MUST be exactly supported by exact_predicates or equal one of the declared enumerated_intervals; sellers MUST reject unsupported ranges with UNSUPPORTED_FEATURE rather than silently widen or narrow them."
        ),
    ] = None
    spot: Annotated[
        Spot | None,
        Field(
            description='Request a spot-level as-run airing log for broadcast TV, radio, or other scheduled inventory. Rows are ordered by aired_at ascending. When limit is omitted, sellers SHOULD return the complete log for the requested reporting period.'
        ),
    ] = None
    placement: Annotated[Placement | None, Field(description='Request placement breakdown.')] = None
    property: Annotated[
        delivery_breakdown_controls.DeliveryBreakdownControls | None,
        Field(
            description='Request delivery by canonical publisher property. Check reporting_capabilities.supports_property_breakdown.'
        ),
    ] = None
    collection: Annotated[
        delivery_breakdown_controls.DeliveryBreakdownControls | None,
        Field(
            description='Request delivery by canonical content collection. Check reporting_capabilities.supports_collection_breakdown.'
        ),
    ] = None
    installment: Annotated[
        delivery_breakdown_controls.DeliveryBreakdownControls | None,
        Field(
            description='Request delivery by canonical installment within a collection. Check reporting_capabilities.supports_installment_breakdown.'
        ),
    ] = None
    collection_property: Annotated[
        delivery_breakdown_controls.DeliveryBreakdownControls | None,
        Field(
            description='Request delivery at the collection × property intersection. This is the reporting grain that can prove a collection delivered on a particular host service; independent collection and property marginals cannot. Check reporting_capabilities.supports_collection_property_breakdown.'
        ),
    ] = None
    installment_property: Annotated[
        delivery_breakdown_controls.DeliveryBreakdownControls | None,
        Field(
            description='Request delivery at the installment × property intersection. This is the reporting grain that can prove a specific airing, episode, issue, or programming block delivered on a particular host service; independent installment and property marginals cannot. Check reporting_capabilities.supports_installment_property_breakdown.'
        ),
    ] = None
    placement_property: Annotated[
        delivery_breakdown_controls.DeliveryBreakdownControls | None,
        Field(
            description='Request delivery at the placement × property intersection. Use when a placement may span multiple web, app, social, or assistant properties. Check reporting_capabilities.supports_placement_property_breakdown.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var audience : Audience | None
var catalog_item : CatalogItem | None
var collection : DeliveryBreakdownControls | None
var collection_property : DeliveryBreakdownControls | None
var creative : Creative | None
var demographic : Demographic | None
var device_platform : DevicePlatform | None
var device_type : DeviceType | None
var format : Format | None
var geo : Geo | None
var installment : DeliveryBreakdownControls | None
var installment_property : DeliveryBreakdownControls | None
var keyword : Keyword | None
var model_config
var placement : Placement | None
var placement_property : DeliveryBreakdownControls | None
var property : DeliveryBreakdownControls | None
var spot : Spot | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportingRevisionBinding (**data: Any)

Expand source code

class ReportingRevisionBinding(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    reporting_revision_id: Annotated[str, Field(max_length=255, min_length=1)]
    row_count: Annotated[SchemaInt, Field(ge=0)]
    control_totals: list[reporting_control_total.ReportingControlTotal]
    content_sha256: Annotated[
        str,
        Field(
            description='SHA-256 of RFC 8785 JCS of {reporting_revision_id,row_count,control_totals,reporting_rows}, where reporting_rows is the complete ordered sequence concatenated across every cursor page; identical to reporting_revision_1.revision_content_sha256.',
            pattern='^[A-Fa-f0-9]{64}$',
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var content_sha256 : str
var control_totals : list[ReportingControlTotal1 | ReportingControlTotal2]
var model_config
var reporting_revision_id : str
var row_count : int

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportingStatusView (*args, **kwds)

Expand source code

class ReportingStatusView(StrEnum):
    summary = 'summary'
    periods = 'periods'
    revision = 'revision'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var periods
var revision
var summary

class RequestProposalsInputRequired (**data: Any)

Expand source code

class RequestProposalsInputRequired(CompactTaskInputRequired):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

CompactTaskInputRequired
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskInputRequired:
- 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 RequestProposalsResponse1 (**data: Any)

Expand source code

class RequestProposalsResponse1(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    outcome: Literal['proposed'] = 'proposed'
    reason: Annotated[str | None, Field(min_length=1)] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    proposals: Annotated[list[Proposal], Field(min_length=1)]
    products: Annotated[list[canonical_product.CanonicalProduct], Field(min_length=1)]
    incomplete: Annotated[
        list[IncompleteItem] | None,
        Field(
            description='Usable partial discovery result retained from the established get_products response. Absence means the source response did not declare an incomplete scope; it does not authorize an adapter to infer missing proposal terms.',
            min_length=1,
        ),
    ] = None
    purchase_continuation: Annotated[
        PurchaseContinuation | PurchaseContinuation1 | None,
        Field(
            deprecated=True,
            description='Deprecated AdCP 3.x projection instruction for purchasing products returned without a proposal. This is coordinator state, not a claim that the established seller implements a compact task. A native 3.2 seller MUST NOT emit it.',
        ),
    ] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description='Response-level confirmation of structured targeting interpreted from explicit hard requirements in the brief. Sellers MUST emit this when that interpretation materially affects eligibility, pricing, or forecasting; otherwise it remains a best practice. Product-specific changes to explicit criteria.targeting_overlay values remain on Product.targeting_resolution.'
        ),
    ] = None
    status: Literal['completed'] = 'completed'
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_version : str | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var incomplete : list[IncompleteItem] | None
var message : str | None
var model_config
var outcome : Literal['proposed']
var products : list[CanonicalProduct]
var proposals : list[Proposal]
var purchase_continuation : PurchaseContinuation | PurchaseContinuation1 | None
var reason : str | None
var replayed : Literal[True] | None
var status : Literal['completed']
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var task_id : str | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RequestProposalsResponse2 (**data: Any)

Expand source code

class RequestProposalsResponse2(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    outcome: Literal['products_available'] = 'products_available'
    reason: Annotated[str | None, Field(min_length=1)] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    proposals: Annotated[list[Proposal] | None, Field(min_length=1)] = None
    products: Annotated[list[canonical_product.CanonicalProduct], Field(min_length=1)]
    incomplete: Annotated[
        list[IncompleteItem5] | None,
        Field(
            description='Usable partial discovery result retained from the established get_products response. Absence means the source response did not declare an incomplete scope; it does not authorize an adapter to infer missing proposal terms.',
            min_length=1,
        ),
    ] = None
    purchase_continuation: Annotated[
        PurchaseContinuation2 | PurchaseContinuation3,
        Field(
            deprecated=True,
            description='Deprecated AdCP 3.x projection instruction for purchasing products returned without a proposal. This is coordinator state, not a claim that the established seller implements a compact task. A native 3.2 seller MUST NOT emit it.',
        ),
    ]
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description='Response-level confirmation of structured targeting interpreted from explicit hard requirements in the brief. Sellers MUST emit this when that interpretation materially affects eligibility, pricing, or forecasting; otherwise it remains a best practice. Product-specific changes to explicit criteria.targeting_overlay values remain on Product.targeting_resolution.'
        ),
    ] = None
    status: Literal['completed'] = 'completed'
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_version : str | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var incomplete : list[IncompleteItem5] | None
var message : str | None
var model_config
var outcome : Literal['products_available']
var products : list[CanonicalProduct]
var proposals : list[Proposal] | None
var purchase_continuation : PurchaseContinuation2 | PurchaseContinuation3
var reason : str | None
var replayed : Literal[True] | None
var status : Literal['completed']
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var task_id : str | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RequestProposalsResponse3 (**data: Any)

Expand source code

class RequestProposalsResponse3(AdcpResponse, AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    outcome: Literal['rejected'] = 'rejected'
    reason: Annotated[str, Field(min_length=1)]
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    proposals: Annotated[list[Proposal] | None, Field(min_length=1)] = None
    products: Annotated[list[canonical_product.CanonicalProduct] | None, Field(min_length=1)] = None
    incomplete: Annotated[
        list[IncompleteItem6] | None,
        Field(
            description='Usable partial discovery result retained from the established get_products response. Absence means the source response did not declare an incomplete scope; it does not authorize an adapter to infer missing proposal terms.',
            min_length=1,
        ),
    ] = None
    purchase_continuation: Annotated[
        PurchaseContinuation4 | PurchaseContinuation5 | None,
        Field(
            deprecated=True,
            description='Deprecated AdCP 3.x projection instruction for purchasing products returned without a proposal. This is coordinator state, not a claim that the established seller implements a compact task. A native 3.2 seller MUST NOT emit it.',
        ),
    ] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description='Response-level confirmation of structured targeting interpreted from explicit hard requirements in the brief. Sellers MUST emit this when that interpretation materially affects eligibility, pricing, or forecasting; otherwise it remains a best practice. Product-specific changes to explicit criteria.targeting_overlay values remain on Product.targeting_resolution.'
        ),
    ] = None
    status: Literal['completed'] = 'completed'
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_version : str | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var incomplete : list[IncompleteItem6] | None
var message : str | None
var model_config
var outcome : Literal['rejected']
var products : list[CanonicalProduct] | None
var proposals : list[Proposal] | None
var purchase_continuation : PurchaseContinuation4 | PurchaseContinuation5 | None
var reason : str
var replayed : Literal[True] | None
var status : Literal['completed']
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var task_id : str | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RequestProposalsResponse4 (**data: Any)

Expand source code

class RequestProposalsResponse4(AdcpResponse, CompactTaskSubmitted):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    outcome: Outcome | None = None
    reason: Annotated[str | None, Field(min_length=1)] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    proposals: Annotated[list[Proposal] | None, Field(min_length=1)] = None
    products: Annotated[list[canonical_product.CanonicalProduct] | None, Field(min_length=1)] = None
    incomplete: Annotated[
        list[IncompleteItem7] | None,
        Field(
            description='Usable partial discovery result retained from the established get_products response. Absence means the source response did not declare an incomplete scope; it does not authorize an adapter to infer missing proposal terms.',
            min_length=1,
        ),
    ] = None
    purchase_continuation: Annotated[
        PurchaseContinuation6 | PurchaseContinuation7 | None,
        Field(
            deprecated=True,
            description='Deprecated AdCP 3.x projection instruction for purchasing products returned without a proposal. This is coordinator state, not a claim that the established seller implements a compact task. A native 3.2 seller MUST NOT emit it.',
        ),
    ] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description='Response-level confirmation of structured targeting interpreted from explicit hard requirements in the brief. Sellers MUST emit this when that interpretation materially affects eligibility, pricing, or forecasting; otherwise it remains a best practice. Product-specific changes to explicit criteria.targeting_overlay values remain on Product.targeting_resolution.'
        ),
    ] = None
    status: Status | None = None
    task_id: Annotated[str | None, Field(min_length=1)] = None
    message: Annotated[str | None, Field(max_length=2000)] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    replayed: Literal[True] | None = None

The response message of a task in the pinned bundle's task registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpResponse
adcp.types.base._AdcpMessage
CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_version : str | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var incomplete : list[IncompleteItem7] | None
var message : str | None
var model_config
var outcome : Outcome | None
var products : list[CanonicalProduct] | None
var proposals : list[Proposal] | None
var purchase_continuation : PurchaseContinuation6 | PurchaseContinuation7 | None
var reason : str | None
var replayed : Literal[True] | None
var status : Status | None
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var task_id : str | None

Inherited members

AdcpResponse:
- get_adcp_error
- get_context
- get_message
- get_replayed
- get_status
- get_task_id
CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class RequestProposalsSubmitted (**data: Any)

Expand source code

class RequestProposalsSubmitted(CompactTaskSubmitted):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

CompactTaskSubmitted
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskSubmitted:
- model_dump
- model_dump_json
- model_summary

class RequestProposalsWorking (**data: Any)

Expand source code

class RequestProposalsWorking(CompactTaskWorking):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

CompactTaskWorking
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

CompactTaskWorking:
- model_dump
- model_dump_json
- model_summary

class Results1 (**data: Any)

Expand source code

class Results1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['declined'] = 'declined'
    reason: Annotated[
        str | None,
        Field(
            description='Why the seller could not apply a decline. Present only for outcome unable.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Results4

Class variables

var model_config
var outcome : Literal['declined']
var proposal_id : str
var reason : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results10 (**data: Any)

Expand source code

class Results10(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['partial'] = 'partial'
    proposal: canonical_proposal.CanonicalProposal | None = None
    proposals: Annotated[
        list[Proposal2],
        Field(
            description='Draft successors produced for a revision. Without alternatives this contains one proposal. With alternatives.count, revised contains exactly that many proposals with unique terms_digest values; fewer or commercially duplicate proposals require partial.',
            min_length=1,
        ),
    ]
    reason_code: Annotated[
        proposal_refinement_reason.ProposalRefinementReason,
        Field(
            description='Single most-significant code for this result. constraint_unsatisfiable takes precedence over every other code; an alternatives shortfall alongside an unsatisfied constraint remains visible through proposals.length.'
        ),
    ]
    reason: Annotated[str, Field(min_length=1)]
    unsatisfied_constraints: Annotated[
        list[UnsatisfiedConstraint] | None,
        Field(
            description='Stable keys from the request constraints object that were not satisfied by every returned draft. A result carrying any key here MUST use outcome partial or unable, never revised.',
            min_length=1,
        ),
    ] = None
    unsatisfied_product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Requested product actions not satisfied by every returned draft. This is a subset of the request product_changes map and is valid only on partial or unable results.'
        ),
    ] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description="Confirmation of structured targeting interpreted from this refinement's explicit hard prose instructions. Required when that interpretation materially affects the revised proposal's eligibility, pricing, or forecast; otherwise a best practice."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['partial']
var proposal : CanonicalProposal | None
var proposals : list[Proposal2]
var reason : str
var reason_code : ProposalRefinementReason
var source_proposal_id : str
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var unsatisfied_constraints : list[UnsatisfiedConstraint] | None
var unsatisfied_product_changes : ProductChangeMap | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results11 (**data: Any)

Expand source code

class Results11(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['finalized'] = 'finalized'
    proposal: Annotated[
        Proposal3,
        Field(
            description='Compact immutable proposal for the AdCP 3.2 lifecycle. commercial_terms is the sole authoritative commercial envelope; narrative fields do not duplicate legacy allocation or creative graphs.',
            title='Canonical Proposal',
        ),
    ]
    proposals: Annotated[
        list[canonical_proposal.CanonicalProposal] | None,
        Field(
            description='Draft successors produced for a revision. Without alternatives this contains one proposal. With alternatives.count, revised contains exactly that many proposals with unique terms_digest values; fewer or commercially duplicate proposals require partial.',
            min_length=1,
        ),
    ] = None
    reason_code: Annotated[
        proposal_refinement_reason.ProposalRefinementReason | None,
        Field(
            description='Single most-significant code for this result. constraint_unsatisfiable takes precedence over every other code; an alternatives shortfall alongside an unsatisfied constraint remains visible through proposals.length.'
        ),
    ] = None
    reason: Annotated[str | None, Field(min_length=1)] = None
    unsatisfied_constraints: Annotated[
        list[UnsatisfiedConstraint] | None,
        Field(
            description='Stable keys from the request constraints object that were not satisfied by every returned draft. A result carrying any key here MUST use outcome partial or unable, never revised.',
            min_length=1,
        ),
    ] = None
    unsatisfied_product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Requested product actions not satisfied by every returned draft. This is a subset of the request product_changes map and is valid only on partial or unable results.'
        ),
    ] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description="Confirmation of structured targeting interpreted from this refinement's explicit hard prose instructions. Required when that interpretation materially affects the revised proposal's eligibility, pricing, or forecast; otherwise a best practice."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['finalized']
var proposal : Proposal3
var proposals : list[CanonicalProposal] | None
var reason : str | None
var reason_code : ProposalRefinementReason | None
var source_proposal_id : str
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var unsatisfied_constraints : list[UnsatisfiedConstraint] | None
var unsatisfied_product_changes : ProductChangeMap | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results12 (**data: Any)

Expand source code

class Results12(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['unable'] = 'unable'
    proposal: canonical_proposal.CanonicalProposal | None = None
    proposals: Annotated[
        list[canonical_proposal.CanonicalProposal] | None,
        Field(
            description='Draft successors produced for a revision. Without alternatives this contains one proposal. With alternatives.count, revised contains exactly that many proposals with unique terms_digest values; fewer or commercially duplicate proposals require partial.',
            min_length=1,
        ),
    ] = None
    reason_code: Annotated[
        proposal_refinement_reason.ProposalRefinementReason,
        Field(
            description='Single most-significant code for this result. constraint_unsatisfiable takes precedence over every other code; an alternatives shortfall alongside an unsatisfied constraint remains visible through proposals.length.'
        ),
    ]
    reason: Annotated[str, Field(min_length=1)]
    unsatisfied_constraints: Annotated[
        list[UnsatisfiedConstraint] | None,
        Field(
            description='Stable keys from the request constraints object that were not satisfied by every returned draft. A result carrying any key here MUST use outcome partial or unable, never revised.',
            min_length=1,
        ),
    ] = None
    unsatisfied_product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Requested product actions not satisfied by every returned draft. This is a subset of the request product_changes map and is valid only on partial or unable results.'
        ),
    ] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description="Confirmation of structured targeting interpreted from this refinement's explicit hard prose instructions. Required when that interpretation materially affects the revised proposal's eligibility, pricing, or forecast; otherwise a best practice."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Results18

Class variables

var model_config
var outcome : Literal['unable']
var proposal : CanonicalProposal | None
var proposals : list[CanonicalProposal] | None
var reason : str
var reason_code : ProposalRefinementReason
var source_proposal_id : str
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var unsatisfied_constraints : list[UnsatisfiedConstraint] | None
var unsatisfied_product_changes : ProductChangeMap | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results15 (**data: Any)

Expand source code

class Results15(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['revised'] = 'revised'
    proposal: canonical_proposal.CanonicalProposal | None = None
    proposals: Annotated[
        list[Proposal4],
        Field(
            description='Draft successors produced for a revision. Without alternatives this contains one proposal. With alternatives.count, revised contains exactly that many proposals with unique terms_digest values; fewer or commercially duplicate proposals require partial.',
            min_length=1,
        ),
    ]
    reason_code: Annotated[
        proposal_refinement_reason.ProposalRefinementReason | None,
        Field(
            description='Single most-significant code for this result. constraint_unsatisfiable takes precedence over every other code; an alternatives shortfall alongside an unsatisfied constraint remains visible through proposals.length.'
        ),
    ] = None
    reason: Annotated[str | None, Field(min_length=1)] = None
    unsatisfied_constraints: Annotated[
        list[UnsatisfiedConstraint] | None,
        Field(
            description='Stable keys from the request constraints object that were not satisfied by every returned draft. A result carrying any key here MUST use outcome partial or unable, never revised.',
            min_length=1,
        ),
    ] = None
    unsatisfied_product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Requested product actions not satisfied by every returned draft. This is a subset of the request product_changes map and is valid only on partial or unable results.'
        ),
    ] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description="Confirmation of structured targeting interpreted from this refinement's explicit hard prose instructions. Required when that interpretation materially affects the revised proposal's eligibility, pricing, or forecast; otherwise a best practice."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['revised']
var proposal : CanonicalProposal | None
var proposals : list[Proposal4]
var reason : str | None
var reason_code : ProposalRefinementReason | None
var source_proposal_id : str
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var unsatisfied_constraints : list[UnsatisfiedConstraint] | None
var unsatisfied_product_changes : ProductChangeMap | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results16 (**data: Any)

Expand source code

class Results16(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['partial'] = 'partial'
    proposal: canonical_proposal.CanonicalProposal | None = None
    proposals: Annotated[
        list[Proposal5],
        Field(
            description='Draft successors produced for a revision. Without alternatives this contains one proposal. With alternatives.count, revised contains exactly that many proposals with unique terms_digest values; fewer or commercially duplicate proposals require partial.',
            min_length=1,
        ),
    ]
    reason_code: Annotated[
        proposal_refinement_reason.ProposalRefinementReason,
        Field(
            description='Single most-significant code for this result. constraint_unsatisfiable takes precedence over every other code; an alternatives shortfall alongside an unsatisfied constraint remains visible through proposals.length.'
        ),
    ]
    reason: Annotated[str, Field(min_length=1)]
    unsatisfied_constraints: Annotated[
        list[UnsatisfiedConstraint] | None,
        Field(
            description='Stable keys from the request constraints object that were not satisfied by every returned draft. A result carrying any key here MUST use outcome partial or unable, never revised.',
            min_length=1,
        ),
    ] = None
    unsatisfied_product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Requested product actions not satisfied by every returned draft. This is a subset of the request product_changes map and is valid only on partial or unable results.'
        ),
    ] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description="Confirmation of structured targeting interpreted from this refinement's explicit hard prose instructions. Required when that interpretation materially affects the revised proposal's eligibility, pricing, or forecast; otherwise a best practice."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['partial']
var proposal : CanonicalProposal | None
var proposals : list[Proposal5]
var reason : str
var reason_code : ProposalRefinementReason
var source_proposal_id : str
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var unsatisfied_constraints : list[UnsatisfiedConstraint] | None
var unsatisfied_product_changes : ProductChangeMap | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results17 (**data: Any)

Expand source code

class Results17(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['finalized'] = 'finalized'
    proposal: Annotated[
        Proposal6,
        Field(
            description='Compact immutable proposal for the AdCP 3.2 lifecycle. commercial_terms is the sole authoritative commercial envelope; narrative fields do not duplicate legacy allocation or creative graphs.',
            title='Canonical Proposal',
        ),
    ]
    proposals: Annotated[
        list[canonical_proposal.CanonicalProposal] | None,
        Field(
            description='Draft successors produced for a revision. Without alternatives this contains one proposal. With alternatives.count, revised contains exactly that many proposals with unique terms_digest values; fewer or commercially duplicate proposals require partial.',
            min_length=1,
        ),
    ] = None
    reason_code: Annotated[
        proposal_refinement_reason.ProposalRefinementReason | None,
        Field(
            description='Single most-significant code for this result. constraint_unsatisfiable takes precedence over every other code; an alternatives shortfall alongside an unsatisfied constraint remains visible through proposals.length.'
        ),
    ] = None
    reason: Annotated[str | None, Field(min_length=1)] = None
    unsatisfied_constraints: Annotated[
        list[UnsatisfiedConstraint] | None,
        Field(
            description='Stable keys from the request constraints object that were not satisfied by every returned draft. A result carrying any key here MUST use outcome partial or unable, never revised.',
            min_length=1,
        ),
    ] = None
    unsatisfied_product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Requested product actions not satisfied by every returned draft. This is a subset of the request product_changes map and is valid only on partial or unable results.'
        ),
    ] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description="Confirmation of structured targeting interpreted from this refinement's explicit hard prose instructions. Required when that interpretation materially affects the revised proposal's eligibility, pricing, or forecast; otherwise a best practice."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['finalized']
var proposal : Proposal6
var proposals : list[CanonicalProposal] | None
var reason : str | None
var reason_code : ProposalRefinementReason | None
var source_proposal_id : str
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var unsatisfied_constraints : list[UnsatisfiedConstraint] | None
var unsatisfied_product_changes : ProductChangeMap | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results18 (**data: Any)

Expand source code

class Results18(Results12):
    outcome: Literal['unable'] = 'unable'

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Results12
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['unable']

Inherited members

Results12:
- model_dump
- model_dump_json
- model_summary

class Results2 (**data: Any)

Expand source code

class Results2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['unable'] = 'unable'
    reason: Annotated[
        str,
        Field(
            description='Why the seller could not apply a decline. Present only for outcome unable.',
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Results5

Class variables

var model_config
var outcome : Literal['unable']
var proposal_id : str
var reason : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results20 (**data: Any)

Expand source code

class Results20(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    result: Literal['recorded'] = 'recorded'
    receipt: reporting_receipt.ReportingReceipt

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var receipt : ReportingReceipt
var result : Literal['recorded']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results21 (**data: Any)

Expand source code

class Results21(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    result: Literal['unchanged'] = 'unchanged'
    receipt: reporting_receipt.ReportingReceipt

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var receipt : ReportingReceipt
var result : Literal['unchanged']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results22 (**data: Any)

Expand source code

class Results22(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    result: Literal['recorded'] = 'recorded'
    adjustment_receipt: reporting_adjustment_receipt.ReportingAdjustmentReceipt

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adjustment_receipt : ReportingAdjustmentReceipt
var model_config
var result : Literal['recorded']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results23 (**data: Any)

Expand source code

class Results23(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    result: Literal['unchanged'] = 'unchanged'
    adjustment_receipt: reporting_adjustment_receipt.ReportingAdjustmentReceipt

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adjustment_receipt : ReportingAdjustmentReceipt
var model_config
var result : Literal['unchanged']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results26 (**data: Any)

Expand source code

class Results26(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    result: Literal['unchanged'] = 'unchanged'
    consumer_status: reporting_consumer_status.ReportingConsumerStatus

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var consumer_status : ReportingConsumerStatus
var model_config
var result : Literal['unchanged']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results27 (**data: Any)

Expand source code

class Results27(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    result: Literal['failed'] = 'failed'
    reporting_status_id: Annotated[
        str, Field(max_length=255, min_length=16, pattern='^[A-Za-z0-9_.:-]{16,255}$')
    ]
    errors: Annotated[list[error.Error], Field(max_length=16, min_length=1)]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var errors : list[Error]
var model_config
var reporting_status_id : str
var result : Literal['failed']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results4 (**data: Any)

Expand source code

class Results4(Results1):
    outcome: Literal['declined'] = 'declined'

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Results1
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['declined']

Inherited members

Results1:
- model_dump
- model_dump_json
- model_summary

class Results5 (**data: Any)

Expand source code

class Results5(Results2):
    outcome: Literal['unable'] = 'unable'

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Results2
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['unable']

Inherited members

Results2:
- model_dump
- model_dump_json
- model_summary

class Results9 (**data: Any)

Expand source code

class Results9(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    source_proposal_id: Annotated[str, Field(min_length=1)]
    outcome: Literal['revised'] = 'revised'
    proposal: canonical_proposal.CanonicalProposal | None = None
    proposals: Annotated[
        list[Proposal],
        Field(
            description='Draft successors produced for a revision. Without alternatives this contains one proposal. With alternatives.count, revised contains exactly that many proposals with unique terms_digest values; fewer or commercially duplicate proposals require partial.',
            min_length=1,
        ),
    ]
    reason_code: Annotated[
        proposal_refinement_reason.ProposalRefinementReason | None,
        Field(
            description='Single most-significant code for this result. constraint_unsatisfiable takes precedence over every other code; an alternatives shortfall alongside an unsatisfied constraint remains visible through proposals.length.'
        ),
    ] = None
    reason: Annotated[str | None, Field(min_length=1)] = None
    unsatisfied_constraints: Annotated[
        list[UnsatisfiedConstraint] | None,
        Field(
            description='Stable keys from the request constraints object that were not satisfied by every returned draft. A result carrying any key here MUST use outcome partial or unable, never revised.',
            min_length=1,
        ),
    ] = None
    unsatisfied_product_changes: Annotated[
        product_change_map.ProductChangeMap | None,
        Field(
            description='Requested product actions not satisfied by every returned draft. This is a subset of the request product_changes map and is valid only on partial or unable results.'
        ),
    ] = None
    suggestions: Annotated[list[Suggestion] | None, Field(min_length=1)] = None
    targeting_resolution: Annotated[
        get_products_targeting_resolution.ProductDiscoveryTargetingResolution | None,
        Field(
            description="Confirmation of structured targeting interpreted from this refinement's explicit hard prose instructions. Required when that interpretation materially affects the revised proposal's eligibility, pricing, or forecast; otherwise a best practice."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var outcome : Literal['revised']
var proposal : CanonicalProposal | None
var proposals : list[Proposal]
var reason : str | None
var reason_code : ProposalRefinementReason | None
var source_proposal_id : str
var suggestions : list[Suggestion] | None
var targeting_resolution : ProductDiscoveryTargetingResolution | None
var unsatisfied_constraints : list[UnsatisfiedConstraint] | None
var unsatisfied_product_changes : ProductChangeMap | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SelectedProductId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class SelectedProductId(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 Semantics (*args, **kwds)

Expand source code

class Semantics(StrEnum):
    only = 'only'
    any = 'any'
    approximate = 'approximate'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var any
var approximate
var only

class Setup (**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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 SignalCondition1 (**data: Any)

Expand source code

class SignalCondition1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(description='The signal to target. New targeting constraints 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
    value_type: Annotated[Literal['binary'], Field(description='Discriminator for binary signals')] = 'binary'
    value: Annotated[
        StrictBool,
        Field(
            description='Whether to include (true) or exclude (false) users matching this signal'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

SignalCondition5

Class variables

var model_config
var signal_id : SignalId8 | SignalId9 | None
var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None
var value : bool
var value_type : Literal['binary']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalCondition2 (**data: Any)

Expand source code

class SignalCondition2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(description='The signal to target. New targeting constraints 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
    value_type: Annotated[
        Literal['categorical'], Field(description='Discriminator for categorical signals')
    ] = 'categorical'
    values: Annotated[
        list[str],
        Field(
            description='Values to target. Users with any of these values will be included.',
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

SignalCondition6

Class variables

var model_config
var signal_id : SignalId8 | SignalId9 | None
var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None
var value_type : Literal['categorical']
var values : list[str]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalCondition3 (**data: Any)

Expand source code

class SignalCondition3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_ref: Annotated[
        signal_ref_1.SignalRef | None,
        Field(description='The signal to target. New targeting constraints 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
    value_type: Annotated[
        Literal['numeric'], Field(description='Discriminator for numeric signals')
    ] = 'numeric'
    min_value: Annotated[
        StrictFloat | None,
        Field(
            description="Minimum value (inclusive). Omit for no minimum. Must be <= max_value when both are provided. Should be >= signal's range.min if defined."
        ),
    ] = None
    max_value: Annotated[
        StrictFloat | None,
        Field(
            description="Maximum value (inclusive). Omit for no maximum. Must be >= min_value when both are provided. Should be <= signal's range.max if defined."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

SignalCondition7

Class variables

var max_value : float | None
var min_value : float | None
var model_config
var signal_id : SignalId8 | SignalId9 | None
var signal_ref : SignalRef1 | SignalRef2 | SignalRef3 | None
var value_type : Literal['numeric']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalCondition4 (**data: Any)

Expand source code

class SignalCondition4(AdCPBaseModel):
    signal_agent_segment_id: Annotated[
        str | None,
        Field(
            description="Optional opaque resolved-segment handle for this fan-out condition — the RESOLVED condition identity, distinct from signal_ref's DEFINITION identity. When get_signals or a product signal_targeting_options entry exposed a signal_agent_segment_id for the targeted signal, echo it here verbatim so the produced creative's signal_condition carries the resolved-segment identity that the trafficking-compatibility check (SIGNAL_TARGETING_INCOMPATIBLE) matches on exactly. Providers MAY namespace it (e.g. provider_a:weather:rain_realtime vs provider_b:precip:high) so cross-provider conditions stay distinct without a shared taxonomy registry; treat as opaque, do not parse the namespace for business logic. Prefer it over reconstructing condition identity from categorical values — categorical {signal_ref,value} identity is the weaker fallback, appropriate only for inherently-categorical signals with no resolved handle, and never a cross-provider equivalence claim."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

Class variables

var model_config
var signal_agent_segment_id : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalCondition5 (**data: Any)

Expand source code

class SignalCondition5(SignalCondition1, SignalCondition4):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var model_config

Inherited members

SignalCondition1:
- model_dump
- model_dump_json
- model_summary

class SignalCondition6 (**data: Any)

Expand source code

class SignalCondition6(SignalCondition2, SignalCondition4):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var model_config

Inherited members

SignalCondition2:
- model_dump
- model_dump_json
- model_summary

class SignalCondition7 (**data: Any)

Expand source code

class SignalCondition7(SignalCondition3, SignalCondition4):
    pass

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

Class variables

var model_config

Inherited members

SignalCondition3:
- 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='ISO 8601 timestamp when this snapshot was captured by the platform'),
    ]
    staleness_seconds: Annotated[
        SchemaInt,
        Field(
            description='Maximum age of this data in seconds. For example, 900 means the data may be up to 15 minutes old. Use this to interpret zero delivery: a value of 900 means zero impressions is likely real; a value of 14400 means reporting may still be catching up.',
            ge=0,
        ),
    ]
    impressions: Annotated[
        StrictFloat, Field(description='Total impressions delivered since package start', ge=0.0)
    ]
    spend: Annotated[
        StrictFloat,
        Field(
            description='Total spend since package start, denominated in snapshot.currency when present, otherwise package.currency or media_buy.currency',
            ge=0.0,
        ),
    ]
    currency: Annotated[
        str | None,
        Field(
            description='ISO 4217 currency code for spend in this snapshot. Optional when unchanged from package.currency or media_buy.currency.',
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    clicks: Annotated[
        StrictFloat | None,
        Field(description='Total clicks since package start (when available)', ge=0.0),
    ] = None
    pacing_index: Annotated[
        StrictFloat | None,
        Field(
            description='Current delivery pace relative to expected (1.0 = on track, <1.0 = behind, >1.0 = ahead). Absent when pacing cannot be determined.',
            ge=0.0,
        ),
    ] = None
    delivery_status: Annotated[
        delivery_status_1.DeliveryStatus | None,
        Field(
            description="Operational delivery state of this package. 'not_delivering' means the package is within its scheduled flight but has delivered zero impressions for at least one full staleness cycle — the signal for automated price adjustments or buyer alerts. Implementers must not return 'not_delivering' until at least staleness_seconds have elapsed since package activation."
        ),
    ] = None
    ext: Annotated[
        ext_1.ExtensionObject | None,
        Field(description='Optional extension object for seller-specific snapshot fields.'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var as_of : pydantic.types.AwareDatetime
var clicks : float | None
var currency : str | None
var delivery_status : DeliveryStatus | None
var ext : ExtensionObject | None
var impressions : float
var model_config
var pacing_index : float | None
var spend : float
var staleness_seconds : int

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SourceAdcpVersion (*args, **kwds)

Expand source code

class SourceAdcpVersion(StrEnum):
    field_2_5 = '2.5'
    field_3_0 = '3.0'
    field_3_1 = '3.1'

Enum where members are also (and must be) strings

Ancestors

enum.StrEnum
builtins.str
enum.ReprEnum
enum.Enum

Class variables

var field_2_5
var field_3_0
var field_3_1

class Spot (**data: Any)

Expand source code

class Spot(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    limit: Annotated[
        SchemaInt | None,
        Field(
            description='Optional maximum number of spot rows to return. When the response is incomplete because of this limit or a seller-imposed maximum, by_spot_truncated is true.',
            ge=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var limit : int | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Subject (**data: Any)

Expand source code

class Subject(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    subject_category: Annotated[str, Field(pattern='^[a-z][a-z0-9_]*$')]
    subject_facets: Annotated[list[SubjectFacet] | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var subject_category : str
var subject_facets : list[SubjectFacet] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SubjectCategory (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class SubjectCategory(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

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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 SyncAudiencesResponse2 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 SyncAudiencesResponse3 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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[]
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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 SyncCatalogsResponse2 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 SyncCatalogsResponse3 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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[]
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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 SyncEventSourcesResponse2 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 Tag (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class Tag(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 TargetCapabilityId (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class TargetCapabilityId(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[a-zA-Z0-9_-]+$'}

A str generated from a JSON Schema string root.

Ancestors

adcp.types._scalar.ScalarStr
adcp.types._scalar._ScalarRoot
builtins.str

class TotalBudgetGuidance (**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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 UnsatisfiedConstraint (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class UnsatisfiedConstraint(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

Suggestion

class UpdateMediaBuyInputRequired (**data: Any)

Expand source code

class UpdateMediaBuyInputRequired(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    reason: Annotated[
        Reason | None, Field(description='Reason code indicating why input is needed')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 UpdateMediaBuyRequest (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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 UpdateMediaBuyResponse1 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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.

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 UpdateMediaBuyResponse2 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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 UpdateMediaBuyResponse3 (**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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if 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[]
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 UpdateMediaBuySubmitted (**data: Any)

Expand source code

class UpdateMediaBuySubmitted(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 media_buy_id 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., 'Awaiting operator re-approval; typical turnaround 2–4 hours.' 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.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : 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 UpdateMediaBuyWorking (**data: Any)

Expand source code

class UpdateMediaBuyWorking(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')
    ] = 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
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var 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 ValueCurrency (value: Any = <object object>, *, root: Any = <object object>)

Expand source code

class ValueCurrency(ScalarStr):
    __slots__ = ()
    _constraints = {'pattern': '^[A-Z]{3}$'}

A str generated from a JSON Schema string root.

Ancestors

adcp.types._scalar.ScalarStr
adcp.types._scalar._ScalarRoot
builtins.str

class Variant (**data: Any)

Expand source code

class Variant(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    build_variant_id: str
    recipe_hash: str | None = None
    parent_build_variant_id: str | None = None
    creative_manifest: creative_manifest_1.CreativeManifest
    variant_axis_value: Any | None = None
    recommended: bool | None = None
    rank: Annotated[int, Field(ge=1)] | None = None
    eval: Eval | 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

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdcpVersionEnvelope
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var build_variant_id : str
var consumption : CreativeConsumption | None
var creative_manifest : CreativeManifest
var currency : str | None
var eval : Eval | None
var model_config
var parent_build_variant_id : str | None
var pricing_option_id : str | None
var rank : int | None
var recipe_hash : str | None
var recommended : bool | None
var variant_axis_value : typing.Any | None
var vendor_cost : float | None

Inherited members

AdcpVersionEnvelope:
- model_dump
- model_dump_json
- model_summary

class VariantAxis (**data: Any)

Expand source code

class VariantAxis(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    dimension: Annotated[
        Dimension,
        Field(
            description='What varies across variants. `transformer_config` varies a named config param (name it in `field`); `best_of_n` lets the agent explore and rank; `custom` is agent-defined (describe in `label`).'
        ),
    ]
    field: Annotated[
        str | None,
        Field(
            description='The transformer `config` param `field` this axis sweeps. REQUIRED when `dimension` is `transformer_config`; `values[]` are then interpreted as values for `config[field]`. Omit for other dimensions.'
        ),
    ] = None
    values: Annotated[
        list[Any] | None,
        Field(
            description='Caller-fixed set of values for the axis (e.g. ["isaac", "sara"] for dimension `voice`). When present, len(values) is the variant count and is authoritative over max_variants.',
            min_length=1,
        ),
    ] = None
    label: Annotated[
        str | None,
        Field(description='Human-readable description of the axis, especially for `custom`.'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var dimension : Dimension
var field : str | None
var label : str | None
var model_config
var values : list[typing.Any] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Window (**data: Any)

Expand source code

class Window(AdCPBaseModel):
    window_start: Annotated[
        AwareDatetime,
        Field(
            description='ISO 8601 start of the window slice (inclusive). Daily, weekly, monthly, and quarterly slices start on reporting-timezone calendar boundaries (see reporting_period.timezone), which are UTC midnights only when that timezone is UTC. Weekly slices start Monday 00:00 in the reporting timezone (ISO 8601 weeks). Quarterly slices start on 1 January, 1 April, 1 July and 1 October.'
        ),
    ]
    window_end: Annotated[
        AwareDatetime,
        Field(
            description="ISO 8601 end of the window slice (exclusive). The next row's window_start equals this value when slices are contiguous."
        ),
    ]
    totals: Annotated[
        delivery_metrics.DeliveryMetrics,
        Field(
            description='Aggregate metrics for this window slice across all packages. Shape-aligned with reporting_webhook fire payloads at the same granularity.'
        ),
    ]
    by_package: Annotated[
        list[ByPackageItem1] | None,
        Field(
            description='Per-package metrics for this window slice, using the same metric envelope and package identity as the parent media_buy_deliveries[].by_package row but scoped to the window. Requested reporting_dimensions do not apply to these webhook-aligned recovery rows; sellers may include dimensional fields only as webhook payload extensions, not as a guaranteed result of the GET request. Sellers MAY omit by_package when per-package window-level data is unavailable; when present, package_id values MUST match the parent by_package entries.'
        ),
    ] = None
    is_final: Annotated[
        StrictBool | None,
        Field(
            description='Whether the slice data is final for this window. Same semantics as the per-package is_final flag — when false, a later read may return revised numbers for the same window as measurement matures (broadcast C3 → C7, post-IVT filtering, etc.).'
        ),
    ] = None
    measurement_window: Annotated[
        str | None,
        Field(
            description="Which measurement-window stage this slice represents (e.g., 'live', 'c3', 'c7'), referencing a window_id from the product's reporting_capabilities.measurement_windows. Absent when the data is not phased.",
            max_length=50,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Important

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var by_package : list[ByPackageItem1] | None
var is_final : bool | None
var measurement_window : str | None
var model_config
var totals : DeliveryMetrics
var window_end : pydantic.types.AwareDatetime
var window_start : pydantic.types.AwareDatetime

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary