Skip to main content
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