Module adcp.types.domains.creative.sync_creatives_request

Classes

class Assignment (**data: Any)

Expand source code

class Assignment(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    creative_id: Annotated[str, Field(description='ID of the creative to assign')]
    package_id: Annotated[str, Field(description='ID of the package to assign the creative to')]
    weight: Annotated[
        StrictFloat | None,
        Field(
            description='Relative delivery weight (0-100). When multiple creatives are assigned to the same package, weights determine impression distribution proportionally. 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='Restrict this creative to specific placements within the package. When omitted, the creative is eligible for all placements.',
            min_length=1,
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

Important

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

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

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

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

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

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var creative_id : str

var model_config

var package_id : str

var placement_ids : list[str] | None

var weight : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AssignmentOperations1 (**data: Any)

Expand source code

class AssignmentOperations1(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    operation: Literal['assign'] = 'assign'
    creative_id: Annotated[str, Field(min_length=1)]
    package_id: Annotated[str, Field(min_length=1)]
    weight: Annotated[StrictFloat | None, Field(ge=0.0, le=100.0)] = None
    placement_ids: Annotated[list[PlacementId] | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

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

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

Important

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

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

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

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

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

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var creative_id : str

var model_config

var operation : Literal['assign']

var package_id : str

var placement_ids : list[PlacementId] | None

var weight : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AssignmentOperations2 (**data: Any)

Expand source code

class AssignmentOperations2(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    operation: Literal['unassign'] = 'unassign'
    creative_id: Annotated[str, Field(min_length=1)]
    package_id: Annotated[str, Field(min_length=1)]

Base model for AdCP types with spec-compliant serialization.

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

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

Important

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

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

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

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

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

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var creative_id : str

var model_config

var operation : Literal['unassign']

var package_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class AssignmentOperations3 (**data: Any)

Expand source code

class AssignmentOperations3(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    operation: Literal['replace'] = 'replace'
    creative_id: Annotated[str, Field(description='Replacement creative ID.', min_length=1)]
    replaces_creative_id: Annotated[
        str, Field(description='Currently assigned creative ID to remove atomically.', min_length=1)
    ]
    package_id: Annotated[str, Field(min_length=1)]
    weight: Annotated[StrictFloat | None, Field(ge=0.0, le=100.0)] = None
    placement_ids: Annotated[list[PlacementId] | None, Field(min_length=1)] = None

Base model for AdCP types with spec-compliant serialization.

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

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

Important

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

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

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

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

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

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var creative_id : str

var model_config

var operation : Literal['replace']

var package_id : str

var placement_ids : list[PlacementId] | None

var replaces_creative_id : str

var weight : float | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Creative (**data: Any)

Expand source code

class Creative(CreativeAsset):
    revision_id: Annotated[
        creative_revision_id.CreativeRevisionId | None,
        Field(
            description='Optional buyer-assigned identity for this exact input-content state. Buyers may send it to any 3.2 peer; creative.supports_revisions gates reliance on immutability, echo, readback, and delivery correlation, not whether the open request shape may carry the field. Within a supporting seller, a revision_id is immutable under one creative_id: reusing it with different canonical revision content MUST fail with CREATIVE_REVISION_CONTENT_MISMATCH. Metadata and assignment fields excluded from revision content may change without minting a new revision.'
        ),
    ] = None
    localization: Annotated[
        creative_localization.CreativeLocalization | None,
        Field(
            description='Sync-only materialized-localization mutation. The top-level assets are the source variant; optional locale_fallbacks declare buyer-approved language-family substitutions, and default_locale_variant_id selects the final serving fallback. An object transactionally replaces the source assets and complete locale set, omission preserves existing localization only when the top-level source assets are unchanged, and null removes localization. This field never requests translation or generation. Receivers MUST advertise get_adcp_capabilities creative.localization before accepting it.'
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

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

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

Important

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

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

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

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

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

Ancestors

• CreativeAsset
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var localization : CreativeLocalization | None

var model_config

var revision_id : CreativeRevisionId | None

Inherited members

• CreativeAsset:
  • model_dump
  • model_dump_json
  • model_summary

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

Expand source code

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

A str generated from a JSON Schema string root.

Ancestors

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

class SyncCreativesRequest (**data: Any)

Expand source code

class SyncCreativesRequest(AdcpRequest, AdcpVersionEnvelope):
    model_config = ConfigDict(
        extra='allow',
    )
    account: Annotated[
        account_ref.AccountReference, Field(description='Account that owns these creatives.')
    ]
    creatives: Annotated[
        list[Creative] | None,
        Field(
            description='Array of creative assets to sync (create or update)',
            max_length=100,
            min_length=1,
        ),
    ] = None
    creative_ids: Annotated[
        list[str] | None,
        Field(
            description='Optional filter to limit sync scope to specific creative IDs. When provided, only these creatives will be created/updated. Other creatives in the library are unaffected. Useful for partial updates and error recovery.',
            max_length=100,
            min_length=1,
        ),
    ] = None
    assignments: Annotated[
        list[Assignment] | None,
        Field(
            deprecated=True,
            description='Deprecated additive assignment shorthand. Each entry upserts one creative-to-package assignment. Use assignment_operations for explicit assign, unassign, and replace semantics. Standalone creative agents that do not manage media buys ignore this field.',
            min_length=1,
        ),
    ] = None
    assignment_operations: Annotated[
        list[AssignmentOperations] | None,
        Field(
            description='Explicit, ordered assignment mutations. These operations may be sent without creatives to traffic existing creative IDs independently from MediaBuy commercial control. The entire request is atomic under idempotency_key and therefore requires strict validation; lenient partial processing is not permitted.',
            max_length=500,
            min_length=1,
        ),
    ] = None
    idempotency_key: Annotated[
        str,
        Field(
            description='Client-generated idempotency key for safe retries. If a sync fails without a response, resending with the same idempotency_key guarantees at-most-once execution. MUST be unique per (seller, request) pair to prevent cross-seller correlation. Use a fresh UUID v4 for each request.',
            max_length=255,
            min_length=16,
            pattern='^[A-Za-z0-9_.:-]{16,255}$',
        ),
    ]
    delete_missing: Annotated[
        StrictBool | None,
        Field(
            description='When true, creatives not included in this sync will be archived. Use with caution for full library replacement. Invalid when creative_ids is provided — delete_missing applies to the entire library scope, not a filtered subset.'
        ),
    ] = False
    dry_run: Annotated[
        StrictBool | None,
        Field(
            description="When true, rehearse this sync_creatives operation without applying it. Validates the actual trafficking request in the seller's current context, including library upsert semantics, creative IDs, assignments, account-scoped gates, and seller policies, then returns what would be created/updated/deleted. This is distinct from validate_input, which only validates manifest structure against canonical/product format targets."
        ),
    ] = False
    validation_mode: Annotated[
        validation_mode_1.ValidationMode | None,
        Field(
            description="Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid creatives and reports errors."
        ),
    ] = validation_mode_1.ValidationMode.strict
    push_notification_config: Annotated[
        push_notification_config_1.PushNotificationConfig | None,
        Field(
            description='Optional webhook configuration for async sync notifications. The agent will send a webhook when sync completes if the operation takes longer than immediate response time (typically for large bulk operations or manual approval/HITL).'
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

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

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

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

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

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

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

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

Ancestors

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

Subclasses

• SyncCreativesRequest

Class variables

var account : AccountReference1 | AccountReference2

var assignment_operations : list[AssignmentOperations1 | AssignmentOperations2 | AssignmentOperations3] | None

var assignments : list[Assignment] | None

var context : ContextObject | None

var creative_ids : list[str] | None

var creatives : list[Creative] | None

var delete_missing : bool | None

var dry_run : bool | None

var ext : ExtensionObject | None

var idempotency_key : str

var model_config

var push_notification_config : PushNotificationConfig | None

var validation_mode : ValidationMode | None

Inherited members

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