Module adcp.types

Sub-modules

adcp.types.aliases

Semantic type aliases for generated AdCP types …

adcp.types.base
adcp.types.core
adcp.types.generated_poc
adcp.types.stable

Stable public API for AdCP types …

Classes

class Activity (**data: Any)
Expand source code 
class Activity(BaseModel):
    """Activity event for observability."""

    model_config = {"frozen": True}

    type: ActivityType
    operation_id: str
    agent_id: str
    task_type: str
    status: TaskStatus | None = None
    timestamp: str
    metadata: dict[str, Any] | None = None

Activity event for observability.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 metadata : dict[str, typing.Any] | None
var model_config
var operation_id : str
var status : TaskStatus | None
var task_type : str
var timestamp : str
var type : ActivityType
class ActivityType (*args, **kwds)
Expand source code 
class ActivityType(str, Enum):
    """Types of activity events."""

    PROTOCOL_REQUEST = "protocol_request"
    PROTOCOL_RESPONSE = "protocol_response"
    WEBHOOK_RECEIVED = "webhook_received"
    HANDLER_CALLED = "handler_called"
    STATUS_CHANGE = "status_change"

Types of activity events.

Ancestors

  • builtins.str
  • enum.Enum

Class variables

var HANDLER_CALLED
var PROTOCOL_REQUEST
var PROTOCOL_RESPONSE
var STATUS_CHANGE
var WEBHOOK_RECEIVED
class AdCPBaseModel (**data: Any)
Expand source code 
class AdCPBaseModel(BaseModel):
    """Base model for AdCP types with spec-compliant serialization.

    AdCP JSON schemas use additionalProperties: false and do not allow null
    for optional fields. Therefore, optional fields must be omitted entirely
    when not present (not sent as null).
    """

    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
        if "exclude_none" not in kwargs:
            kwargs["exclude_none"] = True
        return super().model_dump(**kwargs)

    def model_dump_json(self, **kwargs: Any) -> str:
        if "exclude_none" not in kwargs:
            kwargs["exclude_none"] = True
        return super().model_dump_json(**kwargs)

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

Class variables

var model_config

Methods

def model_dump(self, **kwargs: Any) ‑> dict[str, typing.Any]
Expand source code 
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    if "exclude_none" not in kwargs:
        kwargs["exclude_none"] = True
    return super().model_dump(**kwargs)

Usage Documentation

model_dump

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Args

mode
The mode in which to_python should run. If mode is 'json', the output will only contain JSON serializable types. If mode is 'python', the output may contain non-JSON-serializable Python objects.
include
A set of fields to include in the output.
exclude
A set of fields to exclude from the output.
context
Additional context to pass to the serializer.
by_alias
Whether to use the field's alias in the dictionary key if defined.
exclude_unset
Whether to exclude fields that have not been explicitly set.
exclude_defaults
Whether to exclude fields that are set to their default value.
exclude_none
Whether to exclude fields that have a value of None.
exclude_computed_fields
Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.
round_trip
If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings
How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors, "error" raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
fallback
A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.
serialize_as_any
Whether to serialize fields with duck-typing serialization behavior.

Returns

A dictionary representation of the model.

def model_dump_json(self, **kwargs: Any) ‑> str
Expand source code 
def model_dump_json(self, **kwargs: Any) -> str:
    if "exclude_none" not in kwargs:
        kwargs["exclude_none"] = True
    return super().model_dump_json(**kwargs)

Usage Documentation

model_dump_json

Generates a JSON representation of the model using Pydantic's to_json method.

Args

indent
Indentation to use in the JSON output. If None is passed, the output will be compact.
ensure_ascii
If True, the output is guaranteed to have all incoming non-ASCII characters escaped. If False (the default), these characters will be output as-is.
include
Field(s) to include in the JSON output.
exclude
Field(s) to exclude from the JSON output.
context
Additional context to pass to the serializer.
by_alias
Whether to serialize using field aliases.
exclude_unset
Whether to exclude fields that have not been explicitly set.
exclude_defaults
Whether to exclude fields that are set to their default value.
exclude_none
Whether to exclude fields that have a value of None.
exclude_computed_fields
Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated round_trip parameter instead.
round_trip
If True, dumped values should be valid as input for non-idempotent types such as Json[T].
warnings
How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors, "error" raises a [PydanticSerializationError][pydantic_core.PydanticSerializationError].
fallback
A function to call when an unknown value is encountered. If not provided, a [PydanticSerializationError][pydantic_core.PydanticSerializationError] error is raised.
serialize_as_any
Whether to serialize fields with duck-typing serialization behavior.

