> ## 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.

# Append a merchandising simulation revision

> Append a newly captured immutable revision without rewriting prior evidence. Each revision receives a no-override baseline and its own 30-day replay window.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml post /simulator/scenarios/{scenarioId}/revisions
openapi: 3.0.0
info:
  title: Scope3 Storefront API
  version: 2.0.0
  description: |-
    REST API for partners to manage storefronts, 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 storefronts
  - name: AI Usage
    description: Storefront AI token usage visibility by model
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /simulator/scenarios/{scenarioId}/revisions:
    post:
      tags:
        - Storefront
      summary: Append a merchandising simulation revision
      description: >-
        Append a newly captured immutable revision without rewriting prior
        evidence. Each revision receives a no-override baseline and its own
        30-day replay window.
      operationId: createMerchandisingSimulationRevision
      parameters:
        - in: path
          name: scenarioId
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 120
                source:
                  oneOf:
                    - type: object
                      properties:
                        sourceKind:
                          type: string
                          enum:
                            - sample
                        sourceRef:
                          type: string
                          minLength: 1
                          maxLength: 500
                      required:
                        - sourceKind
                        - sourceRef
                      additionalProperties: false
                    - type: object
                      properties:
                        sourceKind:
                          type: string
                          enum:
                            - live_observed
                        sourceRef:
                          type: string
                          pattern: ^\d+$
                      required:
                        - sourceKind
                        - sourceRef
                      additionalProperties: false
                    - type: object
                      properties:
                        sourceKind:
                          type: string
                          enum:
                            - seller_provided
                        sourceRef:
                          type: string
                          minLength: 1
                          maxLength: 500
                        brief:
                          type: string
                          minLength: 1
                          maxLength: 10000
                      required:
                        - sourceKind
                        - sourceRef
                        - brief
                      additionalProperties: false
                  type: object
              required:
                - title
                - source
              additionalProperties: false
      responses:
        '201':
          description: Append a merchandising simulation revision
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  scenarioId:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  revisionNumber:
                    type: integer
                    maximum: 9007199254740991
                    minimum: 1
                  title:
                    type: string
                  sourceKind:
                    type: string
                    enum:
                      - sample
                      - seller_provided
                      - live_observed
                  sourceRef:
                    type: string
                  briefSnapshot:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/MerchandisingSimulationJsonValue'
                  observedDecisionSnapshot:
                    nullable: true
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/MerchandisingSimulationJsonValue'
                  inputSummary:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/MerchandisingSimulationJsonValue'
                  inputDigest:
                    type: string
                    pattern: ^[a-f0-9]{64}$
                  schemaVersion:
                    type: integer
                    maximum: 9007199254740991
                    minimum: 1
                  runnableUntil:
                    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))$
                  isRunnable:
                    type: boolean
                  replayAvailableUntil:
                    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))$
                  variants:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        revisionId:
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        slotIndex:
                          type: integer
                          minimum: 0
                          maximum: 3
                        generation:
                          type: integer
                          maximum: 9007199254740991
                          minimum: 1
                        label:
                          type: string
                        isBaseline:
                          type: boolean
                        overrides:
                          anyOf:
                            - type: object
                              properties: {}
                              additionalProperties: false
                            - type: object
                              properties:
                                posture:
                                  type: object
                                  properties:
                                    selectedPosture:
                                      type: string
                                      enum:
                                        - direct_fit
                                        - hold_value
                                        - value_preserving_compromise
                                        - tradeoff_ladder
                                        - price_first
                                        - wholesale_mirror
                                  required:
                                    - selectedPosture
                                  additionalProperties: false
                                pricing:
                                  type: object
                                  properties:
                                    priceAdjustmentBasisPoints:
                                      type: integer
                                      minimum: -10000
                                      maximum: 100000
                                    floorCpm:
                                      type: object
                                      properties:
                                        amount:
                                          type: number
                                          minimum: 0
                                        currency:
                                          type: string
                                          minLength: 3
                                          maxLength: 3
                                      required:
                                        - amount
                                        - currency
                                      additionalProperties: false
                                  additionalProperties: false
                                rules:
                                  type: object
                                  properties:
                                    requiredBundleIds:
                                      maxItems: 100
                                      type: array
                                      items:
                                        type: string
                                        minLength: 1
                                    excludedBundleIds:
                                      maxItems: 100
                                      type: array
                                      items:
                                        type: string
                                        minLength: 1
                                    maxProducts:
                                      type: integer
                                      minimum: 1
                                      maximum: 100
                                  additionalProperties: false
                              additionalProperties: false
                        overrideDigest:
                          type: string
                          pattern: ^[a-f0-9]{64}$
                        supersedesVariantId:
                          nullable: true
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        createdByUserId:
                          nullable: true
                          type: string
                        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))$
                        executions:
                          default: []
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              revisionId:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              variantId:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              intelligenceRunId:
                                type: string
                              attemptNumber:
                                type: integer
                                maximum: 9007199254740991
                                minimum: 1
                              status:
                                type: string
                                enum:
                                  - succeeded
                                  - failed
                              resultCode:
                                nullable: true
                                type: string
                              inputDigest:
                                type: string
                                pattern: ^[a-f0-9]{64}$
                              overrideDigest:
                                type: string
                                pattern: ^[a-f0-9]{64}$
                              outputDigest:
                                type: string
                                pattern: ^[a-f0-9]{64}$
                              decisionRecord:
                                $ref: '#/components/schemas/SellerDecisionRecord'
                              createdByUserId:
                                nullable: true
                                type: string
                              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))$
                            required:
                              - id
                              - revisionId
                              - variantId
                              - intelligenceRunId
                              - attemptNumber
                              - status
                              - resultCode
                              - inputDigest
                              - overrideDigest
                              - outputDigest
                              - decisionRecord
                              - createdByUserId
                              - createdAt
                            additionalProperties: false
                        executionHistory:
                          default: []
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              revisionId:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              variantId:
                                type: string
                                format: uuid
                                pattern: >-
                                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              intelligenceRunId:
                                type: string
                              attemptNumber:
                                type: integer
                                maximum: 9007199254740991
                                minimum: 1
                              status:
                                type: string
                                enum:
                                  - succeeded
                                  - failed
                              resultCode:
                                nullable: true
                                type: string
                              inputDigest:
                                type: string
                                pattern: ^[a-f0-9]{64}$
                              overrideDigest:
                                type: string
                                pattern: ^[a-f0-9]{64}$
                              outputDigest:
                                type: string
                                pattern: ^[a-f0-9]{64}$
                              createdByUserId:
                                nullable: true
                                type: string
                              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))$
                            required:
                              - id
                              - revisionId
                              - variantId
                              - intelligenceRunId
                              - attemptNumber
                              - status
                              - resultCode
                              - inputDigest
                              - overrideDigest
                              - outputDigest
                              - createdByUserId
                              - createdAt
                            additionalProperties: false
                      required:
                        - id
                        - revisionId
                        - slotIndex
                        - generation
                        - label
                        - isBaseline
                        - overrides
                        - overrideDigest
                        - supersedesVariantId
                        - createdByUserId
                        - createdAt
                        - executions
                        - executionHistory
                      additionalProperties: false
                  createdByUserId:
                    nullable: true
                    type: string
                  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))$
                required:
                  - id
                  - scenarioId
                  - revisionNumber
                  - title
                  - sourceKind
                  - sourceRef
                  - briefSnapshot
                  - observedDecisionSnapshot
                  - inputSummary
                  - inputDigest
                  - schemaVersion
                  - runnableUntil
                  - isRunnable
                  - replayAvailableUntil
                  - variants
                  - createdByUserId
                  - createdAt
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No scenario with this id on the caller’s Storefront.
          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:
    MerchandisingSimulationJsonValue:
      description: Any JSON value captured verbatim in simulation evidence.
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: string
          nullable: true
          enum:
            - null
        - type: array
          items:
            $ref: '#/components/schemas/MerchandisingSimulationJsonValue'
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/MerchandisingSimulationJsonValue'
    SellerDecisionRecord:
      description: >-
        Canonical seller-readable decision record projected from one storefront
        intelligence run and its attributed approval/commercial evidence.
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - pending
            - responded
            - declined
            - failed
            - booked
            - delivered
            - rejected
            - unattributed
        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))$
        purpose:
          type: object
          properties:
            availability:
              type: string
              enum:
                - recorded
                - unavailable
            value:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/IntelligenceRunPurpose'
          required:
            - availability
            - value
          additionalProperties: false
        buyer:
          type: object
          properties:
            operatorDomain:
              nullable: true
              type: string
            brandDomain:
              nullable: true
              type: string
            country:
              nullable: true
              type: string
            customerId:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
          required:
            - operatorDomain
            - brandDomain
            - country
            - customerId
          additionalProperties: false
        ask:
          type: object
          properties:
            brief:
              nullable: true
              type: string
            buyingMode:
              type: string
            requestAsks:
              type: array
              items:
                type: string
            inputSnapshotAvailability:
              type: string
              enum:
                - recorded
                - unavailable
          required:
            - brief
            - buyingMode
            - requestAsks
            - inputSnapshotAvailability
          additionalProperties: false
        fit:
          type: object
          properties:
            disposition:
              nullable: true
              type: string
              enum:
                - responded
                - declined_fit
                - declined_policy
                - not_live
            qualified:
              nullable: true
              type: boolean
            reasonAxis:
              nullable: true
              type: string
              enum:
                - fit
                - policy
            reason:
              nullable: true
              type: string
            matchedProducts:
              type: array
              items:
                $ref: '#/components/schemas/IntelligenceRunProductExplanation'
            unavailableProducts:
              type: array
              items:
                $ref: '#/components/schemas/IntelligenceRunUnpricedProductExplanation'
          required:
            - disposition
            - qualified
            - reasonAxis
            - reason
            - matchedProducts
            - unavailableProducts
          additionalProperties: false
        posture:
          type: object
          properties:
            recommended:
              nullable: true
              type: string
              enum:
                - direct_fit
                - hold_value
                - value_preserving_compromise
                - tradeoff_ladder
                - price_first
                - wholesale_mirror
            selected:
              nullable: true
              type: string
              enum:
                - direct_fit
                - hold_value
                - value_preserving_compromise
                - tradeoff_ladder
                - price_first
                - wholesale_mirror
            rationale:
              nullable: true
              type: string
            intensity:
              nullable: true
              type: string
              enum:
                - low
                - medium
                - high
            signals:
              type: array
              items:
                type: string
            guidance:
              type: array
              items:
                type: string
            matchedPricingFactIds:
              type: array
              items:
                type: string
            operatingInstructionsVersion:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            matchedBuyerInstructionIds:
              type: array
              items:
                type: string
            override:
              type: object
              properties:
                availability:
                  type: string
                  enum:
                    - recorded
                    - unavailable
                actor:
                  nullable: true
                  type: string
              required:
                - availability
                - actor
              additionalProperties: false
            acceptancePolicyVersion:
              type: object
              properties:
                availability:
                  type: string
                  enum:
                    - recorded
                    - unavailable
                value:
                  nullable: true
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
              required:
                - availability
                - value
              additionalProperties: false
          required:
            - recommended
            - selected
            - rationale
            - intensity
            - signals
            - guidance
            - matchedPricingFactIds
            - operatingInstructionsVersion
            - matchedBuyerInstructionIds
            - override
            - acceptancePolicyVersion
          additionalProperties: false
        response:
          type: object
          properties:
            status:
              type: string
              enum:
                - responded
                - withheld
                - failed
                - unavailable
            summary:
              type: string
            exactSentState:
              type: object
              properties:
                availability:
                  type: string
                  enum:
                    - recorded
                    - unavailable
                productCount:
                  nullable: true
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                proposalHistoryAvailability:
                  type: string
                  enum:
                    - recorded
                    - unavailable
              required:
                - availability
                - productCount
                - proposalHistoryAvailability
              additionalProperties: false
            negotiationChanges:
              type: object
              properties:
                requestAsks:
                  type: array
                  items:
                    type: string
                refinementApplied:
                  nullable: true
              required:
                - requestAsks
                - refinementApplied
              additionalProperties: false
          required:
            - status
            - summary
            - exactSentState
            - negotiationChanges
          additionalProperties: false
        approval:
          type: object
          properties:
            availability:
              type: string
              enum:
                - recorded
                - unavailable
            id:
              nullable: true
              type: string
            status:
              nullable: true
              type: string
              enum:
                - pending
                - approved
                - rejected
                - revoked
            reviewedBy:
              nullable: true
              type: string
            reviewedAt:
              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))$
            reviewerNotes:
              nullable: true
              type: string
            forwardedAt:
              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))$
          required:
            - availability
            - id
            - status
            - reviewedBy
            - reviewedAt
            - reviewerNotes
            - forwardedAt
          additionalProperties: false
        outcome:
          type: object
          properties:
            state:
              type: string
              enum:
                - pending
                - booked
                - delivered
                - rejected
                - failed
                - unattributed
                - unavailable
            eventType:
              nullable: true
              type: string
            eventAt:
              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))$
            mediaBuyId:
              nullable: true
              type: string
            mediaBuyStatus:
              nullable: true
              type: string
            pendingApprovalId:
              nullable: true
              type: string
            bookedBudget:
              nullable: true
              type: number
            deliveredImpressions:
              nullable: true
              type: number
            deliveredSpend:
              nullable: true
              type: number
            deliveredCurrency:
              nullable: true
              type: string
            attribution:
              type: object
              properties:
                availability:
                  type: string
                  enum:
                    - recorded
                    - unavailable
                model:
                  nullable: true
                  type: string
                matchedRunId:
                  nullable: true
                  type: string
                matchedProductIds:
                  type: array
                  items:
                    type: string
              required:
                - availability
                - model
                - matchedRunId
                - matchedProductIds
              additionalProperties: false
          required:
            - state
            - eventType
            - eventAt
            - mediaBuyId
            - mediaBuyStatus
            - pendingApprovalId
            - bookedBudget
            - deliveredImpressions
            - deliveredSpend
            - deliveredCurrency
            - attribution
          additionalProperties: false
        learning:
          type: object
          properties:
            analyticsEligibility:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - eligible
                    - ineligible
                    - unavailable
                reason:
                  type: string
              required:
                - status
                - reason
              additionalProperties: false
            postureContribution:
              type: object
              properties:
                availability:
                  type: string
                  enum:
                    - recorded
                    - unavailable
                selected:
                  nullable: true
                  type: string
                  enum:
                    - direct_fit
                    - hold_value
                    - value_preserving_compromise
                    - tradeoff_ladder
                    - price_first
                    - wholesale_mirror
                recommended:
                  nullable: true
                  type: string
                  enum:
                    - direct_fit
                    - hold_value
                    - value_preserving_compromise
                    - tradeoff_ladder
                    - price_first
                    - wholesale_mirror
              required:
                - availability
                - selected
                - recommended
              additionalProperties: false
            recommendationLineage:
              type: object
              properties:
                availability:
                  type: string
                  enum:
                    - recorded
                    - unavailable
              required:
                - availability
              additionalProperties: false
          required:
            - analyticsEligibility
            - postureContribution
            - recommendationLineage
          additionalProperties: false
        provenance:
          type: object
          properties:
            modelProvider:
              nullable: true
              type: string
            modelName:
              type: string
            operatingInstructionsVersion:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            durationMs:
              nullable: true
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
          required:
            - modelProvider
            - modelName
            - operatingInstructionsVersion
            - durationMs
          additionalProperties: false
      required:
        - id
        - status
        - createdAt
        - purpose
        - buyer
        - ask
        - fit
        - posture
        - response
        - approval
        - outcome
        - learning
        - provenance
      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
    IntelligenceRunPurpose:
      description: >-
        Trusted execution classification. Null is reserved for historical runs
        recorded before purpose was required.
      type: string
      enum:
        - live
        - setup_test
        - simulation
        - probe
        - evaluation
    IntelligenceRunProductExplanation:
      description: >-
        Buyer-safe explanation of one product selected for the storefront
        response.
      type: object
      properties:
        productId:
          nullable: true
          type: string
        name:
          nullable: true
          type: string
        description:
          nullable: true
          type: string
        reasoning:
          nullable: true
          type: string
        pricing:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/IntelligenceRunProductPricingExplanation'
        bundleIds:
          type: array
          items:
            type: string
        signalIds:
          type: array
          items:
            type: string
        formatIds:
          type: array
          items:
            $ref: '#/components/schemas/IntelligenceRunProductFormatExplanation'
      required:
        - productId
        - name
        - description
        - reasoning
        - pricing
        - bundleIds
        - signalIds
        - formatIds
      additionalProperties: false
    IntelligenceRunUnpricedProductExplanation:
      description: >-
        Composition the model considered but the platform omitted because it
        could not be priced authoritatively.
      type: object
      properties:
        name:
          nullable: true
          type: string
        reasoning:
          nullable: true
          type: string
        reason:
          type: string
        bundleIds:
          type: array
          items:
            type: string
        signalIds:
          type: array
          items:
            type: string
      required:
        - name
        - reasoning
        - reason
        - bundleIds
        - signalIds
      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
    IntelligenceRunProductPricingExplanation:
      description: Server-computed CPM pricing summary for a selected composition.
      type: object
      properties:
        baseCpm:
          nullable: true
          type: number
        currency:
          nullable: true
          type: string
        operatorDiscount:
          nullable: true
          type: number
        finalCpm:
          nullable: true
          type: number
      required:
        - baseCpm
        - currency
        - operatorDiscount
        - finalCpm
      additionalProperties: false
    IntelligenceRunProductFormatExplanation:
      description: Creative format selected for an explained product.
      type: object
      properties:
        agentUrl:
          nullable: true
          type: string
        id:
          nullable: true
          type: string
      required:
        - agentUrl
        - id
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````