> ## 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. # Create storefront proposal > Save a discover-products response for a buyer (operator) and mint a shareable proposal_code. Buyers redeem the code on discover_products in a follow-up release. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml post /proposals openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: >- REST API for partners to manage Seller Accounts, inventory sources, and billing. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/storefront` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/storefront` 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/storefront description: Production server security: [] tags: - 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: Storefront description: Manage storefront and inventory sources - name: Storefront Agents description: List and manage registered sales, signals, and outcomes agents - name: Storefront Activity description: Audit log of configuration and inventory changes on the storefront - name: Storefront Billing description: Payout bank details and billing configuration for Seller Accounts - name: AI Usage description: Seller Account AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /proposals: post: tags: - Storefront Proposals summary: Create storefront proposal description: >- Save a discover-products response for a buyer (operator) and mint a shareable proposal_code. Buyers redeem the code on discover_products in a follow-up release. operationId: createStorefrontProposal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStorefrontProposalBody' responses: '201': description: Create storefront proposal content: application/json: schema: $ref: '#/components/schemas/StorefrontProposal' '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: CreateStorefrontProposalBody: type: object properties: operatorId: anyOf: - type: string minLength: 1 maxLength: 255 - $ref: '#/components/schemas/StorefrontProposalOperatorReference' description: >- Buyer identity for the proposal. Prefer { "domain": "brand.example" }. Legacy string values are accepted as domain strings, except customer: which is decoded as { customerId }. example: domain: acme.com label: type: string minLength: 1 maxLength: 255 description: Seller's internal label for the proposal example: Acme Q3 RFP — CTV notes: description: Free-form notes about the offline RFP type: string maxLength: 4000 expiresAt: 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))$ description: >- When the proposal code expires (ISO 8601). Server enforces this is no later than the underlying proposal.expiresAt. discoveryId: type: string minLength: 1 maxLength: 255 description: >- Discovery session id from a recent discover-products call. The server reads the cached snapshot for this session and persists it as the frozen offer. The session must have been scoped to this seller and restricted to its storefront sales agents. example: disc_a1b2c3 proposalId: type: string minLength: 1 maxLength: 255 description: >- Which proposal from the discovery snapshot to save with the proposal code. example: proposal_abc123 required: - operatorId - label - expiresAt - discoveryId - proposalId description: Request body for creating a storefront proposal StorefrontProposal: type: object properties: id: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Proposal row id proposalCode: type: string description: >- Short shareable handle. Sellers give this to buyers; buyers pass it to discover_products. example: PRP-XK4A29 operatorId: type: string description: >- Encoded buyer identity retained for backwards compatibility. Use operatorRef for the structured form. operatorRef: description: Structured buyer identity for redemption auth. allOf: - $ref: '#/components/schemas/StorefrontProposalOperatorReferenceOutput' label: type: string notes: nullable: true type: string status: type: string enum: - active - redeemed - expired - revoked description: >- Proposal lifecycle status. 'active': available to redeem. 'redeemed': buyer has applied it to a media buy. 'expired': past TTL. 'revoked': seller withdrew. expiresAt: 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))$ proposalId: type: string description: The protocol-level proposalId from the saved discovery snapshot discoverySessionId: type: string description: >- Discovery session id this proposal was captured from (for traceability) snapshot: description: The frozen products + proposals returned to the buyer on redemption allOf: - $ref: '#/components/schemas/ProposalSnapshot' createdAt: 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))$ createdBy: type: string firstViewedAt: nullable: true 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))$ lastViewedAt: nullable: true 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))$ redeemedAt: nullable: true 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))$ redeemedInMediaBuyId: nullable: true type: string required: - id - proposalCode - operatorId - operatorRef - label - notes - status - expiresAt - proposalId - discoverySessionId - snapshot - createdAt - createdBy - firstViewedAt - lastViewedAt - redeemedAt - redeemedInMediaBuyId additionalProperties: false description: A persisted storefront proposal 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 StorefrontProposalOperatorReference: anyOf: - type: object properties: domain: type: string minLength: 1 maxLength: 255 description: >- Buyer brand domain. The buyer must resolve to this brand domain when redeeming the proposal code. example: acme.com required: - domain - type: object properties: customerId: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: >- Buyer customer id fallback used only when the buyer does not have an advertiser brand domain. example: 123 required: - customerId description: >- Resolvable buyer identity for a storefront proposal. Prefer { domain } for brand-backed buyers; use { customerId } only as an unbranded fallback. StorefrontProposalOperatorReferenceOutput: anyOf: - type: object properties: domain: type: string minLength: 1 maxLength: 255 description: >- Buyer brand domain. The buyer must resolve to this brand domain when redeeming the proposal code. example: acme.com required: - domain additionalProperties: false - type: object properties: customerId: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: >- Buyer customer id fallback used only when the buyer does not have an advertiser brand domain. example: 123 required: - customerId additionalProperties: false description: >- Resolvable buyer identity for a storefront proposal. Prefer { domain } for brand-backed buyers; use { customerId } only as an unbranded fallback. ProposalSnapshot: type: object properties: products: type: array items: $ref: '#/components/schemas/Product' description: All products that were available in the discovery session proposals: type: array items: $ref: '#/components/schemas/Proposal' description: All proposals from the discovery session (including the chosen one) required: - products - proposals additionalProperties: false description: >- Frozen products + proposals captured from the discovery session at compose time 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: 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 (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 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) 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 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 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 ````