Module `adcp.types`

AdCP Type System.

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

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

IMPORTANT: Never import directly from adcp.types.generated_poc or adcp.types._generated. These are internal modules regenerated from upstream schemas. Only import from adcp.types (this module) or adcp.

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

- Enum fields accept string values:
    ListCreativeFormatsRequest(type="video")  # Works!

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

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

See adcp.types._ergonomic for implementation details.

Sub-modules

adcp.types.aliases: Semantic type aliases for generated AdCP types …
adcp.types.base
adcp.types.coercion: Type coercion utilities for improved type ergonomics …
adcp.types.core: Core type definitions.
adcp.types.generated_poc
adcp.types.guards: Type guards for ADCP discriminated union responses …
adcp.types.registry: Registry API types generated from OpenAPI spec …

Classes

class A2UiComponent (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var component : dict[str, dict[str, typing.Any]]
var id : str
var model_config
var parentId : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class A2UiSurface (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalogId : str | None
var components : list[A2UiComponent]
var dataModel : dict[str, typing.Any] | None
var model_config
var rootId : str | None
var surfaceId : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Account (**data: Any)

Expand source code

class Account(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    account_id: Annotated[str, Field(description='Unique identifier for this account')]
    name: Annotated[
        str, Field(description="Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle')")
    ]
    advertiser: Annotated[
        str | None, Field(description='The advertiser whose rates apply to this account')
    ] = None
    billing_proxy: Annotated[
        str | None,
        Field(
            description='Optional intermediary who receives invoices on behalf of the advertiser (e.g., agency)'
        ),
    ] = None
    status: Annotated[
        account_status.AccountStatus,
        Field(
            description='Account lifecycle status. See the Accounts Protocol overview for the operations matrix showing which tasks are permitted in each state.'
        ),
    ]
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(description='Brand reference identifying the advertiser'),
    ] = None
    operator: Annotated[
        str | None,
        Field(
            description="Domain of the entity operating this account. When the brand operates directly, this is the brand's domain.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ] = None
    billing: Annotated[
        Billing | None,
        Field(
            description="Who is invoiced on this account. operator: seller invoices the operator (agency or brand buying direct). agent: agent consolidates billing. advertiser: seller invoices the advertiser directly, even when a different operator places orders on their behalf. See billing_entity for the invoiced party's business details."
        ),
    ] = None
    billing_entity: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description='Business entity details for the party responsible for payment. Contains the legal name, tax IDs, address, and bank details needed for formal B2B invoicing. Corresponds to whoever billing points to (operator, agent, or advertiser). When this account appears in a response, bank details MUST be omitted (write-only).'
        ),
    ] = None
    rate_card: Annotated[
        str | None, Field(description='Identifier for the rate card applied to this account')
    ] = None
    payment_terms: Annotated[
        PaymentTerms | None,
        Field(
            description='Payment terms agreed for this account. Binding for all invoices when the account is active.'
        ),
    ] = None
    credit_limit: Annotated[
        CreditLimit | None, Field(description='Maximum outstanding balance allowed')
    ] = None
    setup: Annotated[
        Setup | None,
        Field(
            description="Present when status is 'pending_approval'. Contains next steps for completing account activation."
        ),
    ] = None
    account_scope: Annotated[
        AccountScope | None,
        Field(
            description="How the seller scoped this account. operator: shared across all brands for this operator. brand: shared across all operators for this brand. operator_brand: dedicated to a specific operator+brand combination. agent: the agent's default account with no brand or operator association."
        ),
    ] = None
    governance_agents: Annotated[
        list[GovernanceAgent] | None,
        Field(
            description='Governance agent endpoints registered on this account. Authentication credentials are write-only and not included in responses — use sync_governance to set or update credentials.',
            max_length=10,
        ),
    ] = None
    reporting_bucket: Annotated[
        ReportingBucket | None,
        Field(
            description="Cloud storage bucket where the seller delivers offline reporting files for this account. Seller provisions a dedicated bucket or a per-account prefix within a shared bucket, and grants the buyer read access out-of-band. Access MUST be scoped at the IAM layer so each account can only read its own prefix — bucket-wide grants are non-compliant even with per-account prefixes. Seller MUST revoke access when the account's status transitions to inactive, suspended, or closed. See security considerations for offline delivery in docs/media-buy/media-buys/optimization-reporting. Only present when the seller supports offline delivery (reporting_delivery_methods includes 'offline' in capabilities)."
        ),
    ] = None
    sandbox: Annotated[
        bool | None,
        Field(
            description='When true, this is a sandbox account — no real platform calls, no real spend. For explicit accounts (require_operator_auth: true), sandbox accounts are pre-existing test accounts on the platform discovered via list_accounts. For implicit accounts, sandbox is part of the natural key: the same brand/operator pair can have both a production and sandbox account.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account_id : str
var account_scope : AccountScope | None
var advertiser : str | None
var billing : Billing | None
var billing_entity : BusinessEntity | None
var billing_proxy : str | None
var brand : BrandReference | None
var credit_limit : CreditLimit | None
var ext : ExtensionObject | None
var governance_agents : list[GovernanceAgent] | None
var model_config
var name : str
var operator : str | None
var payment_terms : PaymentTerms | None
var rate_card : str | None
var reporting_bucket : ReportingBucket | None
var sandbox : bool | None
var setup : Setup | None
var status : AccountStatus

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Expand source code

class AccountReference(RootModel[AccountReference1 | AccountReference2]):
    root: Annotated[
        AccountReference1 | AccountReference2,
        Field(
            description='Reference to an account by seller-assigned ID or natural key. Use account_id for explicit accounts (require_operator_auth: true, discovered via list_accounts). Use the natural key (brand + operator) for implicit accounts (require_operator_auth: false, declared via sync_accounts). For sandbox: explicit accounts use account_id (pre-existing test account), implicit accounts use the natural key with sandbox: true.',
            examples=[
                {'account_id': 'acc_acme_001'},
                {'brand': {'domain': 'acme-corp.com'}, 'operator': 'acme-corp.com'},
                {
                    'brand': {'domain': 'nova-brands.com', 'brand_id': 'spark'},
                    'operator': 'pinnacle-media.com',
                },
                {
                    'brand': {'domain': 'acme-corp.com'},
                    'operator': 'acme-corp.com',
                    'sandbox': True,
                },
            ],
            title='Account Reference',
        ),
    ]

    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

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

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

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

Ancestors

pydantic.root_model.RootModel[Union[AccountReference1, AccountReference2]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : AccountReference1 | AccountReference2

class AccountReferenceById (**data: Any)

Expand source code

class AccountReference1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    account_id: Annotated[
        str,
        Field(
            description='Seller-assigned account identifier (from sync_accounts or list_accounts)'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account_id : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AccountReferenceByNaturalKey (**data: Any)

Expand source code

class AccountReference2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    brand: Annotated[
        brand_ref.BrandReference, Field(description='Brand reference identifying the advertiser')
    ]
    operator: Annotated[
        str,
        Field(
            description="Domain of the entity operating on the brand's behalf. When the brand operates directly, this is the brand's domain.",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    sandbox: Annotated[
        bool | None,
        Field(
            description='When true, references the sandbox account for this brand/operator pair. Defaults to false (production account).'
        ),
    ] = False

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var brand : BrandReference
var model_config
var operator : str
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AccountScope (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var agent
var brand
var operator
var operator_brand

class AcquireRightsRequest (**data: Any)

Expand source code

class AcquireRightsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    rights_id: Annotated[
        str, Field(description='Rights offering identifier from get_rights response')
    ]
    pricing_option_id: Annotated[
        str, Field(description='Selected pricing option from the rights offering')
    ]
    buyer: Annotated[brand_ref.BrandReference, Field(description="The buyer's brand identity")]
    campaign: Annotated[Campaign, Field(description='Campaign details for rights clearance')]
    revocation_webhook: Annotated[
        push_notification_config_1.PushNotificationConfig,
        Field(
            description='Webhook for rights revocation notifications. If the rights holder needs to revoke rights (talent scandal, contract violation, etc.), they POST a revocation-notification to this URL. The buyer is responsible for stopping creative delivery upon receipt.'
        ),
    ]
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Webhook for async status updates if the acquisition requires approval. The rights agent sends a webhook notification when the status transitions to acquired or rejected.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated key for safe retries. Resubmitting with the same key returns the original response rather than creating a duplicate acquisition. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var buyer : BrandReference
var campaign : Campaign
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var pricing_option_id : str
var push_notification_config : PushNotificationConfig | None
var revocation_webhook : PushNotificationConfig
var rights_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcquireRightsAcquiredResponse (**data: Any)

Expand source code

class AcquireRightsResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    rights_id: Annotated[str, Field(description='Rights grant identifier')]
    status: Annotated[
        Literal['acquired'], Field(description='Rights have been cleared and credentials issued')
    ]
    brand_id: Annotated[str, Field(description='Brand identifier of the rights subject')]
    terms: Annotated[rights_terms.RightsTerms, Field(description='Agreed contractual terms')]
    generation_credentials: Annotated[
        list[generation_credential.GenerationCredential],
        Field(description='Scoped credentials for generating rights-cleared content'),
    ]
    restrictions: Annotated[
        list[str] | None, Field(description='Usage restrictions and requirements')
    ] = None
    disclosure: Annotated[
        Disclosure | None, Field(description='Required disclosure for creatives using these rights')
    ] = None
    approval_webhook: Annotated[
        push_notification_config.PushNotificationConfig | None,
        Field(
            description='Authenticated webhook for submitting creatives for approval. POST a creative-approval-request to the URL using the provided authentication. The response is a creative-approval-response.'
        ),
    ] = None
    usage_reporting_url: Annotated[
        AnyUrl | None, Field(description='Endpoint for reporting usage against these rights')
    ] = None
    rights_constraint: Annotated[
        rights_constraint_1.RightsConstraint,
        Field(
            description='Pre-built rights constraint for embedding in creative manifests. Populated from the agreed terms — the buyer does not need to construct it manually.'
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var approval_webhook : PushNotificationConfig | None
var brand_id : str
var context : ContextObject | None
var disclosure : Disclosure | None
var ext : ExtensionObject | None
var generation_credentials : list[GenerationCredential]
var model_config
var restrictions : list[str] | None
var rights_constraint : RightsConstraint
var rights_id : str
var status : Literal['acquired']
var terms : RightsTerms
var usage_reporting_url : pydantic.networks.AnyUrl | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcquireRightsPendingResponse (**data: Any)

Expand source code

class AcquireRightsResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    rights_id: str
    status: Annotated[
        Literal['pending_approval'],
        Field(description='Rights require approval from the rights holder'),
    ]
    brand_id: str
    detail: Annotated[str | None, Field(description='Explanation of what requires approval')] = None
    estimated_response_time: Annotated[
        str | None,
        Field(description="Expected time for approval decision (e.g., '48h', '3 business days')"),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var brand_id : str
var context : ContextObject | None
var detail : str | None
var estimated_response_time : str | None
var ext : ExtensionObject | None
var model_config
var rights_id : str
var status : Literal['pending_approval']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcquireRightsRejectedResponse (**data: Any)

Expand source code

class AcquireRightsResponse3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    rights_id: str
    status: Annotated[Literal['rejected'], Field(description='Rights request was rejected')]
    brand_id: str
    reason: Annotated[
        str,
        Field(
            description="Why the rights request was rejected. May be sanitized to protect confidential brand rules — e.g., 'This violates our public figures brand guidelines' rather than naming the specific rule."
        ),
    ]
    suggestions: Annotated[
        list[str] | None,
        Field(
            description='Actionable alternatives the buyer can try. If present, the rejection is fixable — the buyer can adjust their request. If absent, the rejection is final for this talent/rights combination.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AcquireRightsErrorResponse (**data: Any)

Expand source code

class AcquireRightsResponse4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[list[error.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ActivateSignalRequest (**data: Any)

Expand source code

class ActivateSignalRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    action: Annotated[
        Action | None,
        Field(
            description="Whether to activate or deactivate the signal. Deactivating removes the segment from downstream platforms, required when campaigns end to comply with data governance policies (GDPR, CCPA). Defaults to 'activate' when omitted."
        ),
    ] = Action.activate
    signal_agent_segment_id: Annotated[
        str, Field(description='The universal identifier for the signal to activate')
    ]
    destinations: Annotated[
        list[destination.Destination],
        Field(
            description='Target destination(s) for activation. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ]
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="The pricing option selected from the signal's pricing_options in the get_signals response. Required when the signal has pricing options. Records the buyer's pricing commitment at activation time; pass this same value in report_usage for billing verification."
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for this activation. Associates with a commercial relationship established via sync_accounts.'
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate activations on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var action : Action | None
var adcp_major_version : int | None
var context : ContextObject | None
var destinations : list[Destination]
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var pricing_option_id : str | None
var signal_agent_segment_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ActivateSignalSuccessResponse (**data: Any)

Expand source code

class ActivateSignalResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    deployments: Annotated[
        list[deployment.Deployment],
        Field(description='Array of deployment results for each deployment target'),
    ]
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 deployments : list[Deployment]
var ext : ExtensionObject | None
var model_config
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ActivateSignalErrorResponse (**data: Any)

Expand source code

class ActivateSignalResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[
        list[error.Error],
        Field(
            description='Array of errors explaining why activation failed (e.g., platform connectivity issues, signal definition problems, authentication failures)',
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SegmentIdActivationKey (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot 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

ActivationKey3

Class variables

var key : str
var model_config
var type : Literal['key_value']
var value : str

class PropertyIdActivationKey (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot 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

ActivationKey3

Class variables

var key : str
var model_config
var type : Literal['key_value']
var value : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class KeyValueActivationKey (**data: Any)

Expand source code

class ActivationKey2(ActivationKey):
    pass

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

ActivationKey
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

class PropertyTagActivationKey (**data: Any)

Expand source code

class ActivationKey2(ActivationKey):
    pass

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

ActivationKey
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config

Inherited members

ActivationKey:
- model_dump
- model_dump_json
- model_summary

class AdvertiserIndustry (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var automotive
var automotive_electric_vehicles
var automotive_luxury
var automotive_parts_accessories
var beauty_cosmetics
var beauty_cosmetics_fragrance
var beauty_cosmetics_haircare
var beauty_cosmetics_skincare
var cannabis
var cpg
var cpg_household
var cpg_personal_care
var dating
var education
var education_higher_education
var education_k12
var education_online_learning
var energy_utilities
var energy_utilities_renewable
var fashion_apparel
var fashion_apparel_luxury
var fashion_apparel_sportswear
var finance
var finance_banking
var finance_cryptocurrency
var finance_insurance
var finance_investment
var food_beverage
var food_beverage_alcohol
var food_beverage_packaged_goods
var food_beverage_restaurants
var gambling_betting
var gambling_betting_casino
var gambling_betting_sports_betting
var gaming
var gaming_console_pc
var gaming_esports
var gaming_mobile
var government_nonprofit
var government_nonprofit_charity
var government_nonprofit_political
var healthcare
var healthcare_medical_devices
var healthcare_pharmaceutical
var healthcare_wellness
var home_garden
var home_garden_furniture
var home_garden_home_improvement
var media_entertainment
var media_entertainment_film_tv
var media_entertainment_live_events
var media_entertainment_music
var media_entertainment_podcasts
var media_entertainment_publishing
var pets
var professional_services
var professional_services_consulting
var professional_services_legal
var real_estate
var real_estate_commercial
var real_estate_residential
var recruitment_hr
var retail
var retail_department_stores
var retail_ecommerce
var sports_fitness
var sports_fitness_equipment
var sports_fitness_teams_leagues
var technology
var technology_ai_ml
var technology_hardware
var technology_software
var telecom
var telecom_internet_providers
var telecom_mobile_carriers
var transportation_logistics
var travel_hospitality
var travel_hospitality_airlines
var travel_hospitality_cruise
var travel_hospitality_hotels
var travel_hospitality_tourism

class AgentConfig (**data: Any)

Expand source code

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

    id: str
    agent_uri: str
    protocol: Protocol
    auth_token: str | None = None
    requires_auth: bool = False
    auth_header: str = "x-adcp-auth"  # Header name for authentication
    auth_type: str = "token"  # "token" for direct value, "bearer" for "Bearer {token}"
    timeout: float = 30.0  # Request timeout in seconds
    mcp_transport: str = (
        "streamable_http"  # "streamable_http" (default, modern) or "sse" (legacy fallback)
    )
    debug: bool = False  # Enable debug mode to capture request/response details

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

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

        # Remove trailing slash for consistency
        return v.rstrip("/")

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

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

        return v

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

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

Agent configuration.

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

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

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

Ancestors

pydantic.main.BaseModel

Class variables

var agent_uri : str
var auth_header : str
var auth_token : str | None
var auth_type : str
var debug : bool
var id : str
var mcp_transport : str
var model_config
var protocol : Protocol
var requires_auth : bool
var timeout : float

Static methods

def validate_agent_uri(v: str) ‑> str: Validate agent URI format.
def validate_auth_type(v: str) ‑> str: Validate auth type.
def validate_mcp_transport(v: str) ‑> str: Validate MCP transport type.
def validate_timeout(v: float) ‑> float: Validate timeout is reasonable.

class AggregatedTotals (**data: Any)

Expand source code

class AggregatedTotals(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    impressions: Annotated[
        float, Field(description='Total impressions delivered across all media buys', ge=0.0)
    ]
    spend: Annotated[float, Field(description='Total amount spent across all media buys', ge=0.0)]
    clicks: Annotated[
        float | None,
        Field(description='Total clicks across all media buys (if applicable)', ge=0.0),
    ] = None
    completed_views: Annotated[
        float | None,
        Field(
            description='Total audio/video completions across all media buys (if applicable)',
            ge=0.0,
        ),
    ] = None
    views: Annotated[
        float | None, Field(description='Total views across all media buys (if applicable)', ge=0.0)
    ] = None
    conversions: Annotated[
        float | None,
        Field(description='Total conversions across all media buys (if applicable)', ge=0.0),
    ] = None
    conversion_value: Annotated[
        float | None,
        Field(description='Total conversion value across all media buys (if applicable)', ge=0.0),
    ] = None
    roas: Annotated[
        float | 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[
        float | 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[
        float | None,
        Field(
            description='Aggregate cost per conversion across all media buys (total spend / total conversions)',
            ge=0.0,
        ),
    ] = None
    completion_rate: Annotated[
        float | None,
        Field(
            description='Aggregate completion rate across all media buys (weighted by impressions, not a simple average of per-buy rates)',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    reach: Annotated[
        float | None,
        Field(
            description='Deduplicated reach across all media buys (if the seller can deduplicate across buys; otherwise sum of per-buy reach). Only present when all media buys share the same reach_unit. Omitted when reach units are heterogeneous — use per-buy reach values instead.',
            ge=0.0,
        ),
    ] = 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[
        float | None,
        Field(
            description='Average frequency per reach unit across all media buys (impressions / reach when cross-buy deduplication is available). Only present when reach is present.',
            ge=0.0,
        ),
    ] = None
    media_buy_count: Annotated[
        int, Field(description='Number of media buys included in the response', ge=0)
    ]

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 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 model_config
var new_to_brand_rate : float | None
var reach : float | 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 Artifact (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var artifact_id : str
var assets : list[Assets | Assets1 | Assets2 | Assets3]
var format_id : FormatId | None
var identifiers : Identifiers | None
var last_update_time : pydantic.types.AwareDatetime | None
var metadata : Metadata | None
var model_config
var property_rid : str
var provenance : Provenance | None
var published_time : pydantic.types.AwareDatetime | None
var url : pydantic.networks.AnyUrl | None
var variant_id : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ArtifactWebhookPayload (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var artifacts : list[Artifact]
var batch_id : str
var ext : ExtensionObject | None
var idempotency_key : str
var media_buy_id : str
var model_config
var pagination : Pagination | None
var timestamp : pydantic.types.AwareDatetime

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Asset (**data: Any)

Expand source code

class Asset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_id: Annotated[str, Field(description='Unique identifier')]
    asset_type: Annotated[
        asset_content_type.AssetContentType, Field(description='Type of asset content')
    ]
    url: Annotated[AnyUrl, Field(description='URL to CDN-hosted asset file')]
    tags: Annotated[list[str] | None, Field(description='Tags for discovery')] = None
    name: Annotated[str | None, Field(description='Human-readable name')] = None
    description: Annotated[str | None, Field(description='Asset description or usage notes')] = None
    width: Annotated[int | None, Field(description='Image/video width in pixels')] = None
    height: Annotated[int | None, Field(description='Image/video height in pixels')] = None
    duration_seconds: Annotated[
        float | None, Field(description='Video/audio duration in seconds')
    ] = None
    file_size_bytes: Annotated[int | None, Field(description='File size in bytes')] = None
    format: Annotated[str | None, Field(description="File format (e.g., 'jpg', 'mp4')")] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var asset_id : str
var asset_type : AssetContentType
var description : str | None
var duration_seconds : float | None
var file_size_bytes : int | None
var format : str | None
var height : int | None
var model_config
var name : str | None
var tags : list[str] | None
var url : pydantic.networks.AnyUrl
var width : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AssetContentType (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var audio
var brief
var catalog
var css
var daast
var html
var image
var javascript
var markdown
var text
var url
var vast
var video
var webhook

class AssetType (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var audio
var brief
var catalog
var css
var daast
var html
var image
var javascript
var markdown
var text
var url
var vast
var video
var webhook

class AssignedPackage (**data: Any)

Expand source code

class AssignedPackage(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description='Package identifier')]
    assigned_date: Annotated[AwareDatetime, Field(description='When this assignment was created')]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var assigned_date : pydantic.types.AwareDatetime
var model_config
var package_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Assignments (**data: Any)

Expand source code

class Assignments(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    assignment_count: Annotated[
        int, Field(description='Total number of active package assignments', ge=0)
    ]
    assigned_packages: Annotated[
        list[AssignedPackage] | None,
        Field(description='List of packages this creative is assigned to'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var assigned_packages : list[AssignedPackage] | None
var assignment_count : int
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesAudience (**data: Any)

Expand source code

class Audience(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    audience_id: Annotated[
        str,
        Field(
            description="Buyer's identifier for this audience. Used to reference the audience in targeting overlays."
        ),
    ]
    name: Annotated[str | None, Field(description='Human-readable name for this audience')] = None
    description: Annotated[
        str | None,
        Field(
            description="Human-readable description of this audience's composition or purpose (e.g., 'High-value customers who purchased in the last 90 days')."
        ),
    ] = None
    audience_type: Annotated[
        AudienceType | None,
        Field(
            description="Intended use for this audience. 'crm': target these users. 'suppression': exclude these users from delivery. 'lookalike_seed': use as a seed for the seller's lookalike modeling. Sellers may handle audiences differently based on type (e.g., suppression lists bypass minimum size requirements on some platforms)."
        ),
    ] = None
    tags: Annotated[
        list[Tag] | None,
        Field(
            description="Buyer-defined tags for organizing and filtering audiences (e.g., 'holiday_2026', 'high_ltv'). Tags are stored by the seller and returned in discovery-only calls."
        ),
    ] = None
    add: Annotated[
        list[audience_member.AudienceMember] | None,
        Field(
            description='Members to add to this audience. Hashed before sending — normalize emails to lowercase+trim, phones to E.164.',
            min_length=1,
        ),
    ] = None
    remove: Annotated[
        list[audience_member.AudienceMember] | None,
        Field(
            description='Members to remove from this audience. If the same identifier appears in both add and remove in a single request, remove takes precedence.',
            min_length=1,
        ),
    ] = None
    delete: Annotated[
        bool | None,
        Field(
            description='When true, delete this audience from the account entirely. All other fields on this audience object are ignored. Use this to delete a specific audience without affecting others.'
        ),
    ] = None
    consent_basis: Annotated[
        consent_basis_1.ConsentBasis | None,
        Field(
            description='GDPR lawful basis for processing this audience list. Informational — not validated by the protocol, but required by some sellers operating in regulated markets (e.g. EU). When omitted, the buyer asserts they have a lawful basis appropriate to their jurisdiction.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var add : list[AudienceMember] | None
var audience_id : str
var audience_type : AudienceType | None
var consent_basis : ConsentBasis | None
var delete : bool | None
var description : str | None
var model_config
var name : str | None
var remove : list[AudienceMember] | None
var tags : list[Tag] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AudienceSource (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var lookalike
var platform
var retargeting
var synced
var third_party
var unknown

class AudioAsset (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var bit_depth : BitDepth | None
var bitrate_kbps : int | None
var channels : Channels | None
var codec : str | None
var container_format : str | None
var duration_ms : int | None
var file_size_bytes : int | None
var loudness_lufs : float | None
var model_config
var provenance : Provenance | None
var sampling_rate_hz : int | None
var transcript_url : pydantic.networks.AnyUrl | None
var true_peak_dbfs : float | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Authentication (**data: Any)

Expand source code

class Authentication(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    schemes: Annotated[list[auth_scheme.AuthenticationScheme], Field(max_length=1, min_length=1)]
    credentials: Annotated[
        str, Field(description='Authentication credential (e.g., Bearer token).', min_length=32)
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AuthenticationScheme (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var Bearer
var HMAC_SHA256

class Scheme (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var Bearer
var HMAC_SHA256

class AuthorizedAgents (**data: Any)

Expand source code

class AuthorizedAgents(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
    authorized_for: Annotated[
        str,
        Field(
            description='Human-readable description of what this agent is authorized to sell',
            max_length=500,
            min_length=1,
        ),
    ]
    authorization_type: Annotated[
        Literal['property_ids'],
        Field(description='Discriminator indicating authorization by specific property IDs'),
    ]
    property_ids: Annotated[
        list[property_id.PropertyId],
        Field(
            description='Property IDs this agent is authorized for. Resolved against the top-level properties array in this file',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description='Optional collection constraints. When present, authorization only applies to inventory associated with these collections.',
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        bool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = None
    signing_keys: Annotated[
        list[agent_signing_key.AgentSigningKey] | None,
        Field(
            description='Optional publisher-attested public signing keys for this agent. Use these as the trust anchor for verifying signed agent responses instead of relying on key discovery from the agent domain alone.',
            min_length=1,
        ),
    ] = None
    encryption_keys: Annotated[
        list[agent_encryption_key.AgentEncryptionKey] | None,
        Field(
            description='X25519 public keys for TMPX exposure token encryption. Each key identifies a cluster master that can decrypt TMPX tokens. Used with HPKE mode_base — read replicas encrypt with this public key, only the master can decrypt.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_type : Literal['property_ids']
var authorized_for : str
var collections : list[CollectionSelector] | None
var countries : list[Country] | None
var delegation_type : DelegationType | None
var effective_from : pydantic.types.AwareDatetime | None
var effective_until : pydantic.types.AwareDatetime | None
var encryption_keys : list[AgentEncryptionKey] | None
var exclusive : bool | None
var model_config
var placement_ids : list[str] | None
var placement_tags : list[str] | None
var property_ids : list[PropertyId]
var signing_keys : list[AgentSigningKey] | None
var url : pydantic.networks.AnyUrl

class AuthorizedAgentsByPropertyId (**data: Any)

Expand source code

class AuthorizedAgents(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
    authorized_for: Annotated[
        str,
        Field(
            description='Human-readable description of what this agent is authorized to sell',
            max_length=500,
            min_length=1,
        ),
    ]
    authorization_type: Annotated[
        Literal['property_ids'],
        Field(description='Discriminator indicating authorization by specific property IDs'),
    ]
    property_ids: Annotated[
        list[property_id.PropertyId],
        Field(
            description='Property IDs this agent is authorized for. Resolved against the top-level properties array in this file',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description='Optional collection constraints. When present, authorization only applies to inventory associated with these collections.',
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        bool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = None
    signing_keys: Annotated[
        list[agent_signing_key.AgentSigningKey] | None,
        Field(
            description='Optional publisher-attested public signing keys for this agent. Use these as the trust anchor for verifying signed agent responses instead of relying on key discovery from the agent domain alone.',
            min_length=1,
        ),
    ] = None
    encryption_keys: Annotated[
        list[agent_encryption_key.AgentEncryptionKey] | None,
        Field(
            description='X25519 public keys for TMPX exposure token encryption. Each key identifies a cluster master that can decrypt TMPX tokens. Used with HPKE mode_base — read replicas encrypt with this public key, only the master can decrypt.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_type : Literal['property_ids']
var authorized_for : str
var collections : list[CollectionSelector] | None
var countries : list[Country] | None
var delegation_type : DelegationType | None
var effective_from : pydantic.types.AwareDatetime | None
var effective_until : pydantic.types.AwareDatetime | None
var encryption_keys : list[AgentEncryptionKey] | None
var exclusive : bool | None
var model_config
var placement_ids : list[str] | None
var placement_tags : list[str] | None
var property_ids : list[PropertyId]
var signing_keys : list[AgentSigningKey] | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AuthorizedAgentsByPropertyTag (**data: Any)

Expand source code

class AuthorizedAgents1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
    authorized_for: Annotated[
        str,
        Field(
            description='Human-readable description of what this agent is authorized to sell',
            max_length=500,
            min_length=1,
        ),
    ]
    authorization_type: Annotated[
        Literal['property_tags'],
        Field(description='Discriminator indicating authorization by property tags'),
    ]
    property_tags: Annotated[
        list[property_tag.PropertyTag],
        Field(
            description='Tags identifying which properties this agent is authorized for. Resolved against the top-level properties array in this file using tag matching',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description='Optional collection constraints. When present, authorization only applies to inventory associated with these collections.',
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        bool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = None
    signing_keys: Annotated[
        list[agent_signing_key.AgentSigningKey] | None,
        Field(
            description='Optional publisher-attested public signing keys for this agent. Use these as the trust anchor for verifying signed agent responses instead of relying on key discovery from the agent domain alone.',
            min_length=1,
        ),
    ] = None
    encryption_keys: Annotated[
        list[agent_encryption_key.AgentEncryptionKey] | None,
        Field(
            description='X25519 public keys for TMPX exposure token encryption. Each key identifies a cluster master that can decrypt TMPX tokens. Used with HPKE mode_base — read replicas encrypt with this public key, only the master can decrypt.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_type : Literal['property_tags']
var authorized_for : str
var collections : list[CollectionSelector] | None
var countries : list[Country] | None
var delegation_type : DelegationType | None
var effective_from : pydantic.types.AwareDatetime | None
var effective_until : pydantic.types.AwareDatetime | None
var encryption_keys : list[AgentEncryptionKey] | None
var exclusive : bool | None
var model_config
var placement_ids : list[str] | None
var placement_tags : list[str] | None
var property_tags : list[PropertyTag]
var signing_keys : list[AgentSigningKey] | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AuthorizedAgentsByInlineProperties (**data: Any)

Expand source code

class AuthorizedAgents2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
    authorized_for: Annotated[
        str,
        Field(
            description='Human-readable description of what this agent is authorized to sell',
            max_length=500,
            min_length=1,
        ),
    ]
    authorization_type: Annotated[
        Literal['inline_properties'],
        Field(description='Discriminator indicating authorization by inline property definitions'),
    ]
    properties: Annotated[
        list[property.Property],
        Field(
            description='Specific properties this agent is authorized for (alternative to property_ids/property_tags)',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description='Optional collection constraints. When present, authorization only applies to inventory associated with these collections.',
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        bool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = None
    signing_keys: Annotated[
        list[agent_signing_key.AgentSigningKey] | None,
        Field(
            description='Optional publisher-attested public signing keys for this agent. Use these as the trust anchor for verifying signed agent responses instead of relying on key discovery from the agent domain alone.',
            min_length=1,
        ),
    ] = None
    encryption_keys: Annotated[
        list[agent_encryption_key.AgentEncryptionKey] | None,
        Field(
            description='X25519 public keys for TMPX exposure token encryption. Each key identifies a cluster master that can decrypt TMPX tokens. Used with HPKE mode_base — read replicas encrypt with this public key, only the master can decrypt.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_type : Literal['inline_properties']
var authorized_for : str
var collections : list[CollectionSelector] | None
var countries : list[Country] | None
var delegation_type : DelegationType | None
var effective_from : pydantic.types.AwareDatetime | None
var effective_until : pydantic.types.AwareDatetime | None
var encryption_keys : list[AgentEncryptionKey] | None
var exclusive : bool | None
var model_config
var placement_ids : list[str] | None
var placement_tags : list[str] | None
var properties : list[Property]
var signing_keys : list[AgentSigningKey] | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AuthorizedAgentsByPublisherProperties (**data: Any)

Expand source code

class AuthorizedAgents3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description="The authorized agent's API endpoint URL")]
    authorized_for: Annotated[
        str,
        Field(
            description='Human-readable description of what this agent is authorized to sell',
            max_length=500,
            min_length=1,
        ),
    ]
    authorization_type: Annotated[
        Literal['publisher_properties'],
        Field(
            description='Discriminator indicating authorization for properties from other publisher domains'
        ),
    ]
    publisher_properties: Annotated[
        list[publisher_property_selector.PublisherPropertySelector],
        Field(
            description='Properties from other publisher domains this agent is authorized for. Each entry specifies a publisher domain and which of their properties this agent can sell',
            min_length=1,
        ),
    ]
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description='Optional collection constraints. When present, authorization only applies to inventory associated with these collections.',
            min_length=1,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional placement constraints. When present, authorization only applies to these placement IDs from the top-level placements array in this file.',
            min_length=1,
        ),
    ] = None
    placement_tags: Annotated[
        list[str] | None,
        Field(
            description='Optional placement tag constraints. When present, authorization only applies to placements whose tags include any of these publisher-defined values.',
            min_length=1,
        ),
    ] = None
    delegation_type: Annotated[
        DelegationType | None,
        Field(
            description="Commercial relationship for this inventory path. 'direct' means the publisher treats this as a direct way to buy from them, even if a third party operates the software. 'delegated' means the agent is authorized to sell on the publisher's behalf. 'ad_network' means the inventory is sold as part of a network/package context rather than as the publisher's direct endpoint."
        ),
    ] = None
    exclusive: Annotated[
        bool | None,
        Field(
            description="Whether this agent is the publisher's sole authorized path for the scoped inventory slice. When false or absent, other authorized agents may also sell the same inventory."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Optional ISO 3166-1 alpha-2 country codes limiting where this authorization applies. Omit for worldwide authorization.',
            min_length=1,
        ),
    ] = None
    effective_from: Annotated[
        AwareDatetime | None,
        Field(description='Optional start time for this authorization window.'),
    ] = None
    effective_until: Annotated[
        AwareDatetime | None, Field(description='Optional end time for this authorization window.')
    ] = None
    signing_keys: Annotated[
        list[agent_signing_key.AgentSigningKey] | None,
        Field(
            description='Optional publisher-attested public signing keys for this agent. Use these as the trust anchor for verifying signed agent responses instead of relying on key discovery from the agent domain alone.',
            min_length=1,
        ),
    ] = None
    encryption_keys: Annotated[
        list[agent_encryption_key.AgentEncryptionKey] | None,
        Field(
            description='X25519 public keys for TMPX exposure token encryption. Each key identifies a cluster master that can decrypt TMPX tokens. Used with HPKE mode_base — read replicas encrypt with this public key, only the master can decrypt.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_type : Literal['publisher_properties']
var authorized_for : str
var collections : list[CollectionSelector] | None
var countries : list[Country] | None
var delegation_type : DelegationType | None
var effective_from : pydantic.types.AwareDatetime | None
var effective_until : pydantic.types.AwareDatetime | None
var encryption_keys : list[AgentEncryptionKey] | None
var exclusive : bool | None
var model_config
var placement_ids : list[str] | None
var placement_tags : list[str] | None
var publisher_properties : list[PublisherPropertySelector]
var signing_keys : list[AgentSigningKey] | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AuthorizedAgentsBySignalId (**data: Any)

Expand source code

class AuthorizedAgents4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description="The authorized signals agent's API endpoint URL")]
    authorized_for: Annotated[
        str,
        Field(
            description='Human-readable description of what signals this agent is authorized to resell',
            max_length=500,
            min_length=1,
        ),
    ]
    authorization_type: Annotated[
        Literal['signal_ids'],
        Field(description='Discriminator indicating authorization by specific signal IDs'),
    ]
    signal_ids: Annotated[
        list[SignalId],
        Field(
            description='Signal IDs this agent is authorized to resell. Resolved against the top-level signals array in this file',
            min_length=1,
        ),
    ]
    signing_keys: Annotated[
        list[agent_signing_key.AgentSigningKey] | None,
        Field(
            description='Optional publisher-attested public signing keys for this agent. Use these as the trust anchor for verifying signed agent responses instead of relying on key discovery from the agent domain alone.',
            min_length=1,
        ),
    ] = None
    encryption_keys: Annotated[
        list[agent_encryption_key.AgentEncryptionKey] | None,
        Field(
            description='X25519 public keys for TMPX exposure token encryption. Each key identifies a cluster master that can decrypt TMPX tokens. Used with HPKE mode_base — read replicas encrypt with this public key, only the master can decrypt.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_type : Literal['signal_ids']
var authorized_for : str
var encryption_keys : list[AgentEncryptionKey] | None
var model_config
var signal_ids : list[SignalId]
var signing_keys : list[AgentSigningKey] | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AuthorizedAgentsBySignalTag (**data: Any)

Expand source code

class AuthorizedAgents5(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description="The authorized signals agent's API endpoint URL")]
    authorized_for: Annotated[
        str,
        Field(
            description='Human-readable description of what signals this agent is authorized to resell',
            max_length=500,
            min_length=1,
        ),
    ]
    authorization_type: Annotated[
        Literal['signal_tags'],
        Field(description='Discriminator indicating authorization by signal tags'),
    ]
    signal_tags: Annotated[
        list[SignalTag],
        Field(
            description='Signal tags this agent is authorized for. Agent can resell all signals with these tags',
            min_length=1,
        ),
    ]
    signing_keys: Annotated[
        list[agent_signing_key.AgentSigningKey] | None,
        Field(
            description='Optional publisher-attested public signing keys for this agent. Use these as the trust anchor for verifying signed agent responses instead of relying on key discovery from the agent domain alone.',
            min_length=1,
        ),
    ] = None
    encryption_keys: Annotated[
        list[agent_encryption_key.AgentEncryptionKey] | None,
        Field(
            description='X25519 public keys for TMPX exposure token encryption. Each key identifies a cluster master that can decrypt TMPX tokens. Used with HPKE mode_base — read replicas encrypt with this public key, only the master can decrypt.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authorization_type : Literal['signal_tags']
var authorized_for : str
var encryption_keys : list[AgentEncryptionKey] | None
var model_config
var signal_tags : list[SignalTag]
var signing_keys : list[AgentSigningKey] | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AvailableMetric (*args, **kwds)

Expand source code

class AvailableMetric(Enum):
    impressions = 'impressions'
    spend = 'spend'
    clicks = 'clicks'
    ctr = 'ctr'
    video_completions = 'video_completions'
    completion_rate = 'completion_rate'
    conversions = 'conversions'
    conversion_value = 'conversion_value'
    roas = 'roas'
    cost_per_acquisition = 'cost_per_acquisition'
    new_to_brand_rate = 'new_to_brand_rate'
    viewability = 'viewability'
    engagement_rate = 'engagement_rate'
    views = 'views'
    completed_views = 'completed_views'
    leads = 'leads'
    reach = 'reach'
    frequency = 'frequency'
    grps = 'grps'
    quartile_data = 'quartile_data'
    dooh_metrics = 'dooh_metrics'
    cost_per_click = 'cost_per_click'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var clicks
var completed_views
var completion_rate
var conversion_value
var conversions
var cost_per_acquisition
var cost_per_click
var ctr
var dooh_metrics
var engagement_rate
var frequency
var grps
var impressions
var leads
var new_to_brand_rate
var quartile_data
var reach
var roas
var spend
var video_completions
var viewability
var views

class AvailablePackage (**data: Any)

Expand source code

class AvailablePackage(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    package_id: Annotated[str, Field(description='Unique identifier for the package')]
    media_buy_id: Annotated[str, Field(description='Media buy that this package belongs to')]
    format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Creative format identifiers eligible for this package. Uses the standard AdCP format-id object with agent_url and id for unambiguous format resolution across namespaces.'
        ),
    ] = None
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description="The buyer's catalogs attached to this package, with selectors (ids, gtins, tags, category, query) scoping which items are in play. References synced catalogs by catalog_id. The provider resolves items from its cached copy."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalogs : list[Catalog] | None
var format_ids : list[FormatId] | None
var media_buy_id : str
var model_config
var package_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BrandReference (**data: Any)

Expand source code

class BrandReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    domain: Annotated[
        str,
        Field(
            description="Domain where /.well-known/brand.json is hosted, or the brand's operating domain",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    brand_id: Annotated[
        brand_id_1.BrandId | None,
        Field(
            description='Brand identifier within the house portfolio. Optional for single-brand domains.'
        ),
    ] = None
    industries: Annotated[
        list[str] | None,
        Field(
            description="Inline override for the brand's industries. Useful when the caller cannot modify the brand's canonical brand.json but needs to declare industries for governance (e.g., Annex III vertical detection). brand.json remains the canonical source; when omitted here, governance agents SHOULD resolve from brand.json."
        ),
    ] = None
    data_subject_contestation: Annotated[
        DataSubjectContestation | DataSubjectContestation5 | None,
        Field(
            description="Inline override for the brand's contestation contact point. Useful when the operator does not control brand.json but needs to discharge Art 22(3) for this plan. brand.json is canonical; when omitted, governance agents resolve brand → house → missing."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var brand_id : BrandId | None
var data_subject_contestation : DataSubjectContestation | DataSubjectContestation5 | None
var domain : str
var industries : list[str] | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BrandSource (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var brand_json
var community
var enriched

class BuildCreativeRequest (**data: Any)

Expand source code

class BuildCreativeRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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. For pure generation, this should include the target format_id and any required input assets. For transformation (e.g., resizing, 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_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.FormatId | None,
        Field(
            description='Single format ID to generate. Mutually exclusive with target_format_ids. The format definition specifies required input assets and output structure.'
        ),
    ] = None
    target_format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Array of format IDs to generate in a single call. Mutually exclusive with target_format_id. The creative agent produces one manifest per format. Each format definition specifies its own required input assets and output structure.',
            min_length=1,
        ),
    ] = 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
    item_limit: Annotated[
        int | None,
        Field(
            description="Maximum number of catalog items to use when generating. 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.",
            ge=1,
        ),
    ] = None
    include_preview: Annotated[
        bool | 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. Each input set defines macros and context values for one preview variant. If include_preview is true but this is omitted, the agent generates a single default preview. Only supported with target_format_id (single-format requests). Ignored when using target_format_ids — multi-format requests generate one default preview per format. Ignored when include_preview is false or omitted.',
            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="Macro values to pre-substitute into the output manifest's assets. Keys are universal macro names (e.g., CLICK_URL, CACHEBUSTER); values are the substitution strings. The creative agent translates universal macros to its platform's native syntax. Substitution is literal — all occurrences of each macro in output assets are replaced with the provided value. The caller is responsible for URL-encoding values if the output context requires it. Macros not provided here remain as {MACRO} placeholders for the sales agent to resolve at serve time. Creative agents MUST ignore keys they do not recognize — unknown macro names are not an error."
        ),
    ] = 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}$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var brand : BrandReference | None
var concept_id : str | None
var context : ContextObject | None
var creative_id : str | None
var creative_manifest : CreativeManifest | None
var ext : ExtensionObject | None
var idempotency_key : str
var include_preview : bool | None
var item_limit : int | None
var macro_values : dict[str, str] | None
var media_buy_id : str | None
var message : str | 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 quality : CreativeQuality | None
var target_format_id : FormatId | None
var target_format_ids : list[FormatId] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BuildCreativeSuccessResponse (**data: Any)

Expand source code

class BuildCreativeResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest,
        Field(description='The generated or transformed creative manifest'),
    ]
    sandbox: Annotated[
        bool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when generated asset URLs in the manifest expire. Set to the earliest expiration across all generated assets. Re-build the creative after this time to get fresh URLs.'
        ),
    ] = None
    preview: Annotated[
        Preview | None,
        Field(
            description='Preview renders included when the request set include_preview to true and the agent supports it. Contains the same content fields as a preview_creative single response (previews, interactive_url, expires_at) minus the response_type discriminator, so clients can reuse the same preview rendering logic.'
        ),
    ] = None
    preview_error: Annotated[
        error.Error | None,
        Field(
            description="When include_preview was true in the request but preview generation failed. Uses the standard error structure with code, message, and recovery classification. Distinguishes 'agent does not support inline preview' (preview and preview_error both absent) from 'preview generation failed' (preview absent, preview_error present). Omitted when preview succeeded or was not requested."
        ),
    ] = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description='Which rate card pricing option was applied for this build. Present when the creative agent charges for its services. Pass this in report_usage to identify which pricing option was applied.'
        ),
    ] = None
    vendor_cost: Annotated[
        float | None,
        Field(
            description='Cost incurred for this build, denominated in currency. May be 0 for CPM-priced creatives where cost accrues at serve time rather than build time.',
            ge=0.0,
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(description='ISO 4217 currency code for vendor_cost.', pattern='^[A-Z]{3}$'),
    ] = None
    consumption: Annotated[
        creative_consumption.CreativeConsumption | None,
        Field(
            description='Structured consumption details for this build. Informational — lets the buyer verify that vendor_cost is consistent with the rate card. vendor_cost is the billing source of truth.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var consumption : CreativeConsumption | None
var context : ContextObject | None
var creative_manifest : CreativeManifest
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 sandbox : bool | None
var vendor_cost : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BuildCreativeErrorResponse (**data: Any)

Expand source code

class BuildCreativeResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_manifests: Annotated[
        list[creative_manifest_1.CreativeManifest],
        Field(
            description='Array of generated creative manifests, one per requested format. Each manifest contains its own format_id identifying which format it was generated for.',
            min_length=1,
        ),
    ]
    sandbox: Annotated[
        bool | None,
        Field(description='When true, this response contains simulated data from sandbox mode.'),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when the earliest generated asset URL expires across all manifests. Re-build after this time to get fresh URLs.'
        ),
    ] = None
    preview: Annotated[
        Preview2 | None,
        Field(
            description='Preview renders included when the request set include_preview to true and the agent supports it. Contains one default preview per requested format. preview_inputs is ignored for multi-format requests.'
        ),
    ] = None
    preview_error: Annotated[
        error.Error | None,
        Field(
            description='When include_preview was true in the request but preview generation failed. Uses the standard error structure with code, message, and recovery classification. Omitted when preview succeeded or was not requested.'
        ),
    ] = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description='Which rate card pricing option was applied for this build. Represents the total cost of the entire multi-format build call. Present when the creative agent charges for its services.'
        ),
    ] = None
    vendor_cost: Annotated[
        float | None,
        Field(
            description='Total cost incurred for this multi-format build, denominated in currency. May be 0 for CPM-priced creatives where cost accrues at serve time.',
            ge=0.0,
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(description='ISO 4217 currency code for vendor_cost.', pattern='^[A-Z]{3}$'),
    ] = None
    consumption: Annotated[
        creative_consumption.CreativeConsumption | None,
        Field(
            description='Structured consumption details for this build. Informational — lets the buyer verify that vendor_cost is consistent with the rate card.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var consumption : CreativeConsumption | None
var context : ContextObject | None
var creative_manifests : list[CreativeManifest]
var currency : str | None
var expires_at : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var model_config
var preview : Preview2 | None
var preview_error : Error | None
var pricing_option_id : str | None
var sandbox : bool | None
var vendor_cost : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BuyingMode (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var brief
var refine
var wholesale

class ByCatalogItemItem (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var content_id : str
var content_id_type : ContentIdType | None
var impressions : Any
var model_config
var spend : Any

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class ByPackageItem (**data: Any)

Expand source code

class ByPackageItem(DeliveryMetrics):
    package_id: Annotated[str, Field(description="Seller's package identifier")]
    pacing_index: Annotated[
        float | None,
        Field(description='Delivery pace (1.0 = on track, <1.0 = behind, >1.0 = ahead)', ge=0.0),
    ] = None
    pricing_model: Annotated[
        pricing_model_1.PricingModel,
        Field(
            description='The pricing model used for this package (e.g., cpm, cpcv, cpp). Indicates how the package is billed and which metrics are most relevant for optimization.'
        ),
    ]
    rate: Annotated[
        float,
        Field(
            description='The pricing rate for this package in the specified currency. For fixed-rate pricing, this is the agreed rate (e.g., CPM rate of 12.50 means $12.50 per 1,000 impressions). For auction-based pricing, this represents the effective rate based on actual delivery.',
            ge=0.0,
        ),
    ]
    currency: Annotated[
        str,
        Field(
            description="ISO 4217 currency code (e.g., USD, EUR, GBP) for this package's pricing. Indicates the currency in which the rate and spend values are denominated. Different packages can use different currencies when supported by the publisher.",
            pattern='^[A-Z]{3}$',
        ),
    ]
    delivery_status: Annotated[
        DeliveryStatus | None,
        Field(
            description='System-reported operational state of this package. Reflects actual delivery state independent of buyer pause control.'
        ),
    ] = None
    paused: Annotated[
        bool | None, Field(description='Whether this package is currently paused by the buyer')
    ] = None
    is_final: Annotated[
        bool | None,
        Field(
            description='Whether this delivery data is final for the reporting period. When false, the data may be updated as measurement matures (e.g., broadcast C7 window accumulating DVR playback) or as processing completes (e.g., IVT filtering, deduplication). When true, the seller considers this data closed — no further updates for this period. Absent means the seller does not distinguish provisional from final data.'
        ),
    ] = None
    measurement_window: Annotated[
        str | None,
        Field(
            description="Which measurement window this data represents, referencing a window_id from the product's reporting_capabilities.measurement_windows. For broadcast: 'live', 'c3', 'c7'. When absent, the data is not windowed (standard digital reporting). When present with is_final: false, a later report for the same period will provide a wider window or more complete data.",
            examples=['live', 'c3', 'c7'],
            max_length=50,
        ),
    ] = None
    supersedes_window: Annotated[
        str | None,
        Field(
            description="Which measurement window this data replaces. Present on window_update notifications to indicate progression (e.g., 'live' when reporting C3 data that supersedes live-only numbers). Absent on the first report for a period. Buyers should replace stored data for the superseded window with this report's data.",
            examples=['live', 'c3'],
            max_length=50,
        ),
    ] = None
    by_catalog_item: Annotated[
        list[ByCatalogItemItem] | None,
        Field(
            description='Delivery by catalog item within this package. Available for catalog-driven packages when the seller supports item-level reporting.'
        ),
    ] = None
    by_creative: Annotated[
        list[ByCreativeItem] | None,
        Field(
            description='Metrics broken down by creative within this package. Available when the seller supports creative-level reporting.'
        ),
    ] = None
    by_keyword: Annotated[
        list[ByKeywordItem] | None,
        Field(
            description='Metrics broken down by keyword within this package. One row per (keyword, match_type) pair — the same keyword with different match types appears as separate rows. Keyword-grain only: rows reflect aggregate performance of each targeted keyword, not individual search queries. Rows may not sum to package totals when a single impression is attributed to the triggering keyword only. Available for search and retail media packages when the seller supports keyword-level reporting.'
        ),
    ] = None
    by_geo: Annotated[
        list[ByGeoItem] | None,
        Field(
            description="Delivery by geographic area within this package. Available when the buyer requests geo breakdown via reporting_dimensions and the seller supports it. Each dimension's rows are independent slices that should sum to the package total."
        ),
    ] = None
    by_geo_truncated: Annotated[
        bool | None,
        Field(
            description='Whether by_geo was truncated due to the requested limit or a seller-imposed maximum. Sellers MUST return this flag whenever by_geo is present (false means the list is complete).'
        ),
    ] = None
    by_device_type: Annotated[
        list[ByDeviceTypeItem] | None,
        Field(
            description='Delivery by device form factor within this package. Available when the buyer requests device_type breakdown via reporting_dimensions and the seller supports it.'
        ),
    ] = None
    by_device_type_truncated: Annotated[
        bool | None,
        Field(
            description='Whether by_device_type was truncated. Sellers MUST return this flag whenever by_device_type is present (false means the list is complete).'
        ),
    ] = None
    by_device_platform: Annotated[
        list[ByDevicePlatformItem] | None,
        Field(
            description='Delivery by operating system within this package. Available when the buyer requests device_platform breakdown via reporting_dimensions and the seller supports it. Useful for CTV campaigns where tvOS vs Roku OS vs Fire OS matters.'
        ),
    ] = None
    by_device_platform_truncated: Annotated[
        bool | None,
        Field(
            description='Whether by_device_platform was truncated. Sellers MUST return this flag whenever by_device_platform is present (false means the list is complete).'
        ),
    ] = None
    by_audience: Annotated[
        list[ByAudienceItem] | None,
        Field(
            description="Delivery by audience segment within this package. Available when the buyer requests audience breakdown via reporting_dimensions and the seller supports it. Only 'synced' audiences are directly targetable via the targeting overlay; other sources are informational."
        ),
    ] = None
    by_audience_truncated: Annotated[
        bool | None,
        Field(
            description='Whether by_audience was truncated. Sellers MUST return this flag whenever by_audience is present (false means the list is complete).'
        ),
    ] = None
    by_placement: Annotated[
        list[ByPlacementItem] | None,
        Field(
            description="Delivery by placement within this package. Available when the buyer requests placement breakdown via reporting_dimensions and the seller supports it. Placement IDs reference the product's placements array."
        ),
    ] = None
    by_placement_truncated: Annotated[
        bool | None,
        Field(
            description='Whether by_placement was truncated. Sellers MUST return this flag whenever by_placement is present (false means the list is complete).'
        ),
    ] = None
    daily_breakdown: Annotated[
        list[DailyBreakdownItem] | None,
        Field(
            description='Day-by-day delivery for this package. Only present when include_package_daily_breakdown is true in the request. Enables per-package pacing analysis and line-item monitoring.'
        ),
    ] = None
    spend: Any

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var by_audience : list[ByAudienceItem] | None
var by_audience_truncated : bool | None
var by_catalog_item : list[ByCatalogItemItem] | None
var by_creative : list[ByCreativeItem] | None
var by_device_platform : list[ByDevicePlatformItem] | None
var by_device_platform_truncated : bool | None
var by_device_type : list[ByDeviceTypeItem] | None
var by_device_type_truncated : bool | None
var by_geo : list[ByGeoItem] | None
var by_geo_truncated : bool | None
var by_keyword : list[ByKeywordItem] | None
var by_placement : list[ByPlacementItem] | None
var by_placement_truncated : bool | None
var currency : str
var daily_breakdown : list[DailyBreakdownItem] | None
var delivery_status : DeliveryStatus | None
var is_final : bool | None
var measurement_window : str | None
var model_config
var pacing_index : float | None
var package_id : str
var paused : bool | None
var pricing_model : PricingModel
var rate : float
var spend : Any
var supersedes_window : str | None

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class CalibrateContentRequest (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var artifact : Artifact
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var standards_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CalibrateContentSuccessResponse (**data: Any)

Expand source code

class CalibrateContentResponse1(AdCPBaseModel):
    verdict: Annotated[
        Verdict, Field(description='Overall pass/fail verdict for the content evaluation')
    ]
    confidence: Annotated[
        float | None, Field(description='Model confidence in the verdict (0-1)', ge=0.0, le=1.0)
    ] = None
    explanation: Annotated[
        str | None, Field(description='Detailed natural language explanation of the decision')
    ] = None
    features: Annotated[
        list[Feature] | None,
        Field(
            description='Per-feature breakdown with explanations. Mirrors validate_content_delivery feature shape so calibration loops can correlate against production verdicts by policy_id.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var confidence : float | None
var context : ContextObject | None
var explanation : str | None
var ext : ExtensionObject | None
var features : list[Feature] | None
var model_config
var verdict : Verdict

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CalibrateContentErrorResponse (**data: Any)

Expand source code

class CalibrateContentResponse2(AdCPBaseModel):
    errors: list[error.Error]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Catalog (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

CatalogAsset

Class variables

var catalog_id : str | None
var category : str | None
var content_id_type : ContentIdType | None
var conversion_events : list[EventType] | None
var feed_field_mappings : list[CatalogFieldMapping] | None
var feed_format : FeedFormat | None
var gtins : list[Gtin] | None
var ids : list[str] | None
var items : list[dict[str, typing.Any]] | None
var model_config
var name : str | None
var query : str | None
var tags : list[str] | None
var type : CatalogType
var update_frequency : UpdateFrequency | None
var url : pydantic.networks.AnyUrl | None

class SyncCatalogResult (**data: Any)

Expand source code

class Catalog(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catalog_id: Annotated[str, Field(description='Catalog ID from the request')]
    action: Annotated[
        catalog_action.CatalogAction, Field(description='Action taken for this catalog')
    ]
    platform_id: Annotated[
        str | None, Field(description='Platform-specific ID assigned to the catalog')
    ] = None
    item_count: Annotated[
        int | None, Field(description='Total number of items in the catalog after sync', ge=0)
    ] = None
    items_approved: Annotated[
        int | None,
        Field(
            description='Number of items approved by the platform. Populated when the platform performs item-level review.',
            ge=0,
        ),
    ] = None
    items_pending: Annotated[
        int | None,
        Field(
            description='Number of items pending platform review. Common for product catalogs where items must pass content policy checks.',
            ge=0,
        ),
    ] = None
    items_rejected: Annotated[
        int | None,
        Field(
            description='Number of items rejected by the platform. Check item_issues for rejection reasons.',
            ge=0,
        ),
    ] = None
    item_issues: Annotated[
        list[ItemIssue] | None,
        Field(
            description='Per-item issues reported by the platform (rejections, warnings). Only present when the platform performs item-level review.'
        ),
    ] = None
    last_synced_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp of when the most recent sync was accepted by the platform'
        ),
    ] = None
    next_fetch_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp of when the platform will next fetch the feed URL. Only present for URL-based catalogs with update_frequency.'
        ),
    ] = None
    changes: Annotated[
        list[str] | None,
        Field(description="Field names that were modified (only present when action='updated')"),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(description="Validation or processing errors (only present when action='failed')"),
    ] = None
    warnings: Annotated[
        list[str] | None, Field(description='Non-fatal warnings about this catalog')
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 : CatalogAction
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

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CatalogAction (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var created
var deleted
var failed
var unchanged
var updated

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

Expand source code

class CatalogFieldBinding(RootModel[ScalarBinding | AssetPoolBinding | CatalogFieldBinding1]):
    root: Annotated[
        ScalarBinding | AssetPoolBinding | CatalogFieldBinding1,
        Field(
            description="Maps a format template slot to a catalog item field or typed asset pool. The 'kind' field identifies the binding variant. All bindings are optional — agents can still infer mappings without them.",
            examples=[
                {
                    'description': 'Scalar binding — hotel name to headline slot',
                    'data': {'kind': 'scalar', 'asset_id': 'headline', 'catalog_field': 'name'},
                },
                {
                    'description': 'Scalar binding — nested field (nightly rate)',
                    'data': {
                        'kind': 'scalar',
                        'asset_id': 'price_badge',
                        'catalog_field': 'price.amount',
                    },
                },
                {
                    'description': 'Asset pool binding — hero image from landscape pool',
                    'data': {
                        'kind': 'asset_pool',
                        'asset_id': 'hero_image',
                        'asset_group_id': 'images_landscape',
                    },
                },
                {
                    'description': 'Asset pool binding — Snap vertical background from vertical pool',
                    'data': {
                        'kind': 'asset_pool',
                        'asset_id': 'snap_background',
                        'asset_group_id': 'images_vertical',
                    },
                },
                {
                    'description': 'Catalog group binding — carousel where each slide is one hotel',
                    'data': {
                        'kind': 'catalog_group',
                        'format_group_id': 'slide',
                        'catalog_item': True,
                        'per_item_bindings': [
                            {'kind': 'scalar', 'asset_id': 'title', 'catalog_field': 'name'},
                            {
                                'kind': 'scalar',
                                'asset_id': 'price',
                                'catalog_field': 'price.amount',
                            },
                            {
                                'kind': 'asset_pool',
                                'asset_id': 'image',
                                'asset_group_id': 'images_landscape',
                            },
                        ],
                    },
                },
            ],
            title='Catalog Field Binding',
        ),
    ]

    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

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

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

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

Ancestors

pydantic.root_model.RootModel[Union[ScalarBinding, AssetPoolBinding, CatalogFieldBinding1]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : ScalarBinding | AssetPoolBinding | CatalogFieldBinding1

class CatalogFieldBinding1 (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalog_item : Literal[True]
var ext : ExtensionObject | None
var format_group_id : str
var kind : Literal['catalog_group']
var model_config
var per_item_bindings : list[ScalarBinding | AssetPoolBinding] | None

class CatalogGroupBinding (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalog_item : Literal[True]
var ext : ExtensionObject | None
var format_group_id : str
var kind : Literal['catalog_group']
var model_config
var per_item_bindings : list[ScalarBinding | AssetPoolBinding] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CatalogFieldMapping (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var asset_group_id : str | None
var by : float | None
var catalog_field : str | None
var default : typing.Any | None
var ext : ExtensionObject | None
var feed_field : str | None
var format : str | None
var model_config
var separator : str | None
var timezone : str | None
var transform : Transform | None
var value : typing.Any | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CatalogItemStatus (*args, **kwds)

Expand source code

class CatalogItemStatus(Enum):
    approved = 'approved'
    pending = 'pending'
    rejected = 'rejected'
    warning = 'warning'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var approved
var pending
var rejected
var warning

class CatalogRequirements (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalog_type : CatalogType
var feed_formats : list[FeedFormat] | None
var field_bindings : list[CatalogFieldBinding] | None
var max_items : int | None
var min_items : int | None
var model_config
var offering_asset_constraints : list[OfferingAssetConstraint] | None
var required : bool | None
var required_fields : list[str] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CatalogType (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var app
var destination
var education
var flight
var hotel
var inventory
var job
var offering
var product
var promotion
var real_estate
var store
var vehicle

class CheckGovernanceRequest (**data: Any)

Expand source code

class CheckGovernanceRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    plan_id: Annotated[str, Field(description='Campaign governance plan identifier.')]
    caller: Annotated[AnyUrl, Field(description='URL of the agent making the request.')]
    purchase_type: Annotated[
        purchase_type_1.PurchaseType | None,
        Field(
            description="The type of financial commitment being checked. Determines which budget allocation (if any) to validate against. Defaults to 'media_buy' when omitted."
        ),
    ] = purchase_type_1.PurchaseType.media_buy
    tool: Annotated[
        str | None,
        Field(
            description="The AdCP tool being checked (e.g., 'create_media_buy', 'acquire_rights', 'activate_signal'). Present on intent checks (orchestrator). The governance agent uses the presence of tool+payload to identify an intent check."
        ),
    ] = None
    payload: Annotated[
        dict[str, Any] | None,
        Field(
            description='The full tool arguments as they would be sent to the seller. Present on intent checks. The governance agent can inspect any field to validate against the plan.'
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description='Governance context token from a prior check_governance response. Pass this on subsequent checks for the same governed action so the governance agent can maintain continuity across the lifecycle. In 3.0 governance agents MUST emit a compact JWS per the AdCP JWS profile (see Security — Signed Governance Context); callers persist and forward the value verbatim.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    phase: Annotated[
        governance_phase.GovernancePhase | None,
        Field(
            description="The phase of the governed action's lifecycle. 'purchase': initial commitment (create_media_buy, acquire_rights, activate_signal). 'modification': update to existing commitment. 'delivery': periodic delivery or usage reporting. Defaults to 'purchase' if omitted."
        ),
    ] = governance_phase.GovernancePhase.purchase
    planned_delivery: Annotated[
        planned_delivery_1.PlannedDelivery | None,
        Field(description='What the seller will actually deliver. Present on execution checks.'),
    ] = None
    delivery_metrics: Annotated[
        DeliveryMetrics | None,
        Field(
            description="Actual delivery performance data. MUST be present for 'delivery' phase. The governance agent compares these metrics against the planned delivery to detect drift."
        ),
    ] = None
    modification_summary: Annotated[
        str | None,
        Field(
            description="Human-readable summary of what changed. SHOULD be present for 'modification' phase.",
            max_length=1000,
        ),
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description='Invoice recipient from the purchase request. MUST be present when the tool payload includes invoice_recipient, so the governance agent can validate billing changes.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var caller : pydantic.networks.AnyUrl
var context : ContextObject | None
var delivery_metrics : DeliveryMetrics | None
var ext : ExtensionObject | None
var governance_context : str | None
var invoice_recipient : BusinessEntity | None
var model_config
var modification_summary : str | None
var payload : dict[str, typing.Any] | None
var phase : GovernancePhase | None
var plan_id : str
var planned_delivery : PlannedDelivery | None
var purchase_type : PurchaseType | None
var tool : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CheckGovernanceResponse (**data: Any)

Expand source code

class CheckGovernanceResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    check_id: Annotated[
        str,
        Field(
            description='Unique identifier for this governance check record. Use in report_plan_outcome to link outcomes to the check that authorized them.'
        ),
    ]
    status: Annotated[
        Status,
        Field(
            description="Governance decision. 'approved': proceed as planned. 'denied': do not proceed. 'conditions': approved if the caller accepts the listed conditions, then re-calls check_governance with the adjusted parameters."
        ),
    ]
    plan_id: Annotated[str, Field(description='Echoed from request.')]
    explanation: Annotated[
        str, Field(description='Human-readable explanation of the governance decision.')
    ]
    findings: Annotated[
        list[Finding] | None,
        Field(
            description="Specific issues found during the governance check. Present when status is 'denied' or 'conditions'. MAY also be present on 'approved' for informational findings (e.g., budget approaching limit)."
        ),
    ] = None
    conditions: Annotated[
        list[Condition] | None,
        Field(
            description="Present when status is 'conditions'. Specific adjustments the caller must make. After applying conditions, the caller MUST re-call check_governance with the adjusted parameters before proceeding."
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description="When this approval expires. Present when status is 'approved' or 'conditions'. The caller must act before this time or re-call check_governance. A lapsed approval is no approval."
        ),
    ] = None
    next_check: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller should next call check_governance with delivery metrics. Present when the governance agent expects ongoing delivery reporting.'
        ),
    ] = None
    categories_evaluated: Annotated[
        list[str] | None, Field(description='Governance categories evaluated during this check.')
    ] = None
    policies_evaluated: Annotated[
        list[str] | None, Field(description='Registry policy IDs evaluated during this check.')
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description="Governance context token for this governed action. The buyer MUST attach this to the protocol envelope when sending the purchase request (media buy, rights acquisition, signal activation) to the seller. The seller MUST persist it and include it on all subsequent check_governance calls for this action's lifecycle.\n\nValue format: in 3.0 governance agents MUST emit a compact JWS per the AdCP JWS profile (see Security — Signed Governance Context). Sellers MAY verify; sellers that do not verify MUST persist and forward the token unchanged so auditors can verify downstream. In 3.1 all sellers MUST verify per the checklist. Non-JWS values from pre-3.0 governance agents are deprecated and will be rejected in 3.1.\n\nSellers that implement verification MUST verify signature, `aud`, `exp`, `jti` replay, and revocation per the profile before treating the request as governance-approved. This is the primary correlation key for audit and reporting across the governance lifecycle — the governance agent decodes its own signed token to look up internal plan state (buyer correlation IDs, policy decision log, etc.).",
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var categories_evaluated : list[str] | None
var check_id : str
var conditions : list[Condition] | None
var context : ContextObject | None
var expires_at : pydantic.types.AwareDatetime | None
var explanation : str
var ext : ExtensionObject | None
var findings : list[Finding] | None
var governance_context : str | None
var model_config
var next_check : pydantic.types.AwareDatetime | None
var plan_id : str
var policies_evaluated : list[str] | None
var status : Status

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CoBrandingRequirement (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var none
var optional
var required

class CoBranding (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var none
var optional
var required

class CollectionList (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var base_collections : list[BaseCollectionSource] | None
var brand : BrandReference | None
var cache_duration_hours : int | None
var collection_count : int | None
var created_at : pydantic.types.AwareDatetime | None
var description : str | None
var filters : CollectionListFilters | None
var list_id : str
var model_config
var name : str
var updated_at : pydantic.types.AwareDatetime | None
var webhook_url : pydantic.networks.AnyUrl | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CollectionListChangedWebhook (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_valid_until : pydantic.types.AwareDatetime | None
var change_summary : ChangeSummary | None
var event : Literal['collection_list_changed']
var ext : ExtensionObject | None
var idempotency_key : str
var list_id : str
var list_name : str | None
var model_config
var resolved_at : pydantic.types.AwareDatetime
var signature : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CollectionListFilters (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var content_ratings_exclude : list[ContentRating] | None
var content_ratings_include : list[ContentRating] | None
var exclude_distribution_ids : list[ExcludeDistributionId] | None
var genre_taxonomy : GenreTaxonomy | None
var genres_exclude : list[str] | None
var genres_include : list[str] | None
var kinds : list[Kind] | None
var model_config
var production_quality : list[ProductionQuality] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Colors (**data: Any)

Expand source code

class Colors(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    primary: Primary | Primary1 | None = None
    secondary: Secondary | Secondary1 | None = None
    accent: Accent | Accent1 | None = None
    background: Background2 | Background3 | None = None
    text: Text | Text1 | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accent : Accent | Accent1 | None
var background : Background2 | Background3 | None
var model_config
var primary : Primary | Primary1 | None
var secondary : Secondary | Secondary1 | None
var text : Text | Text1 | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ComplyTestControllerRequest (**data: Any)

Expand source code

class ComplyTestControllerRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    scenario: Annotated[
        Scenario,
        Field(
            description="Test scenario to execute. 'list_scenarios' discovers supported scenarios. Others trigger state transitions for the specified domain."
        ),
    ]
    params: Annotated[
        Params | None,
        Field(
            description='Scenario-specific parameters. Required for all scenarios except list_scenarios.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 params : Params | None
var scenario : Scenario

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ComplyListScenariosResponse (**data: Any)

Expand source code

class ComplyTestControllerResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Literal[True]
    scenarios: Annotated[list[Scenario], Field(description='Scenarios this seller has implemented')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 scenarios : list[Scenario]
var success : Literal[True]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ComplyStateTransitionResponse (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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_state : str
var ext : ExtensionObject | None
var message : str | None
var model_config
var previous_state : str
var success : Literal[True]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ComplySimulationResponse (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 cumulative : dict[str, typing.Any] | None
var ext : ExtensionObject | None
var message : str | None
var model_config
var simulated : dict[str, typing.Any]
var success : Literal[True]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ComplyErrorResponse (**data: Any)

Expand source code

class ComplyTestControllerResponse4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Literal[False]
    error: Annotated[Error, Field(description='Structured error code')]
    error_detail: Annotated[
        str | None, Field(description='Human-readable explanation of the failure')
    ] = None
    current_state: Annotated[
        str | None, Field(description='Current state of the entity, or null if not found')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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_state : str | None
var error : Error
var error_detail : str | None
var ext : ExtensionObject | None
var model_config
var success : Literal[False]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ConsentBasis (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var consent
var contract
var legal_obligation
var legitimate_interest

class Contact (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var domain : str | None
var email : pydantic.networks.EmailStr | None
var model_config
var name : str
var privacy_policy_url : pydantic.networks.AnyUrl | None
var seller_id : str | None
var tag_id : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ContentIdType (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var app_id
var destination_id
var flight_id
var gtin
var hotel_id
var job_id
var listing_id
var offering_id
var program_id
var sku
var store_id
var vehicle_id

class ContentStandards (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot 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

GetContentStandardsResponse1

Class variables

var calibration_exemplars : CalibrationExemplars | None
var channels_any : list[MediaChannel] | None
var countries_all : list[str] | None
var ext : ExtensionObject | None
var languages_any : list[str] | None
var model_config
var name : str | None
var policies : list[PolicyEntry] | None
var pricing_options : list[VendorPricingOption] | None
var standards_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ContextMatchRequest (**data: Any)

Expand source code

class ContextMatchRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['context_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ]
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any identity match request_id.'
        ),
    ]
    property_rid: Annotated[
        UUID,
        Field(
            description='Property catalog UUID (UUID v7). Globally unique, stable identifier assigned by the property catalog. The primary key for TMP matching and property list targeting.'
        ),
    ]
    property_id: Annotated[
        property_id_1.PropertyId | None,
        Field(
            description="Publisher's human-readable property slug (e.g., 'cnn_homepage'). Optional when property_rid is present. Useful for logging and debugging."
        ),
    ] = None
    property_type: Annotated[
        property_type_1.PropertyType, Field(description='Type of the publisher property')
    ]
    placement_id: Annotated[
        str,
        Field(
            description="Placement identifier from the publisher's placement registry in adagents.json. Identifies where on the property this ad opportunity exists. One placement per request."
        ),
    ]
    artifact: Annotated[
        artifact_1.Artifact | None,
        Field(
            description='Full content artifact adjacent to this ad opportunity. Same schema used for content standards evaluation. The publisher sends the artifact when they want the buyer to evaluate the full content. Contractual protections govern buyer use. TEE deployment upgrades contractual trust to cryptographic verification. Publishers MUST NOT include asset access credentials (bearer tokens, service accounts) — the router fans out to multiple buyer agents. For secured assets, use signed URLs with short expiry. Routers MUST strip access fields from artifacts before forwarding.'
        ),
    ] = None
    artifact_refs: Annotated[
        list[ArtifactRef] | None,
        Field(
            description='Public content references adjacent to this ad opportunity. Each artifact identifies content via a public identifier the buyer can resolve independently — no private registry sync required.',
            max_length=20,
            min_length=1,
        ),
    ] = None
    geo: Annotated[
        Geo | None,
        Field(
            description='Coarse geographic location of the viewer. Publisher controls granularity — country is sufficient for regulatory compliance and volume filtering, region or metro helps with campaign targeting and valuation. Coarsened to prevent user identification: no postcode, no coordinates. All fields optional.'
        ),
    ] = None
    context_signals: Annotated[
        ContextSignals | None,
        Field(
            description='Pre-computed classifier outputs for the content environment. Use when the publisher wants to provide classified context without sharing content or public references. Can supplement artifact_refs (e.g., URL + pre-classified topics) or replace them entirely (e.g., ephemeral conversation turns). Raw content MUST NOT be included — only classified outputs. The publisher is the classifier boundary.'
        ),
    ] = None
    package_ids: Annotated[
        list[str] | None,
        Field(
            description='Restrict evaluation to specific packages. When omitted, the provider evaluates all eligible packages for this placement (the common case). MUST NOT vary by user — the same package_ids must be sent for every user on a given placement. User-dependent filtering leaks identity into the context path.',
            max_length=500,
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var artifact : Artifact | None
var artifact_refs : list[ArtifactRef] | None
var context_signals : ContextSignals | None
var field_schema : pydantic.networks.AnyUrl | None
var geo : Geo | None
var model_config
var package_ids : list[str] | None
var placement_id : str
var property_id : PropertyId | None
var property_rid : uuid.UUID
var property_type : PropertyType
var protocol_version : str | None
var request_id : str
var type : Literal['context_match_request']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ContextMatchResponse (**data: Any)

Expand source code

class ContextMatchResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['context_match_response'],
        Field(description='Message type discriminator for deserialization.'),
    ]
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the context match request')
    ]
    offers: Annotated[
        list[offer.Offer],
        Field(
            description='Offers from the buyer, one per activated package. An empty array means no packages matched. For simple activation, each offer has just package_id. For richer responses, offers include brand, price, summary, and creative manifest.'
        ),
    ]
    cache_ttl: Annotated[
        int | None,
        Field(
            description='Optional override for the default 5-minute cache TTL, in seconds. When present, the router MUST use this value instead of its default. Set to 0 to disable caching (e.g., when targeting configuration has just changed).',
            ge=0,
            le=86400,
        ),
    ] = None
    signals: Annotated[
        Signals | None,
        Field(
            description='Response-level targeting signals for ad server pass-through. In the GAM case, these carry the key-value pairs that trigger line items. Not per-offer — applies to the response as a whole.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_ttl : int | None
var model_config
var offers : list[Offer]
var request_id : str
var signals : Signals | None
var type : Literal['context_match_response']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ContextObject (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 Country (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class Country(RootModel[str]):
    root: Annotated[str, Field(pattern='^[A-Z]{2}$')]

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

Class variables

var model_config
var root : str

class CpaPricingOption (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var custom_event_name : str | None
var eligible_adjustments : list[PriceAdjustmentKind] | None
var event_source_id : str | None
var event_type : EventType
var fixed_price : float
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var pricing_model : Literal['cpa']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CpcPricingOption (**data: Any)

Expand source code

class CpcPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpc'], Field(description='Cost per click')]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per click. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['cpc']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CpcvPricingOption (**data: Any)

Expand source code

class CpcvPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    pricing_option_id: Annotated[
        str, Field(description="Unique identifier for this pricing option within the product")
    ]
    pricing_model: Annotated[
        Literal["cpcv"], Field(description="Cost per completed view (100% completion)")
    ]
    currency: Annotated[
        str,
        Field(
            description="ISO 4217 currency code",
            examples=["USD", "EUR", "GBP", "JPY"],
            pattern="^[A-Z]{3}$",
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description="Fixed price per completed view. If present, this is fixed pricing. If absent, auction-based.",
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description="Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.",
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description="Optional pricing guidance for auction-based bidding"),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description="Minimum spend requirement per package using this pricing option, in the specified currency",
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description="Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present."
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description="Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['cpcv']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CpmPricingOption (**data: Any)

Expand source code

class CpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['cpm']
var pricing_option_id : str

class CpmAuctionPricingOption (**data: Any)

Expand source code

class CpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['cpm']
var pricing_option_id : str

class CpmFixedRatePricingOption (**data: Any)

Expand source code

class CpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['cpm']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CppPricingOption (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var min_spend_per_package : float | None
var model_config
var parameters : Parameters
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['cpp']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CpvPricingOption (**data: Any)

Expand source code

class CpvPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[Literal['cpv'], Field(description='Cost per view at threshold')]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per view. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    parameters: Annotated[
        Parameters, Field(description='CPV-specific parameters defining the view threshold')
    ]
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var parameters : Parameters
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['cpv']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateCollectionListRequest (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var base_collections : list[BaseCollectionSource] | None
var brand : BrandReference | None
var context : ContextObject | None
var description : str | None
var ext : ExtensionObject | None
var filters : CollectionListFilters | None
var idempotency_key : str
var model_config
var name : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateCollectionListResponse (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var auth_token : str
var context : ContextObject | None
var ext : ExtensionObject | None
var list : CollectionList
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateContentStandardsRequest (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var calibration_exemplars : CalibrationExemplars | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var policies : list[PolicyEntry] | None
var registry_policy_ids : list[str] | None
var scope : Scope

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateContentStandardsSuccessResponse (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 standards_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateContentStandardsErrorResponse (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var conflicting_standards_id : str | None
var context : ContextObject | None
var errors : list[Error]
var ext : ExtensionObject | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateMediaBuyRequest (**data: Any)

Expand source code

class CreateMediaBuyRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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(
            description='Campaign governance plan identifier. Required when the account has governance_agents. The seller includes this in the committed check_governance request so the governance agent can validate against the correct plan.'
        ),
    ] = 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 a proposal from get_products to execute. When provided with total_budget, the publisher converts the proposal's allocation percentages into packages automatically. Alternative to providing packages array."
        ),
    ] = None
    total_budget: Annotated[
        TotalBudget | None,
        Field(
            description="Total budget for the media buy when executing a proposal. The publisher applies the proposal's allocation percentages to this amount to derive package budgets."
        ),
    ] = None
    packages: Annotated[
        list[package_request.PackageRequest] | None,
        Field(
            description="Array of package configurations. Required when not using proposal_id. When executing a proposal, this can be omitted and packages will be derived from the proposal's allocations.",
            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
    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 Ad-IDs 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')
    ]
    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). The client generates an operation_id and embeds it in the URL before sending — the publisher echoes it back in webhook payloads for correlation.'
        ),
    ] = 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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
var advertiser_industry : AdvertiserIndustry | None
var agency_estimate_number : str | None
var artifact_webhook : ArtifactWebhook | None
var brand : BrandReference
var context : ContextObject | None
var end_time : pydantic.types.AwareDatetime
var ext : ExtensionObject | None
var idempotency_key : str
var invoice_recipient : BusinessEntity | None
var io_acceptance : IoAcceptance | None
var model_config
var packages : list[PackageRequest] | None
var plan_id : str | 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 : StartTiming
var total_budget : TotalBudget | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateMediaBuySuccessResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    media_buy_id: Annotated[
        str, Field(description="Seller's unique identifier for the created media buy")
    ]
    account: Annotated[
        account_1.Account | None,
        Field(
            description="Account billed for this media buy. Includes advertiser, billing proxy (if any), and rate card applied."
        ),
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description="Per-buy invoice recipient, echoed from the request when provided. Confirms the seller accepted the billing override. Bank details are omitted (write-only)."
        ),
    ] = None
    status: Annotated[
        media_buy_status.MediaBuyStatus | None,
        Field(
            description="Initial media buy status. Either 'pending_creatives' (awaiting creative assets), 'pending_start' (ready to serve, waiting for flight date), or 'active' (immediate activation)."
        ),
    ] = None
    confirmed_at: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp when this media buy was confirmed by the seller. A successful create_media_buy response constitutes order confirmation."
        ),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None, Field(description="ISO 8601 timestamp for creative upload deadline")
    ] = None
    revision: Annotated[
        int | None,
        Field(
            description="Initial revision number for this media buy. Use in subsequent update_media_buy requests for optimistic concurrency.",
            ge=1,
        ),
    ] = None
    valid_actions: Annotated[
        list[ValidAction] | None,
        Field(
            description="Actions the buyer can perform on this media buy after creation. Saves a round-trip to get_media_buys."
        ),
    ] = None
    packages: Annotated[
        list[package.Package],
        Field(description="Array of created packages with complete state information"),
    ]
    planned_delivery: Annotated[
        planned_delivery_1.PlannedDelivery | None,
        Field(
            description="The seller's interpreted delivery parameters. Describes what the seller will actually run -- geo, channels, flight dates, frequency caps, and budget. Present when the account has governance_agents or when the seller chooses to provide delivery transparency."
        ),
    ] = None
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : Account | None
var confirmed_at : pydantic.types.AwareDatetime | None
var context : ContextObject | None
var creative_deadline : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var invoice_recipient : BusinessEntity | None
var media_buy_id : str
var model_config
var packages : list[Package]
var planned_delivery : PlannedDelivery | None
var revision : int | None
var sandbox : bool | None
var status : MediaBuyStatus | None
var valid_actions : list[ValidAction] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreateMediaBuyErrorResponse (**data: Any)

Expand source code

class CreateMediaBuyResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    errors: Annotated[
        list[error.Error],
        Field(description="Array of errors explaining why the operation failed", min_length=1),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreatePropertyListRequest (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var base_properties : list[BasePropertySource] | None
var brand : BrandReference | None
var context : ContextObject | None
var description : str | None
var ext : ExtensionObject | None
var filters : PropertyListFilters | None
var idempotency_key : str
var model_config
var name : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreatePropertyListResponse (**data: Any)

Expand source code

class CreatePropertyListResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list: Annotated[property_list.PropertyList, Field(description='The created property list')]
    auth_token: Annotated[
        str,
        Field(
            description='Token that can be shared with sellers to authorize fetching this list. Store this - it is only returned at creation time.'
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var auth_token : str
var context : ContextObject | None
var ext : ExtensionObject | None
var list : PropertyList
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Creative (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Creative identifier')]
    media_buy_id: Annotated[
        str | None,
        Field(
            description="Publisher's media buy identifier for this creative. Present when the request spanned multiple media buys, so the buyer can correlate each creative to its media buy."
        ),
    ] = None
    format_id: Annotated[
        format_id_1.FormatId | None, Field(description='Format of this creative')
    ] = None
    totals: Annotated[
        delivery_metrics.DeliveryMetrics | None,
        Field(description='Aggregate delivery metrics across all variants of this creative'),
    ] = None
    variant_count: Annotated[
        int | None,
        Field(
            description='Total number of variants for this creative. When max_variants was specified in the request, this may exceed the number of items in the variants array.',
            ge=0,
        ),
    ] = None
    variants: Annotated[
        list[creative_variant.CreativeVariant],
        Field(
            description='Variant-level delivery breakdown. Each variant includes the rendered manifest and delivery metrics. For standard creatives, contains a single variant. For asset group optimization, one per combination. For generative creative, one per generated execution. Empty when a creative has no variants yet.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var creative_id : str
var format_id : FormatId | None
var media_buy_id : str | None
var model_config
var totals : DeliveryMetrics | None
var variant_count : int | None
var variants : list[CreativeVariant]

class SyncCreativeResult (**data: Any)

Expand source code

class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    creative_id: Annotated[str, Field(description="Creative ID from the request")]
    account: Annotated[
        account_1.Account | None, Field(description="Account that owns this creative")
    ] = None
    action: Annotated[
        creative_action.CreativeAction,
        Field(
            description="Action taken for this creative during this sync operation (lifecycle operation, not approval state)."
        ),
    ]
    status: Annotated[
        creative_status.CreativeStatus | None,
        Field(
            description="Advisory review-lifecycle state of the creative after this sync — a UI hint and polling-scheduling signal, NOT a spend-authorization gate. Orthogonal to action — action says what the sync did (created, updated, ...); status says where the creative sits in review. Values come from CreativeStatus only (processing, pending_review, approved, rejected, archived) — never from CreativeAction. Sellers with async review return processing or pending_review; sellers with synchronous review MAY return a terminal value (approved, rejected). Buyers MUST NOT gate downstream spend or package activation on status: approved from this response — a compromised or buggy seller could declare approved while bypassing content-policy review. Reconcile via list_creatives or a signed review webhook before committing spend. Authoritative state is always via list_creatives. MUST be omitted when action is failed or deleted (the creative has no meaningful review state — failure details belong in the errors array; deleted creatives are gone from the library). Omit entirely when the seller has no review lifecycle at all."
        ),
    ] = None
    platform_id: Annotated[
        str | None, Field(description="Platform-specific ID assigned to the creative")
    ] = None
    changes: Annotated[
        list[str] | None,
        Field(description="Field names that were modified (only present when action='updated')"),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(description="Validation or processing errors (only present when action='failed')"),
    ] = None
    warnings: Annotated[
        list[str] | None, Field(description="Non-fatal warnings about this creative")
    ] = None
    preview_url: Annotated[
        AnyUrl | None,
        Field(
            description="Preview URL for generative creatives (only present for generative formats)"
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp when preview link expires (only present when preview_url exists)"
        ),
    ] = None
    assigned_to: Annotated[
        list[str] | None,
        Field(
            description="Package IDs this creative was successfully assigned to (only present when assignments were requested)"
        ),
    ] = None
    assignment_errors: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r"^[a-zA-Z0-9_-]+$")], str] | None,
        Field(
            description="Assignment errors by package ID (only present when assignment failures occurred)"
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : Account | None
var action : CreativeAction
var assigned_to : list[str] | None
var assignment_errors : dict[str, str] | None
var changes : list[str] | None
var creative_id : str
var errors : list[Error] | None
var expires_at : pydantic.types.AwareDatetime | None
var model_config
var platform_id : str | None
var preview_url : pydantic.networks.AnyUrl | None
var status : CreativeStatus | None
var warnings : list[str] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativeAction (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var created
var deleted
var failed
var unchanged
var updated

class Action (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var created
var deleted
var failed
var unchanged
var updated

class CreativeAgent (**data: Any)

Expand source code

class CreativeAgent(AdCPBaseModel):
    agent_url: Annotated[
        AnyUrl,
        Field(
            description="Base URL for the creative agent (e.g., 'https://reference.adcp.org', 'https://dco.example.com'). Call list_creative_formats on this URL to get its formats."
        ),
    ]
    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.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agent_name : str | None
var agent_url : pydantic.networks.AnyUrl
var capabilities : list[CreativeAgentCapability] | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativeAgentCapability (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var assembly
var delivery
var generation
var preview
var validation

class Capability (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var assembly
var delivery
var generation
var preview
var validation

class CreativeApproval (**data: Any)

Expand source code

class CreativeApproval(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var approval_status : CreativeApprovalStatus
var creative_id : str
var model_config
var rejection_reason : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativeApprovalStatus (*args, **kwds)

Expand source code

class CreativeApprovalStatus(Enum):
    pending_review = 'pending_review'
    approved = 'approved'
    rejected = 'rejected'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var approved
var pending_review
var rejected

class CreativeAsset (**data: Any)

Expand source code

class CreativeAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    name: Annotated[str, Field(description='Human-readable creative name')]
    format_id: Annotated[
        format_id_1.FormatId,
        Field(
            description='Format identifier specifying which format this creative conforms to. Can be: (1) concrete format_id referencing a format with fixed dimensions, (2) template format_id referencing a template format, or (3) parameterized format_id with dimensions/duration parameters for template formats.'
        ),
    ]
    assets: Annotated[
        dict[
            Annotated[str, StringConstraints(pattern=r'^[a-z0-9_]+$')],
            image_asset.ImageAsset
            | video_asset.VideoAsset
            | audio_asset.AudioAsset
            | vast_asset.VastAsset
            | text_asset.TextAsset
            | url_asset.UrlAsset
            | html_asset.HtmlAsset
            | javascript_asset.JavascriptAsset
            | webhook_asset.WebhookAsset
            | css_asset.CssAsset
            | daast_asset.DaastAsset
            | markdown_asset.MarkdownAsset
            | brief_asset.BriefAsset
            | catalog_asset.CatalogAsset,
        ],
        Field(description='Assets required by the format, keyed by asset_id'),
    ]
    inputs: Annotated[
        list[Input] | None,
        Field(
            description='Preview contexts for generative formats - defines what scenarios to generate previews for'
        ),
    ] = None
    tags: Annotated[
        list[str] | None, Field(description='User-defined tags for organization and searchability')
    ] = None
    status: Annotated[
        creative_status.CreativeStatus | None,
        Field(
            description="For generative creatives: set to 'approved' to finalize, 'rejected' to request regeneration with updated assets/message. Omit for non-generative creatives (system will set based on processing state)."
        ),
    ] = None
    weight: Annotated[
        float | None,
        Field(
            description='Optional delivery weight for creative rotation when uploading via create_media_buy or update_media_buy (0-100). If omitted, platform determines rotation. Only used during upload to media buy - not stored in creative library.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description="Optional array of placement IDs where this creative should run when uploading via create_media_buy or update_media_buy. References placement_id values from the product's placements array. If omitted, creative runs on all placements. Only used during upload to media buy - not stored in creative library.",
            min_length=1,
        ),
    ] = None
    industry_identifiers: Annotated[
        list[industry_identifier.IndustryIdentifier] | None,
        Field(
            description='Industry-standard identifiers for this creative (e.g., Ad-ID, ISCI, Clearcast clock number). In broadcast buying, these identifiers tie the creative to rotation instructions and traffic systems. A creative may have multiple identifiers when different systems reference the same asset.'
        ),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this creative. Serves as the default provenance for all manifests and assets within this creative. A manifest or asset with its own provenance replaces this object entirely (no field-level merging).'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var assets : dict[str, ImageAsset | VideoAsset | AudioAsset | VastAsset | TextAsset | UrlAsset | HtmlAsset | JavascriptAsset | WebhookAsset | CssAsset | DaastAsset | MarkdownAsset | BriefAsset | CatalogAsset]
var creative_id : str
var format_id : FormatId
var industry_identifiers : list[IndustryIdentifier] | None
var inputs : list[Input] | None
var model_config
var name : str
var placement_ids : list[str] | None
var provenance : Provenance | None
var status : CreativeStatus | None
var tags : list[str] | None
var weight : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativeAssignment (**data: Any)

Expand source code

class CreativeAssignment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    weight: Annotated[
        float | None,
        Field(
            description='Relative delivery weight for this creative (0–100). When multiple creatives are assigned to the same package, weights determine impression distribution proportionally — a creative with weight 2 gets twice the delivery of weight 1. When omitted, the creative receives equal rotation with other unweighted creatives. A weight of 0 means the creative is assigned but paused (receives no delivery).',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    placement_ids: Annotated[
        list[str] | None,
        Field(
            description="Optional array of placement IDs where this creative should run. When omitted, the creative runs on all placements in the package. References placement_id values from the product's placements array.",
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var creative_id : str
var model_config
var placement_ids : list[str] | None
var weight : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativeFilters (**data: Any)

Expand source code

class CreativeFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    accounts: Annotated[
        list[account_ref.AccountReference] | None,
        Field(
            description='Filter creatives by owning accounts. Useful for agencies managing multiple client accounts.',
            min_length=1,
        ),
    ] = None
    statuses: Annotated[
        list[creative_status.CreativeStatus] | None,
        Field(description='Filter by creative approval statuses', min_length=1),
    ] = None
    tags: Annotated[
        list[str] | None,
        Field(description='Filter by creative tags (all tags must match)', min_length=1),
    ] = None
    tags_any: Annotated[
        list[str] | None,
        Field(description='Filter by creative tags (any tag must match)', min_length=1),
    ] = None
    name_contains: Annotated[
        str | None,
        Field(description='Filter by creative names containing this text (case-insensitive)'),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(description='Filter by specific creative IDs', max_length=100, min_length=1),
    ] = None
    created_after: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives created after this date (ISO 8601)'),
    ] = None
    created_before: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives created before this date (ISO 8601)'),
    ] = None
    updated_after: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives last updated after this date (ISO 8601)'),
    ] = None
    updated_before: Annotated[
        AwareDatetime | None,
        Field(description='Filter creatives last updated before this date (ISO 8601)'),
    ] = None
    assigned_to_packages: Annotated[
        list[str] | None,
        Field(
            description='Filter creatives assigned to any of these packages. Sales-agent-specific — standalone creative agents SHOULD ignore this filter.',
            min_length=1,
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter creatives assigned to any of these media buys. Sales-agent-specific — standalone creative agents SHOULD ignore this filter.',
            min_length=1,
        ),
    ] = None
    unassigned: Annotated[
        bool | None,
        Field(
            description='Filter for unassigned creatives when true, assigned creatives when false. Sales-agent-specific — standalone creative agents SHOULD ignore this filter.'
        ),
    ] = None
    has_served: Annotated[
        bool | None,
        Field(
            description='When true, return only creatives that have served at least one impression. When false, return only creatives that have never served.'
        ),
    ] = None
    concept_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter by creative concept IDs. Concepts group related creatives across sizes and formats (e.g., Flashtalking concepts, Celtra campaign folders, CM360 creative groups).',
            min_length=1,
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Filter by structured format IDs. Returns creatives that match any of these formats.',
            min_length=1,
        ),
    ] = None
    has_variables: Annotated[
        bool | None,
        Field(
            description='When true, return only creatives with dynamic variables (DCO). When false, return only static creatives.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accounts : list[AccountReference] | None
var assigned_to_packages : list[str] | None
var concept_ids : list[str] | None
var created_after : pydantic.types.AwareDatetime | None
var created_before : pydantic.types.AwareDatetime | None
var creative_ids : list[str] | None
var format_ids : list[FormatId] | None
var has_served : bool | None
var has_variables : bool | None
var media_buy_ids : list[str] | None
var model_config
var name_contains : str | None
var statuses : list[CreativeStatus] | None
var tags : list[str] | None
var tags_any : list[str] | None
var unassigned : bool | None
var updated_after : pydantic.types.AwareDatetime | None
var updated_before : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativeManifest (**data: Any)

Expand source code

class CreativeManifest(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    format_id: Annotated[
        format_id_1.FormatId,
        Field(
            description="Format identifier this manifest is for. Can be a template format (id only) or a deterministic format (id + dimensions/duration). For dimension-specific creatives, include width/height/unit in the format_id to create a unique identifier (e.g., {id: 'display_static', width: 300, height: 250, unit: 'px'})."
        ),
    ]
    assets: Annotated[
        dict[
            Annotated[str, StringConstraints(pattern=r"^[a-z0-9_]+$")],
            image_asset.ImageAsset
            | video_asset.VideoAsset
            | audio_asset.AudioAsset
            | vast_asset.VastAsset
            | text_asset.TextAsset
            | url_asset.UrlAsset
            | html_asset.HtmlAsset
            | javascript_asset.JavascriptAsset
            | webhook_asset.WebhookAsset
            | css_asset.CssAsset
            | daast_asset.DaastAsset
            | markdown_asset.MarkdownAsset
            | brief_asset.BriefAsset
            | catalog_asset.CatalogAsset,
        ],
        Field(
            description="Map of asset IDs to actual asset content. Each key MUST match an asset_id from the format's assets array (e.g., 'banner_image', 'clickthrough_url', 'video_file', 'vast_tag'). The asset_id is the technical identifier used to match assets to format requirements.\n\nIMPORTANT: Full validation requires format context. The format defines what type each asset_id should be. Standalone schema validation only checks structural conformance — each asset must match at least one valid asset type schema."
        ),
    ]
    rights: Annotated[
        list[rights_constraint.RightsConstraint] | None,
        Field(
            description="Rights constraints attached to this creative. Each entry represents constraints from a single rights holder. A creative may combine multiple rights constraints (e.g., talent likeness + music license). For v1, rights constraints are informational metadata — the buyer/orchestrator manages creative lifecycle against these terms."
        ),
    ] = None
    industry_identifiers: Annotated[
        list[industry_identifier.IndustryIdentifier] | None,
        Field(
            description="Industry-standard identifiers for this specific manifest (e.g., Ad-ID, ISCI, Clearcast clock number). When present, overrides creative-level identifiers. Use when different format versions of the same source creative have distinct Ad-IDs (e.g., the :15 and :30 cuts)."
        ),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description="Provenance metadata for this creative manifest. Serves as the default provenance for all assets in this manifest. An asset with its own provenance replaces this object entirely (no field-level merging)."
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var assets : dict[str, ImageAsset | VideoAsset | AudioAsset | VastAsset | TextAsset | UrlAsset | HtmlAsset | JavascriptAsset | WebhookAsset | CssAsset | DaastAsset | MarkdownAsset | BriefAsset | CatalogAsset]
var ext : ExtensionObject | None
var format_id : FormatId
var industry_identifiers : list[IndustryIdentifier] | None
var model_config
var provenance : Provenance | None
var rights : list[RightsConstraint] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativePolicy (**data: Any)

Expand source code

class CreativePolicy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    co_branding: Annotated[
        co_branding_requirement.CoBrandingRequirement, Field(description='Co-branding requirement')
    ]
    landing_page: Annotated[
        landing_page_requirement.LandingPageRequirement,
        Field(description='Landing page requirements'),
    ]
    templates_available: Annotated[
        bool, Field(description='Whether creative templates are provided')
    ]
    provenance_required: Annotated[
        bool | None,
        Field(
            description='Whether creatives must include provenance metadata. When true, the seller requires buyers to attach provenance declarations to creative submissions. The seller may independently verify claims via get_creative_features.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var co_branding : CoBrandingRequirement
var landing_page : LandingPageRequirement
var model_config
var provenance_required : bool | None
var templates_available : bool

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class CreativeStatus (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var approved
var archived
var pending_review
var processing
var rejected

class CreativeVariant (**data: Any)

Expand source code

class CreativeVariant(DeliveryMetrics):
    variant_id: Annotated[str, Field(description='Platform-assigned identifier for this variant')]
    manifest: Annotated[
        creative_manifest.CreativeManifest | None,
        Field(
            description='The rendered creative manifest for this variant — the actual output that was served, not the input assets. Contains format_id and the resolved assets (specific headline, image, video, etc. the platform selected or generated). For Tier 2, shows which asset combination was picked. For Tier 3, contains the generated assets which may differ entirely from the input brand identity. Pass to preview_creative to re-render.'
        ),
    ] = None
    generation_context: Annotated[
        GenerationContext | None,
        Field(
            description='Input signals that triggered generation of this variant (Tier 3). Describes why the platform created this specific variant. Platforms should provide summarized or anonymized signals rather than raw user input. For web contexts, may include page topic or URL. For conversational contexts, an anonymized content signal. For search, query category or intent. When the content context is managed through AdCP content standards, reference the artifact directly via the artifact field.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 generation_context : GenerationContext | None
var manifest : CreativeManifest | None
var model_config
var variant_id : str

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class CssAsset (**data: Any)

Expand source code

class CssAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    content: Annotated[str, Field(description='CSS content')]
    media: Annotated[
        str | None, Field(description="CSS media query context (e.g., 'screen', 'print')")
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 : str
var media : str | None
var model_config
var provenance : Provenance | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UrlDaastAsset (**data: Any)

Expand source code

class DaastAsset1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    delivery_type: Annotated[
        Literal['url'],
        Field(description='Discriminator indicating DAAST is delivered via URL endpoint'),
    ]
    url: Annotated[AnyUrl, Field(description='URL endpoint that returns DAAST XML')]
    daast_version: Annotated[
        daast_version_1.DaastVersion | None, Field(description='DAAST specification version')
    ] = None
    duration_ms: Annotated[
        int | None, Field(description='Expected audio duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[daast_tracking_event.DaastTrackingEvent] | None,
        Field(description='Tracking events supported by this DAAST tag'),
    ] = None
    companion_ads: Annotated[
        bool | None, Field(description='Whether companion display ads are included')
    ] = None
    transcript_url: Annotated[
        AnyUrl | None, Field(description='URL to text transcript of the audio content')
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var companion_ads : bool | None
var daast_version : DaastVersion | None
var delivery_type : Literal['url']
var duration_ms : int | None
var model_config
var provenance : Provenance | None
var tracking_events : list[DaastTrackingEvent] | None
var transcript_url : pydantic.networks.AnyUrl | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class InlineDaastAsset (**data: Any)

Expand source code

class DaastAsset2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    delivery_type: Annotated[
        Literal['inline'],
        Field(description='Discriminator indicating DAAST is delivered as inline XML content'),
    ]
    content: Annotated[str, Field(description='Inline DAAST XML content')]
    daast_version: Annotated[
        daast_version_1.DaastVersion | None, Field(description='DAAST specification version')
    ] = None
    duration_ms: Annotated[
        int | None, Field(description='Expected audio duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[daast_tracking_event.DaastTrackingEvent] | None,
        Field(description='Tracking events supported by this DAAST tag'),
    ] = None
    companion_ads: Annotated[
        bool | None, Field(description='Whether companion display ads are included')
    ] = None
    transcript_url: Annotated[
        AnyUrl | None, Field(description='URL to text transcript of the audio content')
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var companion_ads : bool | None
var content : str
var daast_version : DaastVersion | None
var delivery_type : Literal['inline']
var duration_ms : int | None
var model_config
var provenance : Provenance | None
var tracking_events : list[DaastTrackingEvent] | None
var transcript_url : pydantic.networks.AnyUrl | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DaastTrackingEvent (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var clickTracking
var close
var complete
var creativeView
var customClick
var error
var firstQuartile
var impression
var loaded
var measurableImpression
var midpoint
var mute
var notViewable
var pause
var progress
var resume
var skip
var start
var thirdQuartile
var unmute
var viewUndetermined
var viewable
var viewableImpression

class DaastVersion (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var field_1_0
var field_1_1

class DailyBreakdownItem (**data: Any)

Expand source code

class DailyBreakdownItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    date: Annotated[str, Field(description='Date (YYYY-MM-DD)', pattern='^\\d{4}-\\d{2}-\\d{2}$')]
    impressions: Annotated[float, Field(description='Daily impressions for this package', ge=0.0)]
    spend: Annotated[float, Field(description='Daily spend for this package', ge=0.0)]
    conversions: Annotated[
        float | None, Field(description='Daily conversions for this package', ge=0.0)
    ] = None
    conversion_value: Annotated[
        float | None, Field(description='Daily conversion value for this package', ge=0.0)
    ] = None
    roas: Annotated[
        float | None,
        Field(description='Daily return on ad spend (conversion_value / spend)', ge=0.0),
    ] = None
    new_to_brand_rate: Annotated[
        float | 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.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var conversion_value : float | None
var conversions : float | None
var date : str
var impressions : float
var model_config
var new_to_brand_rate : float | None
var roas : float | None
var spend : float

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DateRange (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var end : datetime.date
var model_config
var start : datetime.date

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DatetimeRange (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var end : pydantic.types.AwareDatetime
var model_config
var start : pydantic.types.AwareDatetime

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DayOfWeek (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var friday
var monday
var saturday
var sunday
var thursday
var tuesday
var wednesday

class DaypartTarget (**data: Any)

Expand source code

class DaypartTarget(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    days: Annotated[
        list[day_of_week.DayOfWeek],
        Field(
            description='Days of week this window applies to. Use multiple days for compact targeting (e.g., monday-friday in one object).',
            min_length=1,
        ),
    ]
    start_hour: Annotated[
        int,
        Field(
            description='Start hour (inclusive), 0-23 in 24-hour format. 0 = midnight, 6 = 6:00am, 18 = 6:00pm.',
            ge=0,
            le=23,
        ),
    ]
    end_hour: Annotated[
        int,
        Field(
            description='End hour (exclusive), 1-24 in 24-hour format. 10 = 10:00am, 24 = midnight. Must be greater than start_hour.',
            ge=1,
            le=24,
        ),
    ]
    label: Annotated[
        str | None,
        Field(
            description="Optional human-readable name for this time window (e.g., 'Morning Drive', 'Prime Time')"
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var days : list[DayOfWeek]
var end_hour : int
var label : str | None
var model_config
var start_hour : int

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeleteCollectionListRequest (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var list_id : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeleteCollectionListResponse (**data: Any)

Expand source code

class DeleteCollectionListResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    deleted: Annotated[bool, Field(description='Whether the list was successfully deleted')]
    list_id: Annotated[str, Field(description='ID of the deleted list')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 deleted : bool
var ext : ExtensionObject | None
var list_id : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeletePropertyListRequest (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var list_id : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeletePropertyListResponse (**data: Any)

Expand source code

class DeletePropertyListResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    deleted: Annotated[bool, Field(description='Whether the list was successfully deleted')]
    list_id: Annotated[str, Field(description='ID of the deleted list')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 deleted : bool
var ext : ExtensionObject | None
var list_id : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeliveryForecast (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var demographic : str | None
var demographic_system : DemographicSystem | None
var ext : ExtensionObject | None
var forecast_range_unit : ForecastRangeUnit | None
var generated_at : pydantic.types.AwareDatetime | None
var measurement_source : str | None
var method : ForecastMethod
var model_config
var points : list[ForecastPoint]
var reach_unit : ReachUnit | None
var valid_until : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeliveryMeasurement (**data: Any)

Expand source code

class DeliveryMeasurement(AdCPBaseModel):
    provider: Annotated[
        str,
        Field(
            description="Measurement provider(s) used for this product (e.g., 'Google Ad Manager with IAS viewability', 'Nielsen DAR', 'Geopath for DOOH impressions')"
        ),
    ]
    notes: Annotated[
        str | None,
        Field(
            description="Additional details about measurement methodology in plain language (e.g., 'MRC-accredited viewability. 50% in-view for 1s display / 2s video', 'Panel-based demographic measurement updated monthly')"
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var notes : str | None
var provider : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeliveryMetrics (**data: Any)

Expand source code

class DeliveryMetrics(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    impressions: Annotated[float | None, Field(description='Impressions delivered', ge=0.0)] = None
    spend: Annotated[float | None, Field(description='Amount spent', ge=0.0)] = None
    clicks: Annotated[float | None, Field(description='Total clicks', ge=0.0)] = None
    ctr: Annotated[
        float | None, Field(description='Click-through rate (clicks/impressions)', ge=0.0, le=1.0)
    ] = None
    views: Annotated[
        float | None,
        Field(
            description="Content engagements counted toward the billable view threshold. For video this is a platform-defined view event (e.g., 30 seconds or video midpoint); for audio/podcast it is a stream start; for other formats it follows the pricing model's view definition. When the package uses CPV pricing, spend = views × rate.",
            ge=0.0,
        ),
    ] = None
    completed_views: Annotated[
        float | None,
        Field(
            description='Video/audio completions. When the package has a completed_views optimization goal with view_duration_seconds, completions are counted at that threshold rather than 100% completion.',
            ge=0.0,
        ),
    ] = None
    completion_rate: Annotated[
        float | None,
        Field(description='Completion rate (completed_views/impressions)', ge=0.0, le=1.0),
    ] = None
    conversions: Annotated[
        float | None,
        Field(
            description='Total conversions attributed to this delivery. When by_event_type is present, this equals the sum of all by_event_type[].count entries.',
            ge=0.0,
        ),
    ] = None
    conversion_value: Annotated[
        float | None,
        Field(
            description='Total monetary value of attributed conversions (in the reporting currency)',
            ge=0.0,
        ),
    ] = None
    roas: Annotated[
        float | None, Field(description='Return on ad spend (conversion_value / spend)', ge=0.0)
    ] = None
    cost_per_acquisition: Annotated[
        float | None, Field(description='Cost per conversion (spend / conversions)', ge=0.0)
    ] = None
    new_to_brand_rate: Annotated[
        float | None,
        Field(
            description='Fraction of conversions from first-time brand buyers (0 = none, 1 = all)',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    leads: Annotated[
        float | None,
        Field(
            description="Leads generated (convenience alias for by_event_type where event_type='lead')",
            ge=0.0,
        ),
    ] = None
    by_event_type: Annotated[
        list[ByEventTypeItem] | None,
        Field(
            description='Conversion metrics broken down by event type. Spend-derived metrics (ROAS, CPA) are only available at the package/totals level since spend cannot be attributed to individual event types.'
        ),
    ] = None
    grps: Annotated[
        float | None, Field(description='Gross Rating Points delivered (for CPP)', ge=0.0)
    ] = None
    reach: Annotated[
        float | None,
        Field(
            description='Unique reach in the units specified by reach_unit. When reach_unit is omitted, units are unspecified — do not compare reach values across packages or media buys without a common reach_unit.',
            ge=0.0,
        ),
    ] = None
    reach_unit: Annotated[
        reach_unit_1.ReachUnit | None,
        Field(
            description='Unit of measurement for the reach field. Aligns with the reach_unit declared on optimization goals and delivery forecasts. Required when reach is present to enable cross-platform comparison.'
        ),
    ] = None
    frequency: Annotated[
        float | None,
        Field(
            description="Average frequency per reach unit (typically measured over campaign duration, but can vary by measurement provider). When reach_unit is 'households', this is average exposures per household; when 'accounts', per logged-in account; etc.",
            ge=0.0,
        ),
    ] = None
    quartile_data: Annotated[
        QuartileData | None, Field(description='Audio/video quartile completion data')
    ] = None
    dooh_metrics: Annotated[
        DoohMetrics | None,
        Field(description='DOOH-specific metrics (only included for DOOH campaigns)'),
    ] = None
    viewability: Annotated[
        Viewability | None,
        Field(
            description='Viewability metrics. Viewable rate should be calculated as viewable_impressions / measurable_impressions (not total impressions), since some environments cannot measure viewability.'
        ),
    ] = None
    engagements: Annotated[
        float | None,
        Field(
            description="Total engagements — direct interactions with the ad beyond viewing. Includes social reactions/comments/shares, story/unit opens, interactive overlay taps on CTV, companion banner interactions on audio. Platform-specific; corresponds to the 'engagements' optimization metric.",
            ge=0.0,
        ),
    ] = None
    follows: Annotated[
        float | None,
        Field(
            description='New followers, page likes, artist/podcast/channel subscribes attributed to this delivery.',
            ge=0.0,
        ),
    ] = None
    saves: Annotated[
        float | None,
        Field(
            description='Saves, bookmarks, playlist adds, pins attributed to this delivery.', ge=0.0
        ),
    ] = None
    profile_visits: Annotated[
        float | None,
        Field(
            description="Visits to the brand's in-platform page (profile, artist page, channel, or storefront) attributed to this delivery. Does not include external website clicks.",
            ge=0.0,
        ),
    ] = None
    engagement_rate: Annotated[
        float | None,
        Field(
            description='Platform-specific engagement rate (0.0 to 1.0). Typically engagements/impressions, but definition varies by platform.',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    cost_per_click: Annotated[
        float | None, Field(description='Cost per click (spend / clicks)', ge=0.0)
    ] = None
    by_action_source: Annotated[
        list[ByActionSourceItem] | None,
        Field(
            description='Conversion metrics broken down by action source (website, app, in_store, etc.). Useful for omnichannel sellers where conversions occur across digital and physical channels.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot 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 by_action_source : list[ByActionSourceItem] | None
var by_event_type : list[ByEventTypeItem] | None
var clicks : 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 cost_per_click : float | None
var ctr : float | None
var dooh_metrics : DoohMetrics | None
var engagement_rate : float | None
var engagements : float | None
var follows : float | None
var frequency : float | None
var grps : float | None
var impressions : float | None
var leads : float | None
var model_config
var new_to_brand_rate : float | None
var profile_visits : float | None
var quartile_data : QuartileData | None
var reach : float | None
var reach_unit : ReachUnit | None
var roas : float | None
var saves : float | None
var spend : float | None
var viewability : Viewability | None
var views : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DeliveryStatus (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var budget_exhausted
var completed
var delivering
var flight_ended
var goal_met
var not_delivering

class DeliveryType (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var guaranteed
var non_guaranteed

class DemographicSystem (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var agf
var barb
var custom
var mediametrie
var nielsen
var oztam

class PlatformDeployment (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : str | None
var activation_key : ActivationKey | None
var deployed_at : pydantic.types.AwareDatetime | None
var estimated_activation_duration_minutes : float | None
var is_live : bool
var model_config
var platform : str
var type : Literal['platform']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AgentDeployment (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : str | None
var activation_key : ActivationKey | None
var agent_url : pydantic.networks.AnyUrl
var deployed_at : pydantic.types.AwareDatetime | None
var estimated_activation_duration_minutes : float | None
var is_live : bool
var model_config
var type : Literal['agent']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PlatformDestination (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : str | None
var model_config
var platform : str
var type : Literal['platform']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class AgentDestination (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : str | None
var agent_url : pydantic.networks.AnyUrl
var model_config
var type : Literal['agent']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DevicePlatform (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var android
var chromeos
var fire_os
var ios
var linux
var macos
var roku_os
var tizen
var tvos
var unknown
var webos
var windows

class DeviceType (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var ctv
var desktop
var dooh
var mobile
var tablet
var unknown

class DimensionUnit (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var cm
var dp
var inches
var mm
var pt
var px

class Unit (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var cm
var dp
var inches
var mm
var pt
var px

class Disclaimer (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : str | None
var model_config
var required : bool | None
var text : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class DoohMetrics (**data: Any)

Expand source code

class DoohMetrics(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    loop_plays: Annotated[
        int | None, Field(description='Number of times ad played in rotation', ge=0)
    ] = None
    screens_used: Annotated[
        int | None, Field(description='Number of unique screens displaying the ad', ge=0)
    ] = None
    screen_time_seconds: Annotated[
        int | None, Field(description='Total display time in seconds', ge=0)
    ] = None
    sov_achieved: Annotated[
        float | None,
        Field(description='Actual share of voice delivered (0.0 to 1.0)', ge=0.0, le=1.0),
    ] = None
    calculation_notes: Annotated[
        str | None, Field(description='Explanation of how DOOH impressions were calculated')
    ] = None
    venue_breakdown: Annotated[
        list[VenueBreakdownItem] | None, Field(description='Per-venue performance breakdown')
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var calculation_notes : str | None
var loop_plays : int | None
var model_config
var screen_time_seconds : int | None
var screens_used : int | None
var sov_achieved : float | None
var venue_breakdown : list[VenueBreakdownItem] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Duration (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var interval : int
var model_config
var unit : Unit

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Error (**data: Any)

Expand source code

class Error(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    code: Annotated[
        str,
        Field(
            description='Error code for programmatic handling. Standard codes are defined in error-code.json and enable autonomous agent recovery. Sellers MAY use codes not in the standard vocabulary for platform-specific errors; agents MUST handle unknown codes gracefully by falling back to the recovery classification.',
            max_length=64,
            min_length=1,
        ),
    ]
    message: Annotated[str, Field(description='Human-readable error message')]
    field: Annotated[
        str | None,
        Field(description="Field path associated with the error (e.g., 'packages[0].targeting')"),
    ] = None
    suggestion: Annotated[str | None, Field(description='Suggested fix for the error')] = None
    retry_after: Annotated[
        float | None,
        Field(
            description='Seconds to wait before retrying the operation. Sellers MUST return values between 1 and 3600. Clients MUST clamp values outside this range.',
            ge=1.0,
            le=3600.0,
        ),
    ] = None
    details: Annotated[
        dict[str, Any] | None, Field(description='Additional task-specific error details')
    ] = None
    recovery: Annotated[
        Recovery | None,
        Field(
            description='Agent recovery classification. transient: retry after delay (rate limit, service unavailable, timeout). correctable: fix the request and resend (invalid field, budget too low, creative rejected). terminal: requires human action (account suspended, payment required, account not found).'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var code : str
var details : dict[str, typing.Any] | None
var field : str | None
var message : str
var model_config
var recovery : Recovery | None
var retry_after : float | None
var suggestion : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ErrorCode (*args, **kwds)

Expand source code

class ErrorCode(Enum):
    INVALID_REQUEST = "INVALID_REQUEST"
    AUTH_REQUIRED = "AUTH_REQUIRED"
    RATE_LIMITED = "RATE_LIMITED"
    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
    POLICY_VIOLATION = "POLICY_VIOLATION"
    PRODUCT_NOT_FOUND = "PRODUCT_NOT_FOUND"
    PRODUCT_UNAVAILABLE = "PRODUCT_UNAVAILABLE"
    PROPOSAL_EXPIRED = "PROPOSAL_EXPIRED"
    BUDGET_TOO_LOW = "BUDGET_TOO_LOW"
    CREATIVE_REJECTED = "CREATIVE_REJECTED"
    UNSUPPORTED_FEATURE = "UNSUPPORTED_FEATURE"
    AUDIENCE_TOO_SMALL = "AUDIENCE_TOO_SMALL"
    ACCOUNT_NOT_FOUND = "ACCOUNT_NOT_FOUND"
    ACCOUNT_SETUP_REQUIRED = "ACCOUNT_SETUP_REQUIRED"
    ACCOUNT_AMBIGUOUS = "ACCOUNT_AMBIGUOUS"
    ACCOUNT_PAYMENT_REQUIRED = "ACCOUNT_PAYMENT_REQUIRED"
    ACCOUNT_SUSPENDED = "ACCOUNT_SUSPENDED"
    COMPLIANCE_UNSATISFIED = "COMPLIANCE_UNSATISFIED"
    GOVERNANCE_DENIED = "GOVERNANCE_DENIED"
    BUDGET_EXHAUSTED = "BUDGET_EXHAUSTED"
    BUDGET_EXCEEDED = "BUDGET_EXCEEDED"
    CONFLICT = "CONFLICT"
    IDEMPOTENCY_CONFLICT = "IDEMPOTENCY_CONFLICT"
    IDEMPOTENCY_EXPIRED = "IDEMPOTENCY_EXPIRED"
    CREATIVE_DEADLINE_EXCEEDED = "CREATIVE_DEADLINE_EXCEEDED"
    INVALID_STATE = "INVALID_STATE"
    MEDIA_BUY_NOT_FOUND = "MEDIA_BUY_NOT_FOUND"
    NOT_CANCELLABLE = "NOT_CANCELLABLE"
    PACKAGE_NOT_FOUND = "PACKAGE_NOT_FOUND"
    CREATIVE_NOT_FOUND = "CREATIVE_NOT_FOUND"
    SIGNAL_NOT_FOUND = "SIGNAL_NOT_FOUND"
    SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
    SESSION_TERMINATED = "SESSION_TERMINATED"
    VALIDATION_ERROR = "VALIDATION_ERROR"
    PRODUCT_EXPIRED = "PRODUCT_EXPIRED"
    PROPOSAL_NOT_COMMITTED = "PROPOSAL_NOT_COMMITTED"
    IO_REQUIRED = "IO_REQUIRED"
    TERMS_REJECTED = "TERMS_REJECTED"
    VERSION_UNSUPPORTED = "VERSION_UNSUPPORTED"

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var ACCOUNT_AMBIGUOUS
var ACCOUNT_NOT_FOUND
var ACCOUNT_PAYMENT_REQUIRED
var ACCOUNT_SETUP_REQUIRED
var ACCOUNT_SUSPENDED
var AUDIENCE_TOO_SMALL
var AUTH_REQUIRED
var BUDGET_EXCEEDED
var BUDGET_EXHAUSTED
var BUDGET_TOO_LOW
var COMPLIANCE_UNSATISFIED
var CONFLICT
var CREATIVE_DEADLINE_EXCEEDED
var CREATIVE_NOT_FOUND
var CREATIVE_REJECTED
var GOVERNANCE_DENIED
var IDEMPOTENCY_CONFLICT
var IDEMPOTENCY_EXPIRED
var INVALID_REQUEST
var INVALID_STATE
var IO_REQUIRED
var MEDIA_BUY_NOT_FOUND
var NOT_CANCELLABLE
var PACKAGE_NOT_FOUND
var POLICY_VIOLATION
var PRODUCT_EXPIRED
var PRODUCT_NOT_FOUND
var PRODUCT_UNAVAILABLE
var PROPOSAL_EXPIRED
var PROPOSAL_NOT_COMMITTED
var RATE_LIMITED
var SERVICE_UNAVAILABLE
var SESSION_NOT_FOUND
var SESSION_TERMINATED
var SIGNAL_NOT_FOUND
var TERMS_REJECTED
var UNSUPPORTED_FEATURE
var VALIDATION_ERROR
var VERSION_UNSUPPORTED

class EventType (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var add_payment_info
var add_to_cart
var add_to_wishlist
var app_install
var app_launch
var close_convert_lead
var complete_registration
var contact
var custom
var disqualify_lead
var donate
var initiate_checkout
var lead
var page_view
var purchase
var qualify_lead
var refund
var remove_from_cart
var schedule
var search
var select_content
var select_item
var share
var start_trial
var submit_application
var subscribe
var view_content
var viewed_cart

class ExtensionObject (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 FeedFormat (*args, **kwds)

Expand source code

class FeedFormat(Enum):
    google_merchant_center = 'google_merchant_center'
    facebook_catalog = 'facebook_catalog'
    shopify = 'shopify'
    linkedin_jobs = 'linkedin_jobs'
    custom = 'custom'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var custom
var facebook_catalog
var google_merchant_center
var linkedin_jobs
var shopify

class FeedbackSource (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var buyer_attribution
var platform_analytics
var third_party_measurement
var verification_partner

class ListCreativesField (*args, **kwds)

Expand source code

class Field1(Enum):
    created_at = 'created_at'
    updated_at = 'updated_at'
    status = 'status'
    task_type = 'task_type'
    protocol = 'protocol'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var created_at
var protocol
var status
var task_type
var updated_at

class GetProductsField (*args, **kwds)

Expand source code

class Field1(Enum):
    product_id = 'product_id'
    name = 'name'
    description = 'description'
    publisher_properties = 'publisher_properties'
    channels = 'channels'
    format_ids = 'format_ids'
    placements = 'placements'
    delivery_type = 'delivery_type'
    exclusivity = 'exclusivity'
    pricing_options = 'pricing_options'
    forecast = 'forecast'
    outcome_measurement = 'outcome_measurement'
    delivery_measurement = 'delivery_measurement'
    reporting_capabilities = 'reporting_capabilities'
    creative_policy = 'creative_policy'
    catalog_types = 'catalog_types'
    metric_optimization = 'metric_optimization'
    conversion_tracking = 'conversion_tracking'
    data_provider_signals = 'data_provider_signals'
    max_optimization_goals = 'max_optimization_goals'
    catalog_match = 'catalog_match'
    collections = 'collections'
    collection_targeting_allowed = 'collection_targeting_allowed'
    installments = 'installments'
    brief_relevance = 'brief_relevance'
    expires_at = 'expires_at'
    product_card = 'product_card'
    product_card_detailed = 'product_card_detailed'
    enforced_policies = 'enforced_policies'
    trusted_match = 'trusted_match'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var 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 description
var enforced_policies
var exclusivity
var expires_at
var forecast
var format_ids
var installments
var max_optimization_goals
var metric_optimization
var name
var outcome_measurement
var placements
var pricing_options
var product_card
var product_card_detailed
var product_id
var publisher_properties
var reporting_capabilities
var trusted_match

class FieldModel (*args, **kwds)

Expand source code

class Field1(Enum):
    product_id = 'product_id'
    name = 'name'
    description = 'description'
    publisher_properties = 'publisher_properties'
    channels = 'channels'
    format_ids = 'format_ids'
    placements = 'placements'
    delivery_type = 'delivery_type'
    exclusivity = 'exclusivity'
    pricing_options = 'pricing_options'
    forecast = 'forecast'
    outcome_measurement = 'outcome_measurement'
    delivery_measurement = 'delivery_measurement'
    reporting_capabilities = 'reporting_capabilities'
    creative_policy = 'creative_policy'
    catalog_types = 'catalog_types'
    metric_optimization = 'metric_optimization'
    conversion_tracking = 'conversion_tracking'
    data_provider_signals = 'data_provider_signals'
    max_optimization_goals = 'max_optimization_goals'
    catalog_match = 'catalog_match'
    collections = 'collections'
    collection_targeting_allowed = 'collection_targeting_allowed'
    installments = 'installments'
    brief_relevance = 'brief_relevance'
    expires_at = 'expires_at'
    product_card = 'product_card'
    product_card_detailed = 'product_card_detailed'
    enforced_policies = 'enforced_policies'
    trusted_match = 'trusted_match'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var 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 description
var enforced_policies
var exclusivity
var expires_at
var forecast
var format_ids
var installments
var max_optimization_goals
var metric_optimization
var name
var outcome_measurement
var placements
var pricing_options
var product_card
var product_card_detailed
var product_id
var publisher_properties
var reporting_capabilities
var trusted_match

class GetBrandIdentityField (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var assets
var colors
var description
var fonts
var industries
var keller_type
var logos
var rights
var tagline
var tone
var visual_guidelines
var voice_synthesis

class FlatRatePricingOption (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var min_spend_per_package : float | None
var model_config
var parameters : Parameters | None
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['flat_rate']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Fonts (**data: Any)

Expand source code

class Fonts(AdCPBaseModel):
    primary: Annotated[FontRole | None, Field(description='Primary font family')] = None
    secondary: Annotated[FontRole | None, Field(description='Secondary font family')] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var primary : FontRole | None
var secondary : FontRole | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ForecastMethod (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var estimate
var guaranteed
var modeled

class ForecastPoint (**data: Any)

Expand source code

class ForecastPoint(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    label: Annotated[
        str | None,
        Field(
            description="Human-readable name for this forecast point. Required when forecast_range_unit is 'package' so buyer agents can identify and reference individual packages. Optional for other forecast types.",
            examples=['Primetime', 'Morning Drive', 'Large Format Transit'],
            max_length=128,
        ),
    ] = None
    budget: Annotated[
        float | None,
        Field(
            description='Budget amount for this forecast point. Required for spend curves; omit for availability forecasts where the metrics represent total available inventory. For allocation-level forecasts, this is the absolute budget for that allocation (not the percentage). For proposal-level forecasts, this is the total proposal budget. When omitted, use metrics.spend to express the estimated cost of the available inventory.',
            ge=0.0,
        ),
    ] = None
    metrics: Annotated[
        Metrics,
        Field(
            description='Forecasted metric values. Keys are forecastable-metric enum values for delivery/engagement or event-type enum values for outcomes. Values are ForecastRange objects (low/mid/high). Use { "mid": value } for point estimates. When budget is present, these are the expected metrics at that spend level. When budget is omitted, these represent total available inventory — use spend to express the estimated cost. Additional keys beyond the documented properties are allowed for event-type values (purchase, lead, app_install, etc.).'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var budget : float | None
var label : str | None
var metrics : Metrics
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ForecastRange (**data: Any)

Expand source code

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

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var high : float | None
var low : float | None
var mid : float | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ForecastRangeUnit (*args, **kwds)

Expand source code

class ForecastRangeUnit(Enum):
    spend = "spend"
    availability = "availability"
    reach_freq = "reach_freq"
    weekly = "weekly"
    daily = "daily"
    clicks = "clicks"
    conversions = "conversions"
    package = "package"

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var availability
var clicks
var conversions
var daily
var package
var reach_freq
var spend
var weekly

class ForecastableMetric (*args, **kwds)

Expand source code

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

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var audience_size
var clicks
var completed_views
var downloads
var engagements
var follows
var frequency
var grps
var impressions
var measured_impressions
var plays
var profile_visits
var reach
var saves
var spend
var views

class Format (**data: Any)

Expand source code

class Format(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatId,
        Field(description='Structured format identifier with agent URL and format name'),
    ]
    name: Annotated[str, Field(description='Human-readable format name')]
    description: Annotated[
        str | None,
        Field(
            description='Plain text explanation of what this format does and what assets it requires'
        ),
    ] = None
    example_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional URL to showcase page with examples and interactive demos of this format'
        ),
    ] = None
    accepts_parameters: Annotated[
        list[format_id_parameter.FormatIdParameter] | None,
        Field(
            description='List of parameters this format accepts in format_id. Template formats define which parameters (dimensions, duration, etc.) can be specified when instantiating the format. Empty or omitted means this is a concrete format with fixed parameters.'
        ),
    ] = None
    renders: Annotated[
        list[Renders | Renders7] | None,
        Field(
            description='Specification of rendered pieces for this format. Most formats produce a single render. Companion ad formats (video + banner), adaptive formats, and multi-placement formats produce multiple renders. Each render specifies its role and dimensions.',
            min_length=1,
        ),
    ] = None
    assets: Annotated[
        list[
            Assets
            | Assets81
            | Assets82
            | Assets83
            | Assets84
            | Assets85
            | Assets86
            | Assets87
            | Assets88
            | Assets89
            | Assets90
            | Assets91
            | Assets92
            | Assets93
            | Assets94
        ]
        | None,
        Field(
            description="Array of all assets supported for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Use the 'required' boolean on each asset to indicate whether it's mandatory."
        ),
    ] = None
    delivery: Annotated[
        dict[str, Any] | None,
        Field(description='Delivery method specifications (e.g., hosted, VAST, third-party tags)'),
    ] = None
    supported_macros: Annotated[
        list[universal_macro.UniversalMacro | str] | None,
        Field(
            description='List of universal macros supported by this format (e.g., MEDIA_BUY_ID, CACHEBUSTER, DEVICE_ID). Used for validation and developer tooling. See docs/creative/universal-macros.mdx for full documentation.'
        ),
    ] = None
    input_format_ids: Annotated[
        list[format_id_1.FormatId] | None,
        Field(
            description='Array of format IDs this format accepts as input creative manifests. When present, indicates this format can take existing creatives in these formats as input. Omit for formats that work from raw assets (images, text, etc.) rather than existing creatives.'
        ),
    ] = None
    output_format_ids: Annotated[
        list[format_id_1.FormatId] | None,
        Field(
            description='Array of format IDs that this format can produce as output. When present, indicates this format can build creatives in these output formats (e.g., a multi-publisher template format might produce standard display formats across many publishers). Omit for formats that produce a single fixed output (the format itself).'
        ),
    ] = None
    format_card: Annotated[
        FormatCard | None,
        Field(
            description='Optional standard visual card (300x400px) for displaying this format in user interfaces. Can be rendered via preview_creative or pre-generated.'
        ),
    ] = None
    accessibility: Annotated[
        Accessibility | None,
        Field(
            description='Accessibility posture of this format. Declares the WCAG conformance level that creatives produced by this format will meet.'
        ),
    ] = None
    supported_disclosure_positions: Annotated[
        list[disclosure_position.DisclosurePosition] | None,
        Field(
            description='Disclosure positions this format can render. Buyers use this to determine whether a format can satisfy their compliance requirements before submitting a creative. When omitted, the format makes no disclosure rendering guarantees — creative agents SHOULD treat this as incompatible with briefs that require specific disclosure positions. Values correspond to positions on creative-brief.json required_disclosures.',
            min_length=1,
        ),
    ] = None
    disclosure_capabilities: Annotated[
        list[DisclosureCapability] | None,
        Field(
            description='Structured disclosure capabilities per position with persistence modes. Declares which persistence behaviors each disclosure position supports, enabling persistence-aware matching against provenance render guidance and brief requirements. When present, supersedes supported_disclosure_positions for persistence-aware queries. The flat supported_disclosure_positions field is retained for backward compatibility. Each position MUST appear at most once; validators and agents SHOULD reject duplicates.',
            min_length=1,
        ),
    ] = None
    format_card_detailed: Annotated[
        FormatCardDetailed | None,
        Field(
            description='Optional detailed card with carousel and full specifications. Provides rich format documentation similar to ad spec pages.'
        ),
    ] = None
    reported_metrics: Annotated[
        list[available_metric.AvailableMetric] | None,
        Field(
            description='Metrics this format can produce in delivery reporting. Buyers receive the intersection of format reported_metrics and product available_metrics. If omitted, the format defers entirely to product-level metric declarations.',
            min_length=1,
        ),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for this format. Used by transformation and generation agents that charge per format adapted, per image generated, or per unit of work. Present when the request included include_pricing=true and account. Ad servers and library-based agents expose pricing on list_creatives instead.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accepts_parameters : list[FormatIdParameter] | None
var accessibility : Accessibility | None
var assets : list[Assets | Assets81 | Assets82 | Assets83 | Assets84 | Assets85 | Assets86 | Assets87 | Assets88 | Assets89 | Assets90 | Assets91 | Assets92 | Assets93 | Assets94] | None
var delivery : dict[str, typing.Any] | None
var description : str | None
var disclosure_capabilities : list[DisclosureCapability] | None
var example_url : pydantic.networks.AnyUrl | None
var format_card : FormatCard | None
var format_card_detailed : FormatCardDetailed | None
var format_id : FormatId
var input_format_ids : list[FormatId] | None
var model_config
var name : str
var output_format_ids : list[FormatId] | None
var pricing_options : list[VendorPricingOption] | None
var renders : list[Renders | Renders7] | None
var reported_metrics : list[AvailableMetric] | None
var supported_disclosure_positions : list[DisclosurePosition] | None
var supported_macros : list[UniversalMacro | str] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class FormatCard (**data: Any)

Expand source code

class FormatCard(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatId,
        Field(
            description='Creative format defining the card layout (typically format_card_standard)'
        ),
    ]
    manifest: Annotated[
        dict[str, Any],
        Field(description='Asset manifest for rendering the card, structure defined by the format'),
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var format_id : FormatId
var manifest : dict[str, typing.Any]
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class FormatCardDetailed (**data: Any)

Expand source code

class FormatCardDetailed(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatId,
        Field(
            description='Creative format defining the detailed card layout (typically format_card_detailed)'
        ),
    ]
    manifest: Annotated[
        dict[str, Any],
        Field(
            description='Asset manifest for rendering the detailed card, structure defined by the format'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var format_id : FormatId
var manifest : dict[str, typing.Any]
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class FormatId (**data: Any)

Expand source code

class FormatId(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    agent_url: Annotated[
        AnyUrl,
        Field(
            description="URL of the agent that defines this format (e.g., 'https://creatives.adcontextprotocol.org' for standard formats, or 'https://publisher.com/.well-known/adcp/sales' for custom formats)"
        ),
    ]
    id: Annotated[
        str,
        Field(
            description="Format identifier within the agent's namespace (e.g., 'display_static', 'video_hosted', 'audio_standard'). When used alone, references a template format. When combined with dimension/duration fields, creates a parameterized format ID for a specific variant.",
            pattern='^[a-zA-Z0-9_-]+$',
        ),
    ]
    width: Annotated[
        int | None,
        Field(
            description='Width in pixels for visual formats. When specified, height must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
            ge=1,
        ),
    ] = None
    height: Annotated[
        int | None,
        Field(
            description='Height in pixels for visual formats. When specified, width must also be specified. Both fields together create a parameterized format ID for dimension-specific variants.',
            ge=1,
        ),
    ] = None
    duration_ms: Annotated[
        float | None,
        Field(
            description='Duration in milliseconds for time-based formats (video, audio). When specified, creates a parameterized format ID. Omit to reference a template format without parameters.',
            ge=1.0,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agent_url : pydantic.networks.AnyUrl
var duration_ms : float | None
var height : int | None
var id : str
var model_config
var width : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class FormatIdParameter (*args, **kwds)

Expand source code

class FormatIdParameter(Enum):
    dimensions = 'dimensions'
    duration = 'duration'

Create a collection of name/value pairs.

Example enumeration:

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

Access them by:

attribute access::

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

value lookup:

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

name lookup:

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

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

>>> len(Color)
3

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

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

Ancestors

enum.Enum

Class variables

var dimensions
var duration

class FrequencyCap (**data: Any)

Expand source code

class FrequencyCap(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    suppress: Annotated[
        duration.Duration | None,
        Field(
            description='Cooldown period between consecutive exposures to the same entity. Prevents back-to-back ad delivery (e.g. {"interval": 60, "unit": "minutes"} for a 1-hour cooldown). Preferred over suppress_minutes.'
        ),
    ] = None
    suppress_minutes: Annotated[
        float | None,
        Field(
            description='Deprecated — use suppress instead. Cooldown period in minutes between consecutive exposures to the same entity (e.g. 60 for a 1-hour cooldown).',
            ge=0.0,
        ),
    ] = None
    max_impressions: Annotated[
        int | None,
        Field(
            description="Maximum number of impressions per entity per window. For duration windows, implementations typically use a rolling window; 'campaign' applies a fixed cap across the full flight.",
            ge=1,
        ),
    ] = None
    per: Annotated[
        reach_unit.ReachUnit | None,
        Field(
            description='Entity granularity for impression counting. Required when max_impressions is set.'
        ),
    ] = None
    window: Annotated[
        duration.Duration | None,
        Field(
            description='Time window for the max_impressions cap (e.g. {"interval": 7, "unit": "days"} or {"interval": 1, "unit": "campaign"} for the full flight). Required when max_impressions is set.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var max_impressions : int | None
var model_config
var per : ReachUnit | None
var suppress : Duration | None
var suppress_minutes : float | None
var window : Duration | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Expand source code

class FrequencyCapScope(RootModel[Literal['package']]):
    root: Annotated[
        Literal['package'],
        Field(description='Scope for frequency cap application', title='Frequency Cap Scope'),
    ]

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

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

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

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

Ancestors

pydantic.root_model.RootModel[Literal['package']]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : Literal['package']

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

Expand source code

class GeoCountry(RootModel[str]):
    root: Annotated[str, Field(pattern='^[A-Z]{2}$')]

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

Subclasses

GeoCountriesExcludeItem

Class variables

var model_config
var root : str

class GeoMetro (**data: Any)

Expand source code

class GeoMetro(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    system: Annotated[
        metro_system.MetroAreaSystem,
        Field(description="Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2')"),
    ]
    values: Annotated[
        list[str],
        Field(
            description="Metro codes within the system (e.g., ['501', '602'] for Nielsen DMAs)",
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var system : MetroAreaSystem
var values : list[str]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GeoPostalArea (**data: Any)

Expand source code

class GeoPostalArea(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    system: Annotated[
        postal_system.PostalCodeSystem,
        Field(
            description="Postal code system (e.g., 'us_zip', 'gb_outward'). System name encodes country and precision."
        ),
    ]
    values: Annotated[
        list[str],
        Field(
            description="Postal codes within the system (e.g., ['10001', '10002'] for us_zip)",
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var system : PostalCodeSystem
var values : list[str]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

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

Expand source code

class GeoRegion(RootModel[str]):
    root: Annotated[str, Field(pattern='^[A-Z]{2}-[A-Z0-9]{1,3}$')]

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

Subclasses

GeoRegionsExcludeItem

Class variables

var model_config
var root : str

class GetAccountFinancialsRequest (**data: Any)

Expand source code

class GetAccountFinancialsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference,
        Field(description="Account to query financials for. Must be an operator-billed account."),
    ]
    period: Annotated[
        date_range.DateRange | None,
        Field(
            description="Date range for the spend summary. Defaults to the current billing cycle if omitted."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var period : DateRange | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetAccountFinancialsSuccessResponse (**data: Any)

Expand source code

class GetAccountFinancialsResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    account: Annotated[
        account_ref.AccountReference,
        Field(description="Account reference, echoed from the request"),
    ]
    currency: Annotated[
        str,
        Field(
            description="ISO 4217 currency code for all monetary amounts in this response",
            pattern="^[A-Z]{3}$",
        ),
    ]
    period: Annotated[
        date_range.DateRange,
        Field(
            description="The actual period covered by spend data. May differ from the requested period if the seller adjusts to billing cycle boundaries."
        ),
    ]
    timezone: Annotated[
        str,
        Field(
            description="IANA timezone of the seller's billing day boundaries (e.g., 'America/New_York'). All dates in this response — period, invoice periods, due dates — are calendar dates in this timezone. Buyers in a different timezone should expect spend boundaries to differ from their own calendar day."
        ),
    ]
    spend: Annotated[Spend | None, Field(description="Spend summary for the period")] = None
    credit: Annotated[
        Credit | None,
        Field(
            description="Credit status. Present for credit-based accounts (payment_terms like net_30)."
        ),
    ] = None
    balance: Annotated[
        Balance | None, Field(description="Prepay balance. Present for prepay accounts.")
    ] = None
    payment_status: Annotated[
        PaymentStatus | None,
        Field(
            description="Overall payment status. current: all obligations met. past_due: one or more invoices overdue. suspended: account suspended due to payment issues."
        ),
    ] = None
    payment_terms: Annotated[
        PaymentTerms | None, Field(description="Payment terms in effect for this account")
    ] = None
    invoices: Annotated[
        list[Invoice] | None,
        Field(description="Recent invoices. Sellers may limit the number returned."),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var balance : Balance | None
var context : ContextObject | None
var credit : Credit | None
var currency : str
var ext : ExtensionObject | None
var invoices : list[Invoice] | None
var model_config
var payment_status : PaymentStatus | None
var payment_terms : PaymentTerms | None
var period : DateRange
var spend : Spend | None
var timezone : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetAccountFinancialsErrorResponse (**data: Any)

Expand source code

class GetAccountFinancialsResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    errors: Annotated[list[error.Error], Field(description="Operation-level errors", min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetAdcpCapabilitiesRequest (**data: Any)

Expand source code

class GetAdcpCapabilitiesRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="The AdCP major version the buyer's payloads conform to. When provided, the seller validates this against its supported major_versions and returns VERSION_UNSUPPORTED if the version is not in range. When omitted, the seller assumes the highest major version it supports.",
            ge=1,
            le=99,
        ),
    ] = None
    protocols: Annotated[
        list[Protocol] | None,
        Field(
            description='Specific protocols to query capabilities for. If omitted, returns capabilities for all supported protocols.',
            min_length=1,
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetAdcpCapabilitiesResponse (**data: Any)

Expand source code

class GetAdcpCapabilitiesResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    adcp: Annotated[Adcp, Field(description="Core AdCP protocol information")]
    supported_protocols: Annotated[
        list[SupportedProtocol],
        Field(
            description="AdCP protocols this agent supports. Each value both (a) declares which tools the agent implements and (b) commits the agent to pass the baseline compliance storyboard at /compliance/{version}/protocols/{protocol}/ (with snake_case → kebab-case path mapping, e.g. media_buy → /compliance/.../protocols/media-buy/). Compliance testing support is declared separately via the `compliance_testing` capability block (below), not as a protocol claim.",
            min_length=1,
        ),
    ]
    account: Annotated[
        Account | None,
        Field(
            description="Account management capabilities. Describes how accounts are established, what billing models are supported, and whether an account is required before browsing products."
        ),
    ] = None
    media_buy: Annotated[
        MediaBuy | None,
        Field(
            description="Media-buy protocol capabilities. Expected when media_buy is in supported_protocols. Sellers declaring media_buy should also include account with supported_billing."
        ),
    ] = None
    signals: Annotated[
        Signals | None,
        Field(
            description="Signals protocol capabilities. Only present if signals is in supported_protocols."
        ),
    ] = None
    governance: Annotated[
        Governance | None,
        Field(
            description="Governance protocol capabilities. Only present if governance is in supported_protocols. Governance agents provide property and creative data like compliance scores, brand safety ratings, sustainability metrics, and creative quality assessments."
        ),
    ] = None
    sponsored_intelligence: Annotated[
        SponsoredIntelligence | None,
        Field(
            description="Sponsored Intelligence protocol capabilities. Only present if sponsored_intelligence is in supported_protocols. SI agents handle conversational brand experiences."
        ),
    ] = None
    brand: Annotated[
        Brand | None,
        Field(
            description="Brand protocol capabilities. Only present if brand is in supported_protocols. Brand agents provide identity data (logos, colors, tone, assets) and optionally rights clearance for licensable content (talent, music, stock media)."
        ),
    ] = None
    creative: Annotated[
        Creative | None,
        Field(
            description="Creative protocol capabilities. Only present if creative is in supported_protocols."
        ),
    ] = None
    request_signing: Annotated[
        RequestSigning | None,
        Field(
            description="RFC 9421 HTTP Signatures support for incoming requests. Optional in 3.0 — capability-advertised so counterparties can opt into signing selectively. Required for spend-committing operations in 4.0 (the next breaking-changes accumulation window). The full profile is defined in docs/building/implementation/security.mdx (Signed Requests (Transport Layer))."
        ),
    ] = None
    compliance_testing: Annotated[
        ComplianceTesting | None,
        Field(
            description="Compliance testing capabilities. The presence of this block declares that the agent supports deterministic testing via comply_test_controller for lifecycle state machine validation. Omit the block entirely if the agent does not support compliance testing."
        ),
    ] = None
    specialisms: Annotated[
        list[specialism.AdcpSpecialism] | None,
        Field(
            description="Optional — specialized compliance claims this agent supports. Omitting the field means the agent declares no specialism claims (it still passes the universal + domain-baseline storyboards implied by supported_protocols). Each specialism maps to a storyboard bundle at /compliance/{version}/specialisms/{id}/ that the AAO compliance runner executes to verify the claim. Each specialism rolls up to one of the protocols in supported_protocols — the runner rejects a specialism claim whose parent protocol is missing. Only list specialisms your agent actually implements — the AAO Verified badge enumerates which specialisms were demonstrably passed."
        ),
    ] = None
    extensions_supported: Annotated[
        list[ExtensionsSupportedItem] | None,
        Field(
            description="Extension namespaces this agent supports. Buyers can expect meaningful data in ext.{namespace} fields on responses from this agent. Extension schemas are published in the AdCP extension registry."
        ),
    ] = None
    experimental_features: Annotated[
        list[ExperimentalFeature] | None,
        Field(
            description="Experimental AdCP surfaces this agent implements. A surface is experimental when its schema carries x-status: experimental and the working group has not yet frozen it. Sellers that implement any experimental surface MUST list its feature id here. Buyers inspect this array before relying on experimental surfaces — a seller that does not list a surface is asserting it does not implement it. Experimental surfaces MAY break between any two 3.x releases with at least 6 weeks notice; the full contract is in docs/reference/experimental-status."
        ),
    ] = None
    last_updated: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp of when capabilities were last updated. Buyers can use this for cache invalidation."
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None, Field(description="Task-specific errors and warnings")
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : Account | None
var adcp : Adcp
var brand : Brand | None
var compliance_testing : ComplianceTesting | None
var context : ContextObject | None
var creative : Creative | None
var errors : list[Error] | None
var experimental_features : list[ExperimentalFeature] | None
var ext : ExtensionObject | None
var extensions_supported : list[ExtensionsSupportedItem] | None
var governance : Governance | None
var last_updated : pydantic.types.AwareDatetime | None
var media_buy : MediaBuy | None
var model_config
var request_signing : RequestSigning | None
var signals : Signals | None
var specialisms : list[AdcpSpecialism] | None
var sponsored_intelligence : SponsoredIntelligence | None
var supported_protocols : list[SupportedProtocol]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetBrandIdentityRequest (**data: Any)

Expand source code

class GetBrandIdentityRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    brand_id: Annotated[str, Field(description='Brand identifier from brand.json brands array')]
    fields: Annotated[
        list[FieldModel] | None,
        Field(
            description='Optional identity sections to include in the response. When omitted, all sections the caller is authorized to see are returned. Core fields (brand_id, house, names) are always returned and do not need to be requested.',
            min_length=1,
        ),
    ] = None
    use_case: Annotated[
        str | None,
        Field(
            description="Intended use case, so the agent can tailor the response. A 'voice_synthesis' use case returns voice configs; a 'likeness' use case returns high-res photos and appearance guidelines."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var brand_id : str
var context : ContextObject | None
var ext : ExtensionObject | None
var fields : list[FieldModel] | None
var model_config
var use_case : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetBrandIdentitySuccessResponse (**data: Any)

Expand source code

class GetBrandIdentityResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    brand_id: Annotated[str, Field(description='Brand identifier')]
    house: Annotated[
        House,
        Field(
            description='The house (corporate entity) this brand belongs to. Always returned regardless of authorization level.'
        ),
    ]
    names: Annotated[
        list[dict[str, str]],
        Field(
            description="Localized brand names with BCP 47 locale code keys (e.g., 'en_US', 'fr_CA'). Bare language codes ('en') are accepted as wildcards for backwards compatibility."
        ),
    ]
    description: Annotated[str | None, Field(description='Brand description')] = None
    industries: Annotated[
        list[str] | None, Field(description='Brand industries.', min_length=1)
    ] = None
    keller_type: Annotated[
        KellerType | None,
        Field(
            description='Brand architecture type: master (primary brand of house), sub_brand (carries parent name), endorsed (independent identity backed by parent), independent (operates separately)'
        ),
    ] = None
    logos: Annotated[
        list[Logo] | None,
        Field(
            description='Brand logos. Public callers get standard logos; authorized callers also receive high-res variants. Shape matches brand.json logo definition.'
        ),
    ] = None
    colors: Annotated[
        Colors | None,
        Field(
            description='Brand color palette. Each role accepts a single hex color or an array of hex colors. Shape matches brand.json colors definition.'
        ),
    ] = None
    fonts: Annotated[
        Fonts | None,
        Field(
            description="Brand typography. Each key is a role name (e.g., 'primary', 'secondary') referenced by type_scale entries. Values are either a CSS font-family string or a structured object with family name and font files. Shape matches brand.json fonts definition."
        ),
    ] = None
    visual_guidelines: Annotated[
        dict[str, Any] | None,
        Field(
            description='Structured visual rules for generative creative systems (photography, graphic_style, colorways, type_scale, motion). Matches brand.json visual_guidelines definition. Authorized callers only.'
        ),
    ] = None
    tone: Annotated[Tone | None, Field(description='Brand voice and messaging guidelines')] = None
    tagline: Annotated[
        str | Tagline | None,
        Field(
            description='Brand tagline or slogan. Accepts a plain string or a localized array matching the names pattern.'
        ),
    ] = None
    voice_synthesis: Annotated[
        VoiceSynthesis | None,
        Field(description='Voice synthesis configuration for AI-generated audio'),
    ] = None
    assets: Annotated[
        list[Asset] | None,
        Field(
            description='Available brand assets (images, audio, video). Authorized callers only. Shape matches brand.json asset definition.'
        ),
    ] = None
    rights: Annotated[
        Rights | None,
        Field(description='Rights availability summary. For detailed pricing, use get_rights.'),
    ] = None
    available_fields: Annotated[
        list[AvailableField] | None,
        Field(
            description='Fields available but not returned in this response due to authorization level. Tells the caller what they would gain by linking their account via sync_accounts. Values match the request fields enum.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var assets : list[Asset] | None
var available_fields : list[AvailableField] | None
var brand_id : str
var colors : Colors | None
var context : ContextObject | None
var description : str | None
var ext : ExtensionObject | None
var fonts : Fonts | None
var house : House
var industries : list[str] | None
var keller_type : KellerType | None
var logos : list[Logo] | None
var model_config
var names : list[dict[str, str]]
var rights : Rights | None
var tagline : str | Tagline | None
var tone : Tone | None
var visual_guidelines : dict[str, typing.Any] | None
var voice_synthesis : VoiceSynthesis | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetBrandIdentityErrorResponse (**data: Any)

Expand source code

class GetBrandIdentityResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[list[error.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetCollectionListRequest (**data: Any)

Expand source code

class GetCollectionListRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    list_id: Annotated[str, Field(description='ID of the collection list to retrieve')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts and the list_id is not globally unique within that scope; optional otherwise.'
        ),
    ] = None
    resolve: Annotated[
        bool | None,
        Field(
            description='Whether to apply filters and return resolved collections (default: true)'
        ),
    ] = True
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination parameters. Uses higher limits than standard pagination because collection lists can contain thousands of entries.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var list_id : str
var model_config
var pagination : Pagination | None
var resolve : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetCollectionListResponse (**data: Any)

Expand source code

class GetCollectionListResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list: Annotated[
        collection_list.CollectionList,
        Field(description='The collection list metadata (always returned)'),
    ]
    collections: Annotated[
        list[Collection] | None,
        Field(
            description='Resolved collections that passed filters (if resolve=true). Each entry contains identification and key metadata for seller matching.'
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    resolved_at: Annotated[
        AwareDatetime | None, Field(description='When the list was resolved')
    ] = None
    cache_valid_until: Annotated[
        AwareDatetime | None,
        Field(
            description='Cache expiration timestamp. Re-fetch the list after this time to get updated collections.'
        ),
    ] = None
    coverage_gaps: Annotated[
        dict[str, list[CoverageGap]] | None,
        Field(
            description="Collections included in the list despite missing metadata for a filtered dimension. Maps dimension name (e.g., 'genre', 'content_rating') to arrays of distribution identifiers for collections not covered. Only present when filters are applied and some collections lack the filtered metadata."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_valid_until : pydantic.types.AwareDatetime | None
var collections : list[Collection] | None
var context : ContextObject | None
var coverage_gaps : dict[str, list[CoverageGap]] | None
var ext : ExtensionObject | None
var list : CollectionList
var model_config
var pagination : PaginationResponse | None
var resolved_at : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetContentStandardsRequest (**data: Any)

Expand source code

class GetContentStandardsRequest(AdCPBaseModel):
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    standards_id: Annotated[
        str, Field(description='Identifier for the standards configuration to retrieve')
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var standards_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetContentStandardsSuccessResponse (**data: Any)

Expand source code

class GetContentStandardsResponse1(ContentStandards):
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

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

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

Ancestors

ContentStandards
AdCPBaseModel
pydantic.main.BaseModel

Class variables

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

Inherited members

ContentStandards:
- model_dump
- model_dump_json
- model_summary

class GetContentStandardsErrorResponse (**data: Any)

Expand source code

class GetContentStandardsResponse2(AdCPBaseModel):
    errors: list[error.Error]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetCreativeDeliveryRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        int | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

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

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var creative_ids : list[str] | None
var end_date : str | None
var ext : ExtensionObject | None
var max_variants : int | None
var media_buy_ids : list[str] | None
var model_config
var pagination : PaginationRequest | None
var start_date : str | None

class GetCreativeDeliveryByBuyerRefRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        int | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var creative_ids : list[str] | None
var end_date : str | None
var ext : ExtensionObject | None
var max_variants : int | None
var media_buy_ids : list[str] | None
var model_config
var pagination : PaginationRequest | None
var start_date : str | None

class GetCreativeDeliveryByCreativeRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        int | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var creative_ids : list[str] | None
var end_date : str | None
var ext : ExtensionObject | None
var max_variants : int | None
var media_buy_ids : list[str] | None
var model_config
var pagination : PaginationRequest | None
var start_date : str | None

class GetCreativeDeliveryByMediaBuyRequest (**data: Any)

Expand source code

class GetCreativeDeliveryRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for routing and scoping. Limits results to creatives within this account.'
        ),
    ] = None
    media_buy_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific media buys by publisher ID. If omitted, returns creative delivery across all matching media buys.',
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Filter to specific creatives by ID. If omitted, returns delivery for all creatives matching the other filters.',
            min_length=1,
        ),
    ] = None
    start_date: Annotated[
        str | None,
        Field(
            description="Start date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    end_date: Annotated[
        str | None,
        Field(
            description="End date for delivery period (YYYY-MM-DD). Interpreted in the platform's reporting timezone.",
            pattern='^\\d{4}-\\d{2}-\\d{2}$',
        ),
    ] = None
    max_variants: Annotated[
        int | None,
        Field(
            description='Maximum number of variants to return per creative. When omitted, the agent returns all variants. Use this to limit response size for generative creatives that may produce large numbers of variants.',
            ge=1,
        ),
    ] = None
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(
            description='Pagination parameters for the creatives array in the response. Uses cursor-based pagination consistent with other list operations.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var creative_ids : list[str] | None
var end_date : str | None
var ext : ExtensionObject | None
var max_variants : int | None
var media_buy_ids : list[str] | None
var model_config
var pagination : PaginationRequest | None
var start_date : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetCreativeDeliveryResponse (**data: Any)

Expand source code

class GetCreativeDeliveryResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    account_id: Annotated[
        str | None,
        Field(
            description='Account identifier. Present when the response spans or is scoped to a specific account.'
        ),
    ] = None
    media_buy_id: Annotated[
        str | None,
        Field(
            description="Publisher's media buy identifier. Present when the request was scoped to a single media buy."
        ),
    ] = None
    currency: Annotated[
        str,
        Field(
            description="ISO 4217 currency code for monetary values in this response (e.g., 'USD', 'EUR')",
            pattern='^[A-Z]{3}$',
        ),
    ]
    reporting_period: Annotated[ReportingPeriod, Field(description='Date range for the report.')]
    creatives: Annotated[
        list[Creative], Field(description='Creative delivery data with variant breakdowns')
    ]
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination information. Present when the request included pagination parameters.'
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None, Field(description='Task-specific errors and warnings')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account_id : str | None
var context : ContextObject | None
var creatives : list[Creative]
var currency : str
var errors : list[Error] | None
var ext : ExtensionObject | None
var media_buy_id : str | None
var model_config
var pagination : Pagination | None
var reporting_period : ReportingPeriod

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetCreativeFeaturesRequest (**data: Any)

Expand source code

class GetCreativeFeaturesRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest,
        Field(description='The creative manifest to evaluate. Contains format_id and assets.'),
    ]
    feature_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional filter to specific features. If omitted, returns all available features.',
            min_length=1,
        ),
    ] = None
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for billing this evaluation. Required when the governance agent charges per evaluation.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var creative_manifest : CreativeManifest
var ext : ExtensionObject | None
var feature_ids : list[str] | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetCreativeFeaturesSuccessResponse (**data: Any)

Expand source code

class GetCreativeFeaturesResponse1(AdCPBaseModel):
    results: Annotated[
        list[creative_feature_result.CreativeFeatureResult],
        Field(description='Feature values for the evaluated creative'),
    ]
    detail_url: Annotated[
        AnyUrl | None,
        Field(
            description="URL to the vendor's full assessment report. The vendor controls what information is disclosed and access control."
        ),
    ] = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description='Which rate card pricing option was applied for this evaluation. Present when the governance agent charges for evaluations and account was provided in the request.'
        ),
    ] = None
    vendor_cost: Annotated[
        float | None,
        Field(description='Cost incurred for this evaluation, denominated in currency.', ge=0.0),
    ] = None
    currency: Annotated[
        str | None,
        Field(description='ISO 4217 currency code for vendor_cost.', pattern='^[A-Z]{3}$'),
    ] = None
    consumption: Annotated[
        creative_consumption.CreativeConsumption | None,
        Field(
            description='Structured consumption details for this evaluation. Informational — lets the buyer verify that vendor_cost is consistent with the rate card. vendor_cost is the billing source of truth.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var consumption : CreativeConsumption | None
var context : ContextObject | None
var currency : str | None
var detail_url : pydantic.networks.AnyUrl | None
var ext : ExtensionObject | None
var model_config
var pricing_option_id : str | None
var results : list[CreativeFeatureResult]
var vendor_cost : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetCreativeFeaturesErrorResponse (**data: Any)

Expand source code

class GetCreativeFeaturesResponse2(AdCPBaseModel):
    errors: list[error.Error]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetMediaBuyArtifactsRequest (**data: Any)

Expand source code

class GetMediaBuyArtifactsRequest(AdCPBaseModel):
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Filter artifacts to a specific account. When omitted, returns artifacts across all accessible accounts.'
        ),
    ] = None
    media_buy_id: Annotated[str, Field(description='Media buy to get artifacts from')]
    package_ids: Annotated[
        list[str] | None,
        Field(description='Filter to specific packages within the media buy', min_length=1),
    ] = None
    failures_only: Annotated[
        bool | None,
        Field(
            description="When true, only return artifacts where the seller's local model returned local_verdict: 'fail'. Useful for auditing false positives. Not useful when the seller does not run a local evaluation model (all verdicts are 'unevaluated')."
        ),
    ] = False
    time_range: Annotated[TimeRange | None, Field(description='Filter to specific time period')] = (
        None
    )
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination parameters. Uses higher limits than standard pagination because artifact result sets can be very large.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var failures_only : bool | None
var media_buy_id : str
var model_config
var package_ids : list[str] | None
var pagination : Pagination | None
var time_range : TimeRange | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetMediaBuyArtifactsSuccessResponse (**data: Any)

Expand source code

class GetMediaBuyArtifactsResponse1(AdCPBaseModel):
    media_buy_id: Annotated[str, Field(description='Media buy these artifacts belong to')]
    artifacts: Annotated[
        list[Artifact], Field(description='Delivery records with full artifact content')
    ]
    collection_info: Annotated[
        CollectionInfo | None,
        Field(
            description='Information about artifact collection for this media buy. Sampling is configured at buy creation time — this reports what was actually collected.'
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var artifacts : list[Artifact]
var collection_info : CollectionInfo | None
var context : ContextObject | None
var ext : ExtensionObject | None
var media_buy_id : str
var model_config
var pagination : PaginationResponse | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetMediaBuyArtifactsErrorResponse (**data: Any)

Expand source code

class GetMediaBuyArtifactsResponse2(AdCPBaseModel):
    errors: list[error.Error]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetMediaBuyDeliveryRequest (**data: Any)

Expand source code

class GetMediaBuyDeliveryRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: 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
    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="Start date for reporting period (YYYY-MM-DD). When omitted along with end_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
    end_date: Annotated[
        str | None,
        Field(
            description="End date for reporting period (YYYY-MM-DD). 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[
        bool | 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
    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. Note: keyword, catalog_item, and creative breakdowns are returned automatically when the seller supports them and are not controlled by this object.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | 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 media_buy_ids : list[str] | None
var model_config
var reporting_dimensions : ReportingDimensions | None
var start_date : str | None
var status_filter : MediaBuyStatus | StatusFilter | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetMediaBuyDeliveryResponse (**data: Any)

Expand source code

class GetMediaBuyDeliveryResponse(AdCPBaseModel):
    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[
        bool | None,
        Field(
            description='Indicates if any media buys in this webhook have missing/delayed data (only present in webhook deliveries)'
        ),
    ] = None
    unavailable_count: Annotated[
        int | 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[
        int | 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='Date range for the report. All periods use UTC timezone.'),
    ]
    currency: Annotated[str, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')]
    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(
            description='Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.'
        ),
    ] = None
    media_buy_deliveries: Annotated[
        list[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[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var aggregated_totals : AggregatedTotals | None
var attribution_window : AttributionWindow | None
var context : ContextObject | None
var currency : str
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 | None
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 GetMediaBuysRequest (**data: Any)

Expand source code

class GetMediaBuysRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: 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
    include_snapshot: Annotated[
        bool | 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[
        int | 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
    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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var include_history : int | None
var include_snapshot : bool | None
var media_buy_ids : list[str] | None
var model_config
var pagination : PaginationRequest | None
var status_filter : MediaBuyStatus | StatusFilter | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetMediaBuysResponse (**data: Any)

Expand source code

class GetMediaBuysResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buys: Annotated[
        list[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 (e.g., media buy not found)'),
    ] = None
    pagination: Annotated[
        pagination_response.PaginationResponse | None,
        Field(description='Pagination metadata for the media_buys array.'),
    ] = None
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 media_buys : list[MediaBuy]
var model_config
var pagination : PaginationResponse | None
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetPlanAuditLogsRequest (**data: Any)

Expand source code

class GetPlanAuditLogsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    plan_ids: Annotated[
        list[str] | None,
        Field(
            description='Plan IDs to retrieve. For a single plan, pass a one-element array.',
            min_length=1,
        ),
    ] = None
    portfolio_plan_ids: Annotated[
        list[str] | None,
        Field(
            description='Portfolio plan IDs. The governance agent expands each to its member_plan_ids and returns combined audit data.',
            min_length=1,
        ),
    ] = None
    governance_contexts: Annotated[
        list[str] | None,
        Field(
            description='Filter audit entries by governance context. Returns only checks and outcomes that share these governance contexts, enabling lifecycle tracing across purchase types.',
            min_length=1,
        ),
    ] = None
    purchase_types: Annotated[
        list[purchase_type.PurchaseType] | None,
        Field(
            description="Filter audit entries by purchase type. Returns only checks and outcomes matching these purchase types (e.g., ['rights_license'] to see all rights activity).",
            min_length=1,
        ),
    ] = None
    include_entries: Annotated[
        bool | None, Field(description='Include the full audit trail. Default: false.')
    ] = False
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var governance_contexts : list[str] | None
var include_entries : bool | None
var model_config
var plan_ids : list[str] | None
var portfolio_plan_ids : list[str] | None
var purchase_types : list[PurchaseType] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetPlanAuditLogsResponse (**data: Any)

Expand source code

class GetPlanAuditLogsResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    plans: Annotated[list[Plan], Field(description='Audit data for each requested plan.')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 plans : list[Plan]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetProductsRequest (**data: Any)

Expand source code

class GetProductsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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 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'."
        ),
    ]
    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'."
        ),
    ] = None
    refine: Annotated[
        list[Refine | Refine1 | Refine2] | 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.",
            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
    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_1.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: product_filters.ProductFilters | None = None
    property_list: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            description='[AdCP 3.0] Reference to an externally managed property list. When provided, the sales agent should filter products to only those available on properties in the list.'
        ),
    ] = None
    fields: Annotated[
        list[Field1] | 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 (e.g., just IDs and pricing for comparison). Required fields (product_id, name) are always included regardless of selection.',
            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
    pagination: pagination_request.PaginationRequest | None = 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | 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[Field1] | None
var filters : ProductFilters | None
var model_config
var pagination : PaginationRequest | None
var preferred_delivery_types : list[DeliveryType] | None
var property_list : PropertyListReference | None
var refine : list[Refine | Refine1 | Refine2] | None
var required_policies : list[str] | None
var time_budget : Duration | None

class GetProductsBriefRequest (**data: Any)

Expand source code

class GetProductsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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 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'."
        ),
    ]
    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'."
        ),
    ] = None
    refine: Annotated[
        list[Refine | Refine1 | Refine2] | 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.",
            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
    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_1.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: product_filters.ProductFilters | None = None
    property_list: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            description='[AdCP 3.0] Reference to an externally managed property list. When provided, the sales agent should filter products to only those available on properties in the list.'
        ),
    ] = None
    fields: Annotated[
        list[Field1] | 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 (e.g., just IDs and pricing for comparison). Required fields (product_id, name) are always included regardless of selection.',
            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
    pagination: pagination_request.PaginationRequest | None = 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | 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[Field1] | None
var filters : ProductFilters | None
var model_config
var pagination : PaginationRequest | None
var preferred_delivery_types : list[DeliveryType] | None
var property_list : PropertyListReference | None
var refine : list[Refine | Refine1 | Refine2] | None
var required_policies : list[str] | None
var time_budget : Duration | None

class GetProductsRefineRequest (**data: Any)

Expand source code

class GetProductsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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 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'."
        ),
    ]
    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'."
        ),
    ] = None
    refine: Annotated[
        list[Refine | Refine1 | Refine2] | 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.",
            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
    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_1.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: product_filters.ProductFilters | None = None
    property_list: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            description='[AdCP 3.0] Reference to an externally managed property list. When provided, the sales agent should filter products to only those available on properties in the list.'
        ),
    ] = None
    fields: Annotated[
        list[Field1] | 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 (e.g., just IDs and pricing for comparison). Required fields (product_id, name) are always included regardless of selection.',
            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
    pagination: pagination_request.PaginationRequest | None = 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | 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[Field1] | None
var filters : ProductFilters | None
var model_config
var pagination : PaginationRequest | None
var preferred_delivery_types : list[DeliveryType] | None
var property_list : PropertyListReference | None
var refine : list[Refine | Refine1 | Refine2] | None
var required_policies : list[str] | None
var time_budget : Duration | None

class GetProductsWholesaleRequest (**data: Any)

Expand source code

class GetProductsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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 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'."
        ),
    ]
    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'."
        ),
    ] = None
    refine: Annotated[
        list[Refine | Refine1 | Refine2] | 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.",
            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
    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_1.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: product_filters.ProductFilters | None = None
    property_list: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            description='[AdCP 3.0] Reference to an externally managed property list. When provided, the sales agent should filter products to only those available on properties in the list.'
        ),
    ] = None
    fields: Annotated[
        list[Field1] | 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 (e.g., just IDs and pricing for comparison). Required fields (product_id, name) are always included regardless of selection.',
            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
    pagination: pagination_request.PaginationRequest | None = 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | 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[Field1] | None
var filters : ProductFilters | None
var model_config
var pagination : PaginationRequest | None
var preferred_delivery_types : list[DeliveryType] | None
var property_list : PropertyListReference | None
var refine : list[Refine | Refine1 | Refine2] | None
var required_policies : list[str] | None
var time_budget : Duration | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetProductsResponse (**data: Any)

Expand source code

class GetProductsResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    products: Annotated[list[product_1.Product], Field(description='Array of matching products')]
    proposals: Annotated[
        list[proposal_1.Proposal] | None,
        Field(
            description='Optional array of proposed media plans with budget allocations across products. Publishers include proposals when they can provide strategic guidance based on the brief. Proposals are actionable - buyers can refine them via follow-up get_products calls within the same session, or execute them directly via create_media_buy.'
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(description='Task-specific errors and warnings (e.g., product filtering issues)'),
    ] = None
    property_list_applied: Annotated[
        bool | None,
        Field(
            description='[AdCP 3.0] Indicates whether property_list filtering was applied. True if the agent filtered products based on the provided property_list. Absent or false if property_list was not provided or not supported by this agent.'
        ),
    ] = None
    catalog_applied: Annotated[
        bool | 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[RefinementAppliedItem] | 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'."
        ),
    ] = 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. Each entry identifies a scope that is missing or partial. Absent when the response is fully complete.",
            min_length=1,
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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_applied : bool | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var incomplete : list[IncompleteItem] | None
var model_config
var pagination : PaginationResponse | None
var products : list[Product]
var property_list_applied : bool | None
var proposals : list[Proposal] | None
var refinement_applied : list[RefinementAppliedItem] | None
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetPropertyListRequest (**data: Any)

Expand source code

class GetPropertyListRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    list_id: Annotated[str, Field(description='ID of the property list to retrieve')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts and the list_id is not globally unique within that scope; optional otherwise.'
        ),
    ] = None
    resolve: Annotated[
        bool | None,
        Field(
            description='Whether to apply filters and return resolved identifiers (default: true)'
        ),
    ] = True
    pagination: Annotated[
        Pagination | None,
        Field(
            description='Pagination parameters. Uses higher limits than standard pagination because property lists can contain tens of thousands of identifiers.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var list_id : str
var model_config
var pagination : Pagination | None
var resolve : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetPropertyListResponse (**data: Any)

Expand source code

class GetPropertyListResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list: Annotated[
        property_list.PropertyList,
        Field(description='The property list metadata (always returned)'),
    ]
    identifiers: Annotated[
        _list[identifier.Identifier] | None,
        Field(
            description='Resolved identifiers that passed filters (if resolve=true). Cache these locally for real-time use.'
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    resolved_at: Annotated[
        AwareDatetime | None, Field(description='When the list was resolved')
    ] = None
    cache_valid_until: Annotated[
        AwareDatetime | None,
        Field(
            description='Cache expiration timestamp. Re-fetch the list after this time to get updated identifiers.'
        ),
    ] = None
    coverage_gaps: Annotated[
        dict[str, _list[identifier.Identifier]] | None,
        Field(
            description="Properties included in the list despite missing feature data. Only present when a feature_requirement has if_not_covered='include'. Maps feature_id to list of identifiers not covered for that feature."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_valid_until : pydantic.types.AwareDatetime | None
var context : ContextObject | None
var coverage_gaps : dict[str, list[Identifier]] | None
var ext : ExtensionObject | None
var identifiers : list[Identifier] | None
var list : PropertyList
var model_config
var pagination : PaginationResponse | None
var resolved_at : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetRightsRequest (**data: Any)

Expand source code

class GetRightsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    query: Annotated[
        str,
        Field(
            description='Natural language description of desired rights. The agent interprets intent, budget signals, and compatibility from this text.',
            max_length=2000,
        ),
    ]
    uses: Annotated[
        list[right_use.RightUse],
        Field(
            description='Rights uses being requested. The agent returns options covering these uses, potentially bundled into composite pricing.',
            min_length=1,
        ),
    ]
    buyer_brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description="The buyer's brand. The agent fetches the buyer's brand.json for compatibility filtering (e.g., dietary conflicts, competitor exclusions)."
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where rights are needed (ISO 3166-1 alpha-2). Filters to rights available in these markets.'
        ),
    ] = None
    brand_id: Annotated[
        str | None,
        Field(
            description="Search within a specific brand's rights. If omitted, searches across the agent's full roster."
        ),
    ] = None
    right_type: Annotated[
        right_type_1.RightType | None,
        Field(description='Filter by type of rights (talent, music, stock_media, etc.)'),
    ] = None
    include_excluded: Annotated[
        bool | None,
        Field(
            description='Include filtered-out results in the excluded array with reasons. Defaults to false.'
        ),
    ] = False
    pagination: Annotated[
        pagination_request.PaginationRequest | None,
        Field(description='Pagination parameters for large result sets'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var brand_id : str | None
var buyer_brand : BrandReference | None
var context : ContextObject | None
var countries : list[Country] | None
var ext : ExtensionObject | None
var include_excluded : bool | None
var model_config
var pagination : PaginationRequest | None
var query : str
var right_type : RightType | None
var uses : list[RightUse]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetRightsSuccessResponse (**data: Any)

Expand source code

class GetRightsResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    rights: Annotated[
        list[Right], Field(description='Matching rights with pricing options, ranked by relevance')
    ]
    excluded: Annotated[
        list[ExcludedItem] | None,
        Field(description='Results that matched but were filtered out, with reasons'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 excluded : list[ExcludedItem] | None
var ext : ExtensionObject | None
var model_config
var rights : list[Right]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetRightsErrorResponse (**data: Any)

Expand source code

class GetRightsResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[list[error.Error], Field(min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetSignalsRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for this request. When provided, the signals agent returns per-account pricing options if configured.'
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description='Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_ids, provides context for the agent but signal_ids matches are returned first.'
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id.SignalId] | None,
        Field(
            description="Specific signals to look up by data provider and ID. Returns exact matches from the data provider's catalog. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    max_results: Annotated[
        int | None, Field(description='Maximum number of results to return', ge=1)
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var countries : list[Country] | None
var destinations : list[Destination] | None
var ext : ExtensionObject | None
var filters : SignalFilters | None
var max_results : int | None
var model_config
var pagination : PaginationRequest | None
var signal_ids : list[SignalId] | None
var signal_spec : str | None

class GetSignalsDiscoveryRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for this request. When provided, the signals agent returns per-account pricing options if configured.'
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description='Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_ids, provides context for the agent but signal_ids matches are returned first.'
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id.SignalId] | None,
        Field(
            description="Specific signals to look up by data provider and ID. Returns exact matches from the data provider's catalog. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    max_results: Annotated[
        int | None, Field(description='Maximum number of results to return', ge=1)
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var countries : list[Country] | None
var destinations : list[Destination] | None
var ext : ExtensionObject | None
var filters : SignalFilters | None
var max_results : int | None
var model_config
var pagination : PaginationRequest | None
var signal_ids : list[SignalId] | None
var signal_spec : str | None

class GetSignalsLookupRequest (**data: Any)

Expand source code

class GetSignalsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account for this request. When provided, the signals agent returns per-account pricing options if configured.'
        ),
    ] = None
    signal_spec: Annotated[
        str | None,
        Field(
            description='Natural language description of the desired signals. When used alone, enables semantic discovery. When combined with signal_ids, provides context for the agent but signal_ids matches are returned first.'
        ),
    ] = None
    signal_ids: Annotated[
        list[signal_id.SignalId] | None,
        Field(
            description="Specific signals to look up by data provider and ID. Returns exact matches from the data provider's catalog. When combined with signal_spec, these signals anchor the starting set and signal_spec guides adjustments.",
            min_length=1,
        ),
    ] = None
    destinations: Annotated[
        list[destination.Destination] | None,
        Field(
            description='Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. If the authenticated caller matches one of these destinations, activation keys will be included in the response.',
            min_length=1,
        ),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description='Countries where signals will be used (ISO 3166-1 alpha-2 codes). When omitted, no geographic filter is applied.',
            min_length=1,
        ),
    ] = None
    filters: signal_filters.SignalFilters | None = None
    max_results: Annotated[
        int | None, Field(description='Maximum number of results to return', ge=1)
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var countries : list[Country] | None
var destinations : list[Destination] | None
var ext : ExtensionObject | None
var filters : SignalFilters | None
var max_results : int | None
var model_config
var pagination : PaginationRequest | None
var signal_ids : list[SignalId] | None
var signal_spec : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class GetSignalsResponse (**data: Any)

Expand source code

class GetSignalsResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signals: Annotated[list[Signal], Field(description='Array of matching signals')]
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description='Task-specific errors and warnings (e.g., signal discovery or pricing issues)'
        ),
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 pagination : PaginationResponse | None
var sandbox : bool | None
var signals : list[Signal]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Gtin (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class Gtin(RootModel[str]):
    root: Annotated[str, Field(pattern='^[0-9]{8,14}$')]

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[str]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : str

class HtmlAsset (**data: Any)

Expand source code

class HtmlAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    content: Annotated[str, Field(description='HTML content')]
    version: Annotated[str | None, Field(description="HTML version (e.g., 'HTML5')")] = None
    accessibility: Annotated[
        Accessibility | None,
        Field(description='Self-declared accessibility properties for this opaque creative'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accessibility : Accessibility | None
var content : str
var model_config
var provenance : Provenance | None
var version : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class HttpMethod (*args, **kwds)

Expand source code

class HttpMethod(Enum):
    GET = 'GET'
    POST = 'POST'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var GET
var POST

class Method (*args, **kwds)

Expand source code

class HttpMethod(Enum):
    GET = 'GET'
    POST = 'POST'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var GET
var POST

class Identifier (**data: Any)

Expand source code

class Identifier(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    type: Annotated[
        identifier_types.PropertyIdentifierTypes, Field(description='Type of identifier')
    ]
    value: Annotated[
        str,
        Field(
            description="The identifier value. For domain type: 'example.com' matches base domain plus www and m subdomains; 'edition.example.com' matches that specific subdomain; '*.example.com' matches ALL subdomains but NOT base domain"
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var type : PropertyIdentifierTypes
var value : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class IdentityMatchRequest (**data: Any)

Expand source code

class IdentityMatchRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    field_schema: Annotated[
        AnyUrl | None,
        Field(
            alias='$schema', description='Optional schema URI for validation. Ignored at runtime.'
        ),
    ] = None
    type: Annotated[
        Literal['identity_match_request'],
        Field(description='Message type discriminator for deserialization.'),
    ]
    protocol_version: Annotated[
        str | None,
        Field(
            description='TMP protocol version. Allows receivers to handle semantic differences across versions.'
        ),
    ] = '1.0'
    request_id: Annotated[
        str,
        Field(
            description='Unique request identifier. MUST NOT correlate with any context match request_id.'
        ),
    ]
    identities: Annotated[
        list[Identity],
        Field(
            description='Identity tokens for the user, each tagged with its type. Publishers SHOULD include every token they have available — the buyer resolves on whichever graph matches. Entry order is not semantically significant; buyers use their own preference order when multiple entries resolve. Duplicate `(uid_type, user_token)` pairs MUST NOT appear; routers MAY reject or dedupe. `maxItems: 3` matches the TMPX plaintext budget (~120 bytes after HPKE overhead fits three 32-byte tokens); exceeding it forces buyer-side truncation.',
            max_length=3,
            min_length=1,
        ),
    ]
    consent: Annotated[
        Consent | None,
        Field(
            description='Privacy consent signals. Buyers in regulated jurisdictions MUST NOT process the user token without consent information.'
        ),
    ] = None
    package_ids: Annotated[
        list[str],
        Field(
            description='ALL active package identifiers for this buyer at this publisher. MUST include every active package, not just those on the current page, to prevent correlation with Context Match requests.',
            min_length=1,
        ),
    ]
    country: Annotated[
        str | None,
        Field(
            description='ISO 3166-1 alpha-2 country code. Routing directive for the TMP Router — used to select the correct regional provider. The router MUST strip this field before forwarding the request to the buyer agent. Not an identity signal.',
            pattern='^[A-Z]{2}$',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var consent : Consent | None
var country : str | None
var field_schema : pydantic.networks.AnyUrl | None
var identities : list[Identity]
var model_config
var package_ids : list[str]
var protocol_version : str | None
var request_id : str
var type : Literal['identity_match_request']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class IdentityMatchResponse (**data: Any)

Expand source code

class IdentityMatchResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['identity_match_response'],
        Field(description='Message type discriminator for deserialization.'),
    ]
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the identity match request')
    ]
    eligible_package_ids: Annotated[
        list[str],
        Field(
            description='Package IDs the user is eligible for. Packages not listed are ineligible.'
        ),
    ]
    ttl_sec: Annotated[
        int,
        Field(
            description='How long the router should cache this response, in seconds. The router returns cached eligibility without re-querying the buyer during this window. A value of 0 means do not cache.',
            ge=0,
            le=86400,
        ),
    ]
    tmpx: Annotated[
        str | None,
        Field(
            description="HPKE-encrypted exposure token containing the resolved user identity tokens. The publisher substitutes this into creative tracking URLs as {TMPX}. The buyer's impression pixel receives the token at serve time, enabling real-time per-user frequency state updates. Wire format: kid.base64url_nopad(ciphertext) — unpadded base64url per RFC 4648 section 5 (no = characters). Publishers MUST treat this value as opaque pass-through data."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var eligible_package_ids : list[str]
var model_config
var request_id : str
var tmpx : str | None
var ttl_sec : int
var type : Literal['identity_match_response']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ImageAsset (**data: Any)

Expand source code

class ImageAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='URL to the image asset')]
    width: Annotated[int, Field(description='Width in pixels', ge=1)]
    height: Annotated[int, Field(description='Height in pixels', ge=1)]
    format: Annotated[
        str | None, Field(description='Image file format (jpg, png, gif, webp, etc.)')
    ] = None
    alt_text: Annotated[str | None, Field(description='Alternative text for accessibility')] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var alt_text : str | None
var format : str | None
var height : int
var model_config
var provenance : Provenance | None
var url : pydantic.networks.AnyUrl
var width : int

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Input (**data: Any)

Expand source code

class Input(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    name: Annotated[str, Field(description='Human-readable name for this preview variant')]
    macros: Annotated[
        dict[str, str] | None, Field(description='Macro values to apply for this preview')
    ] = None
    context_description: Annotated[
        str | None,
        Field(description='Natural language description of the context for AI-generated content'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 JavascriptAsset (**data: Any)

Expand source code

class JavascriptAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    content: Annotated[str, Field(description='JavaScript content')]
    module_type: Annotated[
        javascript_module_type.JavascriptModuleType | None,
        Field(description='JavaScript module type'),
    ] = None
    accessibility: Annotated[
        Accessibility | None,
        Field(description='Self-declared accessibility properties for this opaque creative'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accessibility : Accessibility | None
var content : str
var model_config
var module_type : JavascriptModuleType | None
var provenance : Provenance | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class JavascriptModuleType (*args, **kwds)

Expand source code

class JavascriptModuleType(Enum):
    esm = 'esm'
    commonjs = 'commonjs'
    script = 'script'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var commonjs
var esm
var script

class ModuleType (*args, **kwds)

Expand source code

class JavascriptModuleType(Enum):
    esm = 'esm'
    commonjs = 'commonjs'
    script = 'script'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var commonjs
var esm
var script

class KellerType (*args, **kwds)

Expand source code

class KellerType(Enum):
    master = 'master'
    sub_brand = 'sub_brand'
    endorsed = 'endorsed'
    independent = 'independent'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var endorsed
var independent
var master
var sub_brand

class LandingPageRequirement (*args, **kwds)

Expand source code

class LandingPageRequirement(Enum):
    any = 'any'
    retailer_site_only = 'retailer_site_only'
    must_include_retailer = 'must_include_retailer'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var any
var must_include_retailer
var retailer_site_only

class LandingPage (*args, **kwds)

Expand source code

class LandingPageRequirement(Enum):
    any = 'any'
    retailer_site_only = 'retailer_site_only'
    must_include_retailer = 'must_include_retailer'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var any
var must_include_retailer
var retailer_site_only

class ListAccountsRequest (**data: Any)

Expand source code

class ListAccountsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    status: Annotated[
        Status | None,
        Field(description='Filter accounts by status. Omit to return accounts in all statuses.'),
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    sandbox: Annotated[
        bool | None,
        Field(
            description='Filter by sandbox status. true returns only sandbox accounts, false returns only production accounts. Omit to return all accounts. Primarily used with explicit accounts (require_operator_auth: true) where sandbox accounts are pre-existing test accounts on the platform.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var pagination : PaginationRequest | None
var sandbox : bool | None
var status : Status | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListAccountsResponse (**data: Any)

Expand source code

class ListAccountsResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    accounts: Annotated[
        list[account.Account],
        Field(description='Array of accounts accessible to the authenticated agent'),
    ]
    errors: Annotated[
        list[error.Error] | None, Field(description='Task-specific errors and warnings')
    ] = None
    pagination: pagination_response.PaginationResponse | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accounts : list[Account]
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var model_config
var pagination : PaginationResponse | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListCollectionListsRequest (**data: Any)

Expand source code

class ListCollectionListsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Filter to lists owned by this account. When omitted, returns lists across all accounts accessible to the authenticated agent.'
        ),
    ] = None
    name_contains: Annotated[
        str | None, Field(description='Filter to lists whose name contains this string')
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var name_contains : str | None
var pagination : PaginationRequest | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListCollectionListsResponse (**data: Any)

Expand source code

class ListCollectionListsResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    lists: Annotated[
        list[collection_list.CollectionList],
        Field(description='Array of collection lists (metadata only, not resolved collections)'),
    ]
    pagination: pagination_response.PaginationResponse | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 lists : list[CollectionList]
var model_config
var pagination : PaginationResponse | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListContentStandardsRequest (**data: Any)

Expand source code

class ListContentStandardsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    channels: Annotated[
        list[channels_1.MediaChannel] | None, Field(description='Filter by channel', min_length=1)
    ] = None
    languages: Annotated[
        list[str] | None, Field(description='Filter by BCP 47 language tags', min_length=1)
    ] = None
    countries: Annotated[
        list[str] | None,
        Field(description='Filter by ISO 3166-1 alpha-2 country codes', min_length=1),
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var channels : list[MediaChannel] | None
var context : ContextObject | None
var countries : list[str] | None
var ext : ExtensionObject | None
var languages : list[str] | None
var model_config
var pagination : PaginationRequest | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListContentStandardsSuccessResponse (**data: Any)

Expand source code

class ListContentStandardsResponse1(AdCPBaseModel):
    standards: Annotated[
        list[content_standards.ContentStandards],
        Field(description='Array of content standards configurations matching the filter criteria'),
    ]
    pagination: pagination_response.PaginationResponse | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 pagination : PaginationResponse | None
var standards : list[ContentStandards]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListContentStandardsErrorResponse (**data: Any)

Expand source code

class ListContentStandardsResponse2(AdCPBaseModel):
    errors: list[error.Error]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListCreativeFormatsRequest (**data: Any)

Expand source code

class ListCreativeFormatsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Return only these specific format IDs (e.g., from get_products response)',
            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'. E.g., ['image', 'text'] returns formats with images and text, ['javascript'] returns formats accepting JavaScript tags.",
            min_length=1,
        ),
    ] = None
    max_width: Annotated[
        int | 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[
        int | 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[
        int | None,
        Field(
            description='Minimum width in pixels (inclusive). Returns formats where ANY render has width >= this value.'
        ),
    ] = None
    min_height: Annotated[
        int | None,
        Field(
            description='Minimum height in pixels (inclusive). Returns formats where ANY render has height >= this value.'
        ),
    ] = None
    is_responsive: Annotated[
        bool | 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
    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.FormatId] | 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.FormatId] | 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
    pagination: pagination_request.PaginationRequest | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
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 format_ids : list[FormatId] | None
var input_format_ids : list[FormatId] | 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[FormatId] | None
var pagination : PaginationRequest | None
var wcag_level : WcagLevel | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListCreativeFormatsResponse (**data: Any)

Expand source code

class ListCreativeFormatsResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    formats: Annotated[
        list[format.Format],
        Field(
            description="Full format definitions for all formats this agent supports. Each format's authoritative source is indicated by its agent_url field."
        ),
    ]
    creative_agents: Annotated[
        list[CreativeAgent] | None,
        Field(
            description='Optional: Creative agents that provide additional formats. Buyers can recursively query these agents to discover more formats. No authentication required for list_creative_formats.'
        ),
    ] = 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[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 creative_agents : list[CreativeAgent] | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var formats : list[Format]
var model_config
var pagination : PaginationResponse | None
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListCreativesRequest (**data: Any)

Expand source code

class ListCreativesRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    filters: creative_filters.CreativeFilters | None = None
    sort: Annotated[Sort | None, Field(description='Sorting parameters')] = None
    pagination: pagination_request.PaginationRequest | None = None
    include_assignments: Annotated[
        bool | None, Field(description='Include package assignment information in response')
    ] = True
    include_snapshot: Annotated[
        bool | None,
        Field(
            description='Include a lightweight delivery snapshot per creative (lifetime impressions and last-served date). For detailed performance analytics, use get_creative_delivery.'
        ),
    ] = False
    include_items: Annotated[
        bool | None,
        Field(description='Include items for multi-asset formats like carousels and native ads'),
    ] = False
    include_variables: Annotated[
        bool | None,
        Field(
            description='Include dynamic content variable definitions (DCO slots) for each creative'
        ),
    ] = False
    include_pricing: Annotated[
        bool | None,
        Field(
            description='Include pricing_options on each creative. Requires account to be provided. When false or omitted, pricing is not computed.'
        ),
    ] = False
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description="Account reference for pricing and access. When provided with include_pricing, the agent returns pricing_options from this account's rate card on each creative."
        ),
    ] = None
    fields: Annotated[
        list[Field1] | None,
        Field(
            description="Specific fields to include in response (omit for all fields). The 'concept' value returns both concept_id and concept_name.",
            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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var fields : list[Field1] | None
var filters : CreativeFilters | None
var include_assignments : bool | None
var include_items : bool | None
var include_pricing : bool | None
var include_snapshot : bool | None
var include_variables : bool | None
var model_config
var pagination : PaginationRequest | None
var sort : Sort | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListCreativesResponse (**data: Any)

Expand source code

class ListCreativesResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    query_summary: Annotated[
        QuerySummary, Field(description='Summary of the query that was executed')
    ]
    pagination: pagination_response.PaginationResponse
    creatives: Annotated[
        list[Creative], Field(description='Array of creative assets matching the query')
    ]
    format_summary: Annotated[
        dict[Annotated[str, StringConstraints(pattern=r'^[a-zA-Z0-9_-]+$')], int] | None,
        Field(
            description="Breakdown of creatives by format. Keys are agent-defined format identifiers, optionally including dimensions (e.g., 'display_static_300x250', 'video_30s_vast'). Key construction is platform-specific — there is no required format."
        ),
    ] = None
    status_summary: Annotated[
        StatusSummary | None, Field(description='Breakdown of creatives by status')
    ] = None
    errors: Annotated[
        list[error.Error] | None,
        Field(description='Task-specific errors (e.g., invalid filters, account not found)'),
    ] = None
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 creatives : list[Creative]
var errors : list[Error] | None
var ext : ExtensionObject | None
var format_summary : dict[str, int] | None
var model_config
var pagination : PaginationResponse
var query_summary : QuerySummary
var sandbox : bool | None
var status_summary : StatusSummary | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListPropertyListsRequest (**data: Any)

Expand source code

class ListPropertyListsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Filter to lists owned by this account. When omitted, returns lists across all accounts accessible to the authenticated agent.'
        ),
    ] = None
    name_contains: Annotated[
        str | None, Field(description='Filter to lists whose name contains this string')
    ] = None
    pagination: pagination_request.PaginationRequest | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var name_contains : str | None
var pagination : PaginationRequest | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ListPropertyListsResponse (**data: Any)

Expand source code

class ListPropertyListsResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    lists: Annotated[
        list[property_list.PropertyList],
        Field(description='Array of property lists (metadata only, not resolved properties)'),
    ]
    pagination: pagination_response.PaginationResponse | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 lists : list[PropertyList]
var model_config
var pagination : PaginationResponse | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class LogEventRequest (**data: Any)

Expand source code

class LogEventRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
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

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class LogEventSuccessResponse (**data: Any)

Expand source code

class LogEventResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    events_received: Annotated[int, Field(description='Number of events received', ge=0)]
    events_processed: Annotated[
        int, Field(description='Number of events successfully queued for processing', ge=0)
    ]
    partial_failures: Annotated[
        list[PartialFailure] | None, Field(description='Events that failed validation')
    ] = None
    warnings: Annotated[
        list[str] | None,
        Field(
            description='Non-fatal issues (low match quality, missing recommended fields, deprecation notices)'
        ),
    ] = None
    match_quality: Annotated[
        float | None,
        Field(
            description='Overall match quality score for the batch (0.0 = no matches, 1.0 = all matched)',
            ge=0.0,
            le=1.0,
        ),
    ] = None
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 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

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class LogEventErrorResponse (**data: Any)

Expand source code

class LogEventResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[list[error.Error], Field(description='Operation-level errors', min_length=1)]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Logo (**data: Any)

Expand source code

class Logo(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='URL to the logo asset')]
    orientation: Annotated[
        Orientation | None, Field(description='Logo aspect ratio orientation')
    ] = None
    background: Annotated[Background | None, Field(description='Background compatibility')] = None
    variant: Annotated[Variant | None, Field(description='Logo variant type')] = None
    tags: Annotated[list[str] | None, Field(description='Additional semantic tags')] = None
    usage: Annotated[str | None, Field(description='When to use this logo variant')] = None
    width: Annotated[int | None, Field(description='Width in pixels')] = None
    height: Annotated[int | None, Field(description='Height in pixels')] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var background : Background | None
var height : int | None
var model_config
var orientation : Orientation | None
var tags : list[str] | None
var url : pydantic.networks.AnyUrl
var usage : str | None
var variant : Variant | None
var width : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MarkdownFlavor (*args, **kwds)

Expand source code

class MarkdownFlavor(Enum):
    commonmark = 'commonmark'
    gfm = 'gfm'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var commonmark
var gfm

class McpWebhookPayload (**data: Any)

Expand source code

class McpWebhookPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    idempotency_key: Annotated[
        str,
        Field(
            description="Sender-generated key stable across retries of the same webhook event. Publishers MUST generate a cryptographically random value (UUID v4 recommended) per distinct event and reuse the same key on every retry of that event. Receivers MUST dedupe by this key, scoped to the authenticated sender identity (HMAC secret or Bearer credential) — keys from different publishers are independent. This is the canonical dedup field — the (task_id, status, timestamp) tuple is insufficient when a single transition is retried with unchanged timestamp or when two transitions share a timestamp.",
            max_length=255,
            min_length=16,
            pattern="^[A-Za-z0-9_.:-]{16,255}$",
        ),
    ]
    operation_id: Annotated[
        str | None,
        Field(
            description="Client-generated identifier that was embedded in the webhook URL by the buyer. Publishers echo this back in webhook payloads so clients can correlate notifications without parsing URL paths. Typically generated as a unique ID per task invocation."
        ),
    ] = None
    task_id: Annotated[
        str,
        Field(
            description="Unique identifier for this task. Use this to correlate webhook notifications with the original task submission."
        ),
    ]
    task_type: Annotated[
        task_type_1.TaskType,
        Field(
            description="Type of AdCP operation that triggered this webhook. Enables webhook handlers to route to appropriate processing logic."
        ),
    ]
    protocol: Annotated[
        adcp_protocol.AdcpProtocol | None,
        Field(
            description="AdCP protocol this task belongs to. Helps classify the operation type at a high level."
        ),
    ] = None
    status: Annotated[
        task_status.TaskStatus,
        Field(
            description="Current task status. Webhooks are triggered for status changes after initial submission."
        ),
    ]
    timestamp: Annotated[
        AwareDatetime, Field(description="ISO 8601 timestamp when this webhook was generated.")
    ]
    message: Annotated[
        str | None,
        Field(
            description="Human-readable summary of the current task state. Provides context about what happened and what action may be needed."
        ),
    ] = None
    context_id: Annotated[
        str | None,
        Field(
            description="Session/conversation identifier. Use this to continue the conversation if input-required status needs clarification or additional parameters."
        ),
    ] = None
    result: Annotated[
        async_response_data.AdcpAsyncResponseData | None,
        Field(
            description="Task-specific payload matching the status. For completed/failed, contains the full task response. For working/input-required/submitted, contains status-specific data. This is the data layer that AdCP specs - same structure used in A2A status.message.parts[].data."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_id : str | None
var idempotency_key : str
var message : str | None
var model_config
var operation_id : str | None
var protocol : AdcpProtocol | None
var result : AdcpAsyncResponseData | None
var status : TaskStatus
var task_id : str
var task_type : TaskType
var timestamp : pydantic.types.AwareDatetime

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MeasurementPeriod (**data: Any)

Expand source code

class MeasurementPeriod(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    start: Annotated[
        AwareDatetime, Field(description='ISO 8601 start timestamp for measurement period')
    ]
    end: Annotated[
        AwareDatetime, Field(description='ISO 8601 end timestamp for measurement period')
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var end : pydantic.types.AwareDatetime
var model_config
var start : pydantic.types.AwareDatetime

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MediaBuy (**data: Any)

Expand source code

class MediaBuy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buy_id: Annotated[str, Field(description="Seller's unique identifier for the media buy")]
    account: Annotated[
        account_1.Account | None, Field(description='Account billed for this media buy')
    ] = None
    status: media_buy_status.MediaBuyStatus
    rejection_reason: Annotated[
        str | None,
        Field(
            description="Reason provided by the seller when status is 'rejected'. Present only when status is 'rejected'."
        ),
    ] = None
    confirmed_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when the seller confirmed this media buy. A successful create_media_buy response constitutes order confirmation.'
        ),
    ] = None
    cancellation: Annotated[
        Cancellation | None,
        Field(description="Cancellation metadata. Present only when status is 'canceled'."),
    ] = None
    total_budget: Annotated[float, Field(description='Total budget amount', ge=0.0)]
    packages: Annotated[
        list[package.Package], Field(description='Array of packages within this media buy')
    ]
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description="Per-buy override for who receives the invoice. When provided, the seller invoices this entity instead of the account's default billing_entity. The seller MUST validate the invoice recipient is authorized for this account. When governance_agents are configured, the seller MUST include invoice_recipient in the check_governance request."
        ),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None, Field(description='ISO 8601 timestamp for creative upload deadline')
    ] = None
    revision: Annotated[
        int | None,
        Field(
            description='Monotonically increasing revision number. Incremented on every state change or update. Callers MAY include this in update_media_buy requests for optimistic concurrency — sellers MUST reject with CONFLICT if the provided revision does not match the current value.',
            ge=1,
        ),
    ] = None
    created_at: Annotated[AwareDatetime | None, Field(description='Creation timestamp')] = None
    updated_at: Annotated[AwareDatetime | None, Field(description='Last update timestamp')] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : Account | None
var cancellation : Cancellation | None
var confirmed_at : pydantic.types.AwareDatetime | None
var created_at : pydantic.types.AwareDatetime | None
var creative_deadline : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var invoice_recipient : BusinessEntity | None
var media_buy_id : str
var model_config
var packages : list[Package]
var rejection_reason : str | None
var revision : int | None
var status : MediaBuyStatus
var total_budget : float
var updated_at : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MediaBuyDelivery (**data: Any)

Expand source code

class MediaBuyDelivery(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buy_id: Annotated[str, Field(description="Seller's media buy identifier")]
    status: Annotated[
        Status,
        Field(
            description='Current media buy status. Lifecycle states use the same taxonomy as media-buy-status (`pending_creatives`, `pending_start`, `active`, `paused`, `completed`, `rejected`, `canceled`). In webhook context, reporting_delayed indicates data temporarily unavailable. `pending` is accepted as a legacy alias for pending_start.'
        ),
    ]
    expected_availability: Annotated[
        AwareDatetime | None,
        Field(
            description='When delayed data is expected to be available (only present when status is reporting_delayed)'
        ),
    ] = None
    is_adjusted: Annotated[
        bool | None,
        Field(
            description='Indicates this delivery contains updated data for a previously reported period. Buyer should replace previous period data with these totals.'
        ),
    ] = None
    pricing_model: Annotated[
        pricing_model_1.PricingModel | None,
        Field(description='Pricing model used for this media buy'),
    ] = None
    totals: Totals
    by_package: Annotated[list[ByPackageItem], Field(description='Metrics broken down by package')]
    daily_breakdown: Annotated[
        list[DailyBreakdownItem1] | None, Field(description='Day-by-day delivery')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var by_package : list[ByPackageItem]
var daily_breakdown : list[DailyBreakdownItem1] | None
var expected_availability : pydantic.types.AwareDatetime | None
var is_adjusted : bool | None
var media_buy_id : str
var model_config
var pricing_model : PricingModel | None
var status : Status
var totals : Totals

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MediaBuyStatus (*args, **kwds)

Expand source code

class MediaBuyStatus(Enum):
    pending_creatives = 'pending_creatives'
    pending_start = 'pending_start'
    active = 'active'
    paused = 'paused'
    completed = 'completed'
    rejected = 'rejected'
    canceled = 'canceled'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var active
var canceled
var completed
var paused
var pending_creatives
var pending_start
var rejected

class MediaChannel (*args, **kwds)

Expand source code

class MediaChannel(Enum):
    display = 'display'
    olv = 'olv'
    social = 'social'
    search = 'search'
    ctv = 'ctv'
    linear_tv = 'linear_tv'
    radio = 'radio'
    streaming_audio = 'streaming_audio'
    podcast = 'podcast'
    dooh = 'dooh'
    ooh = 'ooh'
    print = 'print'
    cinema = 'cinema'
    email = 'email'
    gaming = 'gaming'
    retail_media = 'retail_media'
    influencer = 'influencer'
    affiliate = 'affiliate'
    product_placement = 'product_placement'
    sponsored_intelligence = 'sponsored_intelligence'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var affiliate
var cinema
var ctv
var display
var dooh
var email
var gaming
var influencer
var linear_tv
var olv
var ooh
var podcast
var print
var product_placement
var radio
var retail_media
var search
var social
var sponsored_intelligence
var streaming_audio

class MediaSubAsset (*args: object, **kwargs: object)

Expand source code

class MediaSubAsset:
    """Removed from ADCP schema. Previously SubAsset with asset_kind='media'."""

    def __init__(self, *args: object, **kwargs: object) -> None:
        raise TypeError(
            "MediaSubAsset was removed from the ADCP schema. " "There is no direct replacement."
        )

Removed from ADCP schema. Previously SubAsset with asset_kind='media'.

class Member (**data: Any)

Expand source code

class Member(BaseModel):
    """An organization registered in the AAO member directory."""

    model_config = ConfigDict(extra="allow")

    id: str
    slug: str
    display_name: str
    description: str | None = None
    tagline: str | None = None
    logo_url: str | None = None
    logo_light_url: str | None = None
    logo_dark_url: str | None = None
    contact_email: str | None = None
    contact_website: str | None = None
    offerings: list[str] = Field(default_factory=list)
    markets: list[str] = Field(default_factory=list)
    agents: list[dict[str, Any]] = Field(default_factory=list)
    brands: list[dict[str, Any]] = Field(default_factory=list)
    is_public: bool = True
    is_founding_member: bool = False
    featured: bool = False
    si_enabled: bool = False

An organization registered in the AAO member directory.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var agents : list[dict[str, typing.Any]]
var brands : list[dict[str, typing.Any]]
var contact_email : str | None
var contact_website : str | None
var description : str | None
var display_name : str
var featured : bool
var id : str
var is_founding_member : bool
var is_public : bool
var logo_dark_url : str | None
var logo_light_url : str | None
var logo_url : str | None
var markets : list[str]
var model_config
var offerings : list[str]
var si_enabled : bool
var slug : str
var tagline : str | None

class Metadata (**data: Any)

Expand source code

class Metadata(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    canonical: Annotated[AnyUrl | None, Field(description='Canonical URL')] = None
    author: Annotated[str | None, Field(description='Artifact author name')] = None
    keywords: Annotated[str | None, Field(description='Artifact keywords')] = None
    open_graph: Annotated[
        dict[str, Any] | None, Field(description='Open Graph protocol metadata')
    ] = None
    twitter_card: Annotated[dict[str, Any] | None, Field(description='Twitter Card metadata')] = (
        None
    )
    json_ld: Annotated[
        list[dict[str, Any]] | None, Field(description='JSON-LD structured data (schema.org)')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var author : str | None
var canonical : pydantic.networks.AnyUrl | None
var json_ld : list[dict[str, typing.Any]] | None
var keywords : str | None
var model_config
var open_graph : dict[str, typing.Any] | None
var twitter_card : dict[str, typing.Any] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class MetricType (*args, **kwds)

Expand source code

class MetricType(Enum):
    overall_performance = 'overall_performance'
    conversion_rate = 'conversion_rate'
    brand_lift = 'brand_lift'
    click_through_rate = 'click_through_rate'
    completion_rate = 'completion_rate'
    viewability = 'viewability'
    brand_safety = 'brand_safety'
    cost_efficiency = 'cost_efficiency'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var brand_lift
var brand_safety
var click_through_rate
var completion_rate
var conversion_rate
var cost_efficiency
var overall_performance
var viewability

class NotificationType (*args, **kwds)

Expand source code

class NotificationType(Enum):
    scheduled = 'scheduled'
    final = 'final'
    delayed = 'delayed'
    adjusted = 'adjusted'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var adjusted
var delayed
var final
var scheduled

class TmpOffer (**data: Any)

Expand source code

class Offer(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description='Package identifier from the media buy.')]
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand for this offer. Required when the product allows dynamic brands (brand selected at match time rather than fixed on the package). For single-brand packages, the brand is already known from the media buy.'
        ),
    ] = None
    price: Annotated[
        offer_price.OfferPrice | None,
        Field(
            description='Price for this offer. Only present when the product supports variable pricing. For fixed-price packages, price is already set on the media buy.'
        ),
    ] = None
    summary: Annotated[
        str | None,
        Field(
            description="Buyer-generated description of the offer, for the publisher to judge relevance. E.g., '50% off Goldenfield mayo — recipe integration'. The publisher (or their AI assistant) uses this to decide whether the offer fits the context."
        ),
    ] = None
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest | None,
        Field(
            description='Full creative details, inline. When present, the publisher has everything needed to render. Inline for small creatives (markdown, product card). For large creatives (VAST, video), the manifest references external assets via URLs.'
        ),
    ] = None
    macros: Annotated[
        dict[str, str] | None,
        Field(
            description='Key-value pairs the buyer passes for dynamic creative rendering or attribution tracking. In the GAM case, these flow as macro values. Not tied to user identity — attribution reconciliation happens via delivery reporting or clean room.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var brand : BrandReference | None
var creative_manifest : CreativeManifest | None
var macros : dict[str, str] | None
var model_config
var package_id : str
var price : OfferPrice | None
var summary : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class OfferPrice (**data: Any)

Expand source code

class OfferPrice(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    amount: Annotated[float, Field(description='Price amount in the specified currency', ge=0.0)]
    currency: Annotated[
        str | None, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')
    ] = 'USD'
    model: Annotated[Model, Field(description='Pricing model for this offer')]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var amount : float
var currency : str | None
var model : Model
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Offering (**data: Any)

Expand source code

class Offering(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    offering_id: Annotated[
        str,
        Field(
            description='Unique identifier for this offering. Used by hosts to reference specific offerings in si_get_offering calls.'
        ),
    ]
    name: Annotated[
        str,
        Field(
            description="Human-readable offering name (e.g., 'Winter Sale', 'Free Trial', 'Enterprise Platform')"
        ),
    ]
    description: Annotated[str | None, Field(description="Description of what's being offered")] = (
        None
    )
    tagline: Annotated[
        str | None, Field(description='Short promotional tagline for the offering')
    ] = None
    valid_from: Annotated[
        AwareDatetime | None,
        Field(
            description='When the offering becomes available. If not specified, offering is immediately available.'
        ),
    ] = None
    valid_to: Annotated[
        AwareDatetime | None,
        Field(
            description='When the offering expires. If not specified, offering has no expiration.'
        ),
    ] = None
    checkout_url: Annotated[
        AnyUrl | None,
        Field(
            description="URL for checkout/purchase flow when the brand doesn't support agentic checkout."
        ),
    ] = None
    landing_url: Annotated[
        AnyUrl | None,
        Field(
            description="Landing page URL for this offering. For catalog-driven creatives, this is the per-item click-through destination that platforms map to the ad's link-out URL. Every offering in a catalog should have a landing_url unless the format provides its own destination logic."
        ),
    ] = None
    assets: Annotated[
        list[offering_asset_group.OfferingAssetGroup] | None,
        Field(
            description='Structured asset groups for this offering. Each group carries a typed pool of creative assets (headlines, images, videos, etc.) identified by a group ID that matches format-level vocabulary.'
        ),
    ] = None
    geo_targets: Annotated[
        GeoTargets | None,
        Field(
            description="Geographic scope of this offering. Declares where the offering is relevant — for location-specific offerings such as job vacancies, in-store promotions, or local events. Platforms use this to target geographically appropriate audiences and to filter out offerings irrelevant to a user's location. Uses the same geographic structures as targeting_overlay in create_media_buy."
        ),
    ] = None
    keywords: Annotated[
        list[str] | None,
        Field(
            description='Keywords for matching this offering to user intent. Hosts use these for retrieval/relevance scoring.'
        ),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Categories this offering belongs to (e.g., 'measurement', 'identity', 'programmatic')"
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var assets : list[OfferingAssetGroup] | None
var categories : list[str] | None
var checkout_url : pydantic.networks.AnyUrl | None
var description : str | None
var ext : ExtensionObject | None
var geo_targets : GeoTargets | None
var keywords : list[str] | None
var landing_url : pydantic.networks.AnyUrl | None
var model_config
var name : str
var offering_id : str
var tagline : str | None
var valid_from : pydantic.types.AwareDatetime | None
var valid_to : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class OfferingAssetConstraint (**data: Any)

Expand source code

class OfferingAssetConstraint(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_group_id: Annotated[
        str,
        Field(
            description="The asset group this constraint applies to. Values are format-defined vocabulary — each format chooses its own group IDs (e.g., 'headlines', 'images', 'videos'). Buyers discover them via list_creative_formats."
        ),
    ]
    asset_type: Annotated[
        asset_content_type.AssetContentType,
        Field(description='The expected content type for this group.'),
    ]
    required: Annotated[
        bool | None,
        Field(
            description='Whether this asset group must be present in each offering. Defaults to true.'
        ),
    ] = True
    min_count: Annotated[
        int | None, Field(description='Minimum number of items required in this group.', ge=1)
    ] = None
    max_count: Annotated[
        int | None, Field(description='Maximum number of items allowed in this group.', ge=1)
    ] = None
    asset_requirements: Annotated[
        asset_requirements_1.AssetRequirements | None,
        Field(
            description='Technical requirements for each item in this group (e.g., max_length for text, min_width/aspect_ratio for images). Applies uniformly to all items in the group.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var asset_group_id : str
var asset_requirements : AssetRequirements | None
var asset_type : AssetContentType
var ext : ExtensionObject | None
var max_count : int | None
var min_count : int | None
var model_config
var required : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class OfferingAssetGroup (**data: Any)

Expand source code

class OfferingAssetGroup(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    asset_group_id: Annotated[
        str,
        Field(
            description="Identifies the creative role this group fills. Values are defined by each format's offering_asset_constraints — not protocol constants. Discover them via list_creative_formats (e.g., a format might declare 'headlines', 'images', or 'videos')."
        ),
    ]
    asset_type: Annotated[
        asset_content_type.AssetContentType,
        Field(description='The content type of all items in this group.'),
    ]
    items: Annotated[
        list[
            text_asset.TextAsset
            | image_asset.ImageAsset
            | video_asset.VideoAsset
            | audio_asset.AudioAsset
            | url_asset.UrlAsset
            | html_asset.HtmlAsset
            | markdown_asset.MarkdownAsset
            | vast_asset.VastAsset
            | daast_asset.DaastAsset
            | css_asset.CssAsset
            | javascript_asset.JavascriptAsset
            | webhook_asset.WebhookAsset
        ],
        Field(
            description='The assets in this group. Each item should match the structure for the declared asset_type. Note: JSON Schema validation accepts any valid asset structure here; enforcement that items match asset_type is the responsibility of the consuming agent.',
            min_length=1,
        ),
    ]
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var asset_group_id : str
var asset_type : AssetContentType
var ext : ExtensionObject | None
var items : list[TextAsset | ImageAsset | VideoAsset | AudioAsset | UrlAsset | HtmlAsset | MarkdownAsset | VastAsset | DaastAsset | CssAsset | JavascriptAsset | WebhookAsset]
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class OptimizationGoal (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class OptimizationGoal(RootModel[OptimizationGoal1 | OptimizationGoal2]):
    root: Annotated[
        OptimizationGoal1 | OptimizationGoal2,
        Field(
            description='A single optimization target for a package. Packages accept an array of optimization_goals. When multiple goals are present, priority determines which the seller focuses on — 1 is highest priority (primary goal); higher numbers are secondary. Duplicate priority values result in undefined seller behavior.',
            title='Optimization Goal',
        ),
    ]

    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[Union[OptimizationGoal1, OptimizationGoal2]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : OptimizationGoal1 | OptimizationGoal2

class OutcomeMeasurement (**data: Any)

Expand source code

class OutcomeMeasurement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        str,
        Field(
            description='Type of measurement',
            examples=['incremental_sales_lift', 'brand_lift', 'foot_traffic'],
        ),
    ]
    attribution: Annotated[
        str,
        Field(
            description='Attribution methodology',
            examples=['deterministic_purchase', 'probabilistic'],
        ),
    ]
    window: Annotated[
        duration.Duration | None,
        Field(
            description='Attribution window as a structured duration (e.g., {"interval": 30, "unit": "days"}).'
        ),
    ] = None
    reporting: Annotated[
        str,
        Field(
            description='Reporting frequency and format',
            examples=['weekly_dashboard', 'real_time_api'],
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var attribution : str
var model_config
var reporting : str
var type : str
var window : Duration | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Overlay (**data: Any)

Expand source code

class Overlay(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    id: Annotated[
        str,
        Field(
            description="Identifier for this overlay (e.g., 'play_pause', 'volume', 'publisher_logo', 'carousel_prev', 'carousel_next')"
        ),
    ]
    description: Annotated[
        str | None,
        Field(
            description='Human-readable explanation of what this overlay is and how buyers should account for it'
        ),
    ] = None
    visual: Annotated[
        Visual | None,
        Field(
            description='Optional visual reference for this overlay element. Useful for creative agents compositing previews and for buyers understanding what will appear over their content. Must include at least one of: url, light, or dark.'
        ),
    ] = None
    bounds: Annotated[
        Bounds,
        Field(
            description="Position and size of the overlay relative to the asset's own top-left corner. See 'unit' for coordinate interpretation."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var bounds : Bounds
var description : str | None
var id : str
var model_config
var visual : Visual | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Pacing (*args, **kwds)

Expand source code

class Pacing(Enum):
    even = 'even'
    asap = 'asap'
    front_loaded = 'front_loaded'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var asap
var even
var front_loaded

class MediaBuyPackage (**data: Any)

Expand source code

class Package(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description="Seller's package identifier")]
    product_id: Annotated[
        str | None, Field(description='Product identifier this package is purchased from')
    ] = None
    budget: Annotated[
        float | None,
        Field(
            description='Package budget amount, denominated in package.currency when present, otherwise media_buy.currency',
            ge=0.0,
        ),
    ] = None
    currency: Annotated[
        str | None,
        Field(
            description='ISO 4217 currency code for monetary values at this package level (budget, bid_price, snapshot.spend). When absent, inherit media_buy.currency.',
            pattern='^[A-Z]{3}$',
        ),
    ] = None
    bid_price: Annotated[
        float | None,
        Field(
            description='Current bid price for auction-based packages. Denominated in package.currency when present, otherwise media_buy.currency. Relevant for automated price optimization loops.',
            ge=0.0,
        ),
    ] = None
    impressions: Annotated[
        float | None,
        Field(description='Goal impression count for impression-based packages', ge=0.0),
    ] = 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[
        bool | None, Field(description='Whether this package is currently paused by the buyer')
    ] = None
    canceled: Annotated[
        bool | None,
        Field(
            description='Whether this package has been canceled. Canceled packages stop delivery and cannot be reactivated.'
        ),
    ] = None
    cancellation: Annotated[
        Cancellation2 | 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
    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
    format_ids_pending: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Format IDs from the original create_media_buy format_ids_to_provide that have not yet been uploaded via sync_creatives. When empty or absent, all required formats have been provided.'
        ),
    ] = None
    snapshot_unavailable_reason: Annotated[
        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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 budget : float | None
var canceled : bool | None
var cancellation : Cancellation2 | None
var creative_approvals : list[CreativeApproval] | None
var creative_deadline : pydantic.types.AwareDatetime | None
var currency : str | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var format_ids_pending : list[FormatId] | None
var impressions : float | None
var model_config
var package_id : str
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

class Package (**data: Any)

Expand source code

class Package(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    package_id: Annotated[str, Field(description="Seller's unique identifier for the package")]
    product_id: Annotated[
        str | None, Field(description='ID of the product this package is based on')
    ] = None
    budget: Annotated[
        float | None,
        Field(
            description='Budget allocation for this package in the currency specified by the pricing option',
            ge=0.0,
        ),
    ] = None
    pacing: pacing_1.Pacing | None = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="ID of the selected pricing option from the product's pricing_options array"
        ),
    ] = None
    bid_price: Annotated[
        float | None,
        Field(
            description="Bid price for auction-based pricing. This is the exact bid/price to honor unless the selected pricing option has max_bid=true, in which case bid_price is the buyer's maximum willingness to pay (ceiling).",
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description="Breakdown of the effective price for this package. On fixed-price packages, echoes the pricing option's breakdown. On auction packages, shows the clearing price breakdown including any commission or settlement terms."
        ),
    ] = None
    impressions: Annotated[
        float | None, Field(description='Impression goal for this package', ge=0.0)
    ] = None
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description='Catalogs this package promotes. Each catalog MUST have a distinct type (e.g., one product catalog, one store catalog). This constraint is enforced at the application level — sellers MUST reject requests containing multiple catalogs of the same type with a validation_error. Echoed from the create_media_buy request.'
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Format IDs active for this package. Echoed from the create_media_buy request; omitted means all formats for the product are active.'
        ),
    ] = None
    targeting_overlay: targeting.TargetingOverlay | None = None
    measurement_terms: Annotated[
        measurement_terms_1.MeasurementTerms | None,
        Field(
            description="Agreed billing measurement and makegood terms for this package. Reflects what was negotiated — may differ from the buyer's proposal or the product's defaults. When present, these terms are binding for the package's duration."
        ),
    ] = None
    performance_standards: Annotated[
        list[performance_standard.PerformanceStandard] | None,
        Field(
            description='Agreed performance standards for this package. When any entry specifies a vendor, creatives assigned to this package MUST include corresponding tracker_script or tracker_pixel assets from that vendor.',
            min_length=1,
        ),
    ] = None
    creative_assignments: Annotated[
        list[creative_assignment.CreativeAssignment] | None,
        Field(description='Creative assets assigned to this package'),
    ] = None
    format_ids_to_provide: Annotated[
        list[format_id.FormatId] | None,
        Field(description='Format IDs that creative assets will be provided for this package'),
    ] = None
    optimization_goals: Annotated[
        list[optimization_goal.OptimizationGoal] | None,
        Field(
            description='Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.',
            min_length=1,
        ),
    ] = None
    start_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Flight start date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's start_time. Sellers SHOULD always include the resolved value in responses, even when inherited."
        ),
    ] = None
    end_time: Annotated[
        AwareDatetime | None,
        Field(
            description="Flight end date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's end_time. Sellers SHOULD always include the resolved value in responses, even when inherited."
        ),
    ] = None
    paused: Annotated[
        bool | None,
        Field(
            description='Whether this package is paused by the buyer. Paused packages do not deliver impressions. Defaults to false.'
        ),
    ] = False
    canceled: Annotated[
        bool | None,
        Field(
            description='Whether this package has been canceled. Canceled packages stop delivery and cannot be reactivated. Defaults to false.'
        ),
    ] = False
    cancellation: Annotated[
        Cancellation | None,
        Field(description='Cancellation metadata. Present only when canceled is true.'),
    ] = None
    agency_estimate_number: Annotated[
        str | None,
        Field(
            description="Agency estimate or authorization number for this package. Echoed from the buyer's request. When present on the package, takes precedence over the media buy-level estimate number.",
            max_length=100,
        ),
    ] = None
    creative_deadline: Annotated[
        AwareDatetime | None,
        Field(
            description="ISO 8601 timestamp for creative upload or change deadline for this package. After this deadline, creative changes are rejected. When absent, the media buy's creative_deadline applies."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 bid_price : float | None
var budget : float | None
var canceled : bool | None
var cancellation : Cancellation | None
var catalogs : list[Catalog] | None
var context : ContextObject | None
var creative_assignments : list[CreativeAssignment] | None
var creative_deadline : pydantic.types.AwareDatetime | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var format_ids : list[FormatId] | None
var format_ids_to_provide : list[FormatId] | None
var impressions : float | None
var measurement_terms : MeasurementTerms | None
var model_config
var optimization_goals : list[OptimizationGoal] | None
var pacing : Pacing | None
var package_id : str
var paused : bool | None
var performance_standards : list[PerformanceStandard] | None
var price_breakdown : PriceBreakdown | None
var pricing_option_id : str | None
var product_id : str | None
var start_time : pydantic.types.AwareDatetime | None
var targeting_overlay : TargetingOverlay | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PackageRequest (**data: Any)

Expand source code

class PackageRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    product_id: Annotated[str, Field(description='Product ID for this package')]
    format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Array of format IDs that will be used for this package - must be supported by the product. If omitted, defaults to all formats supported by the product.',
            min_length=1,
        ),
    ] = None
    budget: Annotated[
        float,
        Field(description="Budget allocation for this package in the media buy's currency", ge=0.0),
    ]
    pacing: pacing_1.Pacing | None = None
    pricing_option_id: Annotated[
        str,
        Field(
            description="ID of the selected pricing option from the product's pricing_options array"
        ),
    ]
    bid_price: Annotated[
        float | None,
        Field(
            description="Bid price for auction-based pricing options. This is the exact bid/price to honor unless selected pricing_option has max_bid=true, in which case bid_price is the buyer's maximum willingness to pay (ceiling).",
            ge=0.0,
        ),
    ] = None
    impressions: Annotated[
        float | None, Field(description='Impression goal for this package', 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[
        bool | 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: targeting.TargetingOverlay | None = 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
    creative_assignments: Annotated[
        list[creative_assignment.CreativeAssignment] | None,
        Field(
            description='Assign existing library creatives to this package with optional weights and placement targeting',
            min_length=1,
        ),
    ] = None
    creatives: Annotated[
        list[creative_asset.CreativeAsset] | None,
        Field(
            description='Upload new creative assets and assign to this package (creatives will be added to library). 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: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var agency_estimate_number : str | None
var bid_price : float | None
var budget : float
var catalogs : list[Catalog] | None
var context : ContextObject | None
var creative_assignments : list[CreativeAssignment] | None
var creatives : list[CreativeAsset] | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var format_ids : list[FormatId] | None
var impressions : float | None
var measurement_terms : MeasurementTerms | None
var model_config
var optimization_goals : list[OptimizationGoal] | None
var pacing : Pacing | 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 : TargetingOverlay | None

Inherited members

AdCPBaseModel:
- 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[
        float | None,
        Field(
            description='Updated budget allocation for this package in the currency specified by the pricing option',
            ge=0.0,
        ),
    ] = None
    pacing: pacing_1.Pacing | None = None
    bid_price: Annotated[
        float | None,
        Field(
            description="Updated bid price for auction-based pricing options. This is the exact bid/price to honor unless selected pricing_option has max_bid=true, in which case bid_price is the buyer's maximum willingness to pay (ceiling).",
            ge=0.0,
        ),
    ] = None
    impressions: Annotated[
        float | None, Field(description='Updated impression goal for this package', 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[
        bool | None,
        Field(description='Pause/resume specific package (true = paused, false = active)'),
    ] = None
    canceled: Annotated[
        Literal[True],
        Field(
            description='Cancel this specific package. Cancellation is irreversible — canceled packages stop delivery and cannot be reactivated. Sellers MAY reject with NOT_CANCELLABLE.'
        ),
    ] = True
    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.TargetingOverlay | None,
        Field(
            description='Targeting overlay to apply to this package. Uses replacement semantics — the full overlay replaces the previous one. Omit to leave targeting unchanged. For keyword and negative keyword updates, prefer the incremental operations (keyword_targets_add, keyword_targets_remove, negative_keywords_add, negative_keywords_remove) which avoid replacing the full overlay. Sellers SHOULD return a validation error if targeting_overlay.keyword_targets is present in the same request as keyword_targets_add or keyword_targets_remove, and likewise for negative_keywords.'
        ),
    ] = 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 weights and placement targeting. Uses replacement semantics - omit to leave assignments unchanged.'
        ),
    ] = None
    creatives: Annotated[
        list[creative_asset.CreativeAsset] | None,
        Field(
            description='Upload new creative assets and assign to this package (creatives will be added to library). 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 budget : float | None
var canceled : Literal[True]
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 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 model_config
var negative_keywords_add : list[NegativeKeywordsAddItem] | None
var negative_keywords_remove : list[NegativeKeywordsRemoveItem] | None
var optimization_goals : list[OptimizationGoal] | None
var pacing : Pacing | None
var package_id : str
var paused : bool | None
var start_time : pydantic.types.AwareDatetime | None
var targeting_overlay : TargetingOverlay | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Pagination (**data: Any)

Expand source code

class Pagination(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    max_results: Annotated[
        int | None,
        Field(description='Maximum number of collections to return per page', ge=1, le=10000),
    ] = 1000
    cursor: Annotated[
        str | None,
        Field(description='Opaque cursor from a previous response to fetch the next page'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var max_results : int | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PaginationRequest (**data: Any)

Expand source code

class PaginationRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    max_results: Annotated[
        int | None, Field(description='Maximum number of items to return per page', ge=1, le=100)
    ] = 50
    cursor: Annotated[
        str | None,
        Field(description='Opaque cursor from a previous response to fetch the next page'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var max_results : int | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PaginationResponse (**data: Any)

Expand source code

class PaginationResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    has_more: Annotated[
        bool, Field(description='Whether more results are available beyond this page')
    ]
    cursor: Annotated[
        str | None,
        Field(
            description='Opaque cursor to pass in the next request to fetch the next page. Only present when has_more is true.'
        ),
    ] = None
    total_count: Annotated[
        int | None,
        Field(
            description='Total number of items matching the query across all pages. Optional because not all backends can efficiently compute this.',
            ge=0,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cursor : str | None
var has_more : bool
var model_config
var total_count : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Parameters (**data: Any)

Expand source code

class Parameters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    demographic_system: Annotated[
        demographic_system_1.DemographicSystem | None,
        Field(
            description='Measurement system for the demographic field. Defaults to nielsen when omitted.'
        ),
    ] = None
    demographic: Annotated[
        str,
        Field(
            description='Target demographic code within the specified demographic_system (e.g., P18-49 for Nielsen, ABC1 Adults for BARB)'
        ),
    ]
    min_points: Annotated[float | None, Field(description='Minimum GRPs/TRPs required', ge=0.0)] = (
        None
    )

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var demographic : str
var demographic_system : DemographicSystem | None
var min_points : float | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PerformanceFeedback (**data: Any)

Expand source code

class PerformanceFeedback(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    feedback_id: Annotated[
        str, Field(description='Unique identifier for this performance feedback submission')
    ]
    media_buy_id: Annotated[str, Field(description="Publisher's media buy identifier")]
    package_id: Annotated[
        str | None,
        Field(
            description='Specific package within the media buy (if feedback is package-specific)'
        ),
    ] = None
    creative_id: Annotated[
        str | None, Field(description='Specific creative asset (if feedback is creative-specific)')
    ] = None
    measurement_period: Annotated[
        MeasurementPeriod, Field(description='Time period for performance measurement')
    ]
    performance_index: Annotated[
        float,
        Field(
            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
            ge=0.0,
        ),
    ]
    metric_type: Annotated[
        metric_type_1.MetricType, Field(description='The business metric being measured')
    ]
    feedback_source: Annotated[
        feedback_source_1.FeedbackSource, Field(description='Source of the performance data')
    ]
    status: Annotated[Status, Field(description='Processing status of the performance feedback')]
    submitted_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when feedback was submitted')
    ]
    applied_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when feedback was applied to optimization algorithms'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var applied_at : pydantic.types.AwareDatetime | None
var creative_id : str | None
var feedback_id : str
var feedback_source : FeedbackSource
var measurement_period : MeasurementPeriod
var media_buy_id : str
var metric_type : MetricType
var model_config
var package_id : str | None
var performance_index : float
var status : Status
var submitted_at : pydantic.types.AwareDatetime

class Performance (**data: Any)

Expand source code

class PerformanceFeedback(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    feedback_id: Annotated[
        str, Field(description='Unique identifier for this performance feedback submission')
    ]
    media_buy_id: Annotated[str, Field(description="Publisher's media buy identifier")]
    package_id: Annotated[
        str | None,
        Field(
            description='Specific package within the media buy (if feedback is package-specific)'
        ),
    ] = None
    creative_id: Annotated[
        str | None, Field(description='Specific creative asset (if feedback is creative-specific)')
    ] = None
    measurement_period: Annotated[
        MeasurementPeriod, Field(description='Time period for performance measurement')
    ]
    performance_index: Annotated[
        float,
        Field(
            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
            ge=0.0,
        ),
    ]
    metric_type: Annotated[
        metric_type_1.MetricType, Field(description='The business metric being measured')
    ]
    feedback_source: Annotated[
        feedback_source_1.FeedbackSource, Field(description='Source of the performance data')
    ]
    status: Annotated[Status, Field(description='Processing status of the performance feedback')]
    submitted_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when feedback was submitted')
    ]
    applied_at: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when feedback was applied to optimization algorithms'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var applied_at : pydantic.types.AwareDatetime | None
var creative_id : str | None
var feedback_id : str
var feedback_source : FeedbackSource
var measurement_period : MeasurementPeriod
var media_buy_id : str
var metric_type : MetricType
var model_config
var package_id : str | None
var performance_index : float
var status : Status
var submitted_at : 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',
    )
    placement_id: Annotated[
        str, Field(description='Unique identifier for the placement within the product')
    ]
    name: Annotated[
        str,
        Field(
            description="Human-readable name for the placement (e.g., 'Homepage Banner', 'Article Sidebar')"
        ),
    ]
    description: Annotated[
        str | None, Field(description='Detailed description of where and how the placement appears')
    ] = None
    tags: Annotated[
        list[str] | None,
        Field(
            description="Optional tags for grouping placements within a product (e.g., 'homepage', 'native', 'premium'). When the placement_id comes from the publisher registry, these should align with the registry tags unless the product is narrowing scope."
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(
            description='Format IDs supported by this specific placement. Can include: (1) concrete format_ids (fixed dimensions), (2) template format_ids without parameters (accepts any dimensions/duration), or (3) parameterized format_ids (specific dimension/duration constraints).',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 model_config
var name : str
var placement_id : str
var tags : list[str] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Policy (**data: Any)

Expand source code

class Policy(PolicySummary):
    """Full governance policy including policy text and calibration exemplars."""

    policy: str
    guidance: str | None = None
    exemplars: PolicyExemplars | None = None
    ext: dict[str, Any] | None = None

Full governance policy including policy text and calibration exemplars.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

PolicySummary
pydantic.main.BaseModel

Class variables

var exemplars : PolicyExemplars | None
var ext : dict[str, typing.Any] | None
var guidance : str | None
var model_config
var policy : str

class PolicyExemplar (**data: Any)

Expand source code

class PolicyExemplar(BaseModel):
    """A pass/fail scenario used to calibrate governance agent interpretation."""

    model_config = ConfigDict(extra="allow")

    scenario: str
    explanation: str

A pass/fail scenario used to calibrate governance agent interpretation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var explanation : str
var model_config
var scenario : str

class PolicyExemplars (**data: Any)

Expand source code

class PolicyExemplars(BaseModel):
    """Collection of pass/fail exemplars for a policy."""

    model_config = ConfigDict(extra="allow")

    pass_: list[PolicyExemplar] = Field(default_factory=list, alias="pass")
    fail: list[PolicyExemplar] = Field(default_factory=list)

Collection of pass/fail exemplars for a policy.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var fail : list[PolicyExemplar]
var model_config
var pass_ : list[PolicyExemplar]

class PolicyHistory (**data: Any)

Expand source code

class PolicyHistory(BaseModel):
    """Edit history for a policy."""

    model_config = ConfigDict(extra="allow")

    policy_id: str
    total: int
    revisions: list[PolicyRevision] = Field(default_factory=list)

Edit history for a policy.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var model_config
var policy_id : str
var revisions : list[PolicyRevision]
var total : int

class PolicyRevision (**data: Any)

Expand source code

class PolicyRevision(BaseModel):
    """A single revision in a policy's edit history."""

    model_config = ConfigDict(extra="allow")

    revision_number: int
    editor_name: str
    edit_summary: str
    is_rollback: bool
    rolled_back_to: int | None = None
    created_at: str

A single revision in a policy's edit history.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var created_at : str
var edit_summary : str
var editor_name : str
var is_rollback : bool
var model_config
var revision_number : int
var rolled_back_to : int | None

class PolicySummary (**data: Any)

Expand source code

class PolicySummary(BaseModel):
    """Summary of a governance policy from the registry."""

    model_config = ConfigDict(extra="allow", populate_by_name=True)

    policy_id: str
    version: str
    name: str
    description: str | None = None
    category: str
    enforcement: str
    jurisdictions: list[str] = Field(default_factory=list)
    region_aliases: dict[str, list[str]] = Field(default_factory=dict)
    verticals: list[str] = Field(default_factory=list)
    channels: list[str] | None = None
    governance_domains: list[str] = Field(default_factory=list)
    effective_date: str | None = None
    sunset_date: str | None = None
    source_url: str | None = None
    source_name: str | None = None
    source_type: str | None = None
    review_status: str | None = None
    created_at: str | None = None
    updated_at: str | None = None

Summary of a governance policy from the registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Subclasses

Policy

Class variables

var category : str
var channels : list[str] | None
var created_at : str | None
var description : str | None
var effective_date : str | None
var enforcement : str
var governance_domains : list[str]
var jurisdictions : list[str]
var model_config
var name : str
var policy_id : str
var region_aliases : dict[str, list[str]]
var review_status : str | None
var source_name : str | None
var source_type : str | None
var source_url : str | None
var sunset_date : str | None
var updated_at : str | None
var version : str
var verticals : list[str]

class Preview (**data: Any)

Expand source code

class Preview(AdCPBaseModel):
    preview_id: Annotated[str, Field(description='Unique identifier for this preview variant')]
    renders: Annotated[
        list[preview_render.PreviewRender],
        Field(
            description='Array of rendered pieces for this preview variant. Most formats render as a single piece. Companion ad formats (video + banner), multi-placement formats, and adaptive formats render as multiple pieces.',
            min_length=1,
        ),
    ]
    input: Annotated[
        Input,
        Field(
            description='The input parameters that generated this preview variant. Echoes back the request input or shows defaults used.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var input : Input
var model_config
var preview_id : str
var renders : list[PreviewRender]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PreviewCreativeRequest (**data: Any)

Expand source code

class PreviewCreativeRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    request_type: Annotated[
        RequestType,
        Field(
            description="Preview mode. 'single' previews one creative manifest. 'batch' previews multiple creatives in one call. 'variant' replays a post-flight variant by ID."
        ),
    ]
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest | None,
        Field(
            description="Complete creative manifest with all required assets for the format. Required when request_type is 'single'. Also accepted per item in batch mode."
        ),
    ] = None
    format_id: Annotated[
        format_id_1.FormatId | None,
        Field(
            description='Format identifier for rendering the preview. Defaults to creative_manifest_1.format_id if omitted. Used in single mode.'
        ),
    ] = None
    inputs: Annotated[
        list[Input] | None,
        Field(
            description='Array of input sets for generating multiple preview variants. Each input set defines macros and context values for one preview rendering. Used in single mode.',
            min_length=1,
        ),
    ] = None
    template_id: Annotated[
        str | None,
        Field(description='Specific template ID for custom format rendering. Used in single mode.'),
    ] = None
    quality: Annotated[
        creative_quality.CreativeQuality | None,
        Field(
            description="Render quality. 'draft' produces fast, lower-fidelity renderings. 'production' produces full-quality renderings. In batch mode, sets the default for all requests (individual items can override)."
        ),
    ] = None
    output_format: Annotated[
        preview_output_format.PreviewOutputFormat | None,
        Field(
            description="Output format. 'url' returns preview_url (iframe-embeddable URL), 'html' returns preview_html (raw HTML). In batch mode, sets the default for all requests (individual items can override). Default: 'url'."
        ),
    ] = preview_output_format.PreviewOutputFormat.url
    item_limit: Annotated[
        int | None,
        Field(
            description='Maximum number of catalog items to render per preview variant. Used in single mode. Creative agents SHOULD default to a reasonable sample when omitted and the catalog is large.',
            ge=1,
        ),
    ] = None
    requests: Annotated[
        list[Request] | None,
        Field(
            description="Array of preview requests (1-50 items). Required when request_type is 'batch'. Each item follows the single request structure.",
            max_length=50,
            min_length=1,
        ),
    ] = None
    variant_id: Annotated[
        str | None,
        Field(
            description="Platform-assigned variant identifier from get_creative_delivery response. Required when request_type is 'variant'."
        ),
    ] = None
    creative_id: Annotated[
        str | None, Field(description='Creative identifier for context. Used in variant mode.')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var creative_id : str | None
var creative_manifest : CreativeManifest | None
var ext : ExtensionObject | None
var format_id : FormatId | None
var inputs : list[Input] | None
var item_limit : int | None
var model_config
var output_format : PreviewOutputFormat | None
var quality : CreativeQuality | None
var request_type : RequestType
var requests : list[Request] | None
var template_id : str | None
var variant_id : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PreviewCreativeSingleResponse (**data: Any)

Expand source code

class PreviewCreativeResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    response_type: Annotated[
        Literal['single'],
        Field(description='Discriminator indicating this is a single preview response'),
    ]
    previews: Annotated[
        list[Preview],
        Field(
            description='Array of preview variants. Each preview corresponds to an input set from the request. If no inputs were provided, returns a single default preview.',
            min_length=1,
        ),
    ]
    interactive_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional URL to an interactive testing page that shows all preview variants with controls to switch between them, modify macro values, and test different scenarios.'
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when preview links expire')
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 expires_at : pydantic.types.AwareDatetime
var ext : ExtensionObject | None
var interactive_url : pydantic.networks.AnyUrl | None
var model_config
var previews : list[Preview]
var response_type : Literal['single']

class PreviewCreativeStaticResponse (**data: Any)

Expand source code

class PreviewCreativeResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    response_type: Annotated[
        Literal['single'],
        Field(description='Discriminator indicating this is a single preview response'),
    ]
    previews: Annotated[
        list[Preview],
        Field(
            description='Array of preview variants. Each preview corresponds to an input set from the request. If no inputs were provided, returns a single default preview.',
            min_length=1,
        ),
    ]
    interactive_url: Annotated[
        AnyUrl | None,
        Field(
            description='Optional URL to an interactive testing page that shows all preview variants with controls to switch between them, modify macro values, and test different scenarios.'
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime, Field(description='ISO 8601 timestamp when preview links expire')
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 expires_at : pydantic.types.AwareDatetime
var ext : ExtensionObject | None
var interactive_url : pydantic.networks.AnyUrl | None
var model_config
var previews : list[Preview]
var response_type : Literal['single']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PreviewCreativeBatchResponse (**data: Any)

Expand source code

class PreviewCreativeResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    response_type: Annotated[
        Literal['batch'],
        Field(description='Discriminator indicating this is a batch preview response'),
    ]
    results: Annotated[
        list[Results | Results1],
        Field(
            description='Array of preview results corresponding to each request in the same order. results[0] is the result for requests[0], results[1] for requests[1], etc. Order is guaranteed even when some requests fail. Each result contains either a successful preview response or an error.',
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 response_type : Literal['batch']
var results : list[Results | Results1]

class PreviewCreativeInteractiveResponse (**data: Any)

Expand source code

class PreviewCreativeResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    response_type: Annotated[
        Literal['batch'],
        Field(description='Discriminator indicating this is a batch preview response'),
    ]
    results: Annotated[
        list[Results | Results1],
        Field(
            description='Array of preview results corresponding to each request in the same order. results[0] is the result for requests[0], results[1] for requests[1], etc. Order is guaranteed even when some requests fail. Each result contains either a successful preview response or an error.',
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 response_type : Literal['batch']
var results : list[Results | Results1]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PreviewCreativeVariantResponse (**data: Any)

Expand source code

class PreviewCreativeResponse3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    response_type: Annotated[
        Literal['variant'],
        Field(description='Discriminator indicating this is a variant preview response'),
    ]
    variant_id: Annotated[str, Field(description='Platform-assigned variant identifier')]
    creative_id: Annotated[
        str | None, Field(description='Creative identifier this variant belongs to')
    ] = None
    previews: Annotated[
        list[Preview11],
        Field(
            description='Array of rendered pieces for this variant. Most formats render as a single piece.',
            min_length=1,
        ),
    ]
    manifest: Annotated[
        creative_manifest.CreativeManifest | None,
        Field(
            description='The rendered creative manifest for this variant — the actual output that was served, not the input assets'
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None, Field(description='ISO 8601 timestamp when preview links expire')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 creative_id : str | None
var expires_at : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var manifest : CreativeManifest | None
var model_config
var previews : list[Preview11]
var response_type : Literal['variant']
var variant_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PreviewOutputFormat (*args, **kwds)

Expand source code

class PreviewOutputFormat(Enum):
    url = "url"
    html = "html"

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var html
var url

class OutputFormat (*args, **kwds)

Expand source code

class PreviewOutputFormat(Enum):
    url = "url"
    html = "html"

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var html
var url

class PreviewRender (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class PreviewRender(RootModel[PreviewRender1 | PreviewRender2 | PreviewRender3]):
    root: Annotated[
        PreviewRender1 | PreviewRender2 | PreviewRender3,
        Field(
            description='A single rendered piece of a creative preview with discriminated output format',
            title='Preview Render',
        ),
    ]

    def __getattr__(self, name: str) -> Any:
        """Proxy attribute access to the wrapped type."""
        if name.startswith('_'):
            raise AttributeError(name)
        return getattr(self.root, name)

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[Union[PreviewRender1, PreviewRender2, PreviewRender3]]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : PreviewRender1 | PreviewRender2 | PreviewRender3

class UrlPreviewRender (**data: Any)

Expand source code

class PreviewRender1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    output_format: Annotated[
        Literal['url'], Field(description='Discriminator indicating preview_url is provided')
    ]
    preview_url: Annotated[
        AnyUrl,
        Field(
            description='URL to an HTML page that renders this piece. Can be embedded in an iframe.'
        ),
    ]
    role: Annotated[
        str,
        Field(
            description="Semantic role of this rendered piece. Use 'primary' for main content, 'companion' for associated banners, descriptive strings for device variants or custom roles."
        ),
    ]
    dimensions: Annotated[
        Dimensions | None, Field(description='Dimensions for this rendered piece')
    ] = None
    embedding: Annotated[
        Embedding | None,
        Field(description='Optional security and embedding metadata for safe iframe integration'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var dimensions : Dimensions | None
var embedding : Embedding | None
var model_config
var output_format : Literal['url']
var preview_url : pydantic.networks.AnyUrl
var render_id : str
var role : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class HtmlPreviewRender (**data: Any)

Expand source code

class PreviewRender2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    output_format: Annotated[
        Literal['html'], Field(description='Discriminator indicating preview_html is provided')
    ]
    preview_html: Annotated[
        str,
        Field(
            description='Raw HTML for this rendered piece. Can be embedded directly in the page without iframe. Security warning: Only use with trusted creative agents as this bypasses iframe sandboxing.'
        ),
    ]
    role: Annotated[
        str,
        Field(
            description="Semantic role of this rendered piece. Use 'primary' for main content, 'companion' for associated banners, descriptive strings for device variants or custom roles."
        ),
    ]
    dimensions: Annotated[
        Dimensions | None, Field(description='Dimensions for this rendered piece')
    ] = None
    embedding: Annotated[
        Embedding | None, Field(description='Optional security and embedding metadata')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var dimensions : Dimensions | None
var embedding : Embedding | None
var model_config
var output_format : Literal['html']
var preview_html : str
var render_id : str
var role : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class BothPreviewRender (**data: Any)

Expand source code

class PreviewRender3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    output_format: Annotated[
        Literal['both'],
        Field(
            description='Discriminator indicating both preview_url and preview_html are provided'
        ),
    ]
    preview_url: Annotated[
        AnyUrl,
        Field(
            description='URL to an HTML page that renders this piece. Can be embedded in an iframe.'
        ),
    ]
    preview_html: Annotated[
        str,
        Field(
            description='Raw HTML for this rendered piece. Can be embedded directly in the page without iframe. Security warning: Only use with trusted creative agents as this bypasses iframe sandboxing.'
        ),
    ]
    role: Annotated[
        str,
        Field(
            description="Semantic role of this rendered piece. Use 'primary' for main content, 'companion' for associated banners, descriptive strings for device variants or custom roles."
        ),
    ]
    dimensions: Annotated[
        Dimensions | None, Field(description='Dimensions for this rendered piece')
    ] = None
    embedding: Annotated[
        Embedding | None,
        Field(description='Optional security and embedding metadata for safe iframe integration'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var dimensions : Dimensions | None
var embedding : Embedding | None
var model_config
var output_format : Literal['both']
var preview_html : str
var preview_url : pydantic.networks.AnyUrl
var render_id : str
var role : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PriceGuidance (**data: Any)

Expand source code

class PriceGuidance(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    p25: Annotated[
        float | None, Field(description='25th percentile of recent winning bids', ge=0.0)
    ] = None
    p50: Annotated[float | None, Field(description='Median of recent winning bids', ge=0.0)] = None
    p75: Annotated[
        float | None, Field(description='75th percentile of recent winning bids', ge=0.0)
    ] = None
    p90: Annotated[
        float | None, Field(description='90th percentile of recent winning bids', ge=0.0)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var p25 : float | None
var p50 : float | None
var p75 : float | None
var p90 : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PricingModel (*args, **kwds)

Expand source code

class PricingModel(Enum):
    cpm = 'cpm'
    vcpm = 'vcpm'
    cpc = 'cpc'
    cpcv = 'cpcv'
    cpv = 'cpv'
    cpp = 'cpp'
    cpa = 'cpa'
    flat_rate = 'flat_rate'
    time = 'time'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var cpa
var cpc
var cpcv
var cpm
var cpp
var cpv
var flat_rate
var time
var vcpm

class PrimaryCountry (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class PrimaryCountry(RootModel[str]):
    root: Annotated[str, Field(pattern="^[A-Z]{2}$")]

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[str]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : str

class Product (**data: Any)

Expand source code

class Product(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    product_id: Annotated[str, Field(description='Unique identifier for the product')]
    name: Annotated[str, Field(description='Human-readable product name')]
    description: Annotated[
        str, Field(description='Detailed description of the product and its inventory')
    ]
    publisher_properties: Annotated[
        list[publisher_property_selector.PublisherPropertySelector],
        Field(
            description="Publisher properties covered by this product. Buyers fetch actual property definitions from each publisher's adagents.json and validate agent authorization. Selection patterns mirror the authorization patterns in adagents.json for consistency.",
            min_length=1,
        ),
    ]
    channels: Annotated[
        list[channels_1.MediaChannel] | None,
        Field(
            description="Advertising channels this product is sold as. Products inherit from their properties' supported_channels but may narrow the scope. For example, a product covering YouTube properties might be sold as ['ctv'] even though those properties support ['olv', 'social', 'ctv']."
        ),
    ] = None
    format_ids: Annotated[
        list[format_id_1.FormatId],
        Field(
            description='Array of supported creative format IDs - structured format_id objects with agent_url and id'
        ),
    ]
    placements: Annotated[
        list[placement.Placement] | None,
        Field(
            description='Optional array of specific placements within this product. When provided, buyers can target specific placements when assigning creatives.',
            min_length=1,
        ),
    ] = None
    delivery_type: delivery_type_1.DeliveryType
    exclusivity: Annotated[
        exclusivity_1.Exclusivity | None,
        Field(
            description="Whether this product offers exclusive access to its inventory. Defaults to 'none' when absent. Most relevant for guaranteed products tied to specific collections or placements."
        ),
    ] = None
    pricing_options: Annotated[
        list[pricing_option.PricingOption],
        Field(description='Available pricing models for this product', min_length=1),
    ]
    forecast: Annotated[
        delivery_forecast.DeliveryForecast | None,
        Field(
            description='Forecasted delivery metrics for this product. Gives buyers an estimate of expected performance before requesting a proposal.'
        ),
    ] = None
    outcome_measurement: outcome_measurement_1.OutcomeMeasurement | None = None
    delivery_measurement: Annotated[
        DeliveryMeasurement | None,
        Field(
            description='Measurement provider and methodology for delivery metrics. The buyer accepts the declared provider as the source of truth for the buy. When absent, buyers should apply their own measurement defaults.'
        ),
    ] = None
    measurement_terms: Annotated[
        measurement_terms_1.MeasurementTerms | None,
        Field(
            description="Seller's default billing measurement and makegood terms. Declares who counts the billing metric and what remedies apply when thresholds are breached. Buyers may propose different terms at media buy creation — sellers accept, reject (TERMS_REJECTED), or adjust per their policy."
        ),
    ] = None
    performance_standards: Annotated[
        list[performance_standard.PerformanceStandard] | None,
        Field(
            description="Seller's default performance standards for this product: viewability, IVT, completion rate, brand safety, attention score. Buyers may propose different standards at media buy creation. When absent, no structured performance standards apply.",
            min_length=1,
        ),
    ] = None
    cancellation_policy: Annotated[
        cancellation_policy_1.CancellationPolicy | None,
        Field(
            description='Cancellation terms for this product. Declares the minimum notice period required before cancellation takes effect and any penalties for insufficient notice. Relevant for guaranteed delivery products. Buyers accept these terms by creating a media buy against the product.'
        ),
    ] = None
    reporting_capabilities: reporting_capabilities_1.ReportingCapabilities
    creative_policy: creative_policy_1.CreativePolicy | None = None
    is_custom: Annotated[bool | None, Field(description='Whether this is a custom product')] = None
    property_targeting_allowed: Annotated[
        bool | None,
        Field(
            description="Whether buyers can filter this product to a subset of its publisher_properties. When false (default), the product is 'all or nothing' - buyers must accept all properties or the product is excluded from property_list filtering results."
        ),
    ] = False
    data_provider_signals: Annotated[
        list[data_provider_signal_selector.DataProviderSignalSelector] | None,
        Field(
            description="Data provider signals available for this product. Buyers fetch signal definitions from each data provider's adagents.json and can verify agent authorization."
        ),
    ] = None
    signal_targeting_allowed: Annotated[
        bool | None,
        Field(
            description='Whether buyers can filter this product to a subset of its data_provider_signals. When false (default), the product includes all listed signals as a bundle. When true, buyers can target specific signals.'
        ),
    ] = False
    catalog_types: Annotated[
        list[catalog_type.CatalogType] | None,
        Field(
            description='Catalog types this product supports for catalog-driven campaigns. A sponsored product listing declares ["product"], a job board declares ["job", "offering"]. Buyers match synced catalogs to products via this field.',
            min_length=1,
        ),
    ] = None
    metric_optimization: Annotated[
        MetricOptimization | None,
        Field(
            description="Metric optimization capabilities for this product. Presence indicates the product supports optimization_goals with kind: 'metric'. No event source or conversion tracking setup required — the seller tracks these metrics natively."
        ),
    ] = None
    max_optimization_goals: Annotated[
        int | None,
        Field(
            description='Maximum number of optimization_goals this product accepts on a package. When absent, no limit is declared. Most social platforms accept only 1 goal — buyers sending arrays longer than this value should expect the seller to use only the highest-priority (lowest priority number) goal.',
            ge=1,
        ),
    ] = None
    measurement_readiness: Annotated[
        measurement_readiness_1.MeasurementReadiness | None,
        Field(
            description="Assessment of whether the buyer's event source setup is sufficient for this product to optimize effectively. Only present when the seller can evaluate the buyer's account context. Buyers should check this before creating media buys with event-based optimization goals."
        ),
    ] = None
    conversion_tracking: Annotated[
        ConversionTracking | None,
        Field(
            description="Conversion event tracking for this product. Presence indicates the product supports optimization_goals with kind: 'event'. Seller-level capabilities (supported event types, UID types, attribution windows) are declared in get_adcp_capabilities."
        ),
    ] = None
    catalog_match: Annotated[
        CatalogMatch | None,
        Field(
            description='When the buyer provides a catalog on get_products, indicates which catalog items are eligible for this product. Only present for products where catalog matching is relevant (e.g., sponsored product listings, job boards, hotel ads).'
        ),
    ] = None
    brief_relevance: Annotated[
        str | None,
        Field(
            description='Explanation of why this product matches the brief (only included when brief is provided)'
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description='Expiration timestamp. After this time, the product may no longer be available for purchase and create_media_buy may reject packages referencing it.'
        ),
    ] = None
    product_card: Annotated[
        ProductCard | None,
        Field(
            description='Optional standard visual card (300x400px) for displaying this product in user interfaces. Can be rendered via preview_creative or pre-generated.'
        ),
    ] = None
    product_card_detailed: Annotated[
        ProductCardDetailed | None,
        Field(
            description='Optional detailed card with carousel and full specifications. Provides rich product presentation similar to media kit pages.'
        ),
    ] = None
    collections: Annotated[
        list[collection_selector.CollectionSelector] | None,
        Field(
            description='Collections available in this product. Each entry references collections declared in an adagents.json by domain and collection ID. Buyers resolve full collection objects from the referenced adagents.json.',
            min_length=1,
        ),
    ] = None
    collection_targeting_allowed: Annotated[
        bool | None,
        Field(
            description="Whether buyers can target a subset of this product's collections. When false (default), the product is a bundle — buyers get all listed collections. When true, buyers can select specific collections in the media buy."
        ),
    ] = False
    installments: Annotated[
        list[installment.Installment] | None,
        Field(
            description='Specific installments included in this product. Each installment references its parent collection via collection_id when the product spans multiple collections. When absent with collections present, the product covers the collections broadly (run-of-collection).'
        ),
    ] = None
    enforced_policies: Annotated[
        list[str] | None,
        Field(
            description='Registry policy IDs the seller enforces for this product. Enforcement level comes from the policy registry. Buyers can filter products by required policies.'
        ),
    ] = None
    trusted_match: Annotated[
        TrustedMatch | None,
        Field(
            description='Trusted Match Protocol capabilities for this product. When present, the product supports real-time contextual and/or identity matching via TMP. Buyers use this to determine what response types the publisher can accept and whether brands can be selected dynamically at match time.'
        ),
    ] = None
    material_submission: Annotated[
        MaterialSubmission | None,
        Field(
            description="Instructions for submitting physical creative materials (print, static OOH, cinema). Present only for products requiring physical delivery outside the digital creative assignment flow. Buyer agents MUST validate url and email domains against the seller's known domains (from adagents.json) before submitting materials. Never auto-submit without human confirmation."
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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_relevance : str | None
var cancellation_policy : CancellationPolicy | None
var catalog_match : CatalogMatch | None
var catalog_types : list[CatalogType] | None
var channels : list[MediaChannel] | None
var collection_targeting_allowed : bool | None
var collections : list[CollectionSelector] | None
var conversion_tracking : ConversionTracking | None
var creative_policy : CreativePolicy | None
var data_provider_signals : list[DataProviderSignalSelector] | None
var delivery_measurement : DeliveryMeasurement | None
var delivery_type : DeliveryType
var description : str
var enforced_policies : list[str] | None
var exclusivity : Exclusivity | None
var expires_at : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var forecast : DeliveryForecast | None
var format_ids : list[FormatId]
var installments : list[Installment] | None
var is_custom : bool | None
var material_submission : MaterialSubmission | None
var max_optimization_goals : int | None
var measurement_readiness : MeasurementReadiness | None
var measurement_terms : MeasurementTerms | None
var metric_optimization : MetricOptimization | None
var model_config
var name : str
var outcome_measurement : OutcomeMeasurement | None
var performance_standards : list[PerformanceStandard] | None
var placements : list[Placement] | None
var pricing_options : list[PricingOption]
var product_card : ProductCard | None
var product_card_detailed : ProductCardDetailed | None
var product_id : str
var property_targeting_allowed : bool | None
var publisher_properties : list[PublisherPropertySelector]
var reporting_capabilities : ReportingCapabilities
var signal_targeting_allowed : bool | None
var trusted_match : TrustedMatch | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductCard (**data: Any)

Expand source code

class ProductCard(AdCPBaseModel):
    title: Annotated[bound_value.A2UiBoundValue, Field(description='Product name')]
    price: Annotated[bound_value.A2UiBoundValue, Field(description='Price display string')]
    image: Annotated[bound_value.A2UiBoundValue | None, Field(description='Product image URL')] = (
        None
    )
    description: Annotated[
        bound_value.A2UiBoundValue | None, Field(description='Product description')
    ] = None
    badge: Annotated[
        bound_value.A2UiBoundValue | None, Field(description="Badge text (e.g., 'Best Seller')")
    ] = None
    ctaLabel: Annotated[
        bound_value.A2UiBoundValue | None, Field(description='CTA button label')
    ] = None
    action: Action7 | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 : Action7 | None
var badge : A2UiBoundValue | None
var ctaLabel : A2UiBoundValue | None
var description : A2UiBoundValue | None
var image : A2UiBoundValue | None
var model_config
var price : A2UiBoundValue
var title : A2UiBoundValue

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductCardDetailed (**data: Any)

Expand source code

class ProductCardDetailed(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatId,
        Field(
            description='Creative format defining the detailed card layout (typically product_card_detailed)'
        ),
    ]
    manifest: Annotated[
        dict[str, Any],
        Field(
            description='Asset manifest for rendering the detailed card, structure defined by the format'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var format_id : FormatId
var manifest : dict[str, typing.Any]
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductCatalog (**data: Any)

Expand source code

class ProductCatalog(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    feed_url: Annotated[AnyUrl, Field(description='URL to product catalog feed')]
    feed_format: Annotated[FeedFormat | None, Field(description='Format of the product feed')] = (
        None
    )
    categories: Annotated[
        list[str] | None, Field(description='Product categories available in the catalog')
    ] = None
    last_updated: Annotated[
        AwareDatetime | None, Field(description='When the product catalog was last updated')
    ] = None
    update_frequency: Annotated[
        UpdateFrequency | None, Field(description='How frequently the product catalog is updated')
    ] = None
    agentic_checkout: Annotated[
        AgenticCheckout | None, Field(description='Agentic checkout endpoint configuration')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agentic_checkout : AgenticCheckout | None
var categories : list[str] | None
var feed_format : FeedFormat | None
var feed_url : pydantic.networks.AnyUrl
var last_updated : pydantic.types.AwareDatetime | None
var model_config
var update_frequency : UpdateFrequency | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProductFilters (**data: Any)

Expand source code

class ProductFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    delivery_type: delivery_type_1.DeliveryType | None = None
    exclusivity: Annotated[
        exclusivity_1.Exclusivity | None,
        Field(
            description="Filter by exclusivity level. Returns products matching the specified exclusivity (e.g., 'exclusive' returns only sole-sponsorship products)."
        ),
    ] = None
    is_fixed_price: Annotated[
        bool | None,
        Field(
            description='Filter by pricing availability: true = products offering fixed pricing (at least one option with fixed_price), false = products offering auction pricing (at least one option without fixed_price). Products with both fixed and auction options match both true and false.'
        ),
    ] = None
    format_ids: Annotated[
        list[format_id.FormatId] | None,
        Field(description='Filter by specific format IDs', min_length=1),
    ] = None
    standard_formats_only: Annotated[
        bool | None, Field(description='Only return products accepting IAB standard formats')
    ] = None
    min_exposures: Annotated[
        int | None,
        Field(description='Minimum exposures/impressions needed for measurement validity', ge=1),
    ] = None
    start_date: Annotated[
        date_aliased | None,
        Field(
            description='Campaign start date (ISO 8601 date format: YYYY-MM-DD) for availability checks'
        ),
    ] = None
    end_date: Annotated[
        date_aliased | None,
        Field(
            description='Campaign end date (ISO 8601 date format: YYYY-MM-DD) for availability checks'
        ),
    ] = None
    budget_range: Annotated[
        BudgetRange | BudgetRange3 | None,
        Field(description='Budget range to filter appropriate products'),
    ] = None
    countries: Annotated[
        list[Country] | None,
        Field(
            description="Filter by country coverage using ISO 3166-1 alpha-2 codes (e.g., ['US', 'CA', 'GB']). Works for all inventory types.",
            min_length=1,
        ),
    ] = None
    regions: Annotated[
        list[Region] | None,
        Field(
            description="Filter by region coverage using ISO 3166-2 codes (e.g., ['US-NY', 'US-CA', 'GB-SCT']). Use for locally-bound inventory (regional OOH, local TV) where products have region-specific coverage.",
            min_length=1,
        ),
    ] = None
    metros: Annotated[
        list[Metro] | None,
        Field(
            description='Filter by metro coverage for locally-bound inventory (radio, DOOH, local TV). Use when products have DMA/metro-specific coverage. For digital inventory where products have broad coverage, use required_geo_targeting instead to filter by seller capability.',
            min_length=1,
        ),
    ] = None
    channels: Annotated[
        list[channels_1.MediaChannel] | None,
        Field(
            description="Filter by advertising channels (e.g., ['display', 'ctv', 'dooh'])",
            min_length=1,
        ),
    ] = None
    required_axe_integrations: Annotated[
        list[AnyUrl] | None,
        Field(
            deprecated=True,
            description='Deprecated: Use trusted_match filter instead. Filter to products executable through specific agentic ad exchanges. URLs are canonical identifiers.',
        ),
    ] = None
    trusted_match: Annotated[
        TrustedMatch | None,
        Field(
            description='Filter products by Trusted Match Protocol capabilities. Only products with matching TMP support are returned.'
        ),
    ] = None
    required_features: Annotated[
        media_buy_features.MediaBuyFeatures | None,
        Field(
            description='Filter to products from sellers supporting specific protocol features. Only features set to true are used for filtering.'
        ),
    ] = None
    required_geo_targeting: Annotated[
        list[RequiredGeoTargetingItem] | None,
        Field(
            description='Filter to products from sellers supporting specific geo targeting capabilities. Each entry specifies a targeting level (country, region, metro, postal_area) and optionally a system for levels that have multiple classification systems.',
            min_length=1,
        ),
    ] = None
    signal_targeting: Annotated[
        list[signal_targeting_1.SignalTargeting] | None,
        Field(
            description='Filter to products supporting specific signals from data provider catalogs. Products must have the requested signals in their data_provider_signals and signal_targeting_allowed must be true (or all signals requested).',
            min_length=1,
        ),
    ] = None
    postal_areas: Annotated[
        list[PostalArea] | None,
        Field(
            description='Filter by postal area coverage for locally-bound inventory (direct mail, DOOH, local campaigns). Use when products have postal-area-specific coverage. For digital inventory where products have broad coverage, use required_geo_targeting instead to filter by seller capability.',
            min_length=1,
        ),
    ] = None
    geo_proximity: Annotated[
        list[GeoProximity | GeoProximity15 | GeoProximity16] | None,
        Field(
            description='Filter by proximity to geographic points. Returns products with inventory coverage near these locations. Follows the same format as the targeting overlay — each entry uses exactly one method: travel_time + transport_mode, radius, or geometry. For locally-bound inventory (DOOH, radio), filters to products with coverage in the area. For digital inventory, filters to products from sellers supporting geo_proximity targeting.',
            min_length=1,
        ),
    ] = None
    required_performance_standards: Annotated[
        list[performance_standard.PerformanceStandard] | None,
        Field(
            description="Filter to products that can meet the buyer's performance standard requirements. Each entry specifies a metric, minimum threshold, and optionally a required vendor and standard. Products that cannot meet these thresholds or do not support the specified vendors are excluded. Use this to tell the seller upfront: 'I need DoubleVerify for viewability at 70% MRC.'",
            min_length=1,
        ),
    ] = None
    keywords: Annotated[
        list[Keyword] | None,
        Field(
            description='Filter by keyword relevance for search and retail media platforms. Returns products that support keyword targeting for these terms. Allows the sell-side agent to assess keyword availability and recommend appropriate products. Use match_type to indicate the desired precision.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var budget_range : BudgetRange | BudgetRange3 | None
var channels : list[MediaChannel] | None
var countries : list[Country] | None
var delivery_type : DeliveryType | None
var end_date : datetime.date | None
var exclusivity : Exclusivity | None
var format_ids : list[FormatId] | None
var geo_proximity : list[GeoProximity | GeoProximity15 | GeoProximity16] | None
var is_fixed_price : bool | None
var keywords : list[Keyword] | None
var metros : list[Metro] | None
var min_exposures : int | None
var model_config
var postal_areas : list[PostalArea] | None
var regions : list[Region] | None
var required_features : MediaBuyFeatures | None
var required_geo_targeting : list[RequiredGeoTargetingItem] | None
var required_performance_standards : list[PerformanceStandard] | None
var signal_targeting : list[SignalTargeting] | None
var standard_formats_only : bool | None
var start_date : datetime.date | None
var trusted_match : TrustedMatch | None

Instance variables

var required_axe_integrations : list[pydantic.networks.AnyUrl] | None

Expand source code

def __get__(self, obj: BaseModel | None, obj_type: type[BaseModel] | None = None) -> Any:
    if obj is None:
        if self.wrapped_property is not None:
            return self.wrapped_property.__get__(None, obj_type)
        raise AttributeError(self.field_name)

    warnings.warn(self.msg, DeprecationWarning, stacklevel=2)

    if self.wrapped_property is not None:
        return self.wrapped_property.__get__(obj, obj_type)
    return obj.__dict__[self.field_name]

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

Attributes

msg: The deprecation message to be emitted.
wrapped_property: The property instance if the deprecated field is a computed field, or None.
field_name: The name of the field being deprecated.

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Property (**data: Any)

Expand source code

class Property(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    property_id: Annotated[
        property_id_1.PropertyId | None,
        Field(
            description='Unique identifier for this property (optional). Enables referencing properties by ID instead of repeating full objects.'
        ),
    ] = None
    property_type: Annotated[
        property_type_1.PropertyType, Field(description='Type of advertising property')
    ]
    name: Annotated[str, Field(description='Human-readable property name')]
    identifiers: Annotated[
        list[Identifier], Field(description='Array of identifiers for this property', min_length=1)
    ]
    tags: Annotated[
        list[property_tag.PropertyTag] | None,
        Field(
            description='Tags for categorization and grouping (e.g., network membership, content categories)'
        ),
    ] = None
    supported_channels: Annotated[
        list[channels.MediaChannel] | None,
        Field(
            description="Advertising channels this property supports (e.g., ['display', 'olv', 'social']). Publishers declare which channels their inventory aligns with. Properties may support multiple channels. See the Media Channel Taxonomy for definitions."
        ),
    ] = None
    publisher_domain: Annotated[
        str | None,
        Field(
            description='Domain where adagents.json should be checked for authorization validation. Optional in adagents.json (file location implies domain).'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var identifiers : list[Identifier]
var model_config
var name : str
var property_id : PropertyId | None
var property_type : PropertyType
var publisher_domain : str | None
var supported_channels : list[MediaChannel] | None
var tags : list[PropertyTag] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PropertyId (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class PropertyId(RootModel[str]):
    root: Annotated[
        str,
        Field(
            description='Identifier for a publisher property. Must be lowercase alphanumeric with underscores only.',
            examples=['cnn_ctv_app', 'homepage', 'mobile_ios', 'instagram'],
            pattern='^[a-z0-9_]+$',
            title='Property ID',
        ),
    ]

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[str]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : str

class PropertyIdentifierTypes (*args, **kwds)

Expand source code

class PropertyIdentifierTypes(Enum):
    domain = 'domain'
    subdomain = 'subdomain'
    network_id = 'network_id'
    ios_bundle = 'ios_bundle'
    android_package = 'android_package'
    apple_app_store_id = 'apple_app_store_id'
    google_play_id = 'google_play_id'
    roku_store_id = 'roku_store_id'
    fire_tv_asin = 'fire_tv_asin'
    samsung_app_id = 'samsung_app_id'
    apple_tv_bundle = 'apple_tv_bundle'
    bundle_id = 'bundle_id'
    venue_id = 'venue_id'
    screen_id = 'screen_id'
    openooh_venue_type = 'openooh_venue_type'
    rss_url = 'rss_url'
    apple_podcast_id = 'apple_podcast_id'
    spotify_collection_id = 'spotify_collection_id'
    podcast_guid = 'podcast_guid'
    station_id = 'station_id'
    facility_id = 'facility_id'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var android_package
var apple_app_store_id
var apple_podcast_id
var apple_tv_bundle
var bundle_id
var domain
var facility_id
var fire_tv_asin
var google_play_id
var ios_bundle
var network_id
var openooh_venue_type
var podcast_guid
var roku_store_id
var rss_url
var samsung_app_id
var screen_id
var spotify_collection_id
var station_id
var subdomain
var venue_id

class PropertyList (**data: Any)

Expand source code

class PropertyList(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list_id: Annotated[str, Field(description='Unique identifier for this property list')]
    name: Annotated[str, Field(description='Human-readable name for the list')]
    description: Annotated[str | None, Field(description="Description of the list's purpose")] = (
        None
    )
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns this list. Returned as account_id form (seller-assigned identifier).'
        ),
    ] = None
    base_properties: Annotated[
        list[base_property_source.BasePropertySource] | None,
        Field(
            description="Array of property sources to evaluate. Each entry is a discriminated union: publisher_tags (publisher_domain + tags), publisher_ids (publisher_domain + property_ids), or identifiers (direct identifiers). If omitted, queries the agent's entire property database."
        ),
    ] = None
    filters: Annotated[
        property_list_filters.PropertyListFilters | None,
        Field(description='Dynamic filters applied when resolving the list'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Brand reference used to automatically apply appropriate rules. Resolved to full brand identity at execution time.'
        ),
    ] = None
    webhook_url: Annotated[
        AnyUrl | None,
        Field(description='URL to receive notifications when the resolved list changes'),
    ] = None
    cache_duration_hours: Annotated[
        int | None,
        Field(
            description='Recommended cache duration for resolved list. Consumers should re-fetch after this period.',
            ge=1,
        ),
    ] = 24
    created_at: Annotated[AwareDatetime | None, Field(description='When the list was created')] = (
        None
    )
    updated_at: Annotated[
        AwareDatetime | None, Field(description='When the list was last modified')
    ] = None
    property_count: Annotated[
        int | None,
        Field(description='Number of properties in the resolved list (at time of last resolution)'),
    ] = None
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption] | None,
        Field(
            description='Pricing options for this property list. Present when the requesting account has a billing relationship with the list provider. The buyer passes the selected pricing_option_id in report_usage.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var base_properties : list[BasePropertySource] | None
var brand : BrandReference | None
var cache_duration_hours : int | None
var created_at : pydantic.types.AwareDatetime | None
var description : str | None
var filters : PropertyListFilters | None
var list_id : str
var model_config
var name : str
var pricing_options : list[VendorPricingOption] | None
var property_count : int | None
var updated_at : pydantic.types.AwareDatetime | None
var webhook_url : pydantic.networks.AnyUrl | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PropertyListChangedWebhook (**data: Any)

Expand source code

class PropertyListChangedWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra="forbid",
    )
    idempotency_key: Annotated[
        str,
        Field(
            description="Sender-generated key stable across retries of the same webhook event. Governance agents MUST generate a cryptographically random value (UUID v4 recommended) per distinct list-change event and reuse the same key on every retry. Recipients MUST dedupe by this key, scoped to the authenticated sender identity (HMAC secret or Bearer credential) — keys from different governance agents are independent.",
            max_length=255,
            min_length=16,
            pattern="^[A-Za-z0-9_.:-]{16,255}$",
        ),
    ]
    event: Annotated[Literal["property_list_changed"], Field(description="The event type")]
    list_id: Annotated[str, Field(description="ID of the property list that changed")]
    list_name: Annotated[str | None, Field(description="Name of the property list")] = None
    change_summary: Annotated[
        ChangeSummary | None, Field(description="Summary of changes to the resolved list")
    ] = None
    resolved_at: Annotated[AwareDatetime, Field(description="When the list was re-resolved")]
    cache_valid_until: Annotated[
        AwareDatetime | None,
        Field(description="When the consumer should refresh from the governance agent"),
    ] = None
    signature: Annotated[
        str,
        Field(
            description="Cryptographic signature of the webhook payload, signed with the agent's private key. Recipients MUST verify this signature."
        ),
    ]
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var cache_valid_until : pydantic.types.AwareDatetime | None
var change_summary : ChangeSummary | None
var event : Literal['property_list_changed']
var ext : ExtensionObject | None
var idempotency_key : str
var list_id : str
var list_name : str | None
var model_config
var resolved_at : pydantic.types.AwareDatetime
var signature : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PropertyListFilters (**data: Any)

Expand source code

class PropertyListFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    countries_all: Annotated[
        list[CountriesAllItem] | None,
        Field(
            description='Property must have feature data for ALL listed countries (ISO codes). When omitted, no country restriction is applied.',
            min_length=1,
        ),
    ] = None
    channels_any: Annotated[
        list[channels.MediaChannel] | None,
        Field(
            description='Property must support ANY of the listed channels. When omitted, no channel restriction is applied.',
            min_length=1,
        ),
    ] = None
    property_types: Annotated[
        list[property_type.PropertyType] | None,
        Field(description='Filter to these property types', min_length=1),
    ] = None
    feature_requirements: Annotated[
        list[feature_requirement.FeatureRequirement] | None,
        Field(
            description='Feature-based requirements. Property must pass ALL requirements (AND logic).',
            min_length=1,
        ),
    ] = None
    exclude_identifiers: Annotated[
        list[identifier.Identifier] | None,
        Field(description='Identifiers to always exclude from results', min_length=1),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var channels_any : list[MediaChannel] | None
var countries_all : list[CountriesAllItem] | None
var exclude_identifiers : list[Identifier] | None
var feature_requirements : list[FeatureRequirement] | None
var model_config
var property_types : list[PropertyType] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PropertyListReference (**data: Any)

Expand source code

class PropertyListReference(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    agent_url: Annotated[AnyUrl, Field(description='URL of the agent managing the property list')]
    list_id: Annotated[
        str, Field(description='Identifier for the property list within the agent', min_length=1)
    ]
    auth_token: Annotated[
        str | None,
        Field(
            description='JWT or other authorization token for accessing the list. Optional if the list is public or caller has implicit access.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var agent_url : pydantic.networks.AnyUrl
var auth_token : str | None
var list_id : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PropertyTag (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class PropertyTag(RootModel[str]):
    root: Annotated[
        str,
        Field(
            description='Tag for categorizing publisher properties. Must be lowercase alphanumeric with underscores only.',
            examples=['ctv', 'premium', 'news', 'sports', 'meta_network', 'social_media'],
            pattern='^[a-z0-9_]+$',
            title='Property Tag',
        ),
    ]

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[str]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : str

class PropertyType (*args, **kwds)

Expand source code

class PropertyType(Enum):
    website = 'website'
    mobile_app = 'mobile_app'
    ctv_app = 'ctv_app'
    desktop_app = 'desktop_app'
    dooh = 'dooh'
    podcast = 'podcast'
    radio = 'radio'
    linear_tv = 'linear_tv'
    streaming_audio = 'streaming_audio'
    ai_assistant = 'ai_assistant'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var ai_assistant
var ctv_app
var desktop_app
var dooh
var linear_tv
var mobile_app
var podcast
var radio
var streaming_audio
var website

class Proposal (**data: Any)

Expand source code

class Proposal(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    proposal_id: Annotated[
        str,
        Field(
            description='Unique identifier for this proposal. Used to execute it via create_media_buy.',
            max_length=255,
        ),
    ]
    name: Annotated[
        str, Field(description='Human-readable name for this media plan proposal', max_length=500)
    ]
    description: Annotated[
        str | None,
        Field(
            description='Explanation of the proposal strategy and what it achieves', max_length=2000
        ),
    ] = None
    allocations: Annotated[
        list[product_allocation.ProductAllocation],
        Field(
            description='Budget allocations across products. Allocation percentages MUST sum to 100. Publishers are responsible for ensuring the sum equals 100; buyers SHOULD validate this before execution.',
            min_length=1,
        ),
    ]
    proposal_status: Annotated[
        proposal_status_1.ProposalStatus | None,
        Field(
            description="Lifecycle status of this proposal. When absent, the proposal is ready to buy (backward compatible). 'draft' means indicative pricing — finalize via refine before purchasing. 'committed' means firm pricing with inventory reserved until expires_at."
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description='When this proposal expires and can no longer be executed. For draft proposals, indicates when indicative pricing becomes stale. For committed proposals, indicates when the inventory hold lapses — the buyer must call create_media_buy before this time.'
        ),
    ] = None
    insertion_order: Annotated[
        insertion_order_1.InsertionOrder | None,
        Field(
            description='Formal insertion order attached to a committed proposal. Present when the seller requires a signed agreement before the media buy can proceed. The buyer references the io_id in io_acceptance on create_media_buy.'
        ),
    ] = None
    total_budget_guidance: Annotated[
        TotalBudgetGuidance | None, Field(description='Optional budget guidance for this proposal')
    ] = None
    brief_alignment: Annotated[
        str | None,
        Field(
            description='Explanation of how this proposal aligns with the campaign brief',
            max_length=2000,
        ),
    ] = None
    forecast: Annotated[
        delivery_forecast.DeliveryForecast | None,
        Field(
            description='Aggregate forecasted delivery metrics for the entire proposal. When both proposal-level and allocation-level forecasts are present, the proposal-level forecast is authoritative for total delivery estimation.'
        ),
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var allocations : list[ProductAllocation]
var brief_alignment : str | None
var description : str | None
var expires_at : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var forecast : DeliveryForecast | None
var insertion_order : InsertionOrder | None
var model_config
var name : str
var proposal_id : str
var proposal_status : ProposalStatus | None
var total_budget_guidance : TotalBudgetGuidance | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Protocol (*args, **kwds)

Expand source code

class Protocol(str, Enum):
    """Supported protocols."""

    A2A = "a2a"
    MCP = "mcp"

Supported protocols.

Ancestors

builtins.str
enum.Enum

Class variables

var A2A
var MCP

class ProtocolEnvelope (**data: Any)

Expand source code

class ProtocolEnvelope(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    context_id: Annotated[
        str | None,
        Field(
            description='Session/conversation identifier for tracking related operations across multiple task invocations. Managed by the protocol layer to maintain conversational context.'
        ),
    ] = None
    task_id: Annotated[
        str | None,
        Field(
            description='Unique identifier for tracking asynchronous operations. Present when a task requires extended processing time. Used to query task status and retrieve results when complete.'
        ),
    ] = None
    status: Annotated[
        task_status.TaskStatus,
        Field(
            description='Current task execution state. Indicates whether the task is completed, in progress (working), submitted for async processing, failed, or requires user input. Managed by the protocol layer.'
        ),
    ]
    message: Annotated[
        str | None,
        Field(
            description='Human-readable summary of the task result. Provides natural language explanation of what happened, suitable for display to end users or for AI agent comprehension. Generated by the protocol layer based on the task response.'
        ),
    ] = None
    timestamp: Annotated[
        AwareDatetime | None,
        Field(
            description='ISO 8601 timestamp when the response was generated. Useful for debugging, logging, cache validation, and tracking async operation progress.'
        ),
    ] = None
    replayed: Annotated[
        bool | None,
        Field(
            description='Set to true when this response is a cached replay returned for an idempotency_key that was already processed. Set to false (or omitted) when the request was executed fresh. Buyers use this to distinguish cached replays from new executions — matters for billing reconciliation, audit logs, and any downstream system that assumes exactly-once event semantics. Only present on responses to mutating requests that carry idempotency_key.'
        ),
    ] = False
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Push notification configuration for async task updates (A2A and REST protocols). Echoed from the request to confirm webhook settings. Specifies URL, authentication scheme (Bearer or HMAC-SHA256), and credentials. MCP uses progress notifications instead of webhooks.'
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description="Governance context token issued by a governance agent during check_governance. Buyers attach it to governed purchase requests (media buys, rights acquisitions, signal activations, creative services); sellers persist it and include it on all subsequent governance calls for that action's lifecycle.\n\nValue format: in 3.0 governance agents MUST emit a compact JWS per the AdCP JWS profile (see Security — Signed Governance Context). Sellers MAY verify; sellers that do not verify MUST persist and forward the token unchanged. In 3.1 all sellers MUST verify. Non-JWS values from pre-3.0 governance agents are deprecated.\n\nThis is the primary correlation key for audit and reporting across the governance lifecycle.",
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    payload: Annotated[
        dict[str, Any],
        Field(
            description='The actual task-specific response data. This is the content defined in individual task response schemas (e.g., get-products-response.json, create-media-buy-response.json). Contains only domain-specific data without protocol-level fields.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_id : str | None
var governance_context : str | None
var message : str | None
var model_config
var payload : dict[str, typing.Any]
var push_notification_config : PushNotificationConfig | None
var replayed : bool | None
var status : TaskStatus
var task_id : str | None
var timestamp : pydantic.types.AwareDatetime | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProtocolResponse (**data: Any)

Expand source code

class ProtocolResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    message: Annotated[str, Field(description='Human-readable summary')]
    context_id: Annotated[str | None, Field(description='Session continuity identifier')] = None
    data: Annotated[
        Any | None,
        Field(
            description='AdCP task-specific response data (see individual task response schemas)'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context_id : str | None
var data : typing.Any | None
var message : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProvidePerformanceFeedbackRequest (**data: Any)

Expand source code

class ProvidePerformanceFeedbackRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    media_buy_id: Annotated[str, Field(description="Seller's media buy identifier", min_length=1)]
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate feedback submissions 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}$',
        ),
    ]
    measurement_period: Annotated[
        datetime_range.DatetimeRange, Field(description='Time period for performance measurement')
    ]
    performance_index: Annotated[
        float,
        Field(
            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
            ge=0.0,
        ),
    ]
    package_id: Annotated[
        str | None,
        Field(
            description='Specific package within the media buy (if feedback is package-specific)',
            min_length=1,
        ),
    ] = None
    creative_id: Annotated[
        str | None,
        Field(
            description='Specific creative asset (if feedback is creative-specific)', min_length=1
        ),
    ] = None
    metric_type: Annotated[
        metric_type_1.MetricType | None, Field(description='The business metric being measured')
    ] = metric_type_1.MetricType.overall_performance
    feedback_source: Annotated[
        feedback_source_1.FeedbackSource | None, Field(description='Source of the performance data')
    ] = feedback_source_1.FeedbackSource.buyer_attribution
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var creative_id : str | None
var ext : ExtensionObject | None
var feedback_source : FeedbackSource | None
var idempotency_key : str
var measurement_period : DatetimeRange
var media_buy_id : str
var metric_type : MetricType | None
var model_config
var package_id : str | None
var performance_index : float

class ProvidePerformanceFeedbackByBuyerRefRequest (**data: Any)

Expand source code

class ProvidePerformanceFeedbackRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    media_buy_id: Annotated[str, Field(description="Seller's media buy identifier", min_length=1)]
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate feedback submissions 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}$',
        ),
    ]
    measurement_period: Annotated[
        datetime_range.DatetimeRange, Field(description='Time period for performance measurement')
    ]
    performance_index: Annotated[
        float,
        Field(
            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
            ge=0.0,
        ),
    ]
    package_id: Annotated[
        str | None,
        Field(
            description='Specific package within the media buy (if feedback is package-specific)',
            min_length=1,
        ),
    ] = None
    creative_id: Annotated[
        str | None,
        Field(
            description='Specific creative asset (if feedback is creative-specific)', min_length=1
        ),
    ] = None
    metric_type: Annotated[
        metric_type_1.MetricType | None, Field(description='The business metric being measured')
    ] = metric_type_1.MetricType.overall_performance
    feedback_source: Annotated[
        feedback_source_1.FeedbackSource | None, Field(description='Source of the performance data')
    ] = feedback_source_1.FeedbackSource.buyer_attribution
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var creative_id : str | None
var ext : ExtensionObject | None
var feedback_source : FeedbackSource | None
var idempotency_key : str
var measurement_period : DatetimeRange
var media_buy_id : str
var metric_type : MetricType | None
var model_config
var package_id : str | None
var performance_index : float

class ProvidePerformanceFeedbackByMediaBuyRequest (**data: Any)

Expand source code

class ProvidePerformanceFeedbackRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    media_buy_id: Annotated[str, Field(description="Seller's media buy identifier", min_length=1)]
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate feedback submissions 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}$',
        ),
    ]
    measurement_period: Annotated[
        datetime_range.DatetimeRange, Field(description='Time period for performance measurement')
    ]
    performance_index: Annotated[
        float,
        Field(
            description='Normalized performance score (0.0 = no value, 1.0 = expected, >1.0 = above expected)',
            ge=0.0,
        ),
    ]
    package_id: Annotated[
        str | None,
        Field(
            description='Specific package within the media buy (if feedback is package-specific)',
            min_length=1,
        ),
    ] = None
    creative_id: Annotated[
        str | None,
        Field(
            description='Specific creative asset (if feedback is creative-specific)', min_length=1
        ),
    ] = None
    metric_type: Annotated[
        metric_type_1.MetricType | None, Field(description='The business metric being measured')
    ] = metric_type_1.MetricType.overall_performance
    feedback_source: Annotated[
        feedback_source_1.FeedbackSource | None, Field(description='Source of the performance data')
    ] = feedback_source_1.FeedbackSource.buyer_attribution
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var creative_id : str | None
var ext : ExtensionObject | None
var feedback_source : FeedbackSource | None
var idempotency_key : str
var measurement_period : DatetimeRange
var media_buy_id : str
var metric_type : MetricType | None
var model_config
var package_id : str | None
var performance_index : float

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProvidePerformanceFeedbackSuccessResponse (**data: Any)

Expand source code

class ProvidePerformanceFeedbackResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Annotated[
        Literal[True],
        Field(description='Whether the performance feedback was successfully received'),
    ]
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 sandbox : bool | None
var success : Literal[True]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ProvidePerformanceFeedbackErrorResponse (**data: Any)

Expand source code

class ProvidePerformanceFeedbackResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[
        list[error.Error],
        Field(
            description='Array of errors explaining why feedback was rejected (e.g., invalid measurement period, missing campaign data)',
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PublisherDomain (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class PublisherDomain(RootModel[str]):
    root: Annotated[
        str, Field(pattern="^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$")
    ]

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[str]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Subclasses

DataProviderDomain

Class variables

var model_config
var root : str

class PublisherIdentifierTypes (*args, **kwds)

Expand source code

class PublisherIdentifierTypes(Enum):
    tag_id = 'tag_id'
    duns = 'duns'
    lei = 'lei'
    seller_id = 'seller_id'
    gln = 'gln'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var duns
var gln
var lei
var seller_id
var tag_id

class PublisherPropertiesAll (**data: Any)

Expand source code

class PublisherPropertySelector1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    publisher_domain: Annotated[
        str,
        Field(
            description="Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    selection_type: Annotated[
        Literal['all'],
        Field(
            description='Discriminator indicating all properties from this publisher are included'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var publisher_domain : str
var selection_type : Literal['all']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PublisherPropertiesById (**data: Any)

Expand source code

class PublisherPropertySelector2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    publisher_domain: Annotated[
        str,
        Field(
            description="Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    selection_type: Annotated[
        Literal['by_id'],
        Field(description='Discriminator indicating selection by specific property IDs'),
    ]
    property_ids: Annotated[
        list[property_id.PropertyId],
        Field(description="Specific property IDs from the publisher's adagents.json", min_length=1),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var property_ids : list[PropertyId]
var publisher_domain : str
var selection_type : Literal['by_id']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PublisherPropertiesByTag (**data: Any)

Expand source code

class PublisherPropertySelector3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    publisher_domain: Annotated[
        str,
        Field(
            description="Domain where publisher's adagents.json is hosted (e.g., 'cnn.com')",
            pattern='^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$',
        ),
    ]
    selection_type: Annotated[
        Literal['by_tag'], Field(description='Discriminator indicating selection by property tags')
    ]
    property_tags: Annotated[
        list[property_tag.PropertyTag],
        Field(
            description="Property tags from the publisher's adagents.json. Selector covers all properties with these tags",
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var property_tags : list[PropertyTag]
var publisher_domain : str
var selection_type : Literal['by_tag']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class PushNotificationConfig (**data: Any)

Expand source code

class PushNotificationConfig(AdCPBaseModel):
    url: Annotated[AnyUrl, Field(description="Webhook endpoint URL for task status notifications")]
    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 | None,
        Field(
            description="Legacy authentication configuration (A2A-compatible). Opts the seller into Bearer or HMAC-SHA256 signing instead of the default RFC 9421 webhook profile. Deprecated; removed in AdCP 4.0. When omitted, the seller MUST sign webhooks with the 9421 profile."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authentication : Authentication | None
var model_config
var token : str | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class QuartileData (**data: Any)

Expand source code

class QuartileData(AdCPBaseModel):
    q1_views: Annotated[float | None, Field(description='25% completion views', ge=0.0)] = None
    q2_views: Annotated[float | None, Field(description='50% completion views', ge=0.0)] = None
    q3_views: Annotated[float | None, Field(description='75% completion views', ge=0.0)] = None
    q4_views: Annotated[float | None, Field(description='100% completion views', ge=0.0)] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var model_config
var q1_views : float | None
var q2_views : float | None
var q3_views : float | None
var q4_views : float | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class QuerySummary (**data: Any)

Expand source code

class QuerySummary(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    total_matching: Annotated[
        int | None,
        Field(description='Total number of tasks matching filters (across all pages)', ge=0),
    ] = None
    returned: Annotated[
        int | None, Field(description='Number of tasks returned in this response', ge=0)
    ] = None
    domain_breakdown: Annotated[
        DomainBreakdown | None, Field(description='Count of tasks by domain')
    ] = None
    status_breakdown: Annotated[
        dict[str, int] | None, Field(description='Count of tasks by status')
    ] = None
    filters_applied: Annotated[
        list[str] | None, Field(description='List of filters that were applied to the query')
    ] = None
    sort_applied: Annotated[
        SortApplied | None, Field(description='Sort order that was applied')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var domain_breakdown : DomainBreakdown | None
var filters_applied : list[str] | None
var model_config
var returned : int | None
var sort_applied : SortApplied | None
var status_breakdown : dict[str, int] | None
var total_matching : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReachUnit (*args, **kwds)

Expand source code

class ReachUnit(Enum):
    individuals = 'individuals'
    households = 'households'
    devices = 'devices'
    accounts = 'accounts'
    cookies = 'cookies'
    custom = 'custom'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var accounts
var cookies
var custom
var devices
var households
var individuals

class Refine (**data: Any)

Expand source code

class Refine(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.'
        ),
    ]
    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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 ReportPlanOutcomeRequest (**data: Any)

Expand source code

class ReportPlanOutcomeRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    plan_id: Annotated[str, Field(description='The plan this outcome is for.')]
    check_id: Annotated[
        str | None,
        Field(
            description="The check_id from check_governance. Links the outcome to the governance check that authorized it. Required for 'completed' and 'failed' outcomes."
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate outcome reports 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}$',
        ),
    ]
    purchase_type: Annotated[
        purchase_type_1.PurchaseType | None,
        Field(
            description="The type of financial commitment this outcome is for. Determines which budget allocation (if any) to charge against. Defaults to 'media_buy' when omitted."
        ),
    ] = purchase_type_1.PurchaseType.media_buy
    outcome: Annotated[outcome_type.OutcomeType, Field(description='Outcome type.')]
    seller_response: Annotated[
        SellerResponse | None,
        Field(description="The seller's full response. Required when outcome is 'completed'."),
    ] = None
    delivery: Annotated[
        Delivery | None, Field(description="Delivery metrics. Required when outcome is 'delivery'.")
    ] = None
    error: Annotated[
        Error | None, Field(description="Error details. Required when outcome is 'failed'.")
    ] = None
    governance_context: Annotated[
        str,
        Field(
            description='Opaque governance context from the check_governance response that authorized this action. Enables the governance agent to correlate the outcome to the original check.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var check_id : str | None
var context : ContextObject | None
var delivery : Delivery | None
var error : Error | None
var ext : ExtensionObject | None
var governance_context : str
var idempotency_key : str
var model_config
var outcome : OutcomeType
var plan_id : str
var purchase_type : PurchaseType | None
var seller_response : SellerResponse | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportPlanOutcomeResponse (**data: Any)

Expand source code

class ReportPlanOutcomeResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    outcome_id: Annotated[str, Field(description='Unique identifier for this outcome record.')]
    status: Annotated[
        Status,
        Field(
            description="'accepted' means state updated with no issues. 'findings' means issues were detected."
        ),
    ]
    committed_budget: Annotated[
        float | None,
        Field(
            description="Budget committed from this outcome. Present for 'completed' and 'failed' outcomes."
        ),
    ] = None
    findings: Annotated[
        list[Finding] | None,
        Field(description="Issues detected. Present only when status is 'findings'."),
    ] = None
    plan_summary: Annotated[
        PlanSummary | None,
        Field(
            description="Updated plan budget state. Present for 'completed' and 'failed' outcomes."
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var committed_budget : float | None
var context : ContextObject | None
var ext : ExtensionObject | None
var findings : list[Finding] | None
var model_config
var outcome_id : str
var plan_summary : PlanSummary | None
var status : Status

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportUsageRequest (**data: Any)

Expand source code

class ReportUsageRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description="Client-generated unique key for this request. If a request with the same key has already been accepted, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request. Prevents duplicate billing on retries."
        ),
    ]
    reporting_period: Annotated[
        datetime_range.DatetimeRange,
        Field(
            description="The time range covered by this usage report. Applies to all records in the request."
        ),
    ]
    usage: Annotated[
        list[UsageItem],
        Field(
            description="One or more usage records. Each record is self-contained: it carries its own account, allowing a single request to span multiple accounts.",
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var reporting_period : DatetimeRange
var usage : list[UsageItem]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportUsageResponse (**data: Any)

Expand source code

class ReportUsageResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    accepted: Annotated[
        int, Field(description='Number of usage records successfully stored.', ge=0)
    ]
    errors: Annotated[
        list[error.Error] | None,
        Field(
            description="Validation errors for individual records. The field property identifies which record failed (e.g., 'usage[1].pricing_option_id')."
        ),
    ] = None
    sandbox: Annotated[
        bool | None,
        Field(description='When true, the account is a sandbox account and no billing occurred.'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 : int
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var model_config
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportingCapabilities (**data: Any)

Expand source code

class ReportingCapabilities(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    available_reporting_frequencies: Annotated[
        list[reporting_frequency.ReportingFrequency],
        Field(description='Supported reporting frequency options', min_length=1),
    ]
    expected_delay_minutes: Annotated[
        int,
        Field(
            description='Expected delay in minutes before reporting data becomes available (e.g., 240 for 4-hour delay)',
            examples=[240, 300, 1440],
            ge=0,
        ),
    ]
    timezone: Annotated[
        str,
        Field(
            description="Timezone for reporting periods. Use 'UTC' or IANA timezone (e.g., 'America/New_York'). Critical for daily/monthly frequency alignment.",
            examples=['UTC', 'America/New_York', 'Europe/London', 'America/Los_Angeles'],
        ),
    ]
    supports_webhooks: Annotated[
        bool,
        Field(description='Whether this product supports webhook-based reporting notifications'),
    ]
    available_metrics: Annotated[
        list[available_metric.AvailableMetric],
        Field(
            description="Metrics available in reporting. Impressions and spend are always implicitly included. When a creative format declares reported_metrics, buyers receive the intersection of these product-level metrics and the format's reported_metrics.",
            examples=[
                ['impressions', 'spend', 'clicks', 'video_completions'],
                ['impressions', 'spend', 'conversions'],
            ],
        ),
    ]
    supports_creative_breakdown: Annotated[
        bool | None,
        Field(
            description='Whether this product supports creative-level metric breakdowns in delivery reporting (by_creative within by_package)'
        ),
    ] = None
    supports_keyword_breakdown: Annotated[
        bool | None,
        Field(
            description='Whether this product supports keyword-level metric breakdowns in delivery reporting (by_keyword within by_package)'
        ),
    ] = None
    supports_geo_breakdown: Annotated[
        geo_breakdown_support.GeographicBreakdownSupport | None,
        Field(
            description='Geographic breakdown support for this product. Declares which geo levels and systems are available for by_geo reporting within by_package.'
        ),
    ] = None
    supports_device_type_breakdown: Annotated[
        bool | None,
        Field(
            description='Whether this product supports device type breakdowns in delivery reporting (by_device_type within by_package)'
        ),
    ] = None
    supports_device_platform_breakdown: Annotated[
        bool | None,
        Field(
            description='Whether this product supports device platform breakdowns in delivery reporting (by_device_platform within by_package)'
        ),
    ] = None
    supports_audience_breakdown: Annotated[
        bool | None,
        Field(
            description='Whether this product supports audience segment breakdowns in delivery reporting (by_audience within by_package)'
        ),
    ] = None
    supports_placement_breakdown: Annotated[
        bool | None,
        Field(
            description='Whether this product supports placement breakdowns in delivery reporting (by_placement within by_package)'
        ),
    ] = None
    date_range_support: Annotated[
        DateRangeSupport,
        Field(
            description="Whether delivery data can be filtered to arbitrary date ranges. 'date_range' means the platform supports start_date/end_date parameters. 'lifetime_only' means the platform returns campaign lifetime totals and date range parameters are not accepted."
        ),
    ]
    measurement_windows: Annotated[
        list[measurement_window.MeasurementWindow] | None,
        Field(
            description='Measurement maturation stages available for this product. Used by any channel where billing-grade data is produced in phases rather than arriving final on day one. Examples: broadcast/linear TV (Live → C3 → C7 DVR accumulation), DOOH (tentative plays → post-IVT/fraud-check final), digital with IVT filtering (raw → GIVT filtered → SIVT filtered), podcast (7-day downloads → 30-day downloads). Each window defines an accumulation period and expected data availability. When present, delivery reports reference a specific window_id. Sellers whose data is final on first delivery typically omit this.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var available_metrics : list[AvailableMetric]
var available_reporting_frequencies : list[ReportingFrequency]
var date_range_support : DateRangeSupport
var expected_delay_minutes : int
var measurement_windows : list[MeasurementWindow] | None
var model_config
var supports_audience_breakdown : bool | None
var supports_creative_breakdown : bool | None
var supports_device_platform_breakdown : bool | None
var supports_device_type_breakdown : bool | None
var supports_geo_breakdown : GeographicBreakdownSupport | None
var supports_keyword_breakdown : bool | None
var supports_placement_breakdown : bool | None
var supports_webhooks : bool
var timezone : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportingFrequency (*args, **kwds)

Expand source code

class ReportingFrequency(Enum):
    hourly = 'hourly'
    daily = 'daily'
    monthly = 'monthly'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var daily
var hourly
var monthly

class AvailableReportingFrequency (*args, **kwds)

Expand source code

class ReportingFrequency(Enum):
    hourly = 'hourly'
    daily = 'daily'
    monthly = 'monthly'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var daily
var hourly
var monthly

class ReportingPeriod (**data: Any)

Expand source code

class ReportingPeriod(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    start: Annotated[AwareDatetime, Field(description='ISO 8601 start timestamp')]
    end: Annotated[AwareDatetime, Field(description='ISO 8601 end timestamp')]
    timezone: Annotated[
        str | None,
        Field(
            description="IANA timezone identifier for the reporting period (e.g., 'America/New_York', 'UTC'). Platforms report in their native timezone."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var end : pydantic.types.AwareDatetime
var model_config
var start : pydantic.types.AwareDatetime
var timezone : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ReportingWebhook (**data: Any)

Expand source code

class ReportingWebhook(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='Webhook endpoint URL for reporting notifications')]
    token: Annotated[
        str | None,
        Field(
            description='Optional client-provided token for webhook validation. Echoed back in webhook payload to validate request authenticity.',
            min_length=16,
        ),
    ] = None
    authentication: Annotated[
        Authentication,
        Field(description='Authentication configuration for webhook delivery (A2A-compatible)'),
    ]
    reporting_frequency: Annotated[
        ReportingFrequency,
        Field(
            description='Frequency for automated reporting delivery. Must be supported by all products in the media buy.'
        ),
    ]
    requested_metrics: Annotated[
        list[available_metric.AvailableMetric] | None,
        Field(
            description="Optional list of metrics to include in webhook notifications. If omitted, all available metrics are included. Must be subset of product's available_metrics."
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var authentication : Authentication
var model_config
var reporting_frequency : ReportingFrequency
var requested_metrics : list[AvailableMetric] | None
var token : str | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Request (**data: Any)

Expand source code

class Request(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    format_id: Annotated[
        format_id_1.FormatId | None,
        Field(
            description='Format identifier for rendering the preview. Defaults to creative_manifest_1.format_id if omitted.'
        ),
    ] = None
    creative_manifest: Annotated[
        creative_manifest_1.CreativeManifest,
        Field(description='Complete creative manifest with all required assets.'),
    ]
    inputs: Annotated[
        list[Input8] | None,
        Field(
            description='Array of input sets for generating multiple preview variants', min_length=1
        ),
    ] = None
    template_id: Annotated[
        str | None, Field(description='Specific template ID for custom format rendering')
    ] = None
    quality: Annotated[
        creative_quality.CreativeQuality | None,
        Field(description='Render quality for this preview. Overrides batch-level default.'),
    ] = None
    output_format: Annotated[
        preview_output_format.PreviewOutputFormat | None,
        Field(description='Output format for this preview. Overrides batch-level default.'),
    ] = preview_output_format.PreviewOutputFormat.url
    item_limit: Annotated[
        int | None,
        Field(description='Maximum number of catalog items to render in this preview.', ge=1),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var creative_manifest : CreativeManifest
var format_id : FormatId | None
var inputs : list[Input8] | None
var item_limit : int | None
var model_config
var output_format : PreviewOutputFormat | None
var quality : CreativeQuality | None
var template_id : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ResolvedBrand (**data: Any)

Expand source code

class ResolvedBrand(BaseModel):
    """Brand identity resolved from the AdCP registry."""

    model_config = ConfigDict(extra="allow")

    canonical_id: str
    canonical_domain: str
    brand_name: str
    names: list[dict[str, str]] | None = None
    keller_type: str | None = None
    parent_brand: str | None = None
    house_domain: str | None = None
    house_name: str | None = None
    brand_agent_url: str | None = None
    brand: dict[str, Any] | None = None
    source: str

Brand identity resolved from the AdCP registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var brand : dict[str, typing.Any] | None
var brand_agent_url : str | None
var brand_name : str
var canonical_domain : str
var canonical_id : str
var house_domain : str | None
var house_name : str | None
var keller_type : str | None
var model_config
var names : list[dict[str, str]] | None
var parent_brand : str | None
var source : str

class ResolvedProperty (**data: Any)

Expand source code

class ResolvedProperty(BaseModel):
    """Property information resolved from the AdCP registry."""

    model_config = ConfigDict(extra="allow")

    publisher_domain: str
    source: str
    authorized_agents: list[dict[str, Any]]
    properties: list[dict[str, Any]]
    verified: bool

Property information resolved from the AdCP registry.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var authorized_agents : list[dict[str, typing.Any]]
var model_config
var properties : list[dict[str, typing.Any]]
var publisher_domain : str
var source : str
var verified : bool

class Response (**data: Any)

Expand source code

class Response(AdCPBaseModel):
    previews: Annotated[
        list[Preview9],
        Field(description='Array of preview variants for this creative', min_length=1),
    ]
    interactive_url: AnyUrl | None = None
    expires_at: Annotated[AwareDatetime, Field(description='When the preview URLs expire')]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var expires_at : pydantic.types.AwareDatetime
var interactive_url : pydantic.networks.AnyUrl | None
var model_config
var previews : list[Preview9]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Responsive (**data: Any)

Expand source code

class Responsive(AdCPBaseModel):
    width: bool
    height: bool

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var height : bool
var model_config
var width : bool

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Results (**data: Any)

Expand source code

class Results(AdCPBaseModel):
    success: Annotated[Literal[True], Field(description='Indicates this preview request succeeded')]
    creative_id: Annotated[
        str,
        Field(
            description='ID of the creative this result corresponds to. Enables correlation when processing batch results.'
        ),
    ]
    response: Annotated[Response, Field(description='Preview data for successful requests')]
    errors: Annotated[
        list[error.Error] | None, Field(description='Errors for failed requests', min_length=1)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var creative_id : str
var errors : list[Error] | None
var model_config
var response : Response
var success : Literal[True]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RightsPricingOption (**data: Any)

Expand source code

class RightsPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str,
        Field(
            description='Unique identifier for this pricing option. Referenced in acquire_rights and report_usage.'
        ),
    ]
    model: Annotated[
        pricing_model.PricingModel, Field(description='Pricing model (cpm, flat_rate, etc.)')
    ]
    price: Annotated[
        float,
        Field(
            description='Price amount. Interpretation depends on model: CPM = cost per 1,000 impressions, flat_rate = fixed cost per period.',
            ge=0.0,
        ),
    ]
    currency: Annotated[str, Field(description='ISO 4217 currency code', pattern='^[A-Z]{3}$')]
    uses: Annotated[
        list[right_use.RightUse],
        Field(
            description='Which rights uses this pricing option covers. A single option can bundle multiple uses (e.g., likeness + voice).',
            min_length=1,
        ),
    ]
    period: Annotated[
        Period | None, Field(description='Billing period for flat_rate and time-based models')
    ] = None
    impression_cap: Annotated[
        int | None,
        Field(description='Maximum impressions included in this pricing option per period', ge=1),
    ] = None
    overage_cpm: Annotated[
        float | None,
        Field(description='CPM rate applied to impressions exceeding the impression_cap', ge=0.0),
    ] = None
    description: Annotated[
        str | None, Field(description='Human-readable description of this pricing option')
    ] = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var description : str | None
var ext : ExtensionObject | None
var impression_cap : int | None
var model : PricingModel
var model_config
var overage_cpm : float | None
var period : Period | None
var price : float
var pricing_option_id : str
var uses : list[RightUse]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class RightsTerms (**data: Any)

Expand source code

class RightsTerms(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: str
    amount: Annotated[float, Field(ge=0.0)]
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]
    period: Period | None = None
    uses: list[right_use.RightUse]
    impression_cap: Annotated[int | None, Field(ge=1)] = None
    overage_cpm: Annotated[float | None, Field(ge=0.0)] = None
    start_date: date_aliased | None = None
    end_date: date_aliased | None = None
    exclusivity: Annotated[
        Exclusivity | None, Field(description='Exclusivity terms if applicable')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var amount : float
var currency : str
var end_date : datetime.date | None
var exclusivity : Exclusivity | None
var impression_cap : int | None
var model_config
var overage_cpm : float | None
var period : Period | None
var pricing_option_id : str
var start_date : datetime.date | None
var uses : list[RightUse]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Security (**data: Any)

Expand source code

class Security(AdCPBaseModel):
    method: Annotated[
        webhook_security_method.WebhookSecurityMethod, Field(description='Authentication method')
    ]
    hmac_header: Annotated[
        str | None, Field(description="Header name for HMAC signature (e.g., 'X-Signature')")
    ] = None
    api_key_header: Annotated[
        str | None, Field(description="Header name for API key (e.g., 'X-API-Key')")
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var api_key_header : str | None
var hmac_header : str | None
var method : WebhookSecurityMethod
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiCapabilities (**data: Any)

Expand source code

class SiCapabilities(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    modalities: Annotated[
        Modalities | None, Field(description='Interaction modalities supported')
    ] = None
    components: Annotated[Components | None, Field(description='Visual components supported')] = (
        None
    )
    commerce: Annotated[Commerce | None, Field(description='Commerce capabilities')] = None
    a2ui: Annotated[A2ui | None, Field(description='A2UI (Agent-to-UI) capabilities')] = None
    mcp_apps: Annotated[
        bool | None, Field(description='Supports MCP Apps for rendering A2UI surfaces in iframes')
    ] = False

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var a2ui : A2ui | None
var commerce : Commerce | None
var components : Components | None
var mcp_apps : bool | None
var modalities : Modalities | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiGetOfferingRequest (**data: Any)

Expand source code

class SiGetOfferingRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    offering_id: Annotated[
        str, Field(description='Offering identifier from the catalog to get details for')
    ]
    context: Annotated[
        str | None,
        Field(
            description="Optional natural language context about user intent for personalized results (e.g., 'mens size 14 near Cincinnati'). Must be anonymous - no PII."
        ),
    ] = None
    include_products: Annotated[
        bool | None, Field(description='Whether to include matching products in the response')
    ] = False
    product_limit: Annotated[
        int | None, Field(description='Maximum number of matching products to return', ge=1, le=50)
    ] = 5
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : str | None
var ext : ExtensionObject | None
var include_products : bool | None
var model_config
var offering_id : str
var product_limit : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiGetOfferingResponse (**data: Any)

Expand source code

class SiGetOfferingResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    available: Annotated[bool, Field(description='Whether the offering is currently available')]
    offering_token: Annotated[
        str | None,
        Field(
            description="Token to pass to si_initiate_session for session continuity. Brand stores the full query context server-side (products shown, order, context) so they can resolve references like 'the second one' when the session starts."
        ),
    ] = None
    ttl_seconds: Annotated[
        int | None,
        Field(
            description='How long this offering information is valid (seconds). Host should re-fetch after TTL expires.',
            ge=0,
        ),
    ] = None
    checked_at: Annotated[
        AwareDatetime | None, Field(description='When this offering information was retrieved')
    ] = None
    offering: Annotated[Offering | None, Field(description='Offering details')] = None
    matching_products: Annotated[
        list[MatchingProduct] | None,
        Field(
            description='Products matching the request context. Only included if include_products was true.'
        ),
    ] = None
    total_matching: Annotated[
        int | None,
        Field(
            description='Total number of products matching the context (may be more than returned in matching_products)',
            ge=0,
        ),
    ] = None
    unavailable_reason: Annotated[
        str | None,
        Field(
            description="If not available, why (e.g., 'expired', 'sold_out', 'region_restricted')"
        ),
    ] = None
    alternative_offering_ids: Annotated[
        list[str] | None,
        Field(description='Alternative offerings to consider if this one is unavailable'),
    ] = None
    errors: Annotated[
        list[error.Error] | None, Field(description='Errors during offering lookup')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var alternative_offering_ids : list[str] | None
var available : bool
var checked_at : pydantic.types.AwareDatetime | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var matching_products : list[MatchingProduct] | None
var model_config
var offering : Offering | None
var offering_token : str | None
var total_matching : int | None
var ttl_seconds : int | None
var unavailable_reason : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiIdentity (**data: Any)

Expand source code

class SiIdentity(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    consent_granted: Annotated[bool, Field(description='Whether user consented to share identity')]
    consent_timestamp: Annotated[
        AwareDatetime | None, Field(description='When consent was granted (ISO 8601)')
    ] = None
    consent_scope: Annotated[
        list[ConsentScopeEnum] | None, Field(description='What data was consented to share')
    ] = None
    privacy_policy_acknowledged: Annotated[
        PrivacyPolicyAcknowledged | None, Field(description='Brand privacy policy acknowledgment')
    ] = None
    user: Annotated[
        User | None, Field(description='User data (only present if consent_granted is true)')
    ] = None
    anonymous_session_id: Annotated[
        str | None,
        Field(description='Session ID for anonymous users (when consent_granted is false)'),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var anonymous_session_id : str | None
var consent_granted : bool
var consent_scope : list[ConsentScopeEnum] | None
var consent_timestamp : pydantic.types.AwareDatetime | None
var model_config
var privacy_policy_acknowledged : PrivacyPolicyAcknowledged | None
var user : User | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiInitiateSessionRequest (**data: Any)

Expand source code

class SiInitiateSessionRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    context: Annotated[
        str, Field(description='Conversation handoff from the host describing what the user needs')
    ]
    identity: si_identity.SiIdentity
    media_buy_id: Annotated[
        str | None, Field(description='AdCP media buy ID if session was triggered by advertising')
    ] = None
    placement: Annotated[
        str | None,
        Field(
            description="Where this session was triggered (e.g., 'chatgpt_search', 'claude_chat')"
        ),
    ] = None
    offering_id: Annotated[
        str | None, Field(description='Brand-specific offering identifier to apply')
    ] = None
    supported_capabilities: Annotated[
        si_capabilities.SiCapabilities | None,
        Field(description='What capabilities the host supports'),
    ] = None
    offering_token: Annotated[
        str | None,
        Field(
            description="Token from si_get_offering response for session continuity. Brand uses this to recall what products were shown to the user, enabling natural references like 'the second one' or 'that blue shoe'."
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for this request. Prevents duplicate session creation on retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : str
var ext : ExtensionObject | None
var idempotency_key : str
var identity : SiIdentity
var media_buy_id : str | None
var model_config
var offering_id : str | None
var offering_token : str | None
var placement : str | None
var supported_capabilities : SiCapabilities | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiInitiateSessionResponse (**data: Any)

Expand source code

class SiInitiateSessionResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    session_id: Annotated[
        str, Field(description='Unique session identifier for subsequent messages')
    ]
    response: Annotated[Response | None, Field(description="Brand agent's initial response")] = None
    negotiated_capabilities: Annotated[
        si_capabilities.SiCapabilities | None,
        Field(description='Intersection of brand and host capabilities for this session'),
    ] = None
    session_status: Annotated[
        si_session_status.SiSessionStatus,
        Field(
            description='Current session lifecycle state. Returned in initiation, message, and termination responses.'
        ),
    ]
    session_ttl_seconds: Annotated[
        int | None,
        Field(
            description='Session inactivity timeout in seconds. After this duration without a message, the brand agent may terminate the session. Hosts SHOULD warn users before timeout when possible.',
            ge=1,
        ),
    ] = None
    errors: Annotated[
        list[error.Error] | None, Field(description='Errors during session initiation')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 negotiated_capabilities : SiCapabilities | None
var response : Response | None
var session_id : str
var session_status : SiSessionStatus
var session_ttl_seconds : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiSendMessageRequest (**data: Any)

Expand source code

class SiSendMessageRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Each conversational turn is a distinct mutation of session transcript — without this key, a timeout-and-retry produces a duplicate turn and a duplicate model response. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each user turn.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    session_id: Annotated[str, Field(description='Active session identifier')]
    message: Annotated[str | None, Field(description="User's message to the brand agent")] = None
    action_response: Annotated[
        ActionResponse | None,
        Field(description='Response to a previous action_button (e.g., user clicked checkout)'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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_response : ActionResponse | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var message : str | None
var model_config
var session_id : str

class SiSendTextMessageRequest (**data: Any)

Expand source code

class SiSendMessageRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Each conversational turn is a distinct mutation of session transcript — without this key, a timeout-and-retry produces a duplicate turn and a duplicate model response. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each user turn.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    session_id: Annotated[str, Field(description='Active session identifier')]
    message: Annotated[str | None, Field(description="User's message to the brand agent")] = None
    action_response: Annotated[
        ActionResponse | None,
        Field(description='Response to a previous action_button (e.g., user clicked checkout)'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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_response : ActionResponse | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var message : str | None
var model_config
var session_id : str

class SiSendActionResponseRequest (**data: Any)

Expand source code

class SiSendMessageRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Each conversational turn is a distinct mutation of session transcript — without this key, a timeout-and-retry produces a duplicate turn and a duplicate model response. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each user turn.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    session_id: Annotated[str, Field(description='Active session identifier')]
    message: Annotated[str | None, Field(description="User's message to the brand agent")] = None
    action_response: Annotated[
        ActionResponse | None,
        Field(description='Response to a previous action_button (e.g., user clicked checkout)'),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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_response : ActionResponse | None
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var message : str | None
var model_config
var session_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiSendMessageResponse (**data: Any)

Expand source code

class SiSendMessageResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    session_id: Annotated[str, Field(description='Session identifier')]
    response: Annotated[Response | None, Field(description="Brand agent's response")] = None
    mcp_resource_uri: Annotated[
        str | None,
        Field(
            description='MCP resource URI for hosts with MCP Apps support (e.g., ui://si/session-abc123)'
        ),
    ] = None
    session_status: Annotated[
        si_session_status.SiSessionStatus,
        Field(
            description='Current session status. On a successful response, one of: active, pending_handoff, or complete. Terminated sessions return error codes (SESSION_NOT_FOUND or SESSION_TERMINATED) instead of a success response.'
        ),
    ]
    handoff: Annotated[
        Handoff | None, Field(description='Handoff request when session_status is pending_handoff')
    ] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 handoff : Handoff | None
var mcp_resource_uri : str | None
var model_config
var response : Response | None
var session_id : str
var session_status : SiSessionStatus

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiTerminateSessionRequest (**data: Any)

Expand source code

class SiTerminateSessionRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    session_id: Annotated[str, Field(description='Session identifier to terminate')]
    reason: Annotated[Reason, Field(description='Reason for termination')]
    termination_context: Annotated[
        TerminationContext | None, Field(description='Context for the termination')
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var reason : Reason
var session_id : str
var termination_context : TerminationContext | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiTerminateSessionResponse (**data: Any)

Expand source code

class SiTerminateSessionResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    session_id: Annotated[str, Field(description='Terminated session identifier')]
    terminated: Annotated[bool, Field(description='Whether session was successfully terminated')]
    session_status: Annotated[
        si_session_status.SiSessionStatus | None,
        Field(
            description="Resulting session state. 'complete' for handoff_transaction/handoff_complete, 'terminated' for user_exit/session_timeout/host_terminated."
        ),
    ] = None
    acp_handoff: Annotated[
        AcpHandoff | None,
        Field(description='ACP checkout handoff data. Present when reason is handoff_transaction.'),
    ] = None
    follow_up: Annotated[FollowUp | None, Field(description='Suggested follow-up actions')] = None
    errors: list[error.Error] | None = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var acp_handoff : AcpHandoff | None
var context : ContextObject | None
var errors : list[Error] | None
var ext : ExtensionObject | None
var follow_up : FollowUp | None
var model_config
var session_id : str
var session_status : SiSessionStatus | None
var terminated : bool

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SiUiElement (**data: Any)

Expand source code

class SiUiElement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[Type, Field(description='Component type')]
    data: Annotated[dict[str, Any] | None, Field(description='Component-specific data')] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var data : dict[str, typing.Any] | None
var model_config
var type : Type

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Signal (**data: Any)

Expand source code

class Signal(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    signal_id: Annotated[
        signal_id_1.SignalId,
        Field(
            description="Universal signal identifier referencing the data provider's catalog. Use this to verify authorization and look up signal definitions."
        ),
    ]
    signal_agent_segment_id: Annotated[
        str,
        Field(
            description="Opaque identifier used for activation. This is the signals agent's internal segment ID."
        ),
    ]
    name: Annotated[str, Field(description='Human-readable signal name')]
    description: Annotated[str, Field(description='Detailed signal description')]
    value_type: Annotated[
        signal_value_type.SignalValueType | None,
        Field(description="The data type of this signal's values (binary, categorical, numeric)"),
    ] = None
    categories: Annotated[
        list[str] | None,
        Field(
            description="Valid values for categorical signals. Present when value_type is 'categorical'. Buyers must use one of these values in SignalTargeting.values."
        ),
    ] = None
    range: Annotated[
        Range | None,
        Field(description="Valid range for numeric signals. Present when value_type is 'numeric'."),
    ] = None
    signal_type: Annotated[
        signal_catalog_type.SignalCatalogType,
        Field(description='Catalog type of signal (marketplace, custom, owned)'),
    ]
    data_provider: Annotated[str, Field(description='Human-readable name of the data provider')]
    coverage_percentage: Annotated[
        float, Field(description='Percentage of audience coverage', ge=0.0, le=100.0)
    ]
    deployments: Annotated[
        list[deployment.Deployment], Field(description='Array of deployment targets')
    ]
    pricing_options: Annotated[
        list[vendor_pricing_option.VendorPricingOption],
        Field(
            description='Pricing options available for this signal. The buyer selects one and passes its pricing_option_id in report_usage for billing verification.',
            min_length=1,
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var categories : list[str] | None
var coverage_percentage : float
var data_provider : str
var deployments : list[Deployment]
var description : str
var model_config
var name : str
var pricing_options : list[VendorPricingOption]
var range : Range | None
var signal_agent_segment_id : str
var signal_id : SignalId
var signal_type : SignalCatalogType
var value_type : SignalValueType | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalCatalogType (*args, **kwds)

Expand source code

class SignalCatalogType(Enum):
    marketplace = 'marketplace'
    custom = 'custom'
    owned = 'owned'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var custom
var marketplace
var owned

class SignalType (*args, **kwds)

Expand source code

class SignalCatalogType(Enum):
    marketplace = 'marketplace'
    custom = 'custom'
    owned = 'owned'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var custom
var marketplace
var owned

class SignalFilters (**data: Any)

Expand source code

class SignalFilters(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    catalog_types: Annotated[
        list[signal_catalog_type.SignalCatalogType] | None,
        Field(description='Filter by catalog type', min_length=1),
    ] = None
    data_providers: Annotated[
        list[str] | None, Field(description='Filter by specific data providers', min_length=1)
    ] = None
    max_cpm: Annotated[
        float | None,
        Field(description="Maximum CPM filter. Applies only to signals with model='cpm'.", ge=0.0),
    ] = None
    max_percent: Annotated[
        float | None,
        Field(
            description='Maximum percent-of-media rate filter. Signals where all percent_of_media pricing options exceed this value are excluded. Does not account for max_cpm caps.',
            ge=0.0,
            le=100.0,
        ),
    ] = None
    min_coverage_percentage: Annotated[
        float | None, Field(description='Minimum coverage requirement', ge=0.0, le=100.0)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalog_types : list[SignalCatalogType] | None
var data_providers : list[str] | None
var max_cpm : float | None
var max_percent : float | None
var min_coverage_percentage : float | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SignalPricingOption (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class SignalPricingOption(RootModel[vendor_pricing_option.VendorPricingOption]):
    root: Annotated[
        vendor_pricing_option.VendorPricingOption,
        Field(
            description='Deprecated — use vendor-pricing-option.json for new implementations. This alias is retained for backward compatibility.',
            title='Signal Pricing Option',
        ),
    ]

Usage Documentation

RootModel and Custom Root Types

A Pydantic BaseModel for the root object of the model.

Attributes

root: The root object of the model.
__pydantic_root_model__: Whether the model is a RootModel.
__pydantic_private__: Private fields in the model.
__pydantic_extra__: Extra fields in the model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.root_model.RootModel[VendorPricingOption]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : VendorPricingOption

class Snapshot (**data: Any)

Expand source code

class Snapshot(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    as_of: Annotated[
        AwareDatetime, Field(description='When this snapshot was captured by the platform')
    ]
    staleness_seconds: Annotated[
        int,
        Field(
            description='Maximum age of this data in seconds. For example, 3600 means the data may be up to 1 hour old.',
            ge=0,
        ),
    ]
    impressions: Annotated[
        int,
        Field(
            description='Lifetime impressions across all assignments. Not scoped to any date range.',
            ge=0,
        ),
    ]
    last_served: Annotated[
        AwareDatetime | None,
        Field(
            description='Last time this creative served an impression. Absent when the creative has never served.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var as_of : pydantic.types.AwareDatetime
var impressions : int
var last_served : pydantic.types.AwareDatetime | None
var model_config
var staleness_seconds : int

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SnapshotUnavailableReason (*args, **kwds)

Expand source code

class SnapshotUnavailableReason(Enum):
    SNAPSHOT_UNSUPPORTED = 'SNAPSHOT_UNSUPPORTED'
    SNAPSHOT_TEMPORARILY_UNAVAILABLE = 'SNAPSHOT_TEMPORARILY_UNAVAILABLE'
    SNAPSHOT_PERMISSION_DENIED = 'SNAPSHOT_PERMISSION_DENIED'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var SNAPSHOT_PERMISSION_DENIED
var SNAPSHOT_TEMPORARILY_UNAVAILABLE
var SNAPSHOT_UNSUPPORTED

class Sort (**data: Any)

Expand source code

class Sort(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    field: Annotated[Field1 | None, Field(description='Field to sort by')] = Field1.created_at
    direction: Annotated[
        sort_direction.SortDirection | None, Field(description='Sort direction')
    ] = sort_direction.SortDirection.desc

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var direction : SortDirection | None
var field : Field1 | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SortApplied (**data: Any)

Expand source code

class SortApplied(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    field: str
    direction: Direction

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var direction : Direction
var field : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SortDirection (*args, **kwds)

Expand source code

class SortDirection(Enum):
    asc = "asc"
    desc = "desc"

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var asc
var desc

class Status (*args, **kwds)

Expand source code

class Status(Enum):
    pending_creatives = 'pending_creatives'
    pending_start = 'pending_start'
    pending = 'pending'
    active = 'active'
    paused = 'paused'
    completed = 'completed'
    rejected = 'rejected'
    canceled = 'canceled'
    failed = 'failed'
    reporting_delayed = 'reporting_delayed'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var active
var canceled
var completed
var failed
var paused
var pending
var pending_creatives
var pending_start
var rejected
var reporting_delayed

class MediaBuyDeliveryStatus (*args, **kwds)

Expand source code

class Status(Enum):
    pending_creatives = 'pending_creatives'
    pending_start = 'pending_start'
    pending = 'pending'
    active = 'active'
    paused = 'paused'
    completed = 'completed'
    rejected = 'rejected'
    canceled = 'canceled'
    failed = 'failed'
    reporting_delayed = 'reporting_delayed'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var active
var canceled
var completed
var failed
var paused
var pending
var pending_creatives
var pending_start
var rejected
var reporting_delayed

class StatusSummary (**data: Any)

Expand source code

class StatusSummary(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    processing: Annotated[
        int | None, Field(description='Number of creatives being processed', ge=0)
    ] = None
    approved: Annotated[int | None, Field(description='Number of approved creatives', ge=0)] = None
    pending_review: Annotated[
        int | None, Field(description='Number of creatives pending review', ge=0)
    ] = None
    rejected: Annotated[int | None, Field(description='Number of rejected creatives', ge=0)] = None
    archived: Annotated[int | None, Field(description='Number of archived creatives', ge=0)] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var approved : int | None
var archived : int | None
var model_config
var pending_review : int | None
var processing : int | None
var rejected : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAccountsRequest (**data: Any)

Expand source code

class SyncAccountsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. Natural per-account upsert keys (brand, operator) handle resource-level dedup, but the envelope triggers onboarding webhooks, billing setup, and audit events — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    accounts: Annotated[
        list[Account], Field(description='Advertiser accounts to sync', max_length=1000)
    ]
    delete_missing: Annotated[
        bool | None,
        Field(
            description='When true, accounts previously synced by this agent but not included in this request will be deactivated. Scoped to the authenticated agent — does not affect accounts managed by other agents. Use with caution.'
        ),
    ] = False
    dry_run: Annotated[
        bool | None,
        Field(
            description='When true, preview what would change without applying. Returns what would be created/updated/deactivated.'
        ),
    ] = False
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Webhook for async notifications when account status changes (e.g., pending_approval transitions to active).'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accounts : list[Account]
var adcp_major_version : int | None
var context : ContextObject | None
var delete_missing : bool | None
var dry_run : bool | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var push_notification_config : PushNotificationConfig | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAccountsSuccessResponse (**data: Any)

Expand source code

class SyncAccountsResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    dry_run: Annotated[
        bool | None, Field(description='Whether this was a dry run (no actual changes made)')
    ] = None
    accounts: Annotated[list[Account], Field(description='Results for each account processed')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accounts : list[Account]
var context : ContextObject | None
var dry_run : bool | None
var ext : ExtensionObject | None
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAccountsErrorResponse (**data: Any)

Expand source code

class SyncAccountsResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[
        list[error.Error],
        Field(
            description='Operation-level errors (e.g., authentication failure, service unavailable)',
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesRequest (**data: Any)

Expand source code

class SyncAudiencesRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
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

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesSuccessResponse (**data: Any)

Expand source code

class SyncAudiencesResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    audiences: Annotated[
        list[Audience], Field(description='Results for each audience on the account')
    ]
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

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

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncAudiencesErrorResponse (**data: Any)

Expand source code

class SyncAudiencesResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[
        list[error.Error],
        Field(description='Operation-level errors that prevented processing', min_length=1),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `catalog_id` gives resource-level dedup per catalog, but the sync envelope emits audit events and triggers platform review for large feeds — this key prevents those side effects from firing twice on retry. Also serves as a request ID on discovery-only calls (when `catalogs` 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 that owns these catalogs.')
    ]
    catalogs: Annotated[
        list[catalog.Catalog] | None,
        Field(
            description='Array of catalog feeds to sync (create or update). When omitted, the call is discovery-only and returns all existing catalogs on the account without modification.',
            max_length=50,
            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[
        bool | 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. Do not combine with an omitted catalogs array or all buyer-managed catalogs will be deleted.'
        ),
    ] = False
    dry_run: Annotated[
        bool | None,
        Field(
            description='When true, preview changes without applying them. Returns what would be created/updated/deleted.'
        ),
    ] = False
    validation_mode: Annotated[
        validation_mode_1.ValidationMode | None,
        Field(
            description="Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid catalogs and reports errors."
        ),
    ] = validation_mode_1.ValidationMode.strict
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async sync notifications. 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
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 model_config
var push_notification_config : PushNotificationConfig | None
var validation_mode : ValidationMode | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncCatalogsSuccessResponse (**data: Any)

Expand source code

class SyncCatalogsResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    dry_run: Annotated[
        bool | None, Field(description='Whether this was a dry run (no actual changes made)')
    ] = None
    catalogs: Annotated[
        list[Catalog],
        Field(
            description="Results for each catalog processed. Items with action='failed' indicate per-catalog validation/processing failures, not operation-level failures."
        ),
    ]
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalogs : list[Catalog]
var context : ContextObject | None
var dry_run : bool | None
var ext : ExtensionObject | None
var model_config
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncCatalogsErrorResponse (**data: Any)

Expand source code

class SyncCatalogsResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[
        list[error.Error],
        Field(
            description='Operation-level errors that prevented processing any catalogs (e.g., authentication failure, service unavailable, invalid request format)',
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncCatalogsSubmitted (**data: Any)

Expand source code

class SyncCatalogsSubmitted(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

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[
        float | 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[
        int | None, Field(description='Total number of steps in the operation', ge=1)
    ] = None
    step_number: Annotated[int | None, Field(description='Current step number', ge=1)] = None
    catalogs_processed: Annotated[
        int | None, Field(description='Number of catalogs processed so far', ge=0)
    ] = None
    catalogs_total: Annotated[
        int | None, Field(description='Total number of catalogs to process', ge=0)
    ] = None
    items_processed: Annotated[
        int | None,
        Field(description='Total number of catalog items processed across all catalogs', ge=0),
    ] = None
    items_total: Annotated[
        int | 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.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var catalogs_processed : int | None
var catalogs_total : int | None
var context : ContextObject | None
var current_step : str | None
var ext : ExtensionObject | None
var items_processed : int | None
var items_total : int | None
var model_config
var percentage : float | None
var step_number : int | None
var total_steps : int | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncCreativesRequest (**data: Any)

Expand source code

class SyncCreativesRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: Annotated[
        account_ref.AccountReference, Field(description='Account that owns these creatives.')
    ]
    creatives: Annotated[
        list[creative_asset.CreativeAsset],
        Field(
            description='Array of creative assets to sync (create or update)',
            max_length=100,
            min_length=1,
        ),
    ]
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional filter to limit sync scope to specific creative IDs. When provided, only these creatives will be created/updated. Other creatives in the library are unaffected. Useful for partial updates and error recovery.',
            max_length=100,
            min_length=1,
        ),
    ] = None
    assignments: Annotated[
        list[Assignment] | None,
        Field(
            description='Optional bulk assignment of creatives to packages. Each entry maps one creative to one package with optional weight and placement targeting. Standalone creative agents that do not manage media buys ignore this field.',
            min_length=1,
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated idempotency key for safe retries. If a sync fails without a response, resending with the same idempotency_key guarantees at-most-once execution. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    delete_missing: Annotated[
        bool | None,
        Field(
            description='When true, creatives not included in this sync will be archived. Use with caution for full library replacement. Invalid when creative_ids is provided — delete_missing applies to the entire library scope, not a filtered subset.'
        ),
    ] = False
    dry_run: Annotated[
        bool | None,
        Field(
            description='When true, preview changes without applying them. Returns what would be created/updated/deleted.'
        ),
    ] = False
    validation_mode: Annotated[
        validation_mode_1.ValidationMode | None,
        Field(
            description="Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid creatives and reports errors."
        ),
    ] = validation_mode_1.ValidationMode.strict
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async sync notifications. The agent will send a webhook when sync completes if the operation takes longer than immediate response time (typically for large bulk operations or manual approval/HITL).'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
var assignments : list[Assignment] | None
var context : ContextObject | None
var creative_ids : list[str] | None
var creatives : list[CreativeAsset]
var delete_missing : bool | None
var dry_run : bool | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var push_notification_config : PushNotificationConfig | None
var validation_mode : ValidationMode | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncCreativesSuccessResponse (**data: Any)

Expand source code

class SyncCreativesResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    dry_run: Annotated[
        bool | None, Field(description="Whether this was a dry run (no actual changes made)")
    ] = None
    creatives: Annotated[
        list[Creative],
        Field(
            description="Results for each creative processed. Items with action='failed' indicate per-item validation/processing failures, not operation-level failures."
        ),
    ]
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 creatives : list[Creative]
var dry_run : bool | None
var ext : ExtensionObject | None
var model_config
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncCreativesErrorResponse (**data: Any)

Expand source code

class SyncCreativesResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra="allow",
    )
    errors: Annotated[
        list[error.Error],
        Field(
            description="Operation-level errors that prevented processing any creatives (e.g., authentication failure, service unavailable, invalid request format)",
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncEventSourcesRequest (**data: Any)

Expand source code

class SyncEventSourcesRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    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[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
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

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncEventSourcesSuccessResponse (**data: Any)

Expand source code

class SyncEventSourcesResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    event_sources: Annotated[
        list[EventSource],
        Field(
            description='Results for each event source, including both synced and seller-managed sources on the account'
        ),
    ]
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 event_sources : list[EventSource]
var ext : ExtensionObject | None
var model_config
var sandbox : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncEventSourcesErrorResponse (**data: Any)

Expand source code

class SyncEventSourcesResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[
        list[error.Error],
        Field(description='Operation-level errors that prevented processing', min_length=1),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncGovernanceRequest (**data: Any)

Expand source code

class SyncGovernanceRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `account` gives resource-level dedup, but governance changes emit audit events and can trigger reapproval flows — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    accounts: Annotated[
        list[Account],
        Field(
            description='Per-account governance agent configuration. Each entry pairs an account reference with the governance agents for that account.',
            max_length=100,
            min_length=1,
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var accounts : list[Account]
var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncPlansRequest (**data: Any)

Expand source code

class SyncPlansRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. `plan_id` gives resource-level dedup per plan, but the sync envelope emits audit events and can trigger governance reapproval — this key prevents those side effects from firing twice on retry. MUST be unique per (seller, request) pair. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    plans: Annotated[list[Plan], Field(description='One or more campaign plans to sync.')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var plans : list[Plan]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class SyncPlansResponse (**data: Any)

Expand source code

class SyncPlansResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra="forbid",
    )
    plans: Annotated[list[Plan], Field(description="Status for each synced plan.")]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 plans : list[Plan]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Tags (**data: Any)

Expand source code

class Tags(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    name: Annotated[str, Field(description='Human-readable name for this tag')]
    description: Annotated[str, Field(description='Description of what this tag represents')]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Subclasses

SignalTags

Class variables

var description : str
var model_config
var name : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TargetingOverlay (**data: Any)

Expand source code

class TargetingOverlay(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    geo_countries: Annotated[
        list[GeoCountry] | None,
        Field(
            description="Restrict delivery to specific countries. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').",
            min_length=1,
        ),
    ] = None
    geo_countries_exclude: Annotated[
        list[GeoCountriesExcludeItem] | None,
        Field(
            description="Exclude specific countries from delivery. ISO 3166-1 alpha-2 codes (e.g., 'US', 'GB', 'DE').",
            min_length=1,
        ),
    ] = None
    geo_regions: Annotated[
        list[GeoRegion] | None,
        Field(
            description="Restrict delivery to specific regions/states. ISO 3166-2 subdivision codes (e.g., 'US-CA', 'GB-SCT').",
            min_length=1,
        ),
    ] = None
    geo_regions_exclude: Annotated[
        list[GeoRegionsExcludeItem] | None,
        Field(
            description="Exclude specific regions/states from delivery. ISO 3166-2 subdivision codes (e.g., 'US-CA', 'GB-SCT').",
            min_length=1,
        ),
    ] = None
    geo_metros: Annotated[
        list[GeoMetro] | None,
        Field(
            description='Restrict delivery to specific metro areas. Each entry specifies the classification system and target values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_metros_exclude: Annotated[
        list[GeoMetrosExcludeItem] | None,
        Field(
            description='Exclude specific metro areas from delivery. Each entry specifies the classification system and excluded values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_postal_areas: Annotated[
        list[GeoPostalArea] | None,
        Field(
            description='Restrict delivery to specific postal areas. Each entry specifies the postal system and target values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    geo_postal_areas_exclude: Annotated[
        list[GeoPostalAreasExcludeItem] | None,
        Field(
            description='Exclude specific postal areas from delivery. Each entry specifies the postal system and excluded values. Seller must declare supported systems in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    daypart_targets: Annotated[
        list[daypart_target.DaypartTarget] | None,
        Field(
            description='Restrict delivery to specific time windows. Each entry specifies days of week and an hour range.',
            min_length=1,
        ),
    ] = None
    axe_include_segment: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated: Use TMP provider fields instead. AXE segment ID to include for targeting.',
        ),
    ] = None
    axe_exclude_segment: Annotated[
        str | None,
        Field(
            deprecated=True,
            description='Deprecated: Use TMP provider fields instead. AXE segment ID to exclude from targeting.',
        ),
    ] = None
    audience_include: Annotated[
        list[str] | None,
        Field(
            description='Restrict delivery to members of these first-party CRM audiences. Only users present in the uploaded lists are eligible. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Not for lookalike expansion — express that intent in the campaign brief. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    audience_exclude: Annotated[
        list[str] | None,
        Field(
            description='Suppress delivery to members of these first-party CRM audiences. Matched users are excluded regardless of other targeting. References audience_id values from sync_audiences on the same seller account — audience IDs are not portable across sellers. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    frequency_cap: frequency_cap_1.FrequencyCap | None = None
    property_list: Annotated[
        property_list_ref.PropertyListReference | None,
        Field(
            description="Reference to a property list for targeting specific properties within this product. The package runs on the intersection of the product's publisher_properties and this list. Sellers SHOULD return a validation error if the product has property_targeting_allowed: false."
        ),
    ] = None
    collection_list: Annotated[
        collection_list_ref.CollectionListReference | None,
        Field(
            description='Reference to a collection list for including specific collections (programs, shows) within this product. The package runs on the intersection of matched collections and this list. Use for inclusion-based collection targeting. Seller must declare support in get_adcp_capabilities.'
        ),
    ] = None
    collection_list_exclude: Annotated[
        collection_list_ref.CollectionListReference | None,
        Field(
            description="Reference to a collection list for excluding specific collections (programs, shows) from this product. Matched collections must not carry the buyer's ads. Use for brand safety do-not-air lists. Seller must declare support in get_adcp_capabilities."
        ),
    ] = None
    age_restriction: Annotated[
        AgeRestriction | None,
        Field(
            description='Age restriction for compliance. Use for legal requirements (alcohol, gambling), not audience targeting.'
        ),
    ] = None
    device_platform: Annotated[
        list[device_platform_1.DevicePlatform] | None,
        Field(
            description='Restrict to specific platforms. Use for technical compatibility (app only works on iOS). Values from Sec-CH-UA-Platform standard, extended for CTV.',
            min_length=1,
        ),
    ] = None
    device_type: Annotated[
        list[device_type_1.DeviceType] | None,
        Field(
            description='Restrict to specific device form factors. Use for campaigns targeting hardware categories rather than operating systems (e.g., mobile-only promotions, CTV campaigns).',
            min_length=1,
        ),
    ] = None
    device_type_exclude: Annotated[
        list[device_type_1.DeviceType] | None,
        Field(
            description='Exclude specific device form factors from delivery (e.g., exclude CTV for app-install campaigns).',
            min_length=1,
        ),
    ] = None
    store_catchments: Annotated[
        list[StoreCatchment] | None,
        Field(
            description='Target users within store catchment areas from a synced store catalog. Each entry references a store-type catalog and optionally narrows to specific stores or catchment zones.',
            min_length=1,
        ),
    ] = None
    geo_proximity: Annotated[
        list[GeoProximity | GeoProximity18 | GeoProximity19] | None,
        Field(
            description='Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    language: Annotated[
        list[LanguageItem] | None,
        Field(
            description="Restrict to users with specific language preferences. ISO 639-1 codes (e.g., 'en', 'es', 'fr').",
            min_length=1,
        ),
    ] = None
    keyword_targets: Annotated[
        list[KeywordTarget] | None,
        Field(
            description='Keyword targeting for search and retail media platforms. Restricts delivery to queries matching the specified keywords. Each keyword is identified by the tuple (keyword, match_type) — the same keyword string with different match types are distinct targets. Sellers SHOULD reject duplicate (keyword, match_type) pairs within a single request. Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None
    negative_keywords: Annotated[
        list[NegativeKeyword] | None,
        Field(
            description='Keywords to exclude from delivery. Queries matching these keywords will not trigger the ad. Each negative keyword is identified by the tuple (keyword, match_type). Seller must declare support in get_adcp_capabilities.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var age_restriction : AgeRestriction | None
var audience_exclude : list[str] | None
var audience_include : list[str] | None
var collection_list : CollectionListReference | None
var collection_list_exclude : CollectionListReference | None
var daypart_targets : list[DaypartTarget] | None
var device_platform : list[DevicePlatform] | None
var device_type : list[DeviceType] | None
var device_type_exclude : list[DeviceType] | None
var frequency_cap : FrequencyCap | None
var geo_countries : list[GeoCountry] | None
var geo_countries_exclude : list[GeoCountriesExcludeItem] | None
var geo_metros : list[GeoMetro] | None
var geo_metros_exclude : list[GeoMetrosExcludeItem] | None
var geo_postal_areas : list[GeoPostalArea] | None
var geo_postal_areas_exclude : list[GeoPostalAreasExcludeItem] | None
var geo_proximity : list[GeoProximity | GeoProximity18 | GeoProximity19] | None
var geo_regions : list[GeoRegion] | None
var geo_regions_exclude : list[GeoRegionsExcludeItem] | None
var keyword_targets : list[KeywordTarget] | None
var language : list[LanguageItem] | None
var model_config
var negative_keywords : list[NegativeKeyword] | None
var property_list : PropertyListReference | None
var store_catchments : list[StoreCatchment] | None

Instance variables

var axe_exclude_segment : 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.

var axe_include_segment : 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

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TaskResult (**data: Any)

Expand source code

class TaskResult(BaseModel, Generic[T]):
    """Result from task execution."""

    model_config = ConfigDict(arbitrary_types_allowed=True)

    status: TaskStatus
    data: T | None = None
    message: str | None = None  # Human-readable message from agent (e.g., MCP content text)
    submitted: SubmittedInfo | None = None
    needs_input: NeedsInputInfo | None = None
    error: str | None = None
    success: bool = Field(default=True)
    metadata: dict[str, Any] | None = None
    debug_info: DebugInfo | None = None
    # The full idempotency_key the SDK used for this request — echoed here so
    # buyers can correlate against their own records. SENSITIVE inside the
    # seller's replay_ttl_seconds window (serves as a retry-pattern oracle);
    # do not emit to shared logs. The SDK's debug capture redacts keys by
    # default; avoid ``model_dump_json()``-ing a TaskResult into shared sinks.
    idempotency_key: str | None = None
    # True when the seller returned a cached response for a replayed key.
    # Agents that emit side effects on success (notifications, memory writes,
    # downstream tool calls) must check this flag and suppress duplicates.
    replayed: bool = False

Result from task execution.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel
typing.Generic

Subclasses

adcp.types.core.TaskResult[AdcpAsyncResponseData]
adcp.types.core.TaskResult[Any]
adcp.types.core.TaskResult[CheckGovernanceResponse]
adcp.types.core.TaskResult[ContextMatchResponse]
adcp.types.core.TaskResult[CreateCollectionListResponse]
adcp.types.core.TaskResult[CreatePropertyListResponse]
adcp.types.core.TaskResult[DeleteCollectionListResponse]
adcp.types.core.TaskResult[DeletePropertyListResponse]
adcp.types.core.TaskResult[GetAdcpCapabilitiesResponse]
adcp.types.core.TaskResult[GetCollectionListResponse]
adcp.types.core.TaskResult[GetCreativeDeliveryResponse]
adcp.types.core.TaskResult[GetMediaBuyDeliveryResponse]
adcp.types.core.TaskResult[GetMediaBuysResponse]
adcp.types.core.TaskResult[GetPlanAuditLogsResponse]
adcp.types.core.TaskResult[GetProductsResponse]
adcp.types.core.TaskResult[GetPropertyListResponse]
adcp.types.core.TaskResult[GetSignalsResponse]
adcp.types.core.TaskResult[IdentityMatchResponse]
adcp.types.core.TaskResult[ListAccountsResponse]
adcp.types.core.TaskResult[ListCollectionListsResponse]
adcp.types.core.TaskResult[ListCreativeFormatsResponse]
adcp.types.core.TaskResult[ListCreativesResponse]
adcp.types.core.TaskResult[ListPropertyListsResponse]
adcp.types.core.TaskResult[ReportPlanOutcomeResponse]
adcp.types.core.TaskResult[ReportUsageResponse]
adcp.types.core.TaskResult[SiGetOfferingResponse]
adcp.types.core.TaskResult[SiInitiateSessionResponse]
adcp.types.core.TaskResult[SiSendMessageResponse]
adcp.types.core.TaskResult[SiTerminateSessionResponse]
adcp.types.core.TaskResult[SyncPlansResponse]
adcp.types.core.TaskResult[Union[AcquireRightsResponse1, AcquireRightsResponse2, AcquireRightsResponse3, AcquireRightsResponse4]]
adcp.types.core.TaskResult[Union[ActivateSignalResponse1, ActivateSignalResponse2]]
adcp.types.core.TaskResult[Union[BuildCreativeResponse1, BuildCreativeResponse2, BuildCreativeResponse3]]
adcp.types.core.TaskResult[Union[CalibrateContentResponse1, CalibrateContentResponse2]]
adcp.types.core.TaskResult[Union[ComplyTestControllerResponse1, ComplyTestControllerResponse2, ComplyTestControllerResponse3, ComplyTestControllerResponse4]]
adcp.types.core.TaskResult[Union[CreateContentStandardsResponse1, CreateContentStandardsResponse2]]
adcp.types.core.TaskResult[Union[CreateMediaBuyResponse1, CreateMediaBuyResponse2, CreateMediaBuyResponse3]]
adcp.types.core.TaskResult[Union[GetAccountFinancialsResponse1, GetAccountFinancialsResponse2]]
adcp.types.core.TaskResult[Union[GetBrandIdentityResponse1, GetBrandIdentityResponse2]]
adcp.types.core.TaskResult[Union[GetContentStandardsResponse1, GetContentStandardsResponse2]]
adcp.types.core.TaskResult[Union[GetCreativeFeaturesResponse1, GetCreativeFeaturesResponse2]]
adcp.types.core.TaskResult[Union[GetMediaBuyArtifactsResponse1, GetMediaBuyArtifactsResponse2]]
adcp.types.core.TaskResult[Union[GetRightsResponse1, GetRightsResponse2]]
adcp.types.core.TaskResult[Union[ListContentStandardsResponse1, ListContentStandardsResponse2]]
adcp.types.core.TaskResult[Union[LogEventResponse1, LogEventResponse2]]
adcp.types.core.TaskResult[Union[PreviewCreativeResponse1, PreviewCreativeResponse2, PreviewCreativeResponse3]]
adcp.types.core.TaskResult[Union[ProvidePerformanceFeedbackResponse1, ProvidePerformanceFeedbackResponse2]]
adcp.types.core.TaskResult[Union[SyncAccountsResponse1, SyncAccountsResponse2]]
adcp.types.core.TaskResult[Union[SyncAudiencesResponse1, SyncAudiencesResponse2]]
adcp.types.core.TaskResult[Union[SyncCatalogsResponse1, SyncCatalogsResponse2]]
adcp.types.core.TaskResult[Union[SyncCreativesResponse1, SyncCreativesResponse2, SyncCreativesResponse3]]
adcp.types.core.TaskResult[Union[SyncEventSourcesResponse1, SyncEventSourcesResponse2]]
adcp.types.core.TaskResult[Union[SyncGovernanceResponse1, SyncGovernanceResponse2]]
adcp.types.core.TaskResult[Union[UpdateContentStandardsResponse1, UpdateContentStandardsResponse2]]
adcp.types.core.TaskResult[Union[UpdateMediaBuyResponse1, UpdateMediaBuyResponse2]]
adcp.types.core.TaskResult[Union[UpdateRightsResponse1, UpdateRightsResponse2]]
adcp.types.core.TaskResult[Union[ValidateContentDeliveryResponse1, ValidateContentDeliveryResponse2]]
adcp.types.core.TaskResult[UpdateCollectionListResponse]
adcp.types.core.TaskResult[UpdatePropertyListResponse]

Class variables

var data : ~T | None
var debug_info : DebugInfo | None
var error : str | None
var idempotency_key : str | None
var message : str | None
var metadata : dict[str, typing.Any] | None
var model_config
var needs_input : NeedsInputInfo | None
var replayed : bool
var status : TaskStatus
var submitted : SubmittedInfo | None
var success : bool

class GeneratedTaskStatus (*args, **kwds)

Expand source code

class TaskStatus(Enum):
    submitted = 'submitted'
    working = 'working'
    input_required = 'input-required'
    completed = 'completed'
    canceled = 'canceled'
    failed = 'failed'
    rejected = 'rejected'
    auth_required = 'auth-required'
    unknown = 'unknown'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var auth_required
var canceled
var completed
var failed
var input_required
var rejected
var submitted
var unknown
var working

class TaskType (*args, **kwds)

Expand source code

class TaskType(Enum):
    create_media_buy = 'create_media_buy'
    update_media_buy = 'update_media_buy'
    sync_creatives = 'sync_creatives'
    activate_signal = 'activate_signal'
    get_signals = 'get_signals'
    create_property_list = 'create_property_list'
    update_property_list = 'update_property_list'
    get_property_list = 'get_property_list'
    list_property_lists = 'list_property_lists'
    delete_property_list = 'delete_property_list'
    sync_accounts = 'sync_accounts'
    get_account_financials = 'get_account_financials'
    get_creative_delivery = 'get_creative_delivery'
    sync_event_sources = 'sync_event_sources'
    sync_audiences = 'sync_audiences'
    sync_catalogs = 'sync_catalogs'
    log_event = 'log_event'
    get_brand_identity = 'get_brand_identity'
    get_rights = 'get_rights'
    acquire_rights = 'acquire_rights'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var acquire_rights
var activate_signal
var create_media_buy
var create_property_list
var delete_property_list
var get_account_financials
var get_brand_identity
var get_creative_delivery
var get_property_list
var get_rights
var get_signals
var list_property_lists
var log_event
var sync_accounts
var sync_audiences
var sync_catalogs
var sync_creatives
var sync_event_sources
var update_media_buy
var update_property_list

class TextAsset (**data: Any)

Expand source code

class TextAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    content: Annotated[str, Field(description='Text content')]
    language: Annotated[str | None, Field(description="Language code (e.g., 'en', 'es', 'fr')")] = (
        None
    )
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 : str
var language : str | None
var model_config
var provenance : Provenance | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TextSubAsset (*args: object, **kwargs: object)

Expand source code

class TextSubAsset:
    """Removed from ADCP schema. Previously SubAsset with asset_kind='text'."""

    def __init__(self, *args: object, **kwargs: object) -> None:
        raise TypeError(
            "TextSubAsset was removed from the ADCP schema. " "There is no direct replacement."
        )

Removed from ADCP schema. Previously SubAsset with asset_kind='text'.

class TimeBasedPricingOption (**data: Any)

Expand source code

class TimeBasedPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['time'],
        Field(description='Cost per time unit - rate scales with campaign duration'),
    ]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Cost per time unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid per time unit for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    parameters: Annotated[Parameters, Field(description='Time-based pricing parameters')]
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var min_spend_per_package : float | None
var model_config
var parameters : Parameters
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['time']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class TimeUnit (*args, **kwds)

Expand source code

class TimeUnit(Enum):
    hour = 'hour'
    day = 'day'
    week = 'week'
    month = 'month'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var day
var hour
var month
var week

class TmpError (**data: Any)

Expand source code

class TmpError(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    type: Annotated[
        Literal['error'], Field(description='Message type discriminator for deserialization.')
    ]
    request_id: Annotated[
        str, Field(description='Echoed request identifier from the original request')
    ]
    code: Annotated[Code, Field(description='Machine-readable error code')]
    message: Annotated[
        str | None, Field(description='Human-readable error description for debugging')
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var code : Code
var message : str | None
var model_config
var request_id : str
var type : Literal['error']

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class Totals (**data: Any)

Expand source code

class Totals(DeliveryMetrics):
    effective_rate: Annotated[
        float | None,
        Field(
            description="Effective rate paid per unit based on pricing_model (e.g., actual CPM for 'cpm', actual cost per completed view for 'cpcv', actual cost per point for 'cpp')",
            ge=0.0,
        ),
    ] = None
    spend: Any

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

DeliveryMetrics
AdCPBaseModel
pydantic.main.BaseModel

Class variables

var effective_rate : float | None
var model_config
var spend : Any

Inherited members

DeliveryMetrics:
- model_dump
- model_dump_json
- model_summary

class Transform (*args, **kwds)

Expand source code

class Transform(Enum):
    date = 'date'
    divide = 'divide'
    boolean = 'boolean'
    split = 'split'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var boolean
var date
var divide
var split

class UpdateCollectionListRequest (**data: Any)

Expand source code

class UpdateCollectionListRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    list_id: Annotated[str, Field(description='ID of the collection list to update')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts; optional otherwise.'
        ),
    ] = None
    name: Annotated[str | None, Field(description='New name for the list')] = None
    description: Annotated[str | None, Field(description='New description')] = None
    base_collections: Annotated[
        list[base_collection_source.BaseCollectionSource] | None,
        Field(
            description='Complete replacement for the base collections list (not a patch). Each entry is a discriminated union: distribution_ids (platform-independent identifiers), publisher_collections (publisher_domain + collection_ids), or publisher_genres (publisher_domain + genres).'
        ),
    ] = None
    filters: Annotated[
        collection_list_filters.CollectionListFilters | None,
        Field(description='Complete replacement for the filters (not a patch)'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Update brand reference. Resolved to full brand identity at execution time.'
        ),
    ] = None
    webhook_url: Annotated[
        AnyUrl | None,
        Field(
            description='Update the webhook URL for list change notifications (set to empty string to remove). Governance agents MUST validate this URL against SSRF per docs/building/implementation/security#webhook-url-validation-ssrf.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var base_collections : list[BaseCollectionSource] | None
var brand : BrandReference | None
var context : ContextObject | None
var description : str | None
var ext : ExtensionObject | None
var filters : CollectionListFilters | None
var idempotency_key : str
var list_id : str
var model_config
var name : str | None
var webhook_url : pydantic.networks.AnyUrl | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateCollectionListResponse (**data: Any)

Expand source code

class UpdateCollectionListResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list: Annotated[
        collection_list.CollectionList, Field(description='The updated collection list')
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 list : CollectionList
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateContentStandardsRequest (**data: Any)

Expand source code

class UpdateContentStandardsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    standards_id: Annotated[str, Field(description='ID of the standards configuration to update')]
    scope: Annotated[
        Scope | None,
        Field(description='Updated scope for where this standards configuration applies'),
    ] = None
    registry_policy_ids: Annotated[
        list[str] | None,
        Field(
            description='Registry policy IDs to use as the evaluation basis. When provided, the agent resolves policies from the registry and uses their policy text and exemplars as the evaluation criteria.'
        ),
    ] = None
    policies: Annotated[
        list[policy_entry.PolicyEntry] | None,
        Field(
            description='Updated bespoke policies for this content-standards configuration, using the same shape as registry entries. Replaces the existing policies array; use stable policy_ids to track policies across versions. Combines with registry_policy_ids. Bespoke policy_ids MUST be flat (no colons/slashes).',
            min_length=1,
        ),
    ] = None
    calibration_exemplars: Annotated[
        CalibrationExemplars | None,
        Field(
            description='Updated training/test set to calibrate policy interpretation. Use URL references for pages to be fetched and analyzed, or full artifacts for pre-extracted content.'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var calibration_exemplars : CalibrationExemplars | None
var context : ContextObject | None
var ext : ExtensionObject | None
var idempotency_key : str
var model_config
var policies : list[PolicyEntry] | None
var registry_policy_ids : list[str] | None
var scope : Scope | None
var standards_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateContentStandardsSuccessResponse (**data: Any)

Expand source code

class UpdateContentStandardsResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Annotated[
        Literal[True], Field(description='Indicates the update was applied successfully')
    ]
    standards_id: Annotated[str, Field(description='ID of the updated standards configuration')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 standards_id : str
var success : Literal[True]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateContentStandardsErrorResponse (**data: Any)

Expand source code

class UpdateContentStandardsResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    success: Annotated[Literal[False], Field(description='Indicates the update failed')]
    errors: Annotated[
        list[error.Error], Field(description='Errors that occurred during the update', min_length=1)
    ]
    conflicting_standards_id: Annotated[
        str | None,
        Field(
            description='If scope change conflicts with another configuration, the ID of the conflicting standards'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var conflicting_standards_id : str | None
var context : ContextObject | None
var errors : list[Error]
var ext : ExtensionObject | None
var model_config
var success : Literal[False]

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateFrequency (*args, **kwds)

Expand source code

class UpdateFrequency(Enum):
    realtime = 'realtime'
    hourly = 'hourly'
    daily = 'daily'
    weekly = 'weekly'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var daily
var hourly
var realtime
var weekly

class UpdateMediaBuyRequest (**data: Any)

Expand source code

class UpdateMediaBuyRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: 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")]
    revision: Annotated[
        int | None,
        Field(
            description="Expected current revision for optimistic concurrency. When provided, sellers MUST reject the update with CONFLICT if the media buy's current revision does not match. Obtain from get_media_buys or the most recent update response.",
            ge=1,
        ),
    ] = None
    paused: Annotated[
        bool | None,
        Field(description='Pause/resume the entire media buy (true = paused, false = active)'),
    ] = None
    canceled: Annotated[
        Literal[True],
        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.'
        ),
    ] = True
    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
    packages: Annotated[
        list[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. Sellers that support mid-flight package additions advertise add_packages in valid_actions. Sellers that do not support this MUST reject with UNSUPPORTED_FEATURE.',
            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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
var canceled : Literal[True]
var cancellation_reason : str | None
var context : ContextObject | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var idempotency_key : str
var invoice_recipient : BusinessEntity | None
var media_buy_id : str
var model_config
var new_packages : list[PackageRequest] | None
var packages : list[PackageUpdate] | None
var paused : bool | None
var push_notification_config : PushNotificationConfig | None
var reporting_webhook : ReportingWebhook | None
var revision : int | None
var start_time : StartTiming | None

class UpdateMediaBuyPackagesRequest (**data: Any)

Expand source code

class UpdateMediaBuyRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: 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")]
    revision: Annotated[
        int | None,
        Field(
            description="Expected current revision for optimistic concurrency. When provided, sellers MUST reject the update with CONFLICT if the media buy's current revision does not match. Obtain from get_media_buys or the most recent update response.",
            ge=1,
        ),
    ] = None
    paused: Annotated[
        bool | None,
        Field(description='Pause/resume the entire media buy (true = paused, false = active)'),
    ] = None
    canceled: Annotated[
        Literal[True],
        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.'
        ),
    ] = True
    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
    packages: Annotated[
        list[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. Sellers that support mid-flight package additions advertise add_packages in valid_actions. Sellers that do not support this MUST reject with UNSUPPORTED_FEATURE.',
            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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
var canceled : Literal[True]
var cancellation_reason : str | None
var context : ContextObject | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var idempotency_key : str
var invoice_recipient : BusinessEntity | None
var media_buy_id : str
var model_config
var new_packages : list[PackageRequest] | None
var packages : list[PackageUpdate] | None
var paused : bool | None
var push_notification_config : PushNotificationConfig | None
var reporting_webhook : ReportingWebhook | None
var revision : int | None
var start_time : StartTiming | None

class UpdateMediaBuyPropertiesRequest (**data: Any)

Expand source code

class UpdateMediaBuyRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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: 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")]
    revision: Annotated[
        int | None,
        Field(
            description="Expected current revision for optimistic concurrency. When provided, sellers MUST reject the update with CONFLICT if the media buy's current revision does not match. Obtain from get_media_buys or the most recent update response.",
            ge=1,
        ),
    ] = None
    paused: Annotated[
        bool | None,
        Field(description='Pause/resume the entire media buy (true = paused, false = active)'),
    ] = None
    canceled: Annotated[
        Literal[True],
        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.'
        ),
    ] = True
    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
    packages: Annotated[
        list[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. Sellers that support mid-flight package additions advertise add_packages in valid_actions. Sellers that do not support this MUST reject with UNSUPPORTED_FEATURE.',
            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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference
var adcp_major_version : int | None
var canceled : Literal[True]
var cancellation_reason : str | None
var context : ContextObject | None
var end_time : pydantic.types.AwareDatetime | None
var ext : ExtensionObject | None
var idempotency_key : str
var invoice_recipient : BusinessEntity | None
var media_buy_id : str
var model_config
var new_packages : list[PackageRequest] | None
var packages : list[PackageUpdate] | None
var paused : bool | None
var push_notification_config : PushNotificationConfig | None
var reporting_webhook : ReportingWebhook | None
var revision : int | None
var start_time : StartTiming | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateMediaBuySuccessResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    media_buy_id: Annotated[str, Field(description="Seller's identifier for the media buy")]
    status: Annotated[
        media_buy_status.MediaBuyStatus | None,
        Field(
            description="Media buy status after the update. Present when the update changes the media buy's status (e.g., cancellation transitions to 'canceled', pause transitions to 'paused')."
        ),
    ] = None
    revision: Annotated[
        int | None,
        Field(
            description='Revision number after this update. Use this value in subsequent update_media_buy requests for optimistic concurrency.',
            ge=1,
        ),
    ] = None
    implementation_date: Annotated[
        AwareDatetime | None,
        Field(description='ISO 8601 timestamp when changes take effect (null if pending approval)'),
    ] = None
    invoice_recipient: Annotated[
        business_entity.BusinessEntity | None,
        Field(
            description='Updated invoice recipient, echoed from the request when provided. Confirms the seller accepted the billing override. Bank details are omitted (write-only).'
        ),
    ] = None
    affected_packages: Annotated[
        list[package.Package] | None,
        Field(description='Array of packages that were modified with complete state information'),
    ] = None
    valid_actions: Annotated[
        list[ValidAction] | None,
        Field(
            description='Actions the buyer can perform after this update. Saves a round-trip to get_media_buys.'
        ),
    ] = None
    sandbox: Annotated[
        bool | 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

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var affected_packages : list[Package] | None
var context : ContextObject | None
var ext : ExtensionObject | None
var implementation_date : pydantic.types.AwareDatetime | None
var invoice_recipient : BusinessEntity | None
var media_buy_id : str
var model_config
var revision : int | None
var sandbox : bool | None
var status : MediaBuyStatus | None
var valid_actions : list[ValidAction] | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateMediaBuyErrorResponse (**data: Any)

Expand source code

class UpdateMediaBuyResponse2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    errors: Annotated[
        list[error.Error],
        Field(description='Array of errors explaining why the operation failed', min_length=1),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdatePropertyListRequest (**data: Any)

Expand source code

class UpdatePropertyListRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    list_id: Annotated[str, Field(description='ID of the property list to update')]
    account: Annotated[
        account_ref.AccountReference | None,
        Field(
            description='Account that owns the list. Required when the authenticated agent has access to multiple accounts; optional otherwise.'
        ),
    ] = None
    name: Annotated[str | None, Field(description='New name for the list')] = None
    description: Annotated[str | None, Field(description='New description')] = None
    base_properties: Annotated[
        list[base_property_source.BasePropertySource] | None,
        Field(
            description='Complete replacement for the base properties list (not a patch). Each entry is a discriminated union: publisher_tags (publisher_domain + tags), publisher_ids (publisher_domain + property_ids), or identifiers (direct identifiers).'
        ),
    ] = None
    filters: Annotated[
        property_list_filters.PropertyListFilters | None,
        Field(description='Complete replacement for the filters (not a patch)'),
    ] = None
    brand: Annotated[
        brand_ref.BrandReference | None,
        Field(
            description='Update brand reference. Resolved to full brand identity at execution time.'
        ),
    ] = None
    webhook_url: Annotated[
        AnyUrl | None,
        Field(
            description='Update the webhook URL for list change notifications (set to empty string to remove)'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated unique key for at-most-once execution. If a request with the same key has already been processed, the server returns the original response without re-processing. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var account : AccountReference | None
var adcp_major_version : int | None
var base_properties : list[BasePropertySource] | None
var brand : BrandReference | None
var context : ContextObject | None
var description : str | None
var ext : ExtensionObject | None
var filters : PropertyListFilters | None
var idempotency_key : str
var list_id : str
var model_config
var name : str | None
var webhook_url : pydantic.networks.AnyUrl | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdatePropertyListResponse (**data: Any)

Expand source code

class UpdatePropertyListResponse(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    list: Annotated[property_list.PropertyList, Field(description='The updated property list')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 list : PropertyList
var model_config

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UpdateRightsRequest (**data: Any)

Expand source code

class UpdateRightsRequest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    rights_id: Annotated[
        str, Field(description='Rights grant identifier from acquire_rights response')
    ]
    end_date: Annotated[
        date_aliased | None,
        Field(
            description='New end date for the rights grant (must be >= current end_date). Extending the grant may re-issue generation credentials with updated expiration.'
        ),
    ] = None
    impression_cap: Annotated[
        int | None,
        Field(
            description='New impression cap for the grant. Must be >= impressions already delivered.',
            ge=1,
        ),
    ] = None
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="Switch to a different pricing option from the original get_rights offering. The new option must be compatible with the existing grant's uses and countries."
        ),
    ] = None
    paused: Annotated[
        bool | None,
        Field(
            description='Pause or resume the rights grant. When paused, generation credentials are suspended and creative delivery should stop. When resumed, credentials are re-activated.'
        ),
    ] = None
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(description='Webhook for async update notifications if the update requires approval'),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated idempotency key for safe retries. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var end_date : datetime.date | None
var ext : ExtensionObject | None
var idempotency_key : str
var impression_cap : int | None
var model_config
var paused : bool | None
var pricing_option_id : str | None
var push_notification_config : PushNotificationConfig | None
var rights_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UrlAsset (**data: Any)

Expand source code

class UrlAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='URL reference')]
    url_type: Annotated[
        url_asset_type.UrlAssetType | None,
        Field(
            description="Type of URL asset: 'clickthrough' for user click destination (landing page), 'tracker_pixel' for impression/event tracking via HTTP request (fires GET, expects pixel/204 response), 'tracker_script' for measurement SDKs that must load as <script> tag (OMID verification, native event trackers using method:2)"
        ),
    ] = None
    description: Annotated[
        str | None, Field(description='Description of what this URL points to')
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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 model_config
var provenance : Provenance | None
var url : pydantic.networks.AnyUrl
var url_type : UrlAssetType | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class UrlAssetType (*args, **kwds)

Expand source code

class UrlAssetType(Enum):
    clickthrough = 'clickthrough'
    tracker_pixel = 'tracker_pixel'
    tracker_script = 'tracker_script'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var clickthrough
var tracker_pixel
var tracker_script

class UrlType (*args, **kwds)

Expand source code

class UrlAssetType(Enum):
    clickthrough = 'clickthrough'
    tracker_pixel = 'tracker_pixel'
    tracker_script = 'tracker_script'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var clickthrough
var tracker_pixel
var tracker_script

class ValidateContentDeliveryRequest (**data: Any)

Expand source code

class ValidateContentDeliveryRequest(AdCPBaseModel):
    adcp_major_version: Annotated[
        int | None,
        Field(
            description="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
    standards_id: Annotated[str, Field(description='Standards configuration to validate against')]
    records: Annotated[
        list[Record],
        Field(
            description='Delivery records to validate (max 10,000)', max_length=10000, min_length=1
        ),
    ]
    feature_ids: Annotated[
        list[str] | None,
        Field(description='Specific features to evaluate (defaults to all)', min_length=1),
    ] = None
    include_passed: Annotated[
        bool | None, Field(description='Include passed records in results')
    ] = True
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var adcp_major_version : int | None
var context : ContextObject | None
var ext : ExtensionObject | None
var feature_ids : list[str] | None
var include_passed : bool | None
var model_config
var records : list[Record]
var standards_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ValidateContentDeliverySuccessResponse (**data: Any)

Expand source code

class ValidateContentDeliveryResponse1(AdCPBaseModel):
    summary: Annotated[Summary, Field(description='Summary counts across all records')]
    results: Annotated[list[Result], Field(description='Per-record evaluation results')]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var context : ContextObject | None
var ext : ExtensionObject | None
var model_config
var results : list[Result]
var summary : Summary

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ValidateContentDeliveryErrorResponse (**data: Any)

Expand source code

class ValidateContentDeliveryResponse2(AdCPBaseModel):
    errors: list[error.Error]
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to 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

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ValidationMode (*args, **kwds)

Expand source code

class ValidationMode(Enum):
    strict = 'strict'
    lenient = 'lenient'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var lenient
var strict

class UrlVastAsset (**data: Any)

Expand source code

class VastAsset1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    delivery_type: Annotated[
        Literal['url'],
        Field(description='Discriminator indicating VAST is delivered via URL endpoint'),
    ]
    url: Annotated[AnyUrl, Field(description='URL endpoint that returns VAST XML')]
    vast_version: Annotated[
        vast_version_1.VastVersion | None, Field(description='VAST specification version')
    ] = None
    vpaid_enabled: Annotated[
        bool | None,
        Field(description='Whether VPAID (Video Player-Ad Interface Definition) is supported'),
    ] = None
    duration_ms: Annotated[
        int | None, Field(description='Expected video duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[vast_tracking_event.VastTrackingEvent] | None,
        Field(description='Tracking events supported by this VAST tag'),
    ] = None
    captions_url: Annotated[
        AnyUrl | None, Field(description='URL to captions file (WebVTT, SRT, etc.)')
    ] = None
    audio_description_url: Annotated[
        AnyUrl | None,
        Field(description='URL to audio description track for visually impaired users'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var audio_description_url : pydantic.networks.AnyUrl | None
var captions_url : pydantic.networks.AnyUrl | None
var delivery_type : Literal['url']
var duration_ms : int | None
var model_config
var provenance : Provenance | None
var tracking_events : list[VastTrackingEvent] | None
var url : pydantic.networks.AnyUrl
var vast_version : VastVersion | None
var vpaid_enabled : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class InlineVastAsset (**data: Any)

Expand source code

class VastAsset2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    delivery_type: Annotated[
        Literal['inline'],
        Field(description='Discriminator indicating VAST is delivered as inline XML content'),
    ]
    content: Annotated[str, Field(description='Inline VAST XML content')]
    vast_version: Annotated[
        vast_version_1.VastVersion | None, Field(description='VAST specification version')
    ] = None
    vpaid_enabled: Annotated[
        bool | None,
        Field(description='Whether VPAID (Video Player-Ad Interface Definition) is supported'),
    ] = None
    duration_ms: Annotated[
        int | None, Field(description='Expected video duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[vast_tracking_event.VastTrackingEvent] | None,
        Field(description='Tracking events supported by this VAST tag'),
    ] = None
    captions_url: Annotated[
        AnyUrl | None, Field(description='URL to captions file (WebVTT, SRT, etc.)')
    ] = None
    audio_description_url: Annotated[
        AnyUrl | None,
        Field(description='URL to audio description track for visually impaired users'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var audio_description_url : pydantic.networks.AnyUrl | None
var captions_url : pydantic.networks.AnyUrl | None
var content : str
var delivery_type : Literal['inline']
var duration_ms : int | None
var model_config
var provenance : Provenance | None
var tracking_events : list[VastTrackingEvent] | None
var vast_version : VastVersion | None
var vpaid_enabled : bool | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class VastTrackingEvent (*args, **kwds)

Expand source code

class VastTrackingEvent(Enum):
    impression = 'impression'
    creativeView = 'creativeView'
    loaded = 'loaded'
    start = 'start'
    firstQuartile = 'firstQuartile'
    midpoint = 'midpoint'
    thirdQuartile = 'thirdQuartile'
    complete = 'complete'
    mute = 'mute'
    unmute = 'unmute'
    pause = 'pause'
    resume = 'resume'
    rewind = 'rewind'
    skip = 'skip'
    playerExpand = 'playerExpand'
    playerCollapse = 'playerCollapse'
    fullscreen = 'fullscreen'
    exitFullscreen = 'exitFullscreen'
    progress = 'progress'
    notUsed = 'notUsed'
    otherAdInteraction = 'otherAdInteraction'
    interactiveStart = 'interactiveStart'
    clickTracking = 'clickTracking'
    customClick = 'customClick'
    close = 'close'
    closeLinear = 'closeLinear'
    error = 'error'
    viewable = 'viewable'
    notViewable = 'notViewable'
    viewUndetermined = 'viewUndetermined'
    measurableImpression = 'measurableImpression'
    viewableImpression = 'viewableImpression'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var clickTracking
var close
var closeLinear
var complete
var creativeView
var customClick
var error
var exitFullscreen
var firstQuartile
var fullscreen
var impression
var interactiveStart
var loaded
var measurableImpression
var midpoint
var mute
var notUsed
var notViewable
var otherAdInteraction
var pause
var playerCollapse
var playerExpand
var progress
var resume
var rewind
var skip
var start
var thirdQuartile
var unmute
var viewUndetermined
var viewable
var viewableImpression

class TrackingEvent (*args, **kwds)

Expand source code

class VastTrackingEvent(Enum):
    impression = 'impression'
    creativeView = 'creativeView'
    loaded = 'loaded'
    start = 'start'
    firstQuartile = 'firstQuartile'
    midpoint = 'midpoint'
    thirdQuartile = 'thirdQuartile'
    complete = 'complete'
    mute = 'mute'
    unmute = 'unmute'
    pause = 'pause'
    resume = 'resume'
    rewind = 'rewind'
    skip = 'skip'
    playerExpand = 'playerExpand'
    playerCollapse = 'playerCollapse'
    fullscreen = 'fullscreen'
    exitFullscreen = 'exitFullscreen'
    progress = 'progress'
    notUsed = 'notUsed'
    otherAdInteraction = 'otherAdInteraction'
    interactiveStart = 'interactiveStart'
    clickTracking = 'clickTracking'
    customClick = 'customClick'
    close = 'close'
    closeLinear = 'closeLinear'
    error = 'error'
    viewable = 'viewable'
    notViewable = 'notViewable'
    viewUndetermined = 'viewUndetermined'
    measurableImpression = 'measurableImpression'
    viewableImpression = 'viewableImpression'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var clickTracking
var close
var closeLinear
var complete
var creativeView
var customClick
var error
var exitFullscreen
var firstQuartile
var fullscreen
var impression
var interactiveStart
var loaded
var measurableImpression
var midpoint
var mute
var notUsed
var notViewable
var otherAdInteraction
var pause
var playerCollapse
var playerExpand
var progress
var resume
var rewind
var skip
var start
var thirdQuartile
var unmute
var viewUndetermined
var viewable
var viewableImpression

class VastVersion (*args, **kwds)

Expand source code

class VastVersion(Enum):
    field_2_0 = '2.0'
    field_3_0 = '3.0'
    field_4_0 = '4.0'
    field_4_1 = '4.1'
    field_4_2 = '4.2'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var field_2_0
var field_3_0
var field_4_0
var field_4_1
var field_4_2

class VcpmPricingOption (**data: Any)

Expand source code

class VcpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['vcpm']
var pricing_option_id : str

class VcpmAuctionPricingOption (**data: Any)

Expand source code

class VcpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['vcpm']
var pricing_option_id : str

class VcpmFixedRatePricingOption (**data: Any)

Expand source code

class VcpmPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    pricing_option_id: Annotated[
        str, Field(description='Unique identifier for this pricing option within the product')
    ]
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ]
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    fixed_price: Annotated[
        float | None,
        Field(
            description='Fixed price per unit. If present, this is fixed pricing. If absent, auction-based.',
            ge=0.0,
        ),
    ] = None
    floor_price: Annotated[
        float | None,
        Field(
            description='Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.',
            ge=0.0,
        ),
    ] = None
    max_bid: Annotated[
        bool | None,
        Field(
            description="When true, bid_price is interpreted as the buyer's maximum willingness to pay (ceiling) rather than an exact price. Sellers may optimize actual clearing prices between floor_price and bid_price based on delivery pacing. When false or absent, bid_price (if provided) is the exact bid/price to honor."
        ),
    ] = False
    price_guidance: Annotated[
        price_guidance_1.PriceGuidance | None,
        Field(description='Optional pricing guidance for auction-based bidding'),
    ] = None
    min_spend_per_package: Annotated[
        float | None,
        Field(
            description='Minimum spend requirement per package using this pricing option, in the specified currency',
            ge=0.0,
        ),
    ] = None
    price_breakdown: Annotated[
        price_breakdown_1.PriceBreakdown | None,
        Field(
            description='Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.'
        ),
    ] = None
    eligible_adjustments: Annotated[
        list[adjustment_kind.PriceAdjustmentKind] | None,
        Field(
            description='Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var currency : str
var eligible_adjustments : list[PriceAdjustmentKind] | None
var fixed_price : float | None
var floor_price : float | None
var max_bid : bool | None
var min_spend_per_package : float | None
var model_config
var price_breakdown : PriceBreakdown | None
var price_guidance : PriceGuidance | None
var pricing_model : Literal['vcpm']
var pricing_option_id : str

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class VenueBreakdownItem (**data: Any)

Expand source code

class VenueBreakdownItem(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    venue_id: Annotated[str, Field(description='Venue identifier')]
    venue_name: Annotated[str | None, Field(description='Human-readable venue name')] = None
    venue_type: Annotated[
        str | None,
        Field(description="Venue type (e.g., 'airport', 'transit', 'retail', 'billboard')"),
    ] = None
    impressions: Annotated[int, Field(description='Impressions delivered at this venue', ge=0)]
    loop_plays: Annotated[int | None, Field(description='Loop plays at this venue', ge=0)] = None
    screens_used: Annotated[
        int | None, Field(description='Number of screens used at this venue', ge=0)
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var impressions : int
var loop_plays : int | None
var model_config
var screens_used : int | None
var venue_id : str
var venue_name : str | None
var venue_type : str | None

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class VideoAsset (**data: Any)

Expand source code

class VideoAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='URL to the video asset')]
    width: Annotated[int, Field(description='Width in pixels', ge=1)]
    height: Annotated[int, Field(description='Height in pixels', ge=1)]
    duration_ms: Annotated[
        int | None, Field(description='Video duration in milliseconds', ge=1)
    ] = None
    file_size_bytes: Annotated[int | None, Field(description='File size in bytes', ge=1)] = None
    container_format: Annotated[
        str | None, Field(description='Video container format (mp4, webm, mov, etc.)')
    ] = None
    video_codec: Annotated[
        str | None, Field(description='Video codec used (h264, h265, vp9, av1, prores, etc.)')
    ] = None
    video_bitrate_kbps: Annotated[
        int | None, Field(description='Video stream bitrate in kilobits per second', ge=1)
    ] = None
    frame_rate: Annotated[
        str | None,
        Field(
            description="Frame rate as string to preserve precision (e.g., '23.976', '29.97', '30')"
        ),
    ] = None
    frame_rate_type: Annotated[
        FrameRateType | None,
        Field(description='Whether the video uses constant (CFR) or variable (VFR) frame rate'),
    ] = None
    scan_type: Annotated[ScanType | None, Field(description='Scan type of the video')] = None
    color_space: Annotated[ColorSpace | None, Field(description='Color space of the video')] = None
    hdr_format: Annotated[
        HdrFormat | None,
        Field(description="HDR format if applicable, or 'sdr' for standard dynamic range"),
    ] = None
    chroma_subsampling: Annotated[
        ChromaSubsampling | None, Field(description='Chroma subsampling format')
    ] = None
    video_bit_depth: Annotated[VideoBitDepth | None, Field(description='Video bit depth')] = None
    gop_interval_seconds: Annotated[
        float | None, Field(description='GOP/keyframe interval in seconds')
    ] = None
    gop_type: Annotated[GopType | None, Field(description='GOP structure type')] = None
    moov_atom_position: Annotated[
        MoovAtomPosition | None, Field(description='Position of moov atom in MP4 container')
    ] = None
    has_audio: Annotated[
        bool | None, Field(description='Whether the video contains an audio track')
    ] = None
    audio_codec: Annotated[
        str | None,
        Field(description='Audio codec used (aac, aac_lc, he_aac, pcm, mp3, ac3, eac3, etc.)'),
    ] = None
    audio_sampling_rate_hz: Annotated[
        int | None, Field(description='Audio sampling rate in Hz (e.g., 44100, 48000)')
    ] = None
    audio_channels: Annotated[
        AudioChannels | None, Field(description='Audio channel configuration')
    ] = None
    audio_bit_depth: Annotated[AudioBitDepth | None, Field(description='Audio bit depth')] = None
    audio_bitrate_kbps: Annotated[
        int | None, Field(description='Audio bitrate in kilobits per second', ge=1)
    ] = None
    audio_loudness_lufs: Annotated[
        float | None, Field(description='Integrated loudness in LUFS')
    ] = None
    audio_true_peak_dbfs: Annotated[float | None, Field(description='True peak level in dBFS')] = (
        None
    )
    captions_url: Annotated[
        AnyUrl | None, Field(description='URL to captions file (WebVTT, SRT, etc.)')
    ] = None
    transcript_url: Annotated[
        AnyUrl | None, Field(description='URL to text transcript of the video content')
    ] = None
    audio_description_url: Annotated[
        AnyUrl | None,
        Field(description='URL to audio description track for visually impaired users'),
    ] = None
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var audio_bit_depth : AudioBitDepth | None
var audio_bitrate_kbps : int | None
var audio_channels : AudioChannels | None
var audio_codec : str | None
var audio_description_url : pydantic.networks.AnyUrl | None
var audio_loudness_lufs : float | None
var audio_sampling_rate_hz : int | None
var audio_true_peak_dbfs : float | None
var captions_url : pydantic.networks.AnyUrl | None
var chroma_subsampling : ChromaSubsampling | None
var color_space : ColorSpace | None
var container_format : str | None
var duration_ms : int | None
var file_size_bytes : int | None
var frame_rate : str | None
var frame_rate_type : FrameRateType | None
var gop_interval_seconds : float | None
var gop_type : GopType | None
var has_audio : bool | None
var hdr_format : HdrFormat | None
var height : int
var model_config
var moov_atom_position : MoovAtomPosition | None
var provenance : Provenance | None
var scan_type : ScanType | None
var transcript_url : pydantic.networks.AnyUrl | None
var url : pydantic.networks.AnyUrl
var video_bit_depth : VideoBitDepth | None
var video_bitrate_kbps : int | None
var video_codec : str | None
var width : int

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class ViewThreshold (root: RootModelRootType = PydanticUndefined, **data)

Expand source code

class ViewThreshold(RootModel[float]):
    root: Annotated[
        float,
        Field(
            description='Percentage completion threshold (0.0 to 1.0, e.g., 0.5 = 50%)',
            ge=0.0,
            le=1.0,
        ),
    ]

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[float]
pydantic.root_model.RootModel
pydantic.main.BaseModel
typing.Generic

Class variables

var model_config
var root : float

class WcagLevel (*args, **kwds)

Expand source code

class WcagLevel(Enum):
    A = 'A'
    AA = 'AA'
    AAA = 'AAA'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var A
var AA
var AAA

class WebhookAsset (**data: Any)

Expand source code

class WebhookAsset(AdCPBaseModel):
    model_config = ConfigDict(
        extra='allow',
    )
    url: Annotated[AnyUrl, Field(description='Webhook URL to call for dynamic content')]
    method: Annotated[http_method.HttpMethod | None, Field(description='HTTP method')] = (
        http_method.HttpMethod.POST
    )
    timeout_ms: Annotated[
        int | None,
        Field(description='Maximum time to wait for response in milliseconds', ge=10, le=5000),
    ] = 500
    supported_macros: Annotated[
        list[universal_macro.UniversalMacro | str] | None,
        Field(
            description='Universal macros that can be passed to webhook (e.g., DEVICE_TYPE, COUNTRY). See docs/creative/universal-macros.mdx for full list.'
        ),
    ] = None
    required_macros: Annotated[
        list[universal_macro.UniversalMacro | str] | None,
        Field(description='Universal macros that must be provided for webhook to function'),
    ] = None
    response_type: Annotated[
        webhook_response_type.WebhookResponseType,
        Field(description='Expected content type of webhook response'),
    ]
    security: Annotated[Security, Field(description='Security configuration for webhook calls')]
    provenance: Annotated[
        provenance_1.Provenance | None,
        Field(
            description='Provenance metadata for this asset, overrides manifest-level provenance'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

AdCPBaseModel
pydantic.main.BaseModel

Class variables

var method : HttpMethod | None
var model_config
var provenance : Provenance | None
var required_macros : list[UniversalMacro | str] | None
var response_type : WebhookResponseType
var security : Security
var supported_macros : list[UniversalMacro | str] | None
var timeout_ms : int | None
var url : pydantic.networks.AnyUrl

Inherited members

AdCPBaseModel:
- model_dump
- model_dump_json
- model_summary

class WebhookMetadata (**data: Any)

Expand source code

class WebhookMetadata(BaseModel):
    """Metadata passed to webhook handlers."""

    operation_id: str
    agent_id: str
    task_type: str
    status: TaskStatus
    sequence_number: int | None = None
    notification_type: Literal["scheduled", "final", "delayed"] | None = None
    timestamp: str

Metadata passed to webhook handlers.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var agent_id : str
var model_config
var notification_type : Literal['scheduled', 'final', 'delayed'] | None
var operation_id : str
var sequence_number : int | None
var status : TaskStatus
var task_type : str
var timestamp : str

class WebhookResponseType (*args, **kwds)

Expand source code

class WebhookResponseType(Enum):
    html = 'html'
    json = 'json'
    xml = 'xml'
    javascript = 'javascript'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var html
var javascript
var json
var xml

class ResponseType (*args, **kwds)

Expand source code

class WebhookResponseType(Enum):
    html = 'html'
    json = 'json'
    xml = 'xml'
    javascript = 'javascript'

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access::

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

Ancestors

enum.Enum

Class variables

var html
var javascript
var json
var xml