Release Notes

Major release highlights and migration guides for AdCP

High-level summaries of major AdCP releases with migration guidance. For detailed technical changelogs, see CHANGELOG.md.

---

Version 2.5.0

Released: November 2025 | Full Changelog

What’s New

Version 2.5.0 is a developer experience and API refinement release that significantly improves type safety, schema infrastructure, and creative workflow performance. This release prepares AdCP for production-scale integrations with better TypeScript/Python code generation, stricter validation semantics, and flexible schema versioning.

🎯 Key Themes:

1. Type Safety & Code Generation - Comprehensive discriminator fields throughout the protocol enable excellent TypeScript/Python type inference and eliminate ambiguous union types.

2. Batch Creative Previews - Generate previews for up to 50 creatives in a single API call with optional direct HTML embedding, reducing preview generation time by 5-10x.

3. Schema Infrastructure - Build-time schema versioning with semantic paths (/schemas/2.5.0/, /schemas/v2/, /schemas/v2.5/) enables version pinning and automatic minor version tracking.

4. API Consistency - Atomic response semantics (success XOR error) and standardized webhook payloads eliminate ambiguity and improve reliability.

5. Signal Protocol Refinement - Activation keys returned per deployment with permission-based access, enabling proper multi-platform signal activation.

6. Template Formats - Dynamic creative sizing with accepts_parameters enables formats that accept runtime dimensions, durations, and other parameters.

7. Enhanced Product Discovery - Structured filters with date ranges, budget constraints, country targeting, and channel filtering improve product search precision.

Key Enhancements

Type Safety & Code Generation

• Discriminator fields added to all discriminated union types (destinations, pricing, property selectors, preview requests/responses)
• Atomic response semantics - All task responses now use strict success XOR error patterns with oneOf discriminators
• Explicit type declarations on all const fields for proper TypeScript literal type generation
• 31 new enum schemas extracted from inline definitions for better reusability

Schema Infrastructure

• Build-time versioning - Schemas now support semantic version paths (/schemas/2.5.0/), major version aliases (/schemas/v2/), and minor version aliases (/schemas/v2.5/)
• Consistent media buy responses - Both create_media_buy and update_media_buy now return full Package objects
• Standardized webhook payload - Protocol envelope at top-level with task data under result field

Product Discovery

• Structured filters - Extracted filter objects into separate schemas (product-filters.json, creative-filters.json, signal-filters.json)
• Enhanced filtering - Date ranges (start_date, end_date), budget ranges with currency, country targeting, and channel filtering
• Full enum support - Filters now accept complete enum values without artificial restrictions

Signal Protocol

• Activation keys - activate_signal now returns deployment-specific activation keys (segment IDs, key-value pairs) based on authenticated permissions
• Consistent terminology - Standardized on “deployments” throughout signal requests and responses

Creative Protocol

• Batch preview support - Preview multiple creatives in one request (preview_creative supports 1-50 items)
• Direct HTML embedding - Responses can include raw HTML for iframe-free rendering
• Simplified brand manifest - Single required field (name) eliminates duplicate type generation
• Template formats - accepts_parameters field enables dynamic formats (e.g., display_[width]x[height], video_[duration]s)
• Inline creative updates - sync_creatives task provides upsert semantics for updating creatives in existing campaigns

Documentation & Testing

• Testable documentation - All code examples can be validated against live schemas
• Client library prominence - NPM badges and installation instructions in intro
• Fixed 389 broken links across 50 documentation files

Migration Guide

Discriminator Fields (Breaking)

Many schemas now require explicit discriminator fields. Update your code to include these fields:

Signal Destinations:

// Before
{
  "platform_id": "ttd"
}

// After
{
  "type": "platform",
  "platform_id": "ttd"
}

Property Selectors:

// Before
{
  "publisher_domain": "cnn.com",
  "property_ids": ["cnn_ctv_app"]
}

// After
{
  "publisher_domain": "cnn.com",
  "selection_type": "by_id",
  "property_ids": ["cnn_ctv_app"]
}

Pricing Options:

// Before
{
  "pricing_model": "cpm",
  "rate": 12.50
}

// After
{
  "pricing_model": "cpm",
  "is_fixed": true,
  "rate": 12.50
}

Webhook Payload Structure (Breaking)

Webhook payloads now use protocol envelope at top-level:

Before:

{
  "task_id": "task_123",
  "status": "completed",
  "media_buy_id": "mb_456",
  "packages": [...]
}

After:

{
  "task_id": "task_123",
  "task_type": "create_media_buy",
  "status": "completed",
  "timestamp": "2025-11-21T10:30:00Z",
  "result": {
    "media_buy_id": "mb_456",
    "packages": [...]
  }
}

Signal Activation Response (Breaking)

activate_signal response changed from single key to deployments array:

Before:

{
  "activation_key": "segment_123"
}

After:

{
  "deployments": [
    {
      "destination": {"type": "platform", "platform_id": "ttd"},
      "activation_key": "segment_123",
      "status": "active"
    }
  ]
}

Template Formats

Formats can now accept parameters for dynamic sizing:

Template Format Definition:

{
  "format_id": {"agent_url": "https://creative.adcontextprotocol.org", "id": "display_static"},
  "accepts_parameters": ["dimensions"],
  "renders": [{
    "role": "primary",
    "parameters_from_format_id": true
  }]
}

The parameters_from_format_id: true flag indicates dimensions come from the format_id at usage time.

Usage (parameterized format_id):

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_static",
    "width": 300,
    "height": 250
  }
}

