> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the demand-inbox ledger

> The Proposal Studio front-of-house ledger for the calling storefront: a page of brief → proposal → feedback → result rows (each carrying the canonical brief and proposal artifact ids), plus a metrics strip computed only from persisted rows — briefs YTD, answered %, win rate, average grade, and the agent-vs-human split. A metric with no inputs is reported as null (unavailable), never 0. Page with `?skip=` and `?take=`.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml get /demand-inbox
openapi: 3.0.0
info:
  title: Scope3 Storefront API
  version: 2.0.0
  description: >-
    REST API for partners to manage Seller Accounts, inventory sources, and
    billing.


    ## Authentication


    All endpoints require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```


    ## Base URL


    `https://api.interchange.io/api/v2/storefront`


    ## For AI Agents


    AI agents can use the MCP endpoint at `/mcp/v2/storefront` with three tools:

    - `initialize`: Start an MCP session

    - `api_call`: Make REST API calls

    - `ask_about_capability`: Learn about API features
servers:
  - url: https://api.interchange.io/api/v2/storefront
    description: Production server
security: []
tags:
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Asks
    description: >-
      What you are waiting on Scope3 for — support, product, and supply asks in
      one list
  - name: Storefront
    description: Manage storefront and inventory sources
  - name: Storefront Agents
    description: List and manage registered sales, signals, and outcomes agents
  - name: Storefront Activity
    description: Audit log of configuration and inventory changes on the storefront
  - name: Storefront Billing
    description: Payout bank details and billing configuration for Seller Accounts
  - name: AI Usage
    description: Seller Account AI token usage visibility by model
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /demand-inbox:
    get:
      tags:
        - Storefront
      summary: Get the demand-inbox ledger
      description: >-
        The Proposal Studio front-of-house ledger for the calling storefront: a
        page of brief → proposal → feedback → result rows (each carrying the
        canonical brief and proposal artifact ids), plus a metrics strip
        computed only from persisted rows — briefs YTD, answered %, win rate,
        average grade, and the agent-vs-human split. A metric with no inputs is
        reported as null (unavailable), never 0. Page with `?skip=` and
        `?take=`.
      operationId: getDemandInbox
      parameters:
        - in: query
          name: skip
          schema:
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
        - in: query
          name: take
          schema:
            default: 50
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Get the demand-inbox ledger
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemandInboxResponse'
        '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 storefront exists for the calling operator.
          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:
    DemandInboxResponse:
      type: object
      properties:
        metrics:
          $ref: '#/components/schemas/DemandInboxMetrics'
        rows:
          type: array
          items:
            $ref: '#/components/schemas/DemandInboxRow'
        total:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            Total number of brief rows for the storefront. When it exceeds the
            returned page, the client discloses the cap ("showing the N most
            recent of total").
      required:
        - metrics
        - rows
        - total
      additionalProperties: false
      description: >-
        The demand-inbox ledger: a persisted-only metrics strip, a page of brief
        → proposal → feedback → result rows, and the total brief count for
        page-cap disclosure.
    ErrorResponse:
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
      description: Standard error response
    DemandInboxMetrics:
      type: object
      properties:
        briefsYtd:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Count of brief passes received this calendar year.
        answeredPercent:
          nullable: true
          description: >-
            Share of this year’s briefs the agent answered with a proposal
            (0–100). Null when no briefs exist yet.
          type: number
        winRate:
          nullable: true
          description: >-
            Won / (won + lost) across briefs with a decided commercial result
            (0–100). Null when no result is recorded yet.
          type: number
        avgGrade:
          nullable: true
          description: >-
            Mean seller grade rounded to the nearest letter. Null when nothing
            is graded yet.
          type: string
          enum:
            - A
            - B
            - C
            - D
            - F
        agentVsHuman:
          nullable: true
          description: >-
            Led-by split across briefs with recorded attribution. Null when no
            run has been attributed yet.
          type: object
          properties:
            agent:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            human:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
          required:
            - agent
            - human
          additionalProperties: false
        bookedYtd:
          nullable: true
          description: >-
            Money won this calendar year, one entry per currency, from
            attributed outcomes that carried both an amount and its currency
            (delivered spend when reported, else the booked media-buy budget).
            Null when nothing won this year recorded a priced outcome.
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
              currency:
                type: string
            required:
              - amount
              - currency
            additionalProperties: false
      required:
        - briefsYtd
        - answeredPercent
        - winRate
        - avgGrade
        - agentVsHuman
        - bookedYtd
      additionalProperties: false
      description: >-
        Front-of-house scoreboard. Every field is computed only from persisted
        rows; a metric with no inputs reports null (unavailable), never 0.
    DemandInboxRow:
      type: object
      properties:
        id:
          type: string
        brief:
          nullable: true
          description: The brief text the agent answered (label for the row).
          type: string
        buyer:
          nullable: true
          description: >-
            Legacy ambiguous buyer label retained for compatibility. New readers
            must use commercialIdentity instead.
          type: string
        commercialIdentity:
          $ref: '#/components/schemas/DemandCommercialIdentity'
        responseKind:
          $ref: '#/components/schemas/DemandResponseKind'
        commercialLifecycle:
          $ref: '#/components/schemas/DemandCommercialLifecycle'
        budgetRange:
          nullable: true
          description: >-
            The buyer's stated budget range, exactly as sent in the brief's
            filters.budget_range and captured in the brief artifact. Null when
            the buyer did not state one.
          type: object
          properties:
            min:
              nullable: true
              type: number
            max:
              nullable: true
              type: number
            currency:
              type: string
          required:
            - min
            - max
            - currency
          additionalProperties: false
        receivedAt:
          type: string
        respondedAt:
          nullable: true
          description: When the agent answered. Null while the brief is unanswered.
          type: string
        responseTimeMs:
          nullable: true
          description: >-
            Persisted compose duration in milliseconds. Null when duration was
            not recorded; never derived as zero from equal timestamps.
          type: number
          minimum: 0
        ledBy:
          nullable: true
          type: string
          enum:
            - agent
            - human
        feedback:
          nullable: true
          type: string
        result:
          type: string
          enum:
            - closed_won
            - closed_lost
            - pending
          description: >-
            Commercial result derived from this run’s own attributed outcome:
            closed_won (booked/delivered), closed_lost (rejected), else pending.
            A booking attributed to a later refine pass is not rolled up here
            (see the win-rate scope note).
        grade:
          nullable: true
          type: string
          enum:
            - A
            - B
            - C
            - D
            - F
        wonValue:
          nullable: true
          description: >-
            Money attributed to this run's won outcome: delivered spend when
            reporting exists, else the booked media-buy budget. Null unless the
            outcome persisted both an amount and its currency.
          type: object
          properties:
            amount:
              type: number
            currency:
              type: string
          required:
            - amount
            - currency
          additionalProperties: false
        provenance:
          nullable: true
          description: >-
            How this brief reached the ledger: 'live' = an AdCP get_products
            call from a buyer agent, 'uploaded' = a seller-uploaded RFP/brief
            confirmed in chat (AI-4728). Reflects this run's own intake origin
            (AI-5025), falling back to the linked brief artifact's source column
            only for historical runs recorded before that origin was captured.
            Null when neither is available (e.g. a practice pitch or a
            historical pre-capture run). Uploaded briefs never masquerade as
            live buyer demand.
          type: string
        briefArtifactId:
          nullable: true
          description: >-
            Canonical brief artifact id (AI-4693) for the build-3 drill-in. Null
            = artifact unavailable (historical pre-capture run).
          type: string
        proposalArtifactId:
          nullable: true
          description: >-
            Historical storage-table name for the latest canonical
            seller-response artifact. Its presence does not prove a Proposal;
            responseKind is authoritative and 'proposal' requires proposal_id
            evidence.
          type: string
        artifactAvailable:
          type: boolean
          description: >-
            False when the brief artifact was not captured; readers must say
            "artifact unavailable" rather than reconstruct it.
      required:
        - id
        - brief
        - buyer
        - commercialIdentity
        - responseKind
        - commercialLifecycle
        - budgetRange
        - receivedAt
        - respondedAt
        - responseTimeMs
        - ledBy
        - feedback
        - result
        - grade
        - wonValue
        - provenance
        - briefArtifactId
        - proposalArtifactId
        - artifactAvailable
      additionalProperties: false
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Structured error object
    DemandCommercialIdentity:
      type: object
      properties:
        advertiser:
          nullable: true
          description: Advertiser BrandRef domain. This is the primary commercial identity.
          type: object
          properties:
            value:
              type: string
            source:
              type: string
              enum:
                - request.brand
                - request.account.brand
                - request.account.operator
                - request.account.account_id
                - compose_run
          required:
            - value
            - source
          additionalProperties: false
        buyingOperator:
          nullable: true
          description: >-
            Organization operating the buy, independently of the advertiser
            brand.
          type: object
          properties:
            value:
              type: string
            source:
              type: string
              enum:
                - request.brand
                - request.account.brand
                - request.account.operator
                - request.account.account_id
                - compose_run
          required:
            - value
            - source
          additionalProperties: false
        account:
          nullable: true
          description: >-
            Buyer-declared AdCP account_id, when supplied. This is not a CRM id
            or a seller-native source mapping.
          type: object
          properties:
            value:
              type: string
            source:
              type: string
              enum:
                - request.brand
                - request.account.brand
                - request.account.operator
                - request.account.account_id
                - compose_run
          required:
            - value
            - source
          additionalProperties: false
      required:
        - advertiser
        - buyingOperator
        - account
      additionalProperties: false
      description: >-
        Advertiser = BrandRef × Operator (AI-5080), projected from the persisted
        brief request first and the compose-run identity snapshot only as a
        historical fallback. CRM evidence and seller-native mappings are
        deliberately not joined into this identity.
    DemandResponseKind:
      type: string
      enum:
        - product_offer
        - proposal
        - no_offer
        - unavailable
      description: >-
        What the persisted seller response actually proves: 'proposal' requires
        a non-empty proposal_id; products without that evidence are a
        product_offer, never a Proposal.
    DemandCommercialLifecycle:
      type: string
      enum:
        - closed_won
        - closed_lost
        - awaiting_advertiser_decision
        - awaiting_seller_approval
        - forwarding_failed
        - no_offer_returned
        - response_not_recorded
        - response_unavailable
      description: >-
        The most specific commercial lifecycle supported by the persisted
        response and attributed outcome. This supplements result so an undecided
        exchange is never presented as an ambiguous Pending state.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````