Returns

A JSON string representation of the model.

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 BrandManifest (**data: Any)
Expand source code 
class BrandManifest(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    assets: Annotated[
        list[Asset] | None,
        Field(
            description='Brand asset library with explicit assets and tags. Assets are referenced inline with URLs pointing to CDN-hosted files.'
        ),
    ] = None
    colors: Annotated[Colors | None, Field(description='Brand color palette')] = None
    contact: Annotated[Contact | None, Field(description='Brand contact information')] = None
    disclaimers: Annotated[
        list[Disclaimer] | None,
        Field(description='Legal disclaimers or required text that must appear in creatives'),
    ] = None
    fonts: Annotated[Fonts | None, Field(description='Brand typography guidelines')] = None
    industry: Annotated[
        str | None,
        Field(
            description="Industry or vertical (e.g., 'retail', 'automotive', 'finance', 'healthcare')"
        ),
    ] = None
    logos: Annotated[
        list[Logo] | None,
        Field(description='Brand logo assets with semantic tags for different use cases'),
    ] = None
    metadata: Annotated[Metadata | None, Field(description='Additional brand metadata')] = None
    name: Annotated[str, Field(description='Brand or business name')]
    product_catalog: Annotated[
        ProductCatalog | None,
        Field(
            description='Product catalog information for e-commerce advertisers. Enables SKU-level creative generation and product selection.'
        ),
    ] = None
    tagline: Annotated[str | None, Field(description='Brand tagline or slogan')] = None
    target_audience: Annotated[
        str | None, Field(description='Primary target audience description')
    ] = None
    tone: Annotated[
        str | None,
        Field(
            description="Brand voice and messaging tone (e.g., 'professional', 'casual', 'humorous', 'trustworthy', 'innovative')"
        ),
    ] = None
    url: Annotated[
        AnyUrl | None,
        Field(
            description='Primary brand URL for context and asset discovery. Creative agents can infer brand information from this URL.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var assets : list[Asset] | None
var colors : Colors | None
var contact : Contact | None
var disclaimers : list[Disclaimer] | None
var fonts : Fonts | None
var industry : str | None
var logos : list[Logo] | None
var metadata : Metadata | None
var model_config
var name : str
var product_catalog : ProductCatalog | None
var tagline : str | None
var target_audience : str | None
var tone : str | None
var url : pydantic.networks.AnyUrl | None

Inherited members

class CpcPricingOption (**data: Any)
Expand source code 
class CpcPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[True],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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
    pricing_model: Annotated[Literal['cpc'], Field(description='Cost per click')]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'cpc_usd_fixed')"
        ),
    ]
    rate: Annotated[float, Field(description='Fixed CPC rate (cost per click)', ge=0.0)]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[True]
var min_spend_per_package : float | None
var model_config
var pricing_model : Literal['cpc']
var pricing_option_id : str
var rate : float

Inherited members

class CpcvPricingOption (**data: Any)
Expand source code 
class CpcvPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[True],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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
    pricing_model: Annotated[
        Literal['cpcv'], Field(description='Cost per completed view (100% completion)')
    ]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'cpcv_usd_guaranteed')"
        ),
    ]
    rate: Annotated[float, Field(description='Fixed CPCV rate (cost per 100% completion)', ge=0.0)]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[True]
var min_spend_per_package : float | None
var model_config
var pricing_model : Literal['cpcv']
var pricing_option_id : str
var rate : float

Inherited members

class CpmAuctionPricingOption (**data: Any)
Expand source code 
class CpmAuctionPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[False],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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_guidance: Annotated[
        PriceGuidance, Field(description='Pricing guidance for auction-based CPM bidding')
    ]
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'cpm_usd_auction')"
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[False]
var min_spend_per_package : float | None
var model_config
var price_guidance : PriceGuidance
var pricing_model : Literal['cpm']
var pricing_option_id : str

Inherited members

class CpmFixedRatePricingOption (**data: Any)
Expand source code 
class CpmFixedRatePricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[True],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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
    pricing_model: Annotated[Literal['cpm'], Field(description='Cost per 1,000 impressions')]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'cpm_usd_guaranteed')"
        ),
    ]
    rate: Annotated[float, Field(description='Fixed CPM rate (cost per 1,000 impressions)', ge=0.0)]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[True]
var min_spend_per_package : float | None
var model_config
var pricing_model : Literal['cpm']
var pricing_option_id : str
var rate : float