This creates a specific 300x250 variant of the display_static template.

Enhanced Product Filtering

New structured filters in get_products:

{
  "filters": {
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "budget_range": {
      "min": 10000,
      "max": 50000,
      "currency": "USD"
    },
    "countries": ["US", "CA"],
    "channels": ["display", "video"]
  }
}

Schema Versioning

New version paths available:

• /schemas/2.5.0/ - Exact version (recommended for production)
• /schemas/v2.5/ - Latest 2.5.x patch (auto-updates for patch releases)
• /schemas/v2/ - Latest 2.x release (auto-updates for minor/patch)
• /schemas/v1/ - Backward compat alias (same as v2)

Breaking Changes

• Discriminator fields required in destinations, property selectors, pricing options, and preview requests
• Webhook payload structure - Task data moved under result field; domain no longer required
• Signal activation response - Changed from activation_key string to deployments array
• Removed legacy creative fields - media_url, click_url, duration removed from list_creatives response

Non-Breaking Additions

• Application context object (optional) in all task requests
• product_card and format_card fields (optional) for visual UI support
• Batch preview mode in preview_creative (backward compatible)
• Package pricing fields in delivery reporting (already documented, now schema-enforced)
• Minor version symlinks (/schemas/v2.5/)

---

Version 2.3.0

Released: October 2025 | Full Changelog

What’s New

Publisher-Owned Property Definitions - Properties are now owned by publishers and referenced by agents, following the IAB Tech Lab sellers.json model. This eliminates duplication and creates a single source of truth for property information.

Placement Targeting - Products can now define multiple placements (e.g., homepage banner, article sidebar), and buyers can assign different creatives to each placement within a product purchase.

Simplified Budgets - Budget is now only specified at the package level, enabling mixed-currency campaigns and eliminating redundant aggregation at the media buy level.

Migration Guide

Publisher-Owned Properties

Before:

{
  "properties": [{
    "publisher_domain": "cnn.com",
    "property_name": "CNN CTV App",
    "property_tags": ["ctv", "premium"]
  }]
}

After:

{
  "publisher_properties": [
    {
      "publisher_domain": "cnn.com",
      "property_tags": ["ctv"]
    }
  ]
}

Buyers now fetch property definitions from https://cnn.com/.well-known/adagents.json.

Remove Media Buy Budget

Before:

{
  "budget": 50000,
  "packages": [...]
}

After:

{
  "packages": [
    {"package_id": "p1", "budget": 30000},
    {"package_id": "p2", "budget": 20000}
  ]
}

Budget is specified per package only.

Breaking Changes

• properties field in products → publisher_properties
• list_authorized_properties returns publisher_domains array
• Removed budget from create_media_buy/update_media_buy requests

---

Version 2.2.0

Released: October 2025 | Full Changelog

What’s New

Build Creative Alignment - The build_creative task now follows a clear “manifest-in → manifest-out” transformation model with consistent parameter naming.

Migration Guide

Before:

{
  "source_manifest": {...},
  "promoted_offerings": [...]
}

After:

{
  "creative_manifest": {
    "format_id": {...},
    "assets": {
      "promoted_offerings": [...]
    }
  }
}

Breaking Changes

• build_creative parameter renamed: source_manifest → creative_manifest
• Removed promoted_offerings as top-level parameter (now in manifest assets)

---

Version 2.1.0

Released: January 2025 | Full Changelog

What’s New

Simplified Asset Schema - Separated asset payload schemas from format requirement schemas, eliminating redundancy. Asset types are now determined by format specifications rather than declared in manifests.

Migration Guide

Before:

{
  "assets": {
    "banner_image": {
      "asset_type": "image",
      "url": "https://cdn.example.com/banner.jpg",
      "width": 300,
      "height": 250
    }
  }
}

After:

{
  "assets": {
    "banner_image": {
      "url": "https://cdn.example.com/banner.jpg",
      "width": 300,
      "height": 250
    }
  }
}

Breaking Changes

• Removed asset_type field from creative manifest payloads
• Schema paths changed: /creative/asset-types/*.json → /core/assets/*-asset.json
• Constraint fields moved from asset payloads to format specifications

---

Version 2.0.0

Released: October 2025 | Full Changelog

What’s New

First production release of the Advertising Context Protocol with:

• 8 Media Buy Tasks - Complete workflow from product discovery to delivery reporting
• 3 Creative Tasks - AI-powered creative generation and management
• 2 Signals Tasks - First-party data integration
• Standard Formats - Industry-standard display, video, and native formats
• Multi-Protocol Support - Works with MCP and A2A

Core Features

• Natural language product discovery with brief-based targeting
• Asynchronous task management with human-in-the-loop approvals
• JSON Schema validation for all requests and responses
• Publisher-owned property definitions via .well-known/adagents.json
• Comprehensive format specifications with asset requirements

---

Versioning Policy

AdCP follows Semantic Versioning 2.0.0:

• PATCH (x.x.N) - Bug fixes, documentation, clarifications
• MINOR (x.N.0) - New features, backward-compatible additions
• MAJOR (N.0.0) - Breaking changes

Deprecation Process

Breaking changes follow a 6-month deprecation cycle:

1. Deprecation Notice - Feature marked deprecated in minor release
2. Transition Period - Minimum 6 months support with warnings
3. Migration Guide - Detailed upgrade path provided
4. Breaking Change - Removed in next major version

---

Additional Resources

• Technical Changelog - CHANGELOG.md
• GitHub Releases - Release Archive
• Community - Slack
• Issues - GitHub Issues
• Support - [e-mail]