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

# Get storefront readiness

> Check if the storefront is ready to go live. Returns blocking checks for inventory sources, agent status, and agent auth.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml get /readiness
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:
  /readiness:
    get:
      tags:
        - Storefront
      summary: Get storefront readiness
      description: >-
        Check if the storefront is ready to go live. Returns blocking checks for
        inventory sources, agent status, and agent auth.
      operationId: getStorefrontReadiness
      responses:
        '200':
          description: Get storefront readiness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontReadinessResponse'
        '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:
    StorefrontReadinessResponse:
      description: Storefront readiness assessment
      type: object
      properties:
        platformId:
          type: string
        status:
          description: Overall storefront readiness status
          type: string
          enum:
            - ready
            - blocked
        isPaused:
          description: >-
            Compatibility-named seller intake hold. True blocks discovery, new
            buys, and buyer edits but does not pause existing delivery. False is
            neutral and does not itself imply readiness.
          type: boolean
        canTransact:
          description: >-
            Canonical effective availability: non-paused, non-archived, and
            every current blocker complete.
          type: boolean
        effectiveStatus:
          description: >-
            Derived storefront status. Never stored and never copied from
            adcp_agent.status.
          type: string
          enum:
            - archived
            - paused
            - blocked
            - live
        availabilityGuidance:
          description: >-
            Canonical explanation for a top-level paused or archived admission
            control. Check-specific blockers remain in checks[].guidance.
          allOf:
            - $ref: '#/components/schemas/ReadinessBlockingGuidance'
        checks:
          type: array
          items:
            $ref: '#/components/schemas/ReadinessCheck'
        publisherDomains:
          description: >-
            Configured publisher domains with current authorization and
            property-resolution status.
          type: array
          items:
            $ref: '#/components/schemas/StorefrontPublisherDomainReadiness'
        demandCoverage:
          $ref: '#/components/schemas/DemandCoverageSummary'
        sourceDiagnostics:
          type: array
          items:
            $ref: '#/components/schemas/SourceDiagnostics'
        diagnoses:
          description: >-
            Typed source-health diagnoses. Only `seller`-owned entries are
            tasks; `scope3`/`vendor`-owned entries are informational and never
            block readiness.
          type: array
          items:
            $ref: '#/components/schemas/SourceHealthDiagnosis'
        phase:
          $ref: '#/components/schemas/OnboardingPhase'
        onboardingPlan:
          description: >-
            The persisted onboarding plan (target model + phase-transition
            history), loaded and reconciled on this read.
          nullable: true
          allOf:
            - $ref: '#/components/schemas/StorefrontOnboardingPlan'
        liveness:
          description: >-
            The projected storefront liveness verdict (AI-4698) — one derived
            status over settlement invariants, go-live blockers, post-live
            degradation, and multi-source/mode honesty. Authoritative for every
            surface (seller-setup widget, storefront switcher) when present.
          allOf:
            - $ref: '#/components/schemas/StorefrontLiveness'
      required:
        - platformId
        - status
        - isPaused
        - canTransact
        - effectiveStatus
        - checks
        - publisherDomains
        - demandCoverage
        - sourceDiagnostics
        - diagnoses
        - phase
      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
    ReadinessBlockingGuidance:
      description: >-
        Canonical cause, buyer-path effect, evidence, and resolution for an
        incomplete hard readiness requirement.
      type: object
      properties:
        coverage:
          description: >-
            `complete` when the canonical readiness catalog owns a resolution;
            `missing` makes an unregistered future blocker explicit.
          type: string
          enum:
            - complete
            - missing
        stage:
          description: >-
            The blocker stops buyer-serving work at storefront transaction
            admission, before an inventory source receives `get_products`.
          type: string
          enum:
            - before_source_dispatch
        why:
          description: Current cause, using the check's live evidence.
          type: string
        effect:
          description: >-
            Buyer-path consequence. Consumers render this instead of inferring
            demand from source call counts.
          type: string
        fix:
          description: Smallest honest action that clears the blocker.
          type: string
        subjects:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum:
                  - inventory_source
              id:
                nullable: true
                type: string
              name:
                type: string
            required:
              - kind
              - id
              - name
            additionalProperties: false
        evidence:
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - billing_compatibility
                requiredSupportedBilling:
                  type: string
                  enum:
                    - agent
                incompatibleSources:
                  type: array
                  items:
                    type: object
                    properties:
                      sourceId:
                        nullable: true
                        type: string
                      sourceName:
                        type: string
                      advertisedSupportedBillings:
                        type: array
                        items:
                          type: string
                    required:
                      - sourceId
                      - sourceName
                      - advertisedSupportedBillings
                    additionalProperties: false
              required:
                - kind
                - requiredSupportedBilling
                - incompatibleSources
              additionalProperties: false
          type: object
      required:
        - coverage
        - stage
        - why
        - effect
        - fix
        - subjects
      additionalProperties: false
    ReadinessCheck:
      description: Individual readiness check result
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        category:
          type: string
        status:
          description: >-
            Status of a readiness check. `optional` is reserved for checks that
            are explicitly skipped (e.g. billing in non-production environments)
            — they are not required before the storefront can start transacting.
          type: string
          enum:
            - complete
            - partial
            - missing
            - optional
        isBlocker:
          type: boolean
        method:
          type: string
        details:
          type: string
        action:
          description: >-
            Where this step resolves. Absent → the widget falls back to its own
            routing for the check id.
          type: string
          enum:
            - inline_currency
            - inline_operator_domain
            - link
            - policy
            - open
            - chat
            - recheck
        actionLabel:
          description: >-
            Outcome-named action label for this step (e.g. "Connect ad server",
            "Set currency") — names the task, not the tool. Absent → the widget
            derives a label from the check name.
          type: string
        actionUrl:
          description: >-
            Absolute application destination for a `link` action. Server-owned
            so every MCP Apps host executes the same destination without a model
            prompt.
          type: string
          format: uri
        actionValue:
          description: >-
            Current value used to seed an inline action control, when
            applicable.
          type: string
        compliance:
          description: Per-agent compliance results (present on agent_connectivity checks)
          type: array
          items:
            $ref: '#/components/schemas/AgentComplianceResult'
        requirement:
          description: >-
            Requirement classification for this storefront's current selling
            path. 'hard': must be resolved before the storefront can go live.
            'soft': advisory — improves outcomes but never blocks.
            'platform_default': the platform applied a sensible default (named
            in appliedDefault) that the seller can change later. The server
            always sets this; optional only for payload compatibility.
          type: string
          enum:
            - hard
            - soft
            - platform_default
        appliedDefault:
          description: >-
            For 'platform_default' checks: the default the platform applied,
            stated in seller terms, and how to change it.
          type: string
        guidance:
          description: >-
            Present on every incomplete hard requirement. Omitted for complete
            or non-blocking checks.
          allOf:
            - $ref: '#/components/schemas/ReadinessBlockingGuidance'
      required:
        - id
        - name
        - description
        - category
        - status
        - isBlocker
      additionalProperties: false
    StorefrontPublisherDomainReadiness:
      description: >-
        One configured publisher domain with its latest AAO/adagents.json
        authorization and managed-sales-agent synchronization evidence.
      type: object
      properties:
        publisherDomain:
          type: string
        status:
          description: >-
            Seller-facing publisher-domain readiness. `pending` has not
            completed a resolution, `authorized` has current positive
            authorization evidence, `unauthorized` is a confident negative,
            `unknown` has no conclusive authorization evidence, and `error`
            means the latest adagents.json resolution failed.
          type: string
          enum:
            - pending
            - authorized
            - unauthorized
            - unknown
            - error
        adagentsStatus:
          nullable: true
          type: string
          enum:
            - resolved
            - no_adagents
            - invalid
            - error
            - pending
        authorizationStatus:
          nullable: true
          type: string
          enum:
            - authorized
            - unauthorized
            - unknown
        authorizationReason:
          nullable: true
          type: string
          enum:
            - no_file
            - file_invalid
            - agent_not_listed
            - agent_untyped
            - agent_not_property_bound
            - authorized
        resolvedPropertyCount:
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
        lastSyncedAt:
          nullable: true
          type: string
        lastPushedAt:
          nullable: true
          type: string
      required:
        - publisherDomain
        - status
        - adagentsStatus
        - authorizationStatus
        - authorizationReason
        - resolvedPropertyCount
        - lastSyncedAt
        - lastPushedAt
      additionalProperties: false
    DemandCoverageSummary:
      description: >-
        Seller-side starter-brief coverage derived from profile, markets,
        channels, and product evidence.
      type: object
      properties:
        eligibleCombinations:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        coveredCombinations:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        categories:
          type: array
          items:
            type: string
        markets:
          type: array
          items:
            type: string
        channels:
          type: array
          items:
            type: string
        missingDimensions:
          type: array
          items:
            description: >-
              Demand-coverage dimension still needed before starter briefs can
              map cleanly to this storefront.
            type: string
            enum:
              - category
              - market
              - channel
              - inventory
        sampleBriefs:
          type: array
          items:
            $ref: '#/components/schemas/DemandCoverageSampleBrief'
      required:
        - eligibleCombinations
        - coveredCombinations
        - categories
        - markets
        - channels
        - missingDimensions
        - sampleBriefs
      additionalProperties: false
    SourceDiagnostics:
      description: Per-inventory-source diagnostics for storefront setup and onboarding
      type: object
      properties:
        id:
          nullable: true
          type: string
        sourceId:
          nullable: true
          type: string
        name:
          type: string
        executionType:
          description: >-
            What backs this private upstream inventory source. `AGENT` is an
            external AdCP-compatible sales agent the Merchandising Agent
            connects to; `MANAGED_SALES_AGENT` is an operator-owned ad server
            with Interchange-managed sales-agent plumbing behind it;
            `LINKED_STOREFRONT` is wholesale inventory discovered automatically
            from the ambient pool of LISTED storefronts whose computed
            `canTransact` projection is true (resolved at runtime, never
            persisted as a source row); `MODULAR_SOURCE` is a composed inventory
            source assembled from private modules such as avails, booking,
            trafficking, and reporting. Storefront-level `ADAPTER` dispatch is
            configured on the storefront, not as an inventory source.
          type: string
          enum:
            - AGENT
            - MANAGED_SALES_AGENT
            - LINKED_STOREFRONT
            - MODULAR_SOURCE
        setupKind:
          description: >-
            Operator-facing setup family when it differs from the internal
            execution type. Clients fall back to executionType when omitted.
          type: string
          enum:
            - ad_server
            - modular
            - external_agent
        detailAction:
          description: >-
            Authorized portable specialist destination for this exact source.
            Omitted when no exact destination is exposed.
          allOf:
            - $ref: '#/components/schemas/SourceDetailAction'
        catalogMappingReadiness:
          description: >-
            Canonical Modular Source catalog progress and next action, reused
            without client-side re-derivation.
          type: object
          properties:
            progress:
              type: object
              properties:
                ready:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                applicable:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                percent:
                  type: integer
                  minimum: 0
                  maximum: 100
              required:
                - ready
                - applicable
                - percent
              additionalProperties: false
            nextAction:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/CatalogMappingAction'
          required:
            - progress
            - nextAction
          additionalProperties: false
        cardPosture:
          $ref: '#/components/schemas/SourceCardPosture'
        sourceStatus:
          description: Inventory source lifecycle status
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
        agentId:
          nullable: true
          type: string
        agentStatus:
          deprecated: true
          description: >-
            Deprecated compatibility projection of sourceStatus for
            external-agent sources. It is not an independent lifecycle signal;
            use sourceStatus.
          nullable: true
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
        endpointUrl:
          nullable: true
          type: string
        protocol:
          nullable: true
          type: string
          enum:
            - MCP
            - A2A
        auth:
          type: object
          properties:
            required:
              type: boolean
            configured:
              type: boolean
            type:
              nullable: true
              type: string
          required:
            - required
            - configured
            - type
          additionalProperties: false
        capabilities:
          type: object
          properties:
            products:
              type: string
              enum:
                - supported
                - unsupported
                - unknown
            createMediaBuy:
              type: string
              enum:
                - supported
                - unsupported
                - unknown
            updateMediaBuy:
              type: string
              enum:
                - supported
                - unsupported
                - unknown
            signals:
              type: string
              enum:
                - supported
                - unsupported
                - unknown
            wholesaleProducts:
              type: string
              enum:
                - supported
                - unsupported
                - unknown
          required:
            - products
            - createMediaBuy
            - updateMediaBuy
            - signals
            - wholesaleProducts
          additionalProperties: false
        productBuilder:
          nullable: true
          type: object
          properties:
            mode:
              type: string
              enum:
                - composition
                - passthrough
                - unknown
            wholesaleProductCount:
              nullable: true
              type: number
            buyerVisibleProductCount:
              nullable: true
              type: number
            currencyMismatchProductCount:
              description: >-
                Of the authored products hidden from buyers, how many are hidden
                only because their operator fixed price is in a different
                currency than the storefront's settlement currency. null when
                the pantry audit did not run.
              nullable: true
              type: number
            reportingStaleProductCount:
              description: >-
                Of the authored products hidden from buyers, how many are hidden
                only because their ad-server-reporting-derived pricing aged past
                the freshness ceiling (60 days without a successful catalog
                refresh). null when the pantry audit did not run.
              nullable: true
              type: number
            signalCount:
              nullable: true
              type: number
            catalogCacheCold:
              type: boolean
            declaredUnsupportedIngredients:
              type: boolean
          required:
            - mode
            - wholesaleProductCount
            - buyerVisibleProductCount
            - currencyMismatchProductCount
            - reportingStaleProductCount
            - signalCount
            - catalogCacheCold
            - declaredUnsupportedIngredients
          additionalProperties: false
        compliance:
          nullable: true
          type: object
          properties:
            passed:
              type: boolean
            summary:
              type: string
            checkedAt:
              nullable: true
              type: string
            trackCounts:
              type: object
              properties:
                total:
                  type: number
                passing:
                  type: number
                partial:
                  type: number
                failing:
                  type: number
              required:
                - total
                - passing
                - partial
                - failing
              additionalProperties: false
          required:
            - passed
            - summary
            - checkedAt
            - trackCounts
          additionalProperties: false
        debug:
          type: object
          properties:
            version:
              nullable: true
              type: string
            syntheticCapabilities:
              nullable: true
              type: boolean
            tools:
              type: array
              items:
                type: string
            supportedBillings:
              type: array
              items:
                type: string
            channels:
              type: array
              items:
                type: string
            countries:
              type: array
              items:
                type: string
            publisherDomains:
              type: array
              items:
                type: string
            requireOperatorAuth:
              nullable: true
              type: boolean
          required:
            - version
            - syntheticCapabilities
            - tools
            - supportedBillings
            - channels
            - countries
            - publisherDomains
            - requireOperatorAuth
          additionalProperties: false
        lastActivity:
          nullable: true
          type: object
          properties:
            action:
              type: string
            resourceType:
              type: string
            resourceId:
              nullable: true
              type: string
            resourceName:
              nullable: true
              type: string
            description:
              type: string
            timestamp:
              type: string
          required:
            - action
            - resourceType
            - resourceId
            - resourceName
            - description
            - timestamp
          additionalProperties: false
        health:
          type: object
          properties:
            status:
              type: string
              enum:
                - healthy
                - degraded
                - unhealthy
                - unknown
            lastError:
              nullable: true
              type: string
            lastErrorCode:
              nullable: true
              type: string
            lastErrorAt:
              nullable: true
              type: string
            lastSuccessAt:
              nullable: true
              type: string
            lastCheckedAt:
              nullable: true
              type: string
          required:
            - status
            - lastError
            - lastErrorCode
            - lastErrorAt
            - lastSuccessAt
            - lastCheckedAt
          additionalProperties: false
        capabilityHealth:
          type: object
          properties:
            inventory:
              type: object
              properties:
                status:
                  nullable: true
                  type: string
                  enum:
                    - healthy
                    - degraded
                    - unhealthy
                observations:
                  type: array
                  items:
                    type: object
                    properties:
                      observer:
                        type: string
                      status:
                        type: string
                        enum:
                          - healthy
                          - degraded
                          - unhealthy
                      previousStatus:
                        nullable: true
                        type: string
                        enum:
                          - healthy
                          - degraded
                          - unhealthy
                      cause:
                        nullable: true
                        type: string
                      detail:
                        nullable: true
                        type: string
                      owner:
                        nullable: true
                        type: string
                      observedAt:
                        type: string
                      lastOkAt:
                        nullable: true
                        type: string
                    required:
                      - observer
                      - status
                      - previousStatus
                      - cause
                      - detail
                      - owner
                      - observedAt
                      - lastOkAt
                    additionalProperties: false
              required:
                - status
                - observations
              additionalProperties: false
            reporting:
              type: object
              properties:
                status:
                  nullable: true
                  type: string
                  enum:
                    - healthy
                    - degraded
                    - unhealthy
                observations:
                  type: array
                  items:
                    type: object
                    properties:
                      observer:
                        type: string
                      status:
                        type: string
                        enum:
                          - healthy
                          - degraded
                          - unhealthy
                      previousStatus:
                        nullable: true
                        type: string
                        enum:
                          - healthy
                          - degraded
                          - unhealthy
                      cause:
                        nullable: true
                        type: string
                      detail:
                        nullable: true
                        type: string
                      owner:
                        nullable: true
                        type: string
                      observedAt:
                        type: string
                      lastOkAt:
                        nullable: true
                        type: string
                    required:
                      - observer
                      - status
                      - previousStatus
                      - cause
                      - detail
                      - owner
                      - observedAt
                      - lastOkAt
                    additionalProperties: false
              required:
                - status
                - observations
              additionalProperties: false
          required:
            - inventory
            - reporting
          additionalProperties: false
      required:
        - id
        - sourceId
        - name
        - executionType
        - cardPosture
        - sourceStatus
        - agentId
        - agentStatus
        - endpointUrl
        - protocol
        - auth
        - capabilities
        - productBuilder
        - compliance
        - debug
        - lastActivity
        - health
        - capabilityHealth
      additionalProperties: false
    SourceHealthDiagnosis:
      description: >-
        One typed source-health diagnosis: what failed, who owns the fix, how
        much it matters to this storefront, and the inline action.
      type: object
      properties:
        diagnosisId:
          description: >-
            Stable within a storefront: "<sourceId or
            storefront>:<failureMode>".
          type: string
        sourceId:
          description: >-
            Inventory source this diagnosis is about; null for storefront-level
            problems (e.g. the ad server source connection).
          nullable: true
          type: string
        sourceName:
          type: string
        failureMode:
          description: Typed failure mode from the source-diagnosis catalog.
          type: string
          enum:
            - catalog_products_stale
            - catalog_products_empty
            - catalog_products_hidden
            - catalog_signals_stale
            - catalog_fetch_error
            - adapter_credentials_invalid
            - ad_server_sync_failed
            - reporting_access_missing
            - forecasting_access_missing
            - source_unreachable
            - source_degraded
            - reporting_unreachable
            - reporting_payload_rejected
            - agent_auth_missing
            - trafficking_error
            - wholesale_pricing_stale
            - media_buy_status_stale
        owner:
          description: >-
            Who owns the fix. Only `seller`-owned diagnoses may become a task, a
            blocker, or a notification; `scope3`/`vendor` diagnoses render as
            passive status lines and route internally.
          type: string
          enum:
            - seller
            - scope3
            - vendor
        severity:
          description: >-
            Impact on THIS storefront, never the failure mechanism: `blocking`
            stops selling/setup, `attention` degrades it, `advisory` will only
            matter later.
          type: string
          enum:
            - blocking
            - attention
            - advisory
        summary:
          description: >-
            Customer-safe, one sentence: what is wrong and why it matters to the
            seller.
          type: string
        detail:
          description: >-
            Customer-safe evidence: counts, ages, codes. Null when nothing
            useful.
          nullable: true
          type: string
        action:
          $ref: '#/components/schemas/DiagnosisAction'
        docsAnchor:
          description: mintlify troubleshooting anchor, when one exists.
          nullable: true
          type: string
        observedAt:
          type: string
      required:
        - diagnosisId
        - sourceId
        - sourceName
        - failureMode
        - owner
        - severity
        - summary
        - detail
        - action
        - docsAnchor
        - observedAt
      additionalProperties: false
    OnboardingPhase:
      description: >-
        Seller onboarding phase, derived live from setup-mode + readiness:
        `pass_through` (a finished-products sales agent — no rungs) or the Crawl
        → Walk → Run progression for composition storefronts. Orients the seller
        ("you are in Phase 1 of 3").
      type: string
      enum:
        - pass_through
        - crawl
        - walk
        - run
    StorefrontOnboardingPlan:
      description: >-
        Durable per-storefront onboarding plan: target model + step-completion +
        phase-transition history.
      type: object
      properties:
        version:
          description: Plan document schema version, for forward migration.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        target:
          type: array
          items:
            $ref: '#/components/schemas/StorefrontTargetEntry'
        steps:
          description: Step-completion records keyed by readiness check id.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/OnboardingPlanStep'
        phaseTransitions:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingPhaseTransition'
        lastUpdatedBy:
          description: Actor of the last write — e.g. "system", "murph", a userId.
          nullable: true
          type: string
        lastUpdatedAt:
          type: string
      required:
        - version
        - target
        - steps
        - phaseTransitions
        - lastUpdatedBy
        - lastUpdatedAt
      additionalProperties: false
    StorefrontLiveness:
      description: >-
        The projected storefront liveness verdict (AI-4698) — one derived status
        computed centrally and consumed by readiness, the seller-setup widget,
        and the storefront switcher.
      type: object
      properties:
        state:
          type: string
          enum:
            - setup
            - live
            - live_attention
            - live_critical
        reasonCode:
          type: string
          enum:
            - archived
            - paused_before_live
            - paused_after_live
            - setup_incomplete
            - settlement_ineligible
            - catalog_empty_live
            - go_live_requirement_regressed
            - degraded_source
            - trafficking_error
            - healthy
        reason:
          description: >-
            Human-readable line pairing with the dot, e.g. "Live — attention:
            pricing feed expires in 5 days" or "Not live — 2 steps remaining".
            Never shown without the dot naming the state (status-color-language
            rule 6).
          type: string
        remainingSteps:
          description: >-
            Open go-live blocker count, present only for state "setup". Null for
            every other state.
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
        actionPath:
          description: >-
            Application path (relative to the customer root, e.g.
            "/inventory-sources") of the surface that owns the fix, sourced from
            the readiness CHECK_ROUTING table. Null when the fix lives on the
            customer home surface (chat / seller-setup widget). Clients navigate
            to it; they never invent their own routing.
          nullable: true
          type: string
      required:
        - state
        - reasonCode
        - reason
        - remainingSteps
        - actionPath
      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
    AgentComplianceResult:
      description: Compliance assessment for a single agent
      type: object
      properties:
        agentId:
          type: string
        agentUrl:
          type: string
        passed:
          type: boolean
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/ComplianceTrackResult'
        summary:
          description: One-line compliance headline
          type: string
        observations:
          description: Advisory observations from compliance checks
          type: array
          items:
            type: object
            properties:
              category:
                type: string
              severity:
                type: string
                enum:
                  - info
                  - suggestion
                  - warning
                  - error
              message:
                type: string
            required:
              - category
              - severity
              - message
            additionalProperties: false
        durationMs:
          type: number
        error:
          type: string
      required:
        - agentId
        - agentUrl
        - passed
        - tracks
        - summary
        - observations
        - durationMs
      additionalProperties: false
    DemandCoverageSampleBrief:
      description: Representative starter-brief combination for seller demand coverage.
      type: object
      properties:
        category:
          type: string
        market:
          type: string
        channel:
          type: string
        status:
          type: string
          enum:
            - covered
            - needs_inventory
        rationale:
          type: string
      required:
        - category
        - market
        - channel
        - status
        - rationale
      additionalProperties: false
    SourceDetailAction:
      description: >-
        Server-selected portable specialist surface for one inventory source.
        The operation discriminant fixes the exact validated arguments shape.
      oneOf:
        - type: object
          properties:
            operation:
              type: string
              enum:
                - list_ad_server_sources
            arguments:
              type: object
              properties:
                esaId:
                  type: string
                  minLength: 1
              required:
                - esaId
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
        - type: object
          properties:
            operation:
              type: string
              enum:
                - get_modular_inventory_source_readiness
            arguments:
              type: object
              properties:
                sourceId:
                  type: string
                  minLength: 1
              required:
                - sourceId
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
        - type: object
          properties:
            operation:
              type: string
              enum:
                - open_source_diagnostics
            arguments:
              type: object
              properties:
                sourceId:
                  type: string
                  minLength: 1
                sourceName:
                  type: string
                  minLength: 1
              required:
                - sourceId
                - sourceName
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
      type: object
    CatalogMappingAction:
      description: >-
        One portable, validated V2 operation. The same action is projected to
        Modular Source and Seller Setup.
      oneOf:
        - type: object
          properties:
            operation:
              type: string
              enum:
                - open_modular_avails_commit
            arguments:
              type: object
              properties:
                sourceId:
                  type: string
              required:
                - sourceId
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
        - type: object
          properties:
            operation:
              type: string
              enum:
                - open_property_roster
            arguments:
              type: object
              properties: {}
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
        - type: object
          properties:
            operation:
              type: string
              enum:
                - get_modular_inventory_source_readiness
            arguments:
              type: object
              properties:
                sourceId:
                  type: string
              required:
                - sourceId
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
        - type: object
          properties:
            operation:
              type: string
              enum:
                - get_playbook
            arguments:
              type: object
              properties: {}
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
        - type: object
          properties:
            operation:
              type: string
              enum:
                - get_business_rules
            arguments:
              type: object
              properties: {}
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
        - type: object
          properties:
            operation:
              type: string
              enum:
                - test_storefront_brief
            arguments:
              type: object
              properties:
                sourceId:
                  type: string
              required:
                - sourceId
              additionalProperties: false
          required:
            - operation
            - arguments
          additionalProperties: false
      type: object
    SourceCardPosture:
      description: >-
        Server-owned seller posture for one source card. This is a bounded
        presentation verdict, not a universal source readiness boolean.
      oneOf:
        - type: object
          properties:
            state:
              type: string
              enum:
                - connected
            reasonCode:
              type: string
              enum:
                - connected
            explanation:
              type: string
              minLength: 1
          required:
            - state
            - reasonCode
            - explanation
          additionalProperties: false
        - type: object
          properties:
            state:
              type: string
              enum:
                - needs_setup
            reasonCode:
              type: string
              enum:
                - source_not_active
                - authentication_required
                - products_unsupported
                - products_missing
            explanation:
              type: string
              minLength: 1
          required:
            - state
            - reasonCode
            - explanation
          additionalProperties: false
        - type: object
          properties:
            state:
              type: string
              enum:
                - needs_attention
            reasonCode:
              type: string
              enum:
                - products_unverified
                - health_degraded
                - health_unverified
            explanation:
              type: string
              minLength: 1
          required:
            - state
            - reasonCode
            - explanation
          additionalProperties: false
      type: object
    DiagnosisAction:
      description: >-
        Typed inline action: `recheck` carries a portable named operation,
        `reconnect` opens the ad-server connect task, `open` opens a focused
        setup surface, `none` means nothing for the seller to do.
      anyOf:
        - $ref: '#/components/schemas/SourceRecheckAction'
        - type: object
          properties:
            kind:
              type: string
              enum:
                - reconnect
            label:
              type: string
          required:
            - kind
            - label
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - open
            label:
              type: string
          required:
            - kind
            - label
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - none
          required:
            - kind
          additionalProperties: false
    StorefrontTargetEntry:
      description: One discovered entry in a storefront onboarding plan target model.
      type: object
      properties:
        kind:
          type: string
          enum:
            - channel
            - format
            - property
            - product
            - signal
            - pricing
        value:
          description: >-
            The target value, e.g. "ctv", "premium homepage takeover", "podcast
            catalog".
          type: string
        sourceRef:
          description: >-
            Which inventory source carries it, when known. Matters for
            enterprise sellers whose storefronts run multiple sources — a gap
            must resolve to the source it should flow through.
          nullable: true
          type: string
        provenance:
          type: string
          enum:
            - declared
            - observed
            - asked
            - buyer_requested
            - researched
        confidence:
          type: number
          minimum: 0
          maximum: 1
        evidenceRefs:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - candidate
            - confirmed
            - expressed
            - declined
      required:
        - kind
        - value
        - sourceRef
        - provenance
        - confidence
        - evidenceRefs
        - status
      additionalProperties: false
    OnboardingPlanStep:
      type: object
      properties:
        completedAt:
          description: ISO timestamp the step was first observed complete.
          type: string
        owner:
          description: >-
            Who completed / owns the step. `null` when observed by the system
            rather than assigned; set when a person or Murph records it.
          nullable: true
          type: string
      required:
        - completedAt
        - owner
      additionalProperties: false
    OnboardingPhaseTransition:
      type: object
      properties:
        from:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OnboardingPhase'
        to:
          $ref: '#/components/schemas/OnboardingPhase'
        at:
          description: ISO timestamp of the transition.
          type: string
      required:
        - from
        - to
        - at
      additionalProperties: false
    ComplianceTrackResult:
      description: Result for a single compliance track
      type: object
      properties:
        track:
          description: Compliance track name
          type: string
        status:
          description: >-
            Track assessment result. 'silent' means the track was wired but
            observation-based assertions saw zero resources — distinct from
            'pass' (verified) and 'skip' (didn't run).
          type: string
          enum:
            - pass
            - fail
            - skip
            - partial
            - silent
        label:
          description: Human-readable track label
          type: string
        durationMs:
          description: Track duration in ms
          type: number
        failureReason:
          description: Why this track failed or partially passed
          type: string
      required:
        - track
        - status
        - label
        - durationMs
      additionalProperties: false
    SourceRecheckAction:
      description: >-
        Portable named operation for re-running a source-health check. Hosts
        resolve method and path from the canonical operation registry;
        deprecated method/path fields remain as a derived compatibility
        projection.
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              enum:
                - recheck
            label:
              type: string
            operation:
              type: string
              enum:
                - refresh_esa
            pathParams:
              type: object
              properties:
                esaId:
                  type: string
              required:
                - esaId
              additionalProperties: false
            method:
              description: >-
                Deprecated compatibility projection. Dispatch the named
                operation instead.
              deprecated: true
              type: string
              enum:
                - POST
            path:
              description: >-
                Deprecated compatibility projection derived from the operation
                registry. Dispatch the named operation instead.
              deprecated: true
              type: string
          required:
            - kind
            - label
            - operation
            - pathParams
            - method
            - path
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - recheck
            label:
              type: string
            operation:
              type: string
              enum:
                - recheck_esa_capability
            pathParams:
              type: object
              properties:
                esaId:
                  type: string
                capability:
                  type: string
                  enum:
                    - reporting
                    - forecasting
              required:
                - esaId
                - capability
              additionalProperties: false
            method:
              description: >-
                Deprecated compatibility projection. Dispatch the named
                operation instead.
              deprecated: true
              type: string
              enum:
                - POST
            path:
              description: >-
                Deprecated compatibility projection derived from the operation
                registry. Dispatch the named operation instead.
              deprecated: true
              type: string
          required:
            - kind
            - label
            - operation
            - pathParams
            - method
            - path
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - recheck
            label:
              type: string
            operation:
              type: string
              enum:
                - run_inventory_source_discovery_test
            pathParams:
              type: object
              properties:
                sourceId:
                  type: string
              required:
                - sourceId
              additionalProperties: false
            body:
              type: object
              properties: {}
              additionalProperties: false
            method:
              description: >-
                Deprecated compatibility projection. Dispatch the named
                operation instead.
              deprecated: true
              type: string
              enum:
                - POST
            path:
              description: >-
                Deprecated compatibility projection derived from the operation
                registry. Dispatch the named operation instead.
              deprecated: true
              type: string
          required:
            - kind
            - label
            - operation
            - pathParams
            - body
            - method
            - path
          additionalProperties: false
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````