> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/llms.txt > Use this file to discover all available pages before exploring further. # Browse products for discovery session > Browse available products for an existing discovery session. Returns product suggestions grouped by publisher with pagination support. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml get /discovery/{discoveryId}/discover-products openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /discovery/{discoveryId}/discover-products: get: tags: - Product Discovery summary: Browse products for discovery session description: >- Browse available products for an existing discovery session. Returns product suggestions grouped by publisher with pagination support. operationId: browseProducts parameters: - in: query name: groupLimit schema: description: 'Maximum number of product groups to return (default: 10, max: 10)' example: 10 default: 10 type: integer maximum: 10 minimum: 1 description: 'Maximum number of product groups to return (default: 10, max: 10)' - in: query name: groupOffset schema: description: Number of groups to skip for pagination example: 0 default: 0 type: integer minimum: 0 maximum: 9007199254740991 description: Number of groups to skip for pagination - in: query name: productsPerGroup schema: description: 'Maximum products to return per group (default: 10, max: 15)' example: 10 default: 10 type: integer maximum: 15 minimum: 1 description: 'Maximum products to return per group (default: 10, max: 15)' - in: query name: productOffset schema: description: >- Number of products to skip within each group (default: 0, max: 1000) example: 5 default: 0 type: integer minimum: 0 maximum: 1000 description: 'Number of products to skip within each group (default: 0, max: 1000)' - in: query name: publisherDomain schema: description: Filter products by publisher domain (exact domain component match) example: hulu type: string minLength: 1 description: Filter products by publisher domain (exact domain component match) - in: query name: pricingModel schema: description: Filter products by pricing model example: cpm type: string enum: - cpm - vcpm - cpc - cpcv - cpv - cpp - cpa - flat_rate - time description: Filter products by pricing model - in: query name: storefrontIds schema: description: Filter products by storefront ID(s) (from `list_storefronts`). example: - 42 - 57 anyOf: - maxItems: 50 type: array items: type: integer maximum: 9007199254740991 minimum: 1 - type: string description: Filter products by storefront ID(s) (from `list_storefronts`). - in: query name: storefrontNames schema: description: >- Filter products by storefront name (case-insensitive substring match). example: - Acme - Acme Exchange anyOf: - maxItems: 50 type: array items: type: string maxLength: 255 - type: string description: >- Filter products by storefront name (case-insensitive substring match). - in: query name: debug schema: description: >- When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting anyOf: - type: boolean - type: string description: >- When true, includes detailed ADCP agent request/response debug logs in the response for troubleshooting - in: query name: waitMode schema: description: >- `quick` waits up to 30 seconds per storefront agent and returns partial results if slow agents miss the window. `long` waits up to 210 seconds per storefront agent; ask the user before using it. example: quick default: quick type: string enum: - quick - long description: >- `quick` waits up to 30 seconds per storefront agent and returns partial results if slow agents miss the window. `long` waits up to 210 seconds per storefront agent; ask the user before using it. - in: query name: waitSeconds schema: description: >- Optional explicit per-storefront wait in seconds, max 210. Overrides waitMode. Ask the user before setting this above 30. example: 120 type: integer maximum: 210 minimum: 1 description: >- Optional explicit per-storefront wait in seconds, max 210. Overrides waitMode. Ask the user before setting this above 30. - in: query name: sinceRevision schema: description: >- Progressive polling: return only seller groups that landed after this snapshot revision. Groups use REPLACE semantics — a group may be re-delivered at a later revision when more of its products land; replace it by groupId, never append. The response always carries the current `revision`, `resultsComplete`, and `pendingAgents`; poll again with the returned revision until `resultsComplete` is true, and stop polling after roughly the wait budget if it never turns true (the fan-out may have been interrupted). example: 3 type: integer minimum: 0 maximum: 9007199254740991 description: >- Progressive polling: return only seller groups that landed after this snapshot revision. Groups use REPLACE semantics — a group may be re-delivered at a later revision when more of its products land; replace it by groupId, never append. The response always carries the current `revision`, `resultsComplete`, and `pendingAgents`; poll again with the returned revision until `resultsComplete` is true, and stop polling after roughly the wait budget if it never turns true (the fan-out may have been interrupted). - in: path name: discoveryId schema: description: Discovery ID example: abc123-def456-ghi789 type: string minLength: 1 required: true description: Discovery ID responses: '200': description: Browse products for discovery session content: application/json: schema: $ref: '#/components/schemas/DiscoverProductsResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: DiscoverProductsResponse: description: Response from discovering products type: object properties: discoveryId: description: Discovery ID example: abc123-def456-ghi789 type: string productGroups: description: Products grouped by publisher type: array items: $ref: '#/components/schemas/ProductGroup' totalGroups: description: Total number of product groups available example: 25 type: integer minimum: 0 maximum: 9007199254740991 hasMoreGroups: description: Whether more groups are available beyond those shown type: boolean summary: description: Summary statistics for discovered products allOf: - $ref: '#/components/schemas/DiscoverySummary' budgetContext: description: Budget context if budget was provided allOf: - $ref: '#/components/schemas/BudgetContextResponse' proposals: description: >- Recommended media plans from sales agents (ADCP v3). Each proposal explains WHY certain products are recommended together and how budget should be allocated. type: array items: $ref: '#/components/schemas/Proposal' incompleteAgents: description: >- Storefront agents that timed out or returned ADCP incomplete scopes under the requested wait window. Present without debug=true so callers can offer a longer retry without exposing raw agent logs. type: array items: $ref: '#/components/schemas/IncompleteDiscoveryAgent' connectionIssues: description: >- Adapter connections that require re-authentication. When present, one or more storefronts were skipped because their OAuth credentials have expired. Go to Settings > Connections to reconnect, then retry. type: array items: $ref: '#/components/schemas/ConnectionIssue' retryWithLongerWaitAvailable: description: >- True when at least one storefront timed out or returned ADCP incomplete scopes and the request used less than the maximum interactive wait window. type: boolean agentResults: description: >- Per-agent debug info. Only present when debug=true; includes timing so callers can decide whether to retry with a longer wait. type: array items: $ref: '#/components/schemas/AgentDiscoveryResult' refinementApplied: description: >- Seller's response to each refinement instruction, matched by position to the request's refine array. Only present when refine was provided. type: array items: $ref: '#/components/schemas/RefinementApplied' revision: description: >- Progressive delivery: monotonic snapshot revision. Present on progressive responses and sinceRevision polls; pass it back as `sinceRevision` to fetch only newly landed seller groups. example: 3 type: integer minimum: 0 maximum: 9007199254740991 resultsComplete: description: >- Progressive delivery: false while sellers are still answering in the background. Poll browse_discovery with `sinceRevision` until true. example: false type: boolean pendingAgents: description: >- Progressive delivery: sellers still in flight (not yet answered). Distinct from incompleteAgents, which timed out or answered partially at the final revision. type: array items: $ref: '#/components/schemas/PendingDiscoveryAgent' progress: description: >- Progressive delivery: authoritative storefront response counts, independent of result-group pagination and sinceRevision delta pages. type: object properties: respondedStorefrontCount: type: integer minimum: 0 maximum: 9007199254740991 totalStorefrontCount: type: integer minimum: 0 maximum: 9007199254740991 waitSeconds: type: integer maximum: 9007199254740991 minimum: 1 required: - respondedStorefrontCount - totalStorefrontCount - waitSeconds additionalProperties: false diagnostics: description: >- Advanced support diagnostics. Returned only to elevated/admin contexts and intended for internal troubleshooting. allOf: - $ref: '#/components/schemas/DiscoveryDiagnostics' guidance: description: >- Human-readable next-step guidance. On progressive responses this spells out the exact continuation call (browse with `sinceRevision`); on empty results it explains what was queried and suggests adding a brief/brand URL or broadening filters. example: >- 2 seller(s) still working — call browse_discovery with sinceRevision: 3 for newly landed results. type: string required: - discoveryId - productGroups - totalGroups - hasMoreGroups - summary additionalProperties: false ErrorResponse: description: Standard error response type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false ProductGroup: description: Group of products from a publisher type: object properties: groupId: description: Unique identifier for the product group type: string groupName: description: Name of the group (typically publisher name) type: string storefrontId: description: Storefront ID when this is a storefront-backed group type: string storefrontName: description: Storefront display name type: string description: description: Description of the product group type: string products: description: Products in this group type: array items: $ref: '#/components/schemas/Product' productCount: description: Number of products in this group type: integer minimum: 0 maximum: 9007199254740991 totalProducts: description: Total number of products available in this group type: integer minimum: 0 maximum: 9007199254740991 hasMoreProducts: description: Whether more products are available beyond those returned type: boolean required: - groupId - groupName - products - productCount - totalProducts - hasMoreProducts additionalProperties: false DiscoverySummary: description: Summary statistics for the discovery type: object properties: totalProducts: description: Total number of products in the discovery example: 150 type: integer minimum: 0 maximum: 9007199254740991 publishersCount: description: Number of unique publishers example: 25 type: integer minimum: 0 maximum: 9007199254740991 priceRange: description: CPM price range across products type: object properties: min: nullable: true type: number max: nullable: true type: number avg: nullable: true type: number currency: description: >- ISO currency code, present only when every priced product in this discovery shares one currency — min/max are not comparable across currencies, so this is omitted when mixed. example: USD type: string required: - min - max - avg additionalProperties: false required: - totalProducts - publishersCount additionalProperties: false BudgetContextResponse: description: Budget allocation context type: object properties: sessionBudget: description: Total budget set for the session nullable: true type: number allocatedBudget: description: Budget allocated to selected products type: number remainingBudget: description: Remaining unallocated budget nullable: true type: number budgetWarning: description: Warning message if budget allocation has issues type: string required: - sessionBudget - allocatedBudget - remainingBudget additionalProperties: false Proposal: description: >- A recommended media plan with budget allocations across products (ADCP v3) type: object properties: proposalId: description: Unique identifier — used to refine or execute the proposal type: string name: description: Human-readable name for this media plan proposal type: string description: description: Strategic explanation of what the proposal achieves type: string briefAlignment: description: Explanation of how this proposal aligns with the brief type: string salesAgentId: description: Sales agent that generated this proposal type: string salesAgentName: description: Human-readable sales agent name type: string storefrontId: description: >- Storefront the proposal was surfaced through. The storefront is the buyer-facing seller identity; the underlying sales agent is internal routing detail. type: string storefrontName: description: >- Human-readable storefront name. Use this as the seller label on proposal cards. type: string supportedRoutingTypes: deprecated: true description: >- Deprecated v2 compatibility field. It is not a storefront type or proposal capability and must not affect eligibility or execution. type: array items: type: string enum: - DECISIONED - ROUTED allocations: description: Budget distribution across products — percentages sum to 100 minItems: 1 type: array items: $ref: '#/components/schemas/ProductAllocation' expiresAt: description: When the proposal expires (ISO 8601) type: string totalBudgetGuidance: description: Budget guidance for this proposal type: object properties: min: type: number recommended: type: number max: type: number currency: type: string additionalProperties: false required: - proposalId - name - allocations additionalProperties: false IncompleteDiscoveryAgent: description: >- Storefront agent that did not fully complete inside the requested discovery wait window, either because the call timed out locally or because the seller returned ADCP incomplete scopes. Use this to ask whether the buyer wants to retry with a longer wait. type: object properties: agentId: description: Sales agent ID type: string agentName: description: Sales agent name type: string storefronts: description: Storefronts represented by this incomplete sales agent result. type: array items: type: object properties: storefrontId: type: string storefrontName: type: string required: - storefrontId - storefrontName additionalProperties: false reason: description: Why this agent result is incomplete. type: string enum: - timeout - upstream_incomplete responseTimeMs: description: >- Wall-clock response time in milliseconds, usually the requested wait window. type: integer minimum: 0 maximum: 9007199254740991 waitSeconds: description: Wait window used for this attempt, in seconds. type: integer maximum: 9007199254740991 minimum: 1 incompleteScopes: description: >- ADCP get_products incomplete scopes reported by the upstream seller. Present when reason is upstream_incomplete. type: array items: $ref: '#/components/schemas/IncompleteDiscoveryScope' required: - agentId - agentName - reason - waitSeconds additionalProperties: false ConnectionIssue: description: >- An adapter connection that requires the buyer to re-authenticate before discovery can reach it. type: object properties: providerType: description: >- Adapter provider type whose OAuth connection needs re-authentication, e.g. "meta" or "snap". example: meta type: string storefrontId: description: ID of the storefront whose connection needs re-authentication. type: string storefrontName: description: Name of the storefront whose connection needs re-authentication. type: string required: - providerType additionalProperties: false AgentDiscoveryResult: description: >- Per-agent discovery result with optional debug info. Same structure as v1 media_product_discover debug output. type: object properties: agentId: description: Sales agent ID type: string agentName: description: Sales agent name type: string responseTimeMs: description: >- Wall-clock response time for this storefront agent, in milliseconds. Present in debug mode when the agent was called. type: integer minimum: 0 maximum: 9007199254740991 timedOut: description: >- Whether this storefront agent hit the requested discovery wait window. type: boolean storefronts: description: >- Storefronts represented by this sales agent result. One agent may back multiple storefronts. type: array items: type: object properties: storefrontId: type: string storefrontName: type: string required: - storefrontId - storefrontName additionalProperties: false success: description: Whether the agent responded successfully type: boolean productCount: description: Number of products returned by the agent type: integer minimum: 0 maximum: 9007199254740991 error: description: Error message if the agent failed type: string skipReason: description: >- Human-readable explanation of why the agent was skipped or failed (e.g. 'We do not support the list of channels you specified'). Prefer this over `error` when surfacing the reason in a UI; falls back to the raw error string when no structured reason is available. Untrusted agent-controlled content; sanitize before rendering in HTML. type: string incomplete: description: >- ADCP get_products incomplete scopes returned by this agent. Present in debug mode when a successful agent response declares partial data. type: array items: type: object properties: scope: type: string enum: - products - pricing - forecast - proposals - wholesale_feed description: type: string estimated_wait: type: object properties: interval: type: number minimum: 0 exclusiveMinimum: true unit: type: string enum: - seconds - minutes - hours - days - campaign required: - interval - unit additionalProperties: false required: - scope - description additionalProperties: false rawResponseData: description: Raw response data from the agent (only present when debug=true) debugLogs: description: Full ADCP request/response debug logs (only present when debug=true) type: array items: $ref: '#/components/schemas/AgentDebugLog' required: - agentId - agentName - success - productCount additionalProperties: false RefinementApplied: description: >- Seller's response to a refinement instruction, matched by position to the request's refine array type: object properties: scope: description: Echoes the scope from the corresponding refinement instruction type: string enum: - request - product - proposal id: description: >- Echoes the id from the corresponding refinement instruction (for product and proposal scopes) type: string status: description: >- 'applied': the ask was fulfilled. 'partial': partially fulfilled. 'unable': could not fulfill. type: string enum: - applied - partial - unable notes: description: Seller explanation of the result type: string required: - status additionalProperties: false PendingDiscoveryAgent: description: >- A seller still answering during a progressive discovery — it has not settled yet. type: object properties: agentId: description: Sales agent identifier type: string agentName: description: Sales agent display name type: string storefronts: description: Storefronts this agent serves, when known type: array items: type: object properties: storefrontId: type: string storefrontName: type: string required: - storefrontId - storefrontName additionalProperties: false required: - agentId - agentName additionalProperties: false DiscoveryDiagnostics: description: Advanced support diagnostics returned only to elevated/admin contexts. type: object properties: trace: description: Trace identifiers for auditing where discovery time was spent. allOf: - $ref: '#/components/schemas/DiscoveryTraceDiagnostics' additionalProperties: false ApiError: description: Structured error object type: object properties: code: description: Machine-readable error code type: string message: description: Human-readable error message type: string field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false Product: description: Product resource for campaign inventory type: object properties: productId: description: Unique identifier for the product example: prod_123 type: string name: description: Product name example: Premium CTV Inventory - Sports type: string channel: description: >- First canonical AdCP media channel. Use channels for the complete set. example: ctv type: string channels: description: Canonical AdCP media channels declared by the product example: - streaming_audio - podcast type: array items: type: string inventoryType: description: >- Inventory classification such as premium or run_of_site; not a media channel example: run_of_site type: string formatTypes: description: >- Canonical AdCP format kinds derived from formatOptions (never legacy named-format IDs) example: - video_hosted type: array items: type: string cpm: description: Cost per mille (CPM) example: 12.5 type: number currency: description: ISO currency code for `cpm` (e.g. "USD", "ZAR") example: USD type: string expiresAt: description: >- When this product's pricing stops being valid (ISO 8601). Present only when the seller quoted an FX-converted price (a rate-of-the-day conversion into a currency the product is not natively priced in); absent for natively-priced products, which carry no expiry and cache freely. A cached product past this timestamp MUST be treated as stale — re-discover or re-quote rather than transacting on the expired price. Selecting or booking against an expired quote gets a fresh price, not the stale one. type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ pricingScope: description: >- Whether this product's pricing is the seller's public rate card ('public') or reflects a buyer-specific discount/rate ('account'). Absent is equivalent to 'public' (a pre-3.1 seller, or a source that has never applied account-specific pricing). A buyer's agent should treat 'public' items as portable across a shared/anonymous cache and 'account' items as private to this account — never re-serve an account-scoped price to another account or a public cache partition. type: string enum: - public - account salesAgentId: description: Sales agent ID type: string salesAgentName: description: Sales agent name type: string storefrontId: description: >- Storefront ID — the storefront this product was discovered through. A single sales agent may back sources across multiple storefronts; products are stamped per (storefront, agent) pairing so the same product can appear in multiple storefronts independently. type: string storefrontName: description: Storefront display name type: string supportedRoutingTypes: deprecated: true description: >- Deprecated v2 compatibility field. It is not a storefront type or product capability and must not affect eligibility or execution. type: array items: type: string enum: - DECISIONED - ROUTED description: description: Product description type: string deliveryType: description: Delivery type — guaranteed means fixed delivery commitment example: guaranteed type: string enum: - guaranteed - non_guaranteed briefRelevance: description: >- AI-generated explanation of why this product matches the campaign brief type: string productCard: description: Standard visual card (300x400px) for UI rendering allOf: - $ref: '#/components/schemas/ProductCardData' productCardDetailed: description: Detailed card with carousel and full specifications allOf: - $ref: '#/components/schemas/ProductCardDetailedData' pricingOptions: description: Full pricing options from the sales agent type: array items: $ref: '#/components/schemas/PricingOptionData' estimatedExposures: description: Estimated impressions for guaranteed products type: integer minimum: -9007199254740991 maximum: 9007199254740991 forecast: description: >- Structured delivery forecast with budget points and metric ranges (ADCP 3.15+) type: object additionalProperties: {} bookability: description: >- Sanitized Sales Agent cached pricing/availability guidance for whether the product is bookable. type: string publisherProperties: description: Publisher properties from ADCP (domains, property types, etc.) type: array items: type: object properties: publisherDomain: type: string propertyType: type: string name: type: string selectionType: type: string identifiers: type: array items: type: object additionalProperties: {} additionalProperties: false isSandbox: description: Whether this product was discovered in sandbox mode type: boolean formatOptions: description: >- AdCP 3.1 format declarations for this product. Each entry carries a format_kind discriminator, optional format_option_id (stable identifier buyers use to select a specific format via format_option_refs in create_media_buy), and canonical params. For hosted-video formats (format_kind "video_hosted"), params.containers / params.video_codecs / params.audio_codecs advertise the accepted delivery containers and codecs, so a buyer can avoid sending a creative that would be rejected downstream. Present only when the sales agent publishes v2 format declarations alongside legacy format_ids. type: array items: $ref: '#/components/schemas/ProductFormatOption' required: - productId - name additionalProperties: false ProductAllocation: description: Budget allocation for a product within a proposal type: object properties: productId: description: Product ID — references a product in the sibling products array type: string allocationPercentage: description: Percentage of total budget allocated to this product type: number minimum: 0 maximum: 100 pricingOptionId: description: Recommended pricing option ID from the product pricing_options type: string rationale: description: Why this product and allocation are recommended type: string sequence: description: Ordering hint for multi-line-item plans (1-based) type: integer minimum: -9007199254740991 maximum: 9007199254740991 tags: description: Categorical tags (e.g., "desktop", "mobile") type: array items: type: string required: - productId - allocationPercentage additionalProperties: false IncompleteDiscoveryScope: description: >- A get_products scope the upstream seller could not fully complete within the requested time budget. type: object properties: scope: type: string enum: - products - pricing - forecast - proposals - wholesale_feed description: description: >- Seller-provided explanation of what is missing or partial, capped at 500 characters. Untrusted agent-controlled content; sanitize before rendering in HTML. type: string maxLength: 500 estimatedWaitSeconds: description: >- Estimated additional wait in seconds if the seller provided ADCP incomplete.estimated_wait. type: integer maximum: 9007199254740991 minimum: 1 required: - scope - description additionalProperties: false AgentDebugLog: description: A single debug log entry from ADCP agent communication type: object properties: timestamp: type: string type: type: string message: type: string request: type: object additionalProperties: {} response: type: object additionalProperties: {} additionalProperties: false DiscoveryTraceDiagnostics: description: Advanced support diagnostics for tracing a discovery fan-out. type: object properties: traceId: description: OpenTelemetry trace ID for the discovery request/fan-out. example: 4bf92f3577b34da6a3ce929d0e0e4736 type: string spanId: description: >- OpenTelemetry span ID for the request span that initiated the discovery fan-out. example: 00f067aa0ba902b7 type: string traceparent: description: >- W3C traceparent value that can be pasted into internal tracing tools. example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 type: string required: - traceId - spanId - traceparent additionalProperties: false ProductCardData: description: Visual card data for rendering a product in UI type: object properties: image: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ created_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} title: type: string description: type: string price_label: type: string cta_label: type: string additionalProperties: false ProductCardDetailedData: description: Detailed inline product card data for buyer UIs type: object properties: hero_image: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ created_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} carousel_images: type: array items: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ created_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} title: type: string description: type: string specifications: type: array items: type: object properties: label: type: string value: type: string required: - label - value additionalProperties: false price_label: type: string cta_label: type: string additionalProperties: false PricingOptionData: description: Pricing option from a sales agent type: object properties: pricingOptionId: type: string pricingModel: type: string isFixed: type: boolean rate: type: number floorPrice: type: number fixedPrice: type: number currency: type: string priceGuidance: description: >- Cached auction guidance percentiles from the Sales Agent. These are estimates, not floors. type: object properties: floor: nullable: true type: number p25: nullable: true type: number p50: nullable: true type: number p75: nullable: true type: number p90: nullable: true type: number additionalProperties: false additionalProperties: false ProductFormatOption: description: AdCP 3.1 format declaration for a product type: object properties: format_kind: description: AdCP format kind discriminator (e.g. video_hosted, image) example: video_hosted type: string format_option_id: description: >- Stable identifier buyers use to select this format via format_option_refs in create_media_buy type: string display_name: description: Human-readable name for this format option type: string params: description: Canonical params for this format option allOf: - $ref: '#/components/schemas/ProductFormatOptionParams' additionalProperties: {} ProductFormatOptionParams: description: >- Canonical format params. For hosted video, carries accepted containers/codecs. type: object properties: containers: description: >- Accepted delivery containers for hosted video. A buyer should only send a creative whose container is listed here. example: - mp4 type: array items: type: string enum: - mp4 - webm - mov video_codecs: description: Accepted video codecs for hosted video. example: - h264 type: array items: type: string enum: - h264 - h265 - vp8 - vp9 - av1 - prores audio_codecs: description: Accepted audio codecs for hosted video. example: - aac type: array items: type: string enum: - aac - mp3 - opus - pcm additionalProperties: {} securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````