Documentation Index
Fetch the complete documentation index at: https://agenticadvertisingorg-changeset-release-main.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Canonical-formats preview (3.1): starting in 3.1, formats can be declared inline on products viaCreative formats define the structural and technical requirements used to instantiate advertising creatives. A format specifies:format_options(an array ofProductFormatDeclarations narrowing one of 12 canonical formats). This page describes the v1 format-registry model, which remains a first-class path through 4.x. For the canonical-formats model, see canonical-formats and the migration guide.
- The asset types required (video, image, text, audio, etc.) via the
assetsarray - Technical constraints for each asset (duration, dimensions, file types, limits)
- How the resulting creative is delivered and validated
Standard vs Custom Formats
AdCP supports two categories of formats based on authority and reuse, not capability.Standard Formats
Standard formats are predefined specifications provided by the AdCP Reference Creative Agent (https://creative.adcontextprotocol.org).
Standard formats are:
- Industry-aligned: Based on IAB format families and widely adopted conventions
- Portable: Designed to work consistently across platforms
- Validated: Pre-tested against known technical constraints
- Discoverable: Returned via
list_creative_formats - Maintained: Centrally documented and updated
- Display formats with fixed or responsive dimensions
- Video formats with standard durations and aspect ratios
- Audio formats with defined spot lengths
- Common DOOH display and video executions
Custom Formats
Custom formats are defined by publishers or platforms for inventory that cannot be accurately represented by standard formats. Custom formats may be used when there are:- Unique constraints: Non-standard dimensions, physical displays, or asset requirements
- Specialized capabilities: Platform-specific rendering or interaction support
- Premium inventory: Differentiated or bespoke ad products
- Custom validation logic: Publisher-specific review or assembly rules
Discovering Formats
Buyers discover supported formats using thelist_creative_formats task exposed by sales agents.
Formats may be sourced from:
- The sales agent itself - for custom formats
- Referenced creative agents - such as the AdCP reference agent, for standard formats
Format Authority
Each format includes anagent_url that identifies the authoritative creative agent responsible for the format:
- Complete format specifications
- Creative element requirements and constraints
- Validation rules
- Preview generation
- Canonical documentation
agent_url to retrieve definitive format information.
Format Visual Presentation
Formats may optionally include metadata to support visual browsing and selection in user interfaces.Example Showcase
Field:example_url
Purpose: Deep link to a publisher-controlled showcase
May include:
- Interactive demos
- Videos
- Multiple creative examples
- Best practices and specifications
Referencing Formats
For a normative contrast between
format_id (structured reference object) and format (full definition object) β including the two most common validation errors β see Format References.Structured Format IDs (Required Everywhere)
ALL format references use structured format ID objects:- Explicit namespacing
- Collision-safe identifiers
- Schema validation
- Extensibility without breaking changes
Where Structured Format IDs Are Used
Requests:sync_creatives- Uploading creative assetsbuild_creative- Generating creatives via agents implementing the Creative Protocolpreview_creative- Preview generationcreate_media_buy- When specifying format requirements
list_creatives- Returning creative detailsget_products- Product format capabilitieslist_creative_formats- Format definitions- Any response containing creative or format details
format_ids(plural) in request filters - Array of structured format_id objects
Validation Rules
All AdCP agents MUST:- β
Accept structured
format_idobjects in ALL contexts - β
Return structured
format_idobjects in ALL responses - β Reject string format_ids with clear error messages
- β Never use string format_ids in any API contract
Legacy Considerations
Some legacy systems may send string format_ids. Implementers have two options:- Strict validation (recommended): Reject strings immediately with clear error
- Auto-upgrade with deprecation: Accept strings temporarily, log warnings, set removal timeline
- Only accept strings for well-known formats you can map to agent URLs
- Fail loudly for unknown format strings
- Log deprecation warnings on every request
- Set and communicate a removal date (recommend 6 months maximum)
Format Structure
Formats are JSON objects with the following key fields:- format_id: Unique identifier (may be namespaced with
domain:id) - agent_url: The creative agent authoritative for this format
- type: (deprecated, optional) High-level category hint. See note below.
- assets: Array of all asset specifications with
requiredboolean indicating mandatory vs optional. This is the authoritative source for understanding creative requirements. - asset_role: Identifies asset purpose (hero_image, logo, cta_button, etc.)
- renders: Array of rendered outputs with dimensions - see below
- accessibility: Optional WCAG conformance declaration β see Accessibility
Deprecation Notice: The
type field is deprecated and optional. The assets array provides precise information about creative requirements (video, image, text, etc.) and should be used instead. Categories like βvideoβ, βdisplayβ, and βnativeβ are lossy abstractions that donβt scale well to emerging formats like Performance Max (spans multiple channels), search ads (text-only with high intent), or conversational AI placements.Asset Discovery
Theassets array enables comprehensive asset discovery. Each asset has a required boolean:
required: true- Asset MUST be provided for a valid creativerequired: false- Asset is optional, enhances the creative when provided (e.g., companion banners, third-party tracking pixels)
Third-Party Tracker Support
Whether a format supports third-party measurement is determined by whether itsassets array includes a tracker slot. A tracker slot is any asset with asset_type: "url" AND either:
url_type: "tracker_pixel"orurl_type: "tracker_script"(mechanism-side declaration), ORrequirements.roleofimpression_tracker,click_tracker,viewability_tracker, orthird_party_tracker(purpose-side declaration; the slot accepts a tracker URL even if the format author declares the role rather than the mechanism)
impression_tracker asset. Formats without a tracker slot β such as broadcast TV spots β do not support creative-level pixel tracking. Measurement for these formats comes from external sources (panel data, set-top box telemetry) declared in the productβs billing_measurement terms, not from creative-embedded pixels.
A buyer agent that requires DoubleVerify viewability or IAS brand safety measurement should filter formats by tracker support. If no tracker slot exists, those vendors cannot instrument the creative β the buyer must rely on the sellerβs declared measurement vendor instead.
Typed Asset Requirements
Each asset type has its own requirements schema that defines what constraints apply to that asset. Therequirements object is typed based on the asset_type:
Image assets (asset_type: "image"):
min_width,max_width,min_height,max_height- Dimension constraints (set min=max for exact)aspect_ratio- Required aspect ratio (e.g., β1:1β)formats- Accepted file formats (jpg, jpeg, png, webp, gif, svg, avif)max_file_size_kb- Maximum file sizeanimation_allowed- Whether animated images are acceptedmax_animation_duration_ms- Maximum animation duration
asset_type: "video"):
min_width,max_width,min_height,max_height- Dimension constraintsaspect_ratio- Required aspect ratio (e.g., β16:9β)min_duration_ms,max_duration_ms- Duration constraintscontainers- Accepted container formats (mp4, webm, mov)codecs- Accepted codecs (h264, h265, vp9, av1)frame_rates- Accepted frame rates (e.g., [24, 30, 60])max_file_size_kb,max_bitrate_kbps- Size constraints
asset_type: "html"):
max_file_size_kb- Maximum file sizesandbox- Execution environment (none,iframe,safeframe,fencedframe)external_resources_allowed- Whether external scripts/images can be loadedallowed_external_domains- Permitted domains for external resources
asset_type: "javascript"):
max_file_size_kb- Maximum file sizemodule_type- Module format (script,module,iife)external_resources_allowed- Whether dynamic resource loading is allowedallowed_external_domains- Permitted domains for dynamic loading
asset_type: "audio"):
min_duration_ms,max_duration_ms- Duration constraintsformats- Accepted audio formats (mp3, aac, wav, ogg, flac)sample_rates- Accepted sample rates in Hz (e.g., [44100, 48000])channels- Accepted channel configurations (mono, stereo)min_bitrate_kbps,max_bitrate_kbps- Bitrate constraintsmax_file_size_kb- Maximum file size
asset_type: "text"):
min_length,max_length- Character limitsmin_lines,max_lines- Line count limitscharacter_pattern- Regex for allowed charactersprohibited_terms- Words/phrases not allowedallowed_values- Closed list of permitted strings; submissions outside the list are rejected withCREATIVE_VALUE_NOT_ALLOWED
allowed_values to expose the exact strings legal or brand has pre-approved. All declared constraints are conjunctive (every allowed value must also satisfy max_length, character_pattern, etc.) and matching is case-sensitive β buyers MUST submit one of the listed strings verbatim. Buyer agents using LLMs to fill text slots should pass allowed_values as a constrained-sampling option rather than generating freely and retrying after rejection.
When a submitted value is not in the list, sellers MUST return CREATIVE_VALUE_NOT_ALLOWED with error.field pointing at the offending asset path and error.details.allowed_values echoing the formatβs list so the buyer can re-prompt deterministically.
URL assets (asset_type: "url"):
role- Standard purpose (clickthrough, impression_tracker, click_tracker, etc.)protocols- Allowed protocols (https, http)allowed_domains- Permitted destination domainsmacro_support- Whether macro substitution is supported
Asset Overlays
Some formats include publisher-controlled elements that render on top of buyer creative content β video player controls, publisher logos, and similar chrome. Formats declare these asoverlays on the relevant asset so creative agents and buyers know which areas will be covered and can compose accordingly.
Overlay bounds are expressed relative to the assetβs own top-left corner. The unit field is either "px" (absolute pixels) or "fraction" (proportional to asset dimensions: for x/y, 0.0 is the assetβs own edge; for width/height, 0.12 means 12% of the asset dimension). Different overlays on the same asset may use different units β creative agents must handle each independently.
visual field is optional but strongly recommended β it allows creative agents to composite accurate previews showing buyer content with publisher chrome in place. Use url for a theme-neutral graphic (e.g., an SVG using currentColor), or provide light/dark variants for separate theme-specific assets.
Rendered Outputs and Dimensions
Formats describe one or more rendered outputs, each with defined dimensions and semantic roles. This supports:- Single-render formats
- Companion creatives
- Multi-placement outputs
- Responsive behavior
- Physical dimensions for non-personal environments
renders array. Most formats produce a single render, but some (companion ads, adaptive formats, multi-placement) produce multiple renders:
- Supports single and multi-render formats uniformly
- No string parsing required - structured dimensions
- Schema-validated dimensions
- Supports responsive and fixed formats equally
- Enables proper preview rendering
- Allows dimension-based filtering
- Supports physical units for DOOH
- Clear semantic roles for each rendered piece
Understanding Format Requirements
Traditional IAB format families (display, video, audio, native) are lossy abstractions that donβt scale to emerging formats:- Performance Max spans video, display, search, and native simultaneously
- Search ads (RSA) are text-only with high intent context
- Conversational AI placements donβt fit traditional categories
assets array tells you exactly what creative elements are needed:
- Video required? Check for
asset_type: 'video' - Images required? Check for
asset_type: 'image' - Text only? All required assets have
asset_type: 'text'
Video Formats
- Standard video (15s, 30s, 60s)
- Vertical video for mobile/stories
- VAST/VPAID tags
- Interactive video
Display Formats
- Standard IAB sizes (300x250, 728x90, etc.)
- Responsive units
- Rich media and expandable
- HTML5 creative
Audio Formats
- Streaming audio (15s, 30s, 60s)
- Podcast insertion
- Companion banners
- VAST audio tags
DOOH Formats
- Digital billboards
- Transit displays
- Retail screens
- Venue-based impression tracking
Carousel/Multi-Asset Formats
- Product carousels (3-10 items)
- Story sequences
- Slideshow formats
- Frame-based structures
Multi-Asset & Frame-Based Formats
Some formats like carousels, slideshows, and stories use repeatable asset groups where each frame contains a collection of assets. See the Carousel & Multi-Asset Formats guide for complete documentation on frame-based format patterns.Reported Metrics
Formats can declare which metrics they produce in delivery reporting via thereported_metrics field. This tells buyers what data to expect when purchasing inventory using this format.
Intersection with Product Metrics
Products declare their available metrics viareporting_capabilities.available_metrics. The buyer receives the intersection of format reported_metrics and product available_metrics.
impressions and spend are always reported regardless of the intersection β they are implicit in every delivery response. The intersection applies to all other metrics.
For example, if a video format declares quartile_data but the product only reports impressions, spend, and clicks, the buyer will not receive quartile data for that product.
When to Omit
Ifreported_metrics is omitted, the format defers entirely to product-level metric declarations. This is appropriate for formats where the creative type does not inherently constrain which metrics are available (e.g., native formats where metrics depend on the platform).
Common Patterns
Video formats:impressions, spend, views, completed_views, completion_rate, quartile_data
Display formats: impressions, spend, clicks, ctr, viewability
DOOH formats: impressions, spend, dooh_metrics
Social/performance formats: impressions, spend, clicks, ctr, conversions, engagement_rate
Format Cards
Format cards provide visual representations of creative formats for display in browsing and selection interfaces. Creative agents can optionally include card definitions that reference card formats and provide the assets needed to render attractive visual cards.Card Types
Creative agents should provide at least the standard card, and optionally a detailed card: Standard Card (format_card):
- Compact 300x400px card for format browsing
- Supports 2x density images for retina displays
- Quick visual understanding of format specs
format_card_detailed, optional):
- Responsive layout with text description alongside hero carousel showing format in context
- Markdown specifications section below
- Full format documentation similar to Yahooβs ad specs
Structure
Rendering Cards
Cards can be rendered in two ways:- Via
preview_creative: Pass the card format and manifest to generate a rendered card - Pre-rendered: Creative agents can pre-generate cards and serve them directly
Standard Card Formats
The AdCP reference creative agent defines two standard card formats:format_card_standard(300x400px) - Compact card for format browsingformat_card_detailed(responsive) - Rich card with carousel and full specs
When to Include Format Cards
Format cards are optional but recommended for:- Visual formats (display, video, DOOH) where mockups help explain the format
- Complex formats with multiple asset requirements
- Custom formats that differ from standard specifications
- Formats where visual preview aids buyer understanding
Client Rendering Guidelines
When displaying formats in UIs, clients should follow this fallback order:- If
format_cardexists β Render card viapreview_creativeor display pre-rendered image - If no
format_cardexists β Render text-only representation (format name + description) - If card rendering fails β Gracefully fall back to text-only representation
Related Documentation
- Creative Protocol Overview - How formats, manifests, and agents work together
- Creative Manifests - Pairing assets with formats
- Asset Types - Understanding asset specifications
- Channel Guides - Detailed format documentation by media type
- Implementing Standard Format Support - For sales agents
- list_creative_formats Task - API reference for format discovery