> ## 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. # Record demand-inbox ledger annotations > Record the seller's grade (A–F), buyer feedback, and led-by attribution (agent | human) on one demand-inbox row. Only the fields provided are changed; grade and feedback accept null to clear them. Scoped to the caller's storefront — a run outside it returns 404. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml put /demand-inbox/{runId}/ledger 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/{runId}/ledger: put: tags: - Storefront summary: Record demand-inbox ledger annotations description: >- Record the seller's grade (A–F), buyer feedback, and led-by attribution (agent | human) on one demand-inbox row. Only the fields provided are changed; grade and feedback accept null to clear them. Scoped to the caller's storefront — a run outside it returns 404. operationId: recordDemandInboxResult parameters: - in: path name: runId schema: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Surrogate id of the chef compose run this ledger row wraps. example: 42 required: true description: Surrogate id of the chef compose run this ledger row wraps. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecordDemandInboxResultBody' responses: '200': description: Record demand-inbox ledger annotations content: application/json: schema: $ref: '#/components/schemas/DemandInboxRow' '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 demand-inbox row with that id in the calling 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: RecordDemandInboxResultBody: type: object properties: grade: description: Seller's letter grade (A–F) for the proposal. Null clears it. nullable: true type: string enum: - A - B - C - D - F feedback: description: Buyer feedback captured against the proposal. Null clears it. nullable: true type: string maxLength: 2000 ledBy: description: >- Who led the response: the agent, or a human who took it over. Omit to leave the run's current attribution. type: string enum: - agent - human description: >- Records the seller-authored ledger annotations (grade, buyer feedback, led-by attribution) on one demand-inbox row. 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 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 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. 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 securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````