Migrating creatives

This page records the 3.0 migration. For new AdCP 3.2 integrations, use canonical format_kind / format_option_ref, discover creative operations through get_adcp_capabilities.creative.supported_formats[], and treat list_creative_formats plus compound format_id as deprecated 3.x compatibility surfaces.

AdCP 3.0 makes three breaking changes to creative handling: the FormatCategory enum and format type field are removed, weighted creative assignments replace simple ID arrays, and a unified assets array replaces assets_required for format discovery.

Format category removal

What changed

v2 field	v3 field	Change type
`type` on format objects (FormatCategory enum)	Removed	Deleted
`format_types` filter on `list_creative_formats` / `get_products`	Removed	Deleted

Why

The FormatCategory enum (video, display, audio, native, social, custom) was a coarse classifier that didn’t map well to multi-asset formats. A “video” format might also require display companion banners and text overlays. The enum forced implementors to pick one category for inherently multi-modal formats, which led to inconsistent filtering and discovery gaps.

Migration

Replace format_types filters with asset_types (what the format needs) or format_ids (exact match): v2:

{
  "format_types": ["video"]
}

v3 — filter by asset type:

{
  "asset_types": ["video"]
}

v3 — filter by exact format ID:

{
  "format_ids": [
    { "agent_url": "https://creatives.example.com", "id": "video_preroll_30s" }
  ]
}

asset_types returns any format that includes at least one asset of that type — so a video format with companion banners appears in both ["video"] and ["image"] results.

Creative assignments

What changed

v2 field	v3 field	Change type
`creative_ids` (string array)	`creative_assignments` (object array)	Replaced

Simple migration (equal weights)

v2:

{
  "creative_ids": ["creative_1", "creative_2"]
}

v3 — omit weight for equal distribution:

{
  "$schema": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/creative-assignment.json",
  "creative_id": "creative_1"
}

In context of a create_media_buy package:

{
  "creative_assignments": [
    { "creative_id": "creative_1" },
    { "creative_id": "creative_2" }
  ]
}

When weight is omitted on all assignments, impressions are distributed equally.

Weighted assignments

Control what percentage of impressions each creative receives:

{
  "creative_assignments": [
    { "creative_id": "hero_video", "weight": 60 },
    { "creative_id": "promo_video", "weight": 40 }
  ]
}

Weights are relative — they don’t need to sum to 100, but doing so makes intent clear.

Rotation modes and groups

rotation_mode is a package policy carried on each assignment row. All assignments in one package MUST resolve to the same mode; omission resolves to weighted, preserving the pre-3.2 behavior above. A seller MUST reject conflicting modes with VALIDATION_ERROR before creating or updating the package rather than picking the first row.

Mode	Selection behavior
`weighted`	Select proportionally by `weight`. Omitted weights are equal; `weight: 0` pauses an assignment. This is the default.
`even`	Balance delivery across eligible assignments without buyer-supplied weights.
`sequential`	Cycle through `sequence_position` in ascending order within each group. Every assignment requires a position.
`random`	Make an independent uniform selection from the eligible assignments.

group_id identifies a pool only within its containing package; the same value in another package is unrelated. Assignments without group_id belong to the package’s default group. In sequential mode, positions start at 1 and MUST be unique within each effective group, so separate groups may reuse the same positions. Conventional weighted pool (the legacy shape remains valid):

{
  "creative_assignments": [
    { "creative_id": "host_read_30", "weight": 70 },
    { "creative_id": "produced_spot_30", "weight": 30 }
  ]
}

Sequential podcast storytelling:

{
  "creative_assignments": [
    {
      "creative_id": "story_chapter_1",
      "rotation_mode": "sequential",
      "group_id": "listener_story",
      "sequence_position": 1
    },
    {
      "creative_id": "story_chapter_2",
      "rotation_mode": "sequential",
      "group_id": "listener_story",
      "sequence_position": 2
    }
  ]
}

weight is valid only for the effective weighted mode. sequence_position is valid only for explicit sequential assignments. Package validators additionally enforce effective-mode consistency and position uniqueness because JSON Schema draft-07 cannot compare values across assignment rows.

Placement targeting

Assign specific creatives to specific placements within a product:

{
  "creative_assignments": [
    {
      "creative_id": "hero_video",
      "placement_ids": ["homepage_hero"],
      "weight": 100
    },
    {
      "creative_id": "sidebar_banner",
      "placement_ids": ["article_sidebar"],
      "weight": 100
    },
    {
      "creative_id": "fallback_banner",
      "weight": 50
    }
  ]
}

When placement_ids is omitted, the creative runs on all placements in the package. placement_ids references placement_id values from the product’s placements array.

sync_creatives does not support placement_ids. Use create_media_buy or update_media_buy for placement-level targeting.

Creative assignment schema

Each assignment object:

{
  "$schema": "https://adcontextprotocol.org/schemas/3.2.0-beta.0/core/creative-assignment.json",
  "creative_id": "hero_video",
  "weight": 60,
  "placement_ids": ["homepage_hero"]
}

Field	Type	Required	Description
`creative_id`	string	Yes	References a creative from `list_creatives` or `sync_creatives`
`weight`	number (0-100)	No	Delivery weight. Omit for equal distribution.
`placement_ids`	string[]	No	Target specific placements. Omit to run everywhere.

Asset discovery

What changed

v2 field	v3 field	Change type
`assets_required` (string array)	`assets` (object array)	Replaced
`preview_image`	`format_card`	Replaced