Inherited members

class CppPricingOption (**data: Any)
Expand source code 
class CppPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[True],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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
    parameters: Annotated[
        Parameters,
        Field(description='CPP-specific parameters for demographic targeting and GRP requirements'),
    ]
    pricing_model: Annotated[Literal['cpp'], Field(description='Cost per Gross Rating Point')]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'cpp_usd_p18-49')"
        ),
    ]
    rate: Annotated[float, Field(description='Fixed CPP rate (cost per rating point)', ge=0.0)]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[True]
var min_spend_per_package : float | None
var model_config
var parameters : Parameters
var pricing_model : Literal['cpp']
var pricing_option_id : str
var rate : float

Inherited members

class CpvPricingOption (**data: Any)
Expand source code 
class CpvPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[True],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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
    parameters: Annotated[
        Parameters, Field(description='CPV-specific parameters defining the view threshold')
    ]
    pricing_model: Annotated[Literal['cpv'], Field(description='Cost per view at threshold')]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'cpv_usd_50pct')"
        ),
    ]
    rate: Annotated[float, Field(description='Fixed CPV rate (cost per view)', ge=0.0)]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[True]
var min_spend_per_package : float | None
var model_config
var parameters : Parameters
var pricing_model : Literal['cpv']
var pricing_option_id : str
var rate : float

Inherited members

