Task Reference

Complete reference for all AdCP Media Buy tasks. Each task is designed for AI agents to automate specific parts of the advertising workflow.

​

All Tasks Overview

​

Response Time Categories

AdCP tasks fall into four response time categories:

​

🟢 Instant (~1 second)

Simple lookups and event ingestion

• list_products - Published offers and canonical Product.format_options[]
• list_creatives - Creative library queries
• get_media_buys - Media buy status and creative approvals
• provide_performance_feedback - Performance signal submission
• sync_event_sources - Event source configuration
• log_event - Event ingestion

​

🟡 Processing (~60 seconds)

AI/LLM inference with backend systems

• request_proposals - Seller planning from a natural-language brief and structured criteria
• refine_proposals - Typed proposal revision and finalization
• get_media_buy_delivery - Performance data aggregation

​

🟠 Asynchronous (Minutes to Days)

Complex operations with potential human approval

• buy_products - Direct published-offer commitment
• accept_proposal - Negotiated commitment, amendment, or cancellation
• control_media_buy - Revision-checked operational control
• sync_catalogs - Catalog feed processing and review
• sync_creatives - Creative asset processing
• sync_audiences - Audience matching and processing

​

Task Categories by Workflow

​

Account Management

Before placing media buys, establish a commercial relationship with the seller. These tasks are shared across all vendor protocols and live in the Commerce Protocol section:

• sync_accounts - Declare brand/operator pairs and billing; seller provisions accounts
• list_accounts - Check account status and retrieve active account_id values

​

Discovery & Planning

Start here to understand what’s available and plan your campaign.

• get_adcp_capabilities - Discover agent capabilities, portfolio, and supported features (protocol-level task)
• list_products - Read published offers or bootstrap and repair a wholesale mirror
• request_proposals, refine_proposals, and decline_proposals - Request seller-authored plans, create immutable successors, finalize holds, or record terminal feedback
• Canonical formats - Understand creative requirements and authority

​

Media Buy Management

Create and manage your advertising campaigns.

• buy_products - Directly buy published product offers
• accept_proposal - Apply negotiated new-buy, amendment, or cancellation terms
• control_media_buy - Modify delivery controls inside accepted terms

​

3.x Compatibility

Use these only when capability discovery does not expose the compact lifecycle:

• create_media_buy and update_media_buy - Deprecated 3.x compatibility facades
• get_products - 3.x compatibility discovery facade; new integrations choose list_products or request_proposals

​

Catalog Management

Sync product feeds, inventory, and store data to seller accounts.

• sync_catalogs - Push catalog feeds with platform review and approval

​

Creative Management

Handle creative assets throughout their lifecycle.

• sync_creatives - Upload assets to an agent-hosted creative library
• list_creatives - Search and manage your creative library (creative protocol)
• assignment_operations - Explicitly assign, unassign, or replace package creatives after compact commitment

​

Performance & Optimization

Monitor and optimize campaign performance.

• get_media_buys - Check campaign status, creative approvals, and near-real-time delivery snapshots
• get_media_buy_delivery - Track delivery and performance metrics for reporting
• provide_performance_feedback - Submit performance signals for publisher optimization

​

Conversion Tracking

Configure event sources and send marketing events for attribution.

• sync_event_sources - Configure event sources on seller accounts
• log_event - Send marketing events for attribution

​

Audience Management

Upload and manage first-party CRM audiences for targeting.

• sync_audiences - Upload hashed customer lists and check matching status

​

Schema Reference

All tasks include JSON schema definitions for requests and responses:

• Request Schemas: /schemas/3.2.0-beta.3/media-buy/[task-name]-request.json
• Response Schemas: /schemas/3.2.0-beta.3/media-buy/[task-name]-response.json

Task Management: For tracking async operations across all AdCP domains, see Task Lifecycle. Schemas are accessible at runtime via the documentation server for validation and tooling.

​

Common Patterns

​

Task Naming Conventions

Task names use snake_case and follow verb-first semantics consistently across Media Buy:

• get_*: Retrieve current state or scoped datasets (for example get_media_buys and get_media_buy_delivery)
• list_*: Enumerate collections with optional filtering (for example list_products and list_creatives)
• request_*, refine_*, and decline_*: Explicit lifecycle transitions over immutable resources; finalized proposals flow into accept_proposal
• buy_* and accept_*: Create or change a commercial commitment from versioned terms
• control_*: Apply revision-checked operational changes inside accepted terms
• sync_*: Reconcile external state into seller systems with upsert-like behavior (sync_catalogs, sync_creatives, sync_event_sources)
• log_*: Ingest append-only event records (log_event)
• provide_*: Submit optimization or feedback signals (provide_performance_feedback)

​

Error Handling

All tasks follow consistent error patterns with:

• HTTP status codes for different error types
• Structured error messages with context
• Retry guidance for transient failures

​

Authentication

Tasks require proper authentication via:

• API keys for service-to-service calls
• Authenticated agent and account scope for multi-tenant operations
• Permission validation for resource access

​

Asynchronous Operations

Long-running tasks provide:

• Immediate response with operation ID
• Status polling endpoints for progress
• Webhook notifications for completion

​

Getting Started

1. Discover capabilities: Read media_buy.lifecycle_tools through get_adcp_capabilities.
2. Choose a commercial path: Use list_products for published offers and wholesale mirrors, or request_proposals for seller planning.
3. Understand formats: Check each selected product’s canonical format_options[] before commitment.
4. Commit: Call buy_products, or revise and finalize a proposal before accept_proposal.
5. Supply creatives: Use sync_creatives and explicit assignment operations after compact commitment.
6. Read operational state: Use get_media_buys for status, revision, accepted terms, approvals, and missing formats.
7. Control delivery: Use control_media_buy for in-envelope changes; start a proposal amendment when the seller returns REQUOTE_REQUIRED.
8. Monitor performance: Track billing-grade reporting with get_media_buy_delivery.

For reporting and reconciliation, treat get_media_buy_delivery as the authoritative, billing-grade source. Use get_media_buys snapshots for operational monitoring only.

​

Related Documentation

• Product Discovery - Natural language inventory discovery
• Media Buys - Campaign lifecycle management
• Creatives - Creative asset management
• Advanced Topics - Targeting, security, and architecture