Format assets

v2 — only listed required asset IDs:

{
  "format_id": { "agent_url": "https://creatives.example.com", "id": "display_300x250" },
  "name": "Standard Banner 300x250",
  "assets_required": ["main_image", "headline"]
}

v3 — lists ALL assets with required boolean:

{
  "format_id": { "agent_url": "https://creatives.example.com", "id": "display_300x250" },
  "name": "Standard Banner 300x250",
  "assets": [
    {
      "item_type": "individual",
      "asset_id": "main_image",
      "asset_type": "image",
      "required": true,
      "requirements": {
        "min_width": 300,
        "min_height": 250,
        "accepted_mime_types": ["image/png", "image/jpeg"]
      }
    },
    {
      "item_type": "individual",
      "asset_id": "headline",
      "asset_type": "text",
      "required": true,
      "requirements": {
        "max_length": 50
      }
    },
    {
      "item_type": "individual",
      "asset_id": "impression_tracker",
      "asset_type": "url",
      "required": false,
      "requirements": {
        "role": "impression_tracker"
      }
    }
  ]
}

What the assets array provides

Full discovery — see ALL assets a format supports, not just required ones
Type information — each asset declares its asset_type (image, video, text, url, etc.)
Requirements — inline constraints (dimensions, length, MIME types)
Optional assets — trackers, companion banners, and other optional elements are now visible
Repeatable groups — carousel and multi-item formats use item_type: "repeatable_group"

Asset item types

Each entry in the assets array has an item_type discriminator: Individual assets (item_type: "individual"):

{
  "item_type": "individual",
  "asset_id": "main_video",
  "asset_type": "video",
  "required": true,
  "requirements": {
    "min_duration_seconds": 15,
    "max_duration_seconds": 30,
    "accepted_mime_types": ["video/mp4"]
  }
}

Repeatable groups (item_type: "repeatable_group") for carousels and multi-item formats:

{
  "item_type": "repeatable_group",
  "asset_group_id": "card",
  "required": true,
  "min_count": 2,
  "max_count": 10,
  "selection_mode": "sequential",
  "assets": [
    {
      "asset_id": "card_image",
      "asset_type": "image",
      "required": true,
      "requirements": {
        "min_width": 600,
        "min_height": 600,
        "aspect_ratio": "1:1"
      }
    },
    {
      "asset_id": "card_title",
      "asset_type": "text",
      "required": true,
      "requirements": {
        "max_length": 40
      }
    }
  ]
}

Format cards (replacing preview_image)

v2’s preview_image URL is replaced by format_card, which uses the creative rendering system:

{
  "format_card": {
    "format_id": {
      "agent_url": "https://creatives.example.com",
      "id": "format_card_standard"
    },
    "manifest": {
      "format_name": "Standard Banner 300x250",
      "preview_url": "https://cdn.example.com/previews/banner_300x250.png"
    }
  }
}

Migration steps

Format category

Remove format_types filters

Remove format_types from list_creative_formats and get_products requests.

Replace with asset_types

Use asset_types to filter formats by what assets they accept (e.g., ["video"], ["image"]).

Or use format_ids

Use format_ids for exact format matching when you know the specific formats you need.

Stop reading type field

Remove any code that reads the type field from format objects — it no longer exists in v3.

Creative assignments

Replace creative_ids

Replace creative_ids arrays with creative_assignments object arrays.

Set creative_id

Set creative_id on each assignment object.

Add weights

Add weights if you need non-equal distribution, otherwise omit weight.

Add placement_ids

Add placement_ids if you need placement-level targeting.

Update sync_creatives calls

These use creative_assignments too, but without placement_ids.

Asset discovery

Replace assets_required

Replace assets_required parsing with assets array iteration.

Check required boolean

Check required boolean on each asset instead of assuming all listed assets are required.

Use asset_type

Use asset_type to understand what kind of file each asset expects.

Handle item_type

Check for "individual" vs "repeatable_group".

Replace preview_image

Replace preview_image reads with format_card rendering.

Validate

Creative manifests must use exact asset_id values as keys.

Creative

Full creative documentation: formats, asset types, manifests, and creative agents.

Getting Started

Building with AdCP

Protocol

Using AAO

FAQ

Trust & Security

Reference

Certification

Migrating creatives

Migrating creatives

Format category removal

What changed

Why

Migration

Creative assignments

What changed

Simple migration (equal weights)

Weighted assignments

Rotation modes and groups

Placement targeting

Creative assignment schema

Asset discovery

What changed

Format assets

What the assets array provides

Asset item types

Format cards (replacing preview_image)

Migration steps

Format category

Creative assignments

Asset discovery

Creative

​Migrating creatives

​Format category removal

​What changed

​Why

​Migration

​Creative assignments

​What changed

​Simple migration (equal weights)

​Weighted assignments

​Rotation modes and groups

​Placement targeting

​Creative assignment schema

​Asset discovery

​What changed

​Format assets

​What the assets array provides

​Asset item types

​Format cards (replacing preview_image)

​Migration steps

​Format category

​Creative assignments

​Asset discovery

Creative

Migrating creatives

Format category removal

What changed

Why

Migration

Creative assignments

What changed

Simple migration (equal weights)

Weighted assignments

Rotation modes and groups

Placement targeting

Creative assignment schema

Asset discovery

What changed

Format assets

What the assets array provides

Asset item types

Format cards (replacing preview_image)

Migration steps

Format category

Creative assignments

Asset discovery