class Creative (**data: Any)
Expand source code 
class Creative(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    assets: Annotated[
        dict[
            str,
            image_asset.ImageAsset
            | video_asset.VideoAsset
            | audio_asset.AudioAsset
            | text_asset.TextAsset
            | html_asset.HtmlAsset
            | css_asset.CssAsset
            | javascript_asset.JavascriptAsset
            | promoted_offerings.PromotedOfferings
            | url_asset.UrlAsset
            | vast_asset.VastAsset1
            | vast_asset.VastAsset2
            | daast_asset.DaastAsset1
            | daast_asset.DaastAsset2,
        ]
        | None,
        Field(description='Assets for this creative, keyed by asset_role'),
    ] = None
    assignments: Annotated[
        Assignments | None,
        Field(description='Current package assignments (included when include_assignments=true)'),
    ] = None
    created_date: Annotated[
        AwareDatetime, Field(description='When the creative was uploaded to the library')
    ]
    creative_id: Annotated[str, Field(description='Unique identifier for the creative')]
    format_id: Annotated[
        format_id_1.FormatId,
        Field(description='Format identifier specifying which format this creative conforms to'),
    ]
    name: Annotated[str, Field(description='Human-readable creative name')]
    performance: Annotated[
        Performance | None,
        Field(
            description='Aggregated performance metrics (included when include_performance=true)'
        ),
    ] = None
    status: Annotated[
        creative_status.CreativeStatus, Field(description='Current approval status of the creative')
    ]
    sub_assets: Annotated[
        list[sub_asset.SubAsset1 | sub_asset.SubAsset2] | None,
        Field(
            description='Sub-assets for multi-asset formats (included when include_sub_assets=true)'
        ),
    ] = None
    tags: Annotated[
        list[str] | None, Field(description='User-defined tags for organization and searchability')
    ] = None
    updated_date: Annotated[AwareDatetime, Field(description='When the creative was last modified')]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var assets : dict[str, ImageAsset | VideoAsset | AudioAsset | TextAsset | HtmlAsset | CssAsset | JavascriptAsset | PromotedOfferings | UrlAsset | VastAsset1 | VastAsset2 | DaastAsset1 | DaastAsset2] | None
var assignments : Assignments | None
var created_date : pydantic.types.AwareDatetime
var creative_id : str
var format_id : FormatId
var model_config
var name : str
var performance : Performance | None
var status : CreativeStatus
var sub_assets : list[SubAsset1 | SubAsset2] | None
var tags : list[str] | None
var updated_date : pydantic.types.AwareDatetime

Inherited members

class CreativeStatus (*args, **kwds)
Expand source code 
class CreativeStatus(Enum):
    processing = 'processing'
    approved = 'approved'
    rejected = 'rejected'
    pending_review = 'pending_review'

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 processing
var rejected
class UrlDaastAsset (**data: Any)
Expand source code 
class DaastAsset1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    companion_ads: Annotated[
        bool | None, Field(description='Whether companion display ads are included')
    ] = None
    daast_version: Annotated[
        DaastVersion | None, Field(description='DAAST specification version')
    ] = None
    delivery_type: Annotated[
        Literal['url'],
        Field(description='Discriminator indicating DAAST is delivered via URL endpoint'),
    ]
    duration_ms: Annotated[
        int | None, Field(description='Expected audio duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[TrackingEvent] | None, Field(description='Tracking events supported by this DAAST tag')
    ] = None
    url: Annotated[AnyUrl, Field(description='URL endpoint that returns DAAST XML')]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

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

Inherited members

class InlineDaastAsset (**data: Any)
Expand source code 
class DaastAsset2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    companion_ads: Annotated[
        bool | None, Field(description='Whether companion display ads are included')
    ] = None
    content: Annotated[str, Field(description='Inline DAAST XML content')]
    daast_version: Annotated[
        DaastVersion | None, Field(description='DAAST specification version')
    ] = None
    delivery_type: Annotated[
        Literal['inline'],
        Field(description='Discriminator indicating DAAST is delivered as inline XML content'),
    ]
    duration_ms: Annotated[
        int | None, Field(description='Expected audio duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[TrackingEvent] | None, Field(description='Tracking events supported by this DAAST tag')
    ] = None

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var 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 tracking_events : list[TrackingEvent] | None

Inherited members

class DebugInfo (**data: Any)
Expand source code 
class DebugInfo(BaseModel):
    """Debug information for troubleshooting."""

    request: dict[str, Any]
    response: dict[str, Any]
    duration_ms: float | None = None

Debug information for troubleshooting.

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

Raises [ValidationError][pydantic_core.ValidationError] if 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 duration_ms : float | None
var model_config
var request : dict[str, typing.Any]
var response : dict[str, typing.Any]
class Error (**data: Any)
Expand source code 
class Error(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    code: Annotated[str, Field(description='Error code for programmatic handling')]
    details: Annotated[Any | None, Field(description='Additional task-specific error details')] = (
        None
    )
    field: Annotated[
        str | None,
        Field(description="Field path associated with the error (e.g., 'packages[0].targeting')"),
    ] = None
    message: Annotated[str, Field(description='Human-readable error message')]
    retry_after: Annotated[
        float | None, Field(description='Seconds to wait before retrying the operation', ge=0.0)
    ] = None
    suggestion: Annotated[str | None, Field(description='Suggested fix for the error')] = None

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var code : str
var details : typing.Any | None
var field : str | None
var message : str
var model_config
var retry_after : float | None
var suggestion : str | None

Inherited members

class FlatRatePricingOption (**data: Any)
Expand source code 
class FlatRatePricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[True],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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
    parameters: Annotated[
        Parameters | None,
        Field(description='Flat rate parameters for DOOH and time-based campaigns'),
    ] = None
    pricing_model: Annotated[
        Literal['flat_rate'], Field(description='Fixed cost regardless of delivery volume')
    ]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'flat_rate_usd_24h_takeover')"
        ),
    ]
    rate: Annotated[float, Field(description='Flat rate cost', ge=0.0)]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[True]
var min_spend_per_package : float | None
var model_config
var parameters : Parameters | None
var pricing_model : Literal['flat_rate']
var pricing_option_id : str
var rate : float

Inherited members

class Format (**data: Any)
Expand source code 
class Format(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    assets_required: Annotated[
        list[AssetsRequired | AssetsRequired1] | None,
        Field(
            description='Array of required assets or asset groups for this format. Each asset is identified by its asset_id, which must be used as the key in creative manifests. Can contain individual assets or repeatable asset sequences (e.g., carousel products, slideshow frames).'
        ),
    ] = None
    delivery: Annotated[
        dict[str, Any] | None,
        Field(description='Delivery method specifications (e.g., hosted, VAST, third-party tags)'),
    ] = None
    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
    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
    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
    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')]
    output_format_ids: Annotated[
        list[format_id_1.FormatId] | None,
        Field(
            description='For generative formats: array of format IDs that this format can generate. When a format accepts inputs like brand_manifest and message, this specifies what concrete output formats can be produced (e.g., a generative banner format might output standard image banner formats).'
        ),
    ] = None
    preview_image: Annotated[
        AnyUrl | None,
        Field(
            description='DEPRECATED: Use format_card instead. Optional preview image URL for format browsing/discovery UI. Should be 400x300px (4:3 aspect ratio) PNG or JPG. Used as thumbnail/card image in format browsers. This field is maintained for backward compatibility but format_card provides a more flexible, structured approach.'
        ),
    ] = None
    renders: Annotated[
        list[Render] | 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
    supported_macros: Annotated[
        list[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.'
        ),
    ] = None
    type: Annotated[
        Type,
        Field(
            description='Media type of this format - determines rendering method and asset requirements'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var assets_required : list[AssetsRequired | AssetsRequired1] | None
var delivery : dict[str, typing.Any] | None
var description : str | None
var example_url : pydantic.networks.AnyUrl | None
var format_card : FormatCard | None
var format_card_detailed : FormatCardDetailed | None
var format_id : FormatId
var model_config
var name : str
var output_format_ids : list[FormatId] | None
var preview_image : pydantic.networks.AnyUrl | None
var renders : list[Render] | None
var supported_macros : list[str] | None
var type : Type

Inherited members

class MediaBuy (**data: Any)
Expand source code 
class MediaBuy(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    buyer_ref: Annotated[
        str | None, Field(description="Buyer's reference identifier for this media buy")
    ] = None
    created_at: Annotated[AwareDatetime | None, Field(description='Creation timestamp')] = None
    creative_deadline: Annotated[
        AwareDatetime | None, Field(description='ISO 8601 timestamp for creative upload deadline')
    ] = None
    media_buy_id: Annotated[
        str, Field(description="Publisher's unique identifier for the media buy")
    ]
    packages: Annotated[
        list[package.Package], Field(description='Array of packages within this media buy')
    ]
    promoted_offering: Annotated[
        str, Field(description='Description of advertiser and what is being promoted')
    ]
    status: media_buy_status.MediaBuyStatus
    total_budget: Annotated[float, Field(description='Total budget amount', ge=0.0)]
    updated_at: Annotated[AwareDatetime | None, Field(description='Last update timestamp')] = None

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var buyer_ref : str | None
var created_at : pydantic.types.AwareDatetime | None
var creative_deadline : pydantic.types.AwareDatetime | None
var media_buy_id : str
var model_config
var packages : list[Package]
var promoted_offering : str
var status : MediaBuyStatus
var total_budget : float
var updated_at : pydantic.types.AwareDatetime | None

Inherited members

class MediaBuyStatus (*args, **kwds)
Expand source code 
class MediaBuyStatus(Enum):
    pending_activation = 'pending_activation'
    active = 'active'
    paused = 'paused'
    completed = 'completed'

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 completed
var paused
var pending_activation
class CreatedPackageReference (**data: Any)
Expand source code 
class Package(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    buyer_ref: Annotated[str, Field(description="Buyer's reference identifier for the package")]
    package_id: Annotated[str, Field(description="Publisher's unique identifier for the package")]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var buyer_ref : str
var model_config
var package_id : str
class Package (**data: Any)
Expand source code 
class Package(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    bid_price: Annotated[
        float | None,
        Field(
            description='Bid price for auction-based CPM pricing (present if using cpm-auction-option)',
            ge=0.0,
        ),
    ] = None
    budget: Annotated[
        float | None,
        Field(
            description='Budget allocation for this package in the currency specified by the pricing option',
            ge=0.0,
        ),
    ] = None
    buyer_ref: Annotated[
        str | None, Field(description="Buyer's reference identifier for this package")
    ] = 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
    impressions: Annotated[
        float | None, Field(description='Impression goal for this package', ge=0.0)
    ] = None
    pacing: pacing_1.Pacing | None = None
    package_id: Annotated[str, Field(description="Publisher's unique identifier for the package")]
    pricing_option_id: Annotated[
        str | None,
        Field(
            description="ID of the selected pricing option from the product's pricing_options array"
        ),
    ] = None
    product_id: Annotated[
        str | None, Field(description='ID of the product this package is based on')
    ] = None
    status: package_status.PackageStatus
    targeting_overlay: targeting.TargetingOverlay | None = None

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var bid_price : float | None
var budget : float | None
var buyer_ref : str | None
var creative_assignments : list[CreativeAssignment] | None
var format_ids_to_provide : list[FormatId] | None
var impressions : float | None
var model_config
var pacing : Pacing | None
var package_id : str
var pricing_option_id : str | None
var product_id : str | None
var status : PackageStatus
var targeting_overlay : TargetingOverlay | None

Inherited members

class PackageStatus (*args, **kwds)
Expand source code 
class PackageStatus(Enum):
    draft = 'draft'
    active = 'active'
    paused = 'paused'
    completed = 'completed'

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 completed
var draft
var paused
class UrlPreviewRender (**data: Any)
Expand source code 
class PreviewRender1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    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.'
        ),
    ]
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    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."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var 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

class HtmlPreviewRender (**data: Any)
Expand source code 
class PreviewRender2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    dimensions: Annotated[
        Dimensions | None, Field(description='Dimensions for this rendered piece')
    ] = None
    embedding: Annotated[
        Embedding | None, Field(description='Optional security and embedding metadata')
    ] = None
    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.'
        ),
    ]
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    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."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var 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

class BothPreviewRender (**data: Any)
Expand source code 
class PreviewRender3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    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
    output_format: Annotated[
        Literal['both'],
        Field(
            description='Discriminator indicating both preview_url and preview_html are 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.'
        ),
    ]
    preview_url: Annotated[
        AnyUrl,
        Field(
            description='URL to an HTML page that renders this piece. Can be embedded in an iframe.'
        ),
    ]
    render_id: Annotated[
        str, Field(description='Unique identifier for this rendered piece within the variant')
    ]
    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."
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var 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

class PricingModel (*args, **kwds)
Expand source code 
class PricingModel(Enum):
    cpm = 'cpm'
    vcpm = 'vcpm'
    cpc = 'cpc'
    cpcv = 'cpcv'
    cpv = 'cpv'
    cpp = 'cpp'
    flat_rate = 'flat_rate'

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 cpc
var cpcv
var cpm
var cpp
var cpv
var flat_rate
var vcpm
class Product (**data: Any)
Expand source code 
class Product(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    brief_relevance: Annotated[
        str | None,
        Field(
            description='Explanation of why this product matches the brief (only included when brief is provided)'
        ),
    ] = None
    creative_policy: creative_policy_1.CreativePolicy | None = None
    delivery_measurement: Annotated[
        DeliveryMeasurement,
        Field(
            description='Measurement provider and methodology for delivery metrics. The buyer accepts the declared provider as the source of truth for the buy. REQUIRED for all products.'
        ),
    ]
    delivery_type: delivery_type_1.DeliveryType
    description: Annotated[
        str, Field(description='Detailed description of the product and its inventory')
    ]
    estimated_exposures: Annotated[
        int | None,
        Field(description='Estimated exposures/impressions for guaranteed products', ge=0),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None, Field(description='Expiration timestamp for custom products')
    ] = 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'
        ),
    ]
    is_custom: Annotated[bool | None, Field(description='Whether this is a custom product')] = None
    measurement: measurement_1.Measurement | None = None
    name: Annotated[str, Field(description='Human-readable product name')]
    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
    pricing_options: Annotated[
        list[
            cpm_fixed_option.CpmFixedRatePricingOption
            | cpm_auction_option.CpmAuctionPricingOption
            | vcpm_fixed_option.VcpmFixedRatePricingOption
            | vcpm_auction_option.VcpmAuctionPricingOption
            | cpc_option.CpcPricingOption
            | cpcv_option.CpcvPricingOption
            | cpv_option.CpvPricingOption
            | cpp_option.CppPricingOption
            | flat_rate_option.FlatRatePricingOption
        ],
        Field(description='Available pricing models for this product', min_length=1),
    ]
    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
    product_id: Annotated[str, Field(description='Unique identifier for the product')]
    publisher_properties: Annotated[
        list[PublisherProperties | PublisherProperties4 | PublisherProperties5],
        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,
        ),
    ]
    reporting_capabilities: reporting_capabilities_1.ReportingCapabilities | None = None

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var brief_relevance : str | None
var creative_policy : CreativePolicy | None
var delivery_measurement : DeliveryMeasurement
var delivery_type : DeliveryType
var description : str
var estimated_exposures : int | None
var expires_at : pydantic.types.AwareDatetime | None
var format_ids : list[FormatId]
var is_custom : bool | None
var measurement : Measurement | None
var model_config
var name : str
var placements : list[Placement] | None
var pricing_options : list[CpmFixedRatePricingOption | CpmAuctionPricingOption | VcpmFixedRatePricingOption | VcpmAuctionPricingOption | CpcPricingOption | CpcvPricingOption | CpvPricingOption | CppPricingOption | FlatRatePricingOption]
var product_card : ProductCard | None
var product_card_detailed : ProductCardDetailed | None
var product_id : str
var publisher_properties : list[PublisherProperties | PublisherProperties4 | PublisherProperties5]
var reporting_capabilities : ReportingCapabilities | None

Inherited members

class Property (**data: Any)
Expand source code 
class Property(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    identifiers: Annotated[
        list[Identifier], Field(description='Array of identifiers for this property', min_length=1)
    ]
    name: Annotated[str, Field(description='Human-readable property name')]
    property_id: Annotated[
        str | None,
        Field(
            description="Unique identifier for this property (optional). Enables referencing properties by ID instead of repeating full objects. Recommended format: lowercase with underscores (e.g., 'cnn_ctv_app', 'instagram_mobile')",
            pattern='^[a-z0-9_]+$',
        ),
    ] = None
    property_type: Annotated[PropertyType, Field(description='Type of advertising property')]
    publisher_domain: Annotated[
        str | None,
        Field(
            description='Domain where adagents.json should be checked for authorization validation. Required for list_authorized_properties response. Optional in adagents.json (file location implies domain).'
        ),
    ] = None
    tags: Annotated[
        list[Tag] | None,
        Field(
            description='Tags for categorization and grouping (e.g., network membership, content categories)'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var identifiers : list[Identifier]
var model_config
var name : str
var property_id : str | None
var property_type : PropertyType
var publisher_domain : str | None
var tags : list[Tag] | None

Inherited members

class PropertyId (root: RootModelRootType = PydanticUndefined, **data)
Expand source code 
class PropertyId(RootModel[str]):
    root: Annotated[str, Field(pattern='^[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

Class variables

var model_config
var root : str
class PropertyTag (root: RootModelRootType = PydanticUndefined, **data)
Expand source code 
class PropertyTag(PropertyId):
    pass

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

  • PropertyId
  • pydantic.root_model.RootModel[str]
  • pydantic.root_model.RootModel
  • pydantic.main.BaseModel
  • typing.Generic

Class variables

var model_config
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 PublisherPropertiesAll (**data: Any)
Expand source code 
class PublisherProperties(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    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.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var model_config
var publisher_domain : str
var selection_type : Literal['all']

Inherited members

class PublisherPropertiesById (**data: Any)
Expand source code 
class PublisherProperties4(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    property_ids: Annotated[
        list[PropertyId],
        Field(description="Specific property IDs from the publisher's adagents.json", min_length=1),
    ]
    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'),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var model_config
var property_ids : list[PropertyId]
var publisher_domain : str
var selection_type : Literal['by_id']

Inherited members

class PublisherPropertiesByTag (**data: Any)
Expand source code 
class PublisherProperties5(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    property_tags: Annotated[
        list[PropertyTag],
        Field(
            description="Property tags from the publisher's adagents.json. Product covers all properties with these tags",
            min_length=1,
        ),
    ]
    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')
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var model_config
var property_tags : list[PropertyTag]
var publisher_domain : str
var selection_type : Literal['by_tag']

Inherited members

class MediaSubAsset (**data: Any)
Expand source code 
class SubAsset1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    asset_id: Annotated[
        str, Field(description='Unique identifier for the asset within the creative')
    ]
    asset_kind: Annotated[
        Literal['media'],
        Field(description='Discriminator indicating this is a media asset with content_uri'),
    ]
    asset_type: Annotated[
        str,
        Field(
            description='Type of asset. Common types: thumbnail_image, product_image, featured_image, logo'
        ),
    ]
    content_uri: Annotated[AnyUrl, Field(description='URL for media assets (images, videos, etc.)')]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var asset_id : str
var asset_kind : Literal['media']
var asset_type : str
var content_uri : pydantic.networks.AnyUrl
var model_config

Inherited members

class TextSubAsset (**data: Any)
Expand source code 
class SubAsset2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    asset_id: Annotated[
        str, Field(description='Unique identifier for the asset within the creative')
    ]
    asset_kind: Annotated[
        Literal['text'],
        Field(description='Discriminator indicating this is a text asset with content'),
    ]
    asset_type: Annotated[
        str,
        Field(
            description='Type of asset. Common types: headline, body_text, cta_text, price_text, sponsor_name, author_name, click_url'
        ),
    ]
    content: Annotated[
        str | list[str],
        Field(
            description='Text content for text-based assets like headlines, body text, CTA text, etc.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var asset_id : str
var asset_kind : Literal['text']
var asset_type : str
var content : str | list[str]
var model_config

Inherited members

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

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[ActivateSignalResponse]
  • adcp.types.core.TaskResult[Any]
  • adcp.types.core.TaskResult[GetMediaBuyDeliveryResponse]
  • adcp.types.core.TaskResult[GetProductsResponse]
  • adcp.types.core.TaskResult[GetSignalsResponse]
  • adcp.types.core.TaskResult[ListAuthorizedPropertiesResponse]
  • adcp.types.core.TaskResult[ListCreativeFormatsResponse]
  • adcp.types.core.TaskResult[ListCreativesResponse]
  • adcp.types.core.TaskResult[PreviewCreativeResponse]
  • adcp.types.core.TaskResult[ProvidePerformanceFeedbackResponse]
  • adcp.types.core.TaskResult[SyncCreativesResponse]

Class variables

var data : ~T | None
var debug_info : DebugInfo | None
var error : str | None
var message : str | None
var metadata : dict[str, typing.Any] | None
var model_config
var needs_input : NeedsInputInfo | None
var status : TaskStatus
var submitted : SubmittedInfo | None
var success : bool
class TaskStatus (*args, **kwds)
Expand source code 
class TaskStatus(str, Enum):
    """Task execution status."""

    COMPLETED = "completed"
    SUBMITTED = "submitted"
    NEEDS_INPUT = "needs_input"
    FAILED = "failed"
    WORKING = "working"

Task execution status.

Ancestors

  • builtins.str
  • enum.Enum

Class variables

var COMPLETED
var FAILED
var NEEDS_INPUT
var SUBMITTED
var WORKING
class UrlVastAsset (**data: Any)
Expand source code 
class VastAsset1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    delivery_type: Annotated[
        Literal['url'],
        Field(description='Discriminator indicating VAST is delivered via URL endpoint'),
    ]
    duration_ms: Annotated[
        int | None, Field(description='Expected video duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[TrackingEvent] | None, Field(description='Tracking events supported by this VAST tag')
    ] = None
    url: Annotated[AnyUrl, Field(description='URL endpoint that returns VAST XML')]
    vast_version: Annotated[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

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var delivery_type : Literal['url']
var duration_ms : int | None
var model_config
var tracking_events : list[TrackingEvent] | None
var url : pydantic.networks.AnyUrl
var vast_version : VastVersion | None
var vpaid_enabled : bool | None

Inherited members

class InlineVastAsset (**data: Any)
Expand source code 
class VastAsset2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    content: Annotated[str, Field(description='Inline VAST XML content')]
    delivery_type: Annotated[
        Literal['inline'],
        Field(description='Discriminator indicating VAST is delivered as inline XML content'),
    ]
    duration_ms: Annotated[
        int | None, Field(description='Expected video duration in milliseconds (if known)', ge=0)
    ] = None
    tracking_events: Annotated[
        list[TrackingEvent] | None, Field(description='Tracking events supported by this VAST tag')
    ] = None
    vast_version: Annotated[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

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var content : str
var delivery_type : Literal['inline']
var duration_ms : int | None
var model_config
var tracking_events : list[TrackingEvent] | None
var vast_version : VastVersion | None
var vpaid_enabled : bool | None

Inherited members

class VcpmAuctionPricingOption (**data: Any)
Expand source code 
class VcpmAuctionPricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[False],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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_guidance: Annotated[
        PriceGuidance, Field(description='Statistical guidance for auction pricing')
    ]
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_auction')"
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[False]
var min_spend_per_package : float | None
var model_config
var price_guidance : PriceGuidance
var pricing_model : Literal['vcpm']
var pricing_option_id : str

Inherited members

class VcpmFixedRatePricingOption (**data: Any)
Expand source code 
class VcpmFixedRatePricingOption(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    currency: Annotated[
        str,
        Field(
            description='ISO 4217 currency code',
            examples=['USD', 'EUR', 'GBP', 'JPY'],
            pattern='^[A-Z]{3}$',
        ),
    ]
    is_fixed: Annotated[
        Literal[True],
        Field(description='Whether this is a fixed rate (true) or auction-based (false)'),
    ]
    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
    pricing_model: Annotated[
        Literal['vcpm'], Field(description='Cost per 1,000 viewable impressions (MRC standard)')
    ]
    pricing_option_id: Annotated[
        str,
        Field(
            description="Unique identifier for this pricing option within the product (e.g., 'vcpm_usd_guaranteed')"
        ),
    ]
    rate: Annotated[
        float, Field(description='Fixed vCPM rate (cost per 1,000 viewable impressions)', ge=0.0)
    ]

Base model for AdCP types with spec-compliant serialization.

AdCP JSON schemas use additionalProperties: false and do not allow null for optional fields. Therefore, optional fields must be omitted entirely when not present (not sent as null).

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

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

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

Ancestors

Class variables

var currency : str
var is_fixed : Literal[True]
var min_spend_per_package : float | None
var model_config
var pricing_model : Literal['vcpm']
var pricing_option_id : str
var rate : float

Inherited members

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