> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/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: default: 10 description: 'Maximum number of product groups to return (default: 10, max: 10)' example: 10 type: integer minimum: 0 exclusiveMinimum: true maximum: 10 description: 'Maximum number of product groups to return (default: 10, max: 10)' - in: query name: groupOffset schema: default: 0 description: Number of groups to skip for pagination example: 0 type: integer minimum: 0 maximum: 9007199254740991 description: Number of groups to skip for pagination - in: query name: productsPerGroup schema: default: 10 description: 'Maximum products to return per group (default: 10, max: 15)' example: 10 type: integer minimum: 0 exclusiveMinimum: true maximum: 15 description: 'Maximum products to return per group (default: 10, max: 15)' - in: query name: productOffset schema: default: 0 description: >- Number of products to skip within each group (default: 0, max: 1000) example: 5 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 - revenue_share - 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 minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 - 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: default: quick 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 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 minimum: 0 exclusiveMinimum: true maximum: 210 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: type: string minLength: 1 description: Discovery ID example: abc123-def456-ghi789 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: type: object properties: discoveryId: type: string description: Discovery ID example: abc123-def456-ghi789 productGroups: type: array items: $ref: '#/components/schemas/ProductGroup' description: Products grouped by publisher totalGroups: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of product groups available example: 25 hasMoreGroups: type: boolean description: Whether more groups are available beyond those shown 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, returned ADCP incomplete scopes, or had unsafe products withheld during host persistence. Present without debug=true and without raw agent or database 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 minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 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 description: Response from discovering products ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response ProductGroup: type: object properties: groupId: type: string description: Unique identifier for the product group groupName: type: string description: Name of the group (typically publisher name) storefrontId: description: Storefront ID when this is a storefront-backed group type: string storefrontName: type: string description: Storefront display name description: description: Description of the product group type: string products: type: array items: $ref: '#/components/schemas/Product' description: Products in this group productCount: type: integer minimum: 0 maximum: 9007199254740991 description: Number of products in this group totalProducts: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of products available in this group hasMoreProducts: type: boolean description: Whether more products are available beyond those returned required: - groupId - groupName - products - productCount - totalProducts - hasMoreProducts additionalProperties: false description: Group of products from a publisher DiscoverySummary: type: object properties: totalProducts: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of products in the discovery example: 150 publishersCount: type: integer minimum: 0 maximum: 9007199254740991 description: Number of unique publishers example: 25 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 description: Summary statistics for the discovery BudgetContextResponse: type: object properties: sessionBudget: nullable: true description: Total budget set for the session type: number allocatedBudget: type: number description: Budget allocated to selected products remainingBudget: nullable: true description: Remaining unallocated budget type: number budgetWarning: description: Warning message if budget allocation has issues type: string required: - sessionBudget - allocatedBudget - remainingBudget additionalProperties: false description: Budget allocation context Proposal: type: object properties: proposalId: type: string description: Unique identifier — used to refine or execute the proposal name: type: string description: Human-readable name for this media plan proposal 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: minItems: 1 type: array items: $ref: '#/components/schemas/ProductAllocation' description: Budget distribution across products — percentages sum to 100 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 description: >- A recommended media plan with budget allocations across products (ADCP v3) IncompleteDiscoveryAgent: 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: type: string enum: - timeout - upstream_incomplete - persistence_incomplete description: >- Why this agent result is incomplete. persistence_incomplete means unsafe products were withheld after the seller answered. responseTimeMs: description: >- Wall-clock response time in milliseconds, usually the requested wait window. type: integer minimum: 0 maximum: 9007199254740991 waitSeconds: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Wait window used for this attempt, in seconds. incompleteScopes: description: >- Incomplete product scopes. Seller-provided scopes use upstream_incomplete; host persistence withholding uses persistence_incomplete. type: array items: $ref: '#/components/schemas/IncompleteDiscoveryScope' required: - agentId - agentName - reason - waitSeconds additionalProperties: false description: >- Storefront agent whose result is incomplete because the call timed out, the seller returned ADCP incomplete scopes, or unsafe products were withheld during host persistence. Only timeout and upstream_incomplete can make a longer wait available. ConnectionIssue: type: object properties: providerType: type: string description: >- Adapter provider type whose OAuth connection needs re-authentication, e.g. "meta" or "snap". example: meta 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 description: >- An adapter connection that requires the buyer to re-authenticate before discovery can reach it. AgentDiscoveryResult: 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: type: boolean description: Whether the agent responded successfully productCount: type: integer minimum: 0 maximum: 9007199254740991 description: Number of products returned by the agent 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 description: >- Per-agent discovery result with optional debug info. Same structure as v1 media_product_discover debug output. RefinementApplied: 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: type: string enum: - applied - partial - unable description: >- 'applied': the ask was fulfilled. 'partial': partially fulfilled. 'unable': could not fulfill. notes: description: Seller explanation of the result type: string required: - status additionalProperties: false description: >- Seller's response to a refinement instruction, matched by position to the request's refine array PendingDiscoveryAgent: type: object properties: agentId: type: string description: Sales agent identifier agentName: type: string description: Sales agent display name 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 description: >- A seller still answering during a progressive discovery — it has not settled yet. DiscoveryDiagnostics: type: object properties: trace: description: Trace identifiers for auditing where discovery time was spent. allOf: - $ref: '#/components/schemas/DiscoveryTraceDiagnostics' additionalProperties: false description: Advanced support diagnostics returned only to elevated/admin contexts. ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object Product: type: object properties: productId: type: string description: >- Opaque product identifier. Pass this exact string back when selecting the product; do not rebuild or decode it. example: prod_123 name: type: string description: Product name example: Premium CTV Inventory - Sports 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 inventorySourceId: description: >- Non-null inventory-source provenance within the Storefront. The opaque productId carries the complete route, including Storefront-owned null identity. type: string pattern: ^[1-9]\d*$ storefrontName: type: string description: Storefront display name 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 (a selector for this discovery result; seller-authored identifiers are stable, while synthetic migrated_ identifiers may change on rediscovery), 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' supportedTargeting: description: >- Targeting dimensions this product accepts as an overlay (e.g. "geo_countries", "language", "device_type"). An empty array means the seller did not declare targeting support. Use this to avoid forwarding overlay dimensions the product cannot resolve. type: array items: type: string required: - productId - name additionalProperties: false description: Product resource for campaign inventory ProductAllocation: type: object properties: productId: type: string description: Product ID — references a product in the sibling products array allocationPercentage: type: number minimum: 0 maximum: 100 description: Percentage of total budget allocated to this product 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 description: Budget allocation for a product within a proposal IncompleteDiscoveryScope: type: object properties: scope: type: string enum: - products - pricing - forecast - proposals - wholesale_feed description: type: string maxLength: 500 description: >- Seller-provided explanation of what is missing or partial, capped at 500 characters. Untrusted agent-controlled content; sanitize before rendering in HTML. estimatedWaitSeconds: description: >- Estimated additional wait in seconds if the seller provided ADCP incomplete.estimated_wait. type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - scope - description additionalProperties: false description: >- A get_products scope the upstream seller could not fully complete within the requested time budget. AgentDebugLog: type: object properties: timestamp: type: string type: type: string message: type: string request: type: object additionalProperties: {} response: type: object additionalProperties: {} additionalProperties: false description: A single debug log entry from ADCP agent communication DiscoveryTraceDiagnostics: type: object properties: traceId: type: string description: OpenTelemetry trace ID for the discovery request/fan-out. example: 4bf92f3577b34da6a3ce929d0e0e4736 spanId: type: string description: >- OpenTelemetry span ID for the request span that initiated the discovery fan-out. example: 00f067aa0ba902b7 traceparent: type: string description: >- W3C traceparent value that can be pasted into internal tracing tools. example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 required: - traceId - spanId - traceparent additionalProperties: false description: Advanced support diagnostics for tracing a discovery fan-out. ProductCardData: type: object properties: image: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 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 synthetic_depiction: type: boolean 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 created_time: type: string 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 feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string 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 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 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: integer minimum: 1 maximum: 9007199254740991 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 additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string 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 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 description: Visual card data for rendering a product in UI ProductCardDetailedData: type: object properties: hero_image: type: object properties: asset_type: type: string enum: - image url: type: string width: type: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 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 synthetic_depiction: type: boolean 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 created_time: type: string 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 feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string 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 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 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: integer minimum: 1 maximum: 9007199254740991 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 additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string 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 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: integer minimum: 1 maximum: 9007199254740991 height: type: integer minimum: 1 maximum: 9007199254740991 file_size_bytes: type: integer minimum: 1 maximum: 9007199254740991 pixel_ratio: type: number minimum: 0 exclusiveMinimum: true state_id: type: string breakpoint_id: type: string focal_point: type: array items: anyOf: - type: number - type: number minItems: 2 maxItems: 2 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 synthetic_depiction: type: boolean 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 created_time: type: string 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 feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: type: string 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 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 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: integer minimum: 1 maximum: 9007199254740991 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 additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: type: string 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 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 description: Detailed inline product card data for buyer UIs PricingOptionData: type: object properties: pricingOptionId: type: string pricingModel: type: string isFixed: type: boolean rate: type: number floorPrice: type: number fixedPrice: type: number maxBid: type: boolean 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 description: Pricing option from a sales agent ProductFormatOption: type: object properties: format_kind: description: AdCP format kind discriminator (e.g. video_hosted, image) example: video_hosted type: string format_option_id: description: >- Identifier buyers use to select this format via format_option_refs in create_media_buy. Seller-authored identifiers are stable; synthetic migrated_ identifiers are scoped to the current discovery result. 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: {} description: AdCP 3.1 format declaration for a product ProductFormatOptionParams: 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: {} description: >- Canonical format params. For hosted video, carries accepted containers/codecs. securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````