> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-snap-format-preview-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md).

***

## Version 2.5.0

**Released:** November 2025 | [Full Changelog](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md#250)

### 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:**

```json theme={null}
// Before
{
  "platform_id": "ttd"
}

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

**Property Selectors:**

```json theme={null}
// 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:**

```json theme={null}
// 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:**

```json theme={null}
{
  "task_id": "task_123",
  "status": "completed",
  "media_buy_id": "mb_456",
  "packages": [...]
}
```

**After:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "activation_key": "segment_123"
}
```

**After:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md#230)

### 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:**

```json theme={null}
{
  "properties": [{
    "publisher_domain": "cnn.com",
    "property_name": "CNN CTV App",
    "property_tags": ["ctv", "premium"]
  }]
}
```

**After:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "budget": 50000,
  "packages": [...]
}
```

**After:**

```json theme={null}
{
  "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](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md#220)

### 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:**

```json theme={null}
{
  "source_manifest": {...},
  "promoted_offerings": [...]
}
```

**After:**

```json theme={null}
{
  "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](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md#210)

### 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:**

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

**After:**

```json theme={null}
{
  "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](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md#200)

### 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](https://semver.org/):

* **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](https://github.com/adcontextprotocol/adcp/blob/main/CHANGELOG.md)
* **GitHub Releases** - [Release Archive](https://github.com/adcontextprotocol/adcp/releases)
* **Community** - [Slack](https://join.slack.com/t/agenticads/shared_invite/zt-3c5sxvdjk-x0rVmLB3OFHVUp~WutVWZg)
* **Issues** - [GitHub Issues](https://github.com/adcontextprotocol/adcp/issues)
* **Support** - [support@adcontextprotocol.org](mailto:support@adcontextprotocol.org)