> ## 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. # List inventory sources > List all inventory sources for the storefront. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml get /inventory-sources 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: /inventory-sources: get: tags: - Storefront summary: List inventory sources description: List all inventory sources for the storefront. operationId: listInventorySources responses: '200': description: List inventory sources content: application/json: schema: type: array items: $ref: '#/components/schemas/InventorySourceResponse' '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: InventorySourceResponse: description: Inventory source response type: object properties: id: description: >- Globally unique surrogate id (BIGINT serialized as string). Use this when acting on rows the caller does not own (e.g. a seller approving an inbound link). type: string sourceId: description: >- Storefront-scoped identifier — unique within the row owner's storefront. Use this for actions on the caller's own rows; use `id` for cross-customer actions. type: string name: description: Display name type: string executionType: description: Execution type type: string enum: - AGENT - MANAGED_SALES_AGENT - LINKED_STOREFRONT - MODULAR_SOURCE connectionType: description: >- Public connection family for a preconfigured ad-server source. Omitted for other inventory-source families. type: string enum: - AD_SERVER adServerProvider: description: >- Ad-server provider for a preconfigured ad-server source. Omitted for other inventory-source families. type: string enum: - citrusad status: description: Source lifecycle status type: string enum: - PENDING - ACTIVE - DISABLED agentId: description: Linked agent ID (when executionType is agent) nullable: true type: string type: description: Agent type nullable: true type: string enum: - SALES - SIGNAL - CREATIVE - OUTCOME endpointUrl: description: Agent endpoint URL nullable: true type: string protocol: description: Agent protocol nullable: true type: string enum: - MCP - A2A description: description: Agent description nullable: true type: string authenticationType: description: Agent authentication type nullable: true type: string enum: - API_KEY - NO_AUTH - JWT - OAUTH - BASIC_AUTH authConfigured: description: Whether the agent has authentication configured type: boolean oauth: description: OAuth authorization info (for OAUTH agents) type: object properties: authorizationUrl: type: string agentId: type: string agentName: type: string required: - authorizationUrl - agentId - agentName additionalProperties: false managedSa: description: >- Embedded-sales-agent state when `executionType` is `MANAGED_SALES_AGENT`. Null/absent for external `AGENT`-type sources. The current REST surface (`/api/v2/storefront/esa/...`) remains the way to mutate this state today; subsequent PRs will move those actions under `/api/v2/storefront/inventory-sources/:sourceId/...`. nullable: true allOf: - $ref: '#/components/schemas/ManagedSalesAgentSummary' linkedStorefront: description: >- Always null. Storefront interchange runs through the ambient wholesale pool: a curator discovers any LISTED storefront’s wholesale inventory automatically, with no per-counterparty link to establish. Retained for response-shape stability. nullable: true allOf: - $ref: '#/components/schemas/LinkedStorefrontSummary' reportingType: description: >- How the underlying agent reports delivery (`WEBHOOK`, `BUCKET`, `POLLING`). Mirrors the AdCP-spec values used when connecting the source. Projected from `storefront_agent_source`; null for non-AGENT sources. nullable: true type: string enum: - WEBHOOK - BUCKET - POLLING reportingPollingCadence: description: >- Polling cadence (`DAILY`, `MONTHLY`) — only meaningful when `reportingType` is `POLLING`. Projected from `storefront_agent_source`; null for non-AGENT sources or non-polling reporting. nullable: true type: string enum: - DAILY - MONTHLY isAdapterSource: description: >- True when this source is routed through an official Scope3-hosted adapter (storefront routing_mode is ADAPTER and the source_id matches the configured adapter). When true, the UI labels this as an official adapter rather than a generic external sales agent. type: boolean agentCapabilityUid: description: >- Explicit reusable SALES Agent capability connected to this Source. Null means the Source requires governed connection reconciliation; endpoint similarity is never used. 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)$ declaredAgentProductMode: description: >- The backing Agent completeness contract. Managed ESA and initial modular Sources project their fixed WHOLESALE contract. nullable: true type: string enum: - WHOLESALE - COMPOSING - BOTH bindingProductMode: description: >- Source product-path selection only when the Agent declares BOTH; null for single-mode Agents. nullable: true type: string enum: - WHOLESALE - COMPOSING - BOTH effectiveProductMode: description: >- Effective mode for new discovery. Null when the explicit Agent connection or declaration is unresolved. nullable: true type: string enum: - WHOLESALE - COMPOSING - BOTH productModeReasons: description: >- Bounded reconciliation reasons when effective mode cannot be resolved. type: array items: type: string enum: - SOURCE_NOT_ACTIVE - AGENT_BINDING_MISSING - AGENT_MODE_UNDECLARED - BOTH_SELECTION_REQUIRED - MERCHANDISING_ACCESS_INACTIVE - WHOLESALE_CATALOG_NOT_READY productPaths: description: >- Readiness for the Agent-supplied and Storefront-built product paths. BOTH exposes both entries; neither path silently replaces the other. type: array items: type: object properties: path: type: string enum: - WHOLESALE - COMPOSING ready: type: boolean reasons: type: array items: type: string enum: - SOURCE_NOT_ACTIVE - AGENT_BINDING_MISSING - AGENT_MODE_UNDECLARED - BOTH_SELECTION_REQUIRED - MERCHANDISING_ACCESS_INACTIVE - WHOLESALE_CATALOG_NOT_READY required: - path - ready - reasons additionalProperties: false createdAt: description: Creation timestamp (ISO 8601) 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))$ updatedAt: description: Last update timestamp (ISO 8601) 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 - sourceId - name - executionType - status - agentId - createdAt - updatedAt 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 ManagedSalesAgentSummary: description: >- Read-only managed ad-server source state for inventory sources with `executionType=MANAGED_SALES_AGENT`. type: object properties: connectionId: description: >- Surrogate id of the underlying managed ad-server source connection (BIGINT serialized as string). Used internally to route action requests; clients should generally identify the source by the inventory `sourceId` instead. type: string tenantId: description: >- Upstream tenant id for the managed ad-server source. Null until provisioning succeeds. nullable: true type: string adServer: description: Publisher-supplied ad-server config. Null if not yet collected. nullable: true allOf: - $ref: '#/components/schemas/AdServerConfigView' lastError: description: >- Failure reason from the most recent provisioning or test-connection attempt. nullable: true type: string lastErrorCode: description: >- Machine-readable classification of the most recent provisioning failure (`ADAPTER_NETWORK_NOT_FOUND`, `ADAPTER_PERMISSION_DENIED`, `ADAPTER_INVALID_CREDENTIALS`, `ADAPTER_INVALID_CONFIG`, `ADAPTER_CONNECTION_FAILED`, or `INTERNAL_ERROR`). Null when there has been no failure. Same vocabulary as `EsaConnection.lastErrorCode` on the full ad-server connection. nullable: true type: string lastTestedAt: 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))$ provisionedAt: 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))$ deactivatedAt: 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: - connectionId - tenantId - adServer - lastError - lastErrorCode - lastTestedAt - provisionedAt - deactivatedAt additionalProperties: false LinkedStorefrontSummary: description: >- Retired. Never populated — storefront interchange runs through the ambient wholesale pool, so no inline link state is produced. Retained as a reserved, always-null component for response-shape stability. type: object properties: status: description: >- Retired. Storefront interchange no longer uses per-counterparty links; this enum is retained only for response-shape stability and is never emitted. type: string enum: - PENDING - ACTIVE - REJECTED - CANCELLED buyer: description: The storefront that initiated the link (the row owner). allOf: - $ref: '#/components/schemas/StorefrontResponse' seller: description: The storefront whose inventory the link surfaces. allOf: - $ref: '#/components/schemas/StorefrontResponse' requestMessage: nullable: true type: string responseMessage: nullable: true type: string requestedAt: 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))$ respondedAt: 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))$ cancelledAt: 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))$ cancelledBy: description: Which side stopped the link. Null until status is `CANCELLED`. nullable: true type: string enum: - BUYER - SELLER required: - status - buyer - seller - requestMessage - responseMessage - requestedAt - respondedAt - cancelledAt - cancelledBy 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 AdServerConfigView: description: >- Non-secret view of the connection ad-server config. Returned by GET endpoints; never contains credentials. oneOf: - type: object properties: type: type: string enum: - google_ad_manager networkCode: description: Google Ad Manager network code. example: '12345678' type: string minLength: 1 maxLength: 32 pattern: ^[0-9]+$ required: - type - networkCode additionalProperties: false - type: object properties: type: type: string enum: - freewheel clientId: nullable: true type: string username: nullable: true type: string environment: type: string enum: - production - staging - sandbox defaultAdvertiserId: nullable: true type: string executionCurrency: default: null nullable: true type: string required: - type - clientId - username - environment - defaultAdvertiserId - executionCurrency additionalProperties: false - type: object properties: type: type: string enum: - springserve email: nullable: true type: string environment: type: string enum: - production defaultDemandPartnerId: nullable: true type: integer minimum: -9007199254740991 maximum: 9007199254740991 rateCurrency: default: null nullable: true type: string required: - type - email - environment - defaultDemandPartnerId - rateCurrency additionalProperties: false - type: object properties: type: type: string enum: - adswizz agencyId: type: integer minimum: -9007199254740991 maximum: 9007199254740991 environment: type: string enum: - AUDIOSERVE baseUrl: type: string forecastingBaseUrl: type: string defaultCurrency: type: string cpmLimit: nullable: true type: number defaultAdvertiserId: nullable: true type: string required: - type - agencyId - environment - baseUrl - forecastingBaseUrl - defaultCurrency - cpmLimit - defaultAdvertiserId additionalProperties: false type: object StorefrontResponse: description: Storefront configuration response type: object properties: storefrontId: description: Surrogate id (BIGINT serialized as string) example: '1234' type: string platformId: description: Public-facing slug example: acme-media type: string name: description: Display name example: Acme Media type: string publisherDomain: description: Publisher domain for the storefront's business profile example: acme.com nullable: true type: string operatorDomain: description: Canonical operator domain example: scope3.com nullable: true type: string brandName: description: Brand name from AAO registry example: Scope3 nullable: true type: string logoUrl: description: Logo URL from brand.json nullable: true type: string logoBackground: description: >- Backdrop the logo is designed for, from brand.json. Null or absent when unknown; the storefront card falls back to a dark tile. nullable: true type: string enum: - dark-bg - light-bg - transparent-bg membershipStatus: description: AAO membership tier. Null when the operator has not set a value. nullable: true type: string enum: - AAO_FOUNDING_MEMBER - AAO_MEMBER - NONE regions: description: >- Legacy merchandising-region context projected from businessProfile. This does not govern brief acceptance or Discovery Card country coverage. type: array items: type: string acceptedCountries: description: >- Operator-confirmed exhaustive country allowlist for brief routing. Null means routing scope has not been confirmed. nullable: true type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: description: Whether the operator explicitly accepts briefs from every country. type: boolean advertisingPolicyDisclosure: description: >- Seller-selected Business Rules sections disclosed publicly as Advertising Policies. Empty means no local disclosure. type: array items: description: >- A Business Rules section the seller elects to disclose publicly as Advertising Policies on its Discovery Card. type: string enum: - brief_acceptance - creative_policy advertisedCountries: description: >- Standard primary countries advertised by backing AdCP sales agents. Authoritative for a pure pass-through Discovery Card; inventory evidence otherwise. type: array items: type: string pattern: ^[A-Z]{2}$ advertisedChannels: description: >- Standard primary channels advertised by backing AdCP sales agents. Authoritative for a pure pass-through Discovery Card; inventory evidence otherwise. type: array items: type: string description: description: Operator-curated description (overrides brand.json). nullable: true type: string channels: description: ADCP channel codes the storefront offers. type: array items: type: string website: description: Operator-curated website URL (overrides brand.json). nullable: true type: string discoveryCard: description: >- Canonical buyer-visible storefront identity and coverage. This is distinct from Media Kit merchandising inputs and seller policies. allOf: - $ref: '#/components/schemas/DiscoveryCard' demandContactName: description: Demand contact name. Null when the operator has not set one. nullable: true type: string demandContactEmail: description: Demand contact email. Null when the operator has not set one. nullable: true type: string operatorDomainVerified: description: >- Whether the operator domain has been verified (email match or manual KYC) type: boolean routingMode: description: >- Which backend function the buyer-facing storefront dispatches to: the Merchandising Agent or an expert-run adapter. type: string enum: - CHEF - ADAPTER adapterProviderType: description: >- Expert-run adapter provider when routingMode is `ADAPTER`; null otherwise. nullable: true type: string enum: - amazon - audiostack - elevenlabs - fal - gemini - google - linkedin - meta - openai - pinterest - reddit - snap - spotify - tiktok - veo adapterSourceKind: description: Adapter role when routingMode is `ADAPTER`; null otherwise. nullable: true type: string enum: - sales - creative - signals - measurement - optimization - composite adapterCredentialMode: description: >- Adapter credential mode when routingMode is `ADAPTER`; null otherwise. nullable: true type: string enum: - BYOK plan: description: Storefront plan tier type: string enum: - basic transacting: description: >- Deprecated compatibility projection of `!isPaused`; not proof that the storefront currently satisfies readiness. type: boolean isPaused: description: >- Compatibility-named seller intake hold. True blocks discovery, new buys, and buyer edits but does not pause existing delivery. False is neutral; it does not by itself make the storefront live. type: boolean archivedAt: description: >- When the storefront was archived (read-only thereafter). Null for non-archived storefronts. 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))$ displayStatus: description: >- Deprecated stored-control display status. This is never proof that the storefront can transact; use the readiness projection. type: string enum: - configuring - transacting - archived - neutral - paused capabilities: description: >- Effective buyer-facing AdCP capabilities. Product composition derives from merchandising access and ready Source product paths; it is not locked to the legacy configured flag. allOf: - $ref: '#/components/schemas/StorefrontCapabilities' configuredCapabilities: description: >- Persisted operator capability flags before source-topology derivation. Compare this field for declarative writes; `capabilities` is the effective buyer-facing projection. allOf: - $ref: '#/components/schemas/StorefrontCapabilities' setupIntent: description: >- Declared selling intent from the first onboarding question, or null when the operator has not been asked yet. A record of the operator's answer — what the storefront exposes is always the derived `capabilities`. nullable: true type: string enum: - third_party_connect - sell_through_scope3 compositionPricing: description: >- Composition pricing settings: fallback pricing percentile plus seller pricing facts. Separate from Scope3 contract/billing rate cards. allOf: - $ref: '#/components/schemas/StorefrontCompositionPricingOutput' creativeApproval: description: >- Stored operator setting for creative submissions. It only affects ad-server-backed or product-composition storefronts; pass-through external-agent storefronts ignore this because their sources own review. type: string enum: - auto - manual mediaBuyApproval: description: >- Stored operator setting for new media buys. It only affects ad-server-backed or product-composition storefronts; pass-through external-agent storefronts ignore this because Interchange does not insert an approval queue. type: string enum: - auto - manual capabilitiesLocked: description: >- Legacy topology projection: true when the storefront has at least one active ad-server-backed inventory source (`executionType=MANAGED_SALES_AGENT`). Product composition is now Source-derived, so this value does not authorize or lock capability writes. type: boolean advertiseAsAgent: description: >- Derived: true when the Storefront has an active Inventory Source, an active embedded Sales Agent, adapter routing, or an advertised Storefront-owned capability. Every active Source remains behind the buyer-facing Storefront AdCP endpoint, including COMPOSING-only Sources. type: boolean sellsThirdPartyInventory: description: >- Operator toggle: when true, the storefront also resells third-party inventory from other Interchange storefronts (composition draws from the marketplace in addition to its own sources). When false/absent (default), the storefront sells only its own inventory sources. type: boolean createdAt: description: Creation timestamp (ISO 8601) 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))$ updatedAt: description: Last update timestamp (ISO 8601) 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))$ businessProfile: description: >- Operator-supplied business profile captured during Murph-led setup. Null when the operator has not shared one. nullable: true allOf: - $ref: '#/components/schemas/BusinessProfileOutput' defaultCurrency: description: >- Seller-confirmed primary settlement currency (ISO-4217). Null until confirmed; required before go-live for Interchange-cleared storefronts. Direct sales adapter storefronts run by our expert agents skip settlement-currency readiness checks because Interchange does not pay the seller on that path. nullable: true type: string paymentCurrencies: description: >- ISO-4217 currencies the storefront will be paid in (the payout set). A media buy settles in one of these. Empty falls back to defaultCurrency. The marketplace may additionally accept buyer currencies outside this set via cross-currency FX, converting each source cost to the buyer currency at the platform spot rate. type: array items: type: string required: - storefrontId - platformId - name - publisherDomain - operatorDomain - brandName - logoUrl - membershipStatus - regions - acceptedCountries - acceptsAllCountries - advertisingPolicyDisclosure - advertisedCountries - advertisedChannels - description - channels - website - discoveryCard - demandContactName - demandContactEmail - operatorDomainVerified - routingMode - adapterProviderType - adapterSourceKind - adapterCredentialMode - plan - transacting - isPaused - archivedAt - displayStatus - capabilities - configuredCapabilities - compositionPricing - creativeApproval - mediaBuyApproval - capabilitiesLocked - advertiseAsAgent - createdAt - updatedAt - businessProfile additionalProperties: false DiscoveryCard: description: >- Canonical buyer-visible storefront identity, coverage declaration, and optional Advertising Policies disclosure. Unknown coverage never means worldwide or all channels. type: object properties: storefrontId: type: string platformId: type: string storefrontKind: type: string enum: - managed - external_pass_through displayName: type: string logoUrl: nullable: true type: string logoBackground: nullable: true type: string enum: - dark-bg - light-bg - transparent-bg description: nullable: true type: string website: nullable: true type: string brandColors: nullable: true type: object additionalProperties: type: string channels: description: >- Aggregate channel facets for search and display. Do not combine these with aggregate countries as a cross-product coverage promise. type: array items: type: string countries: description: >- Aggregate ISO 3166-1 alpha-2 country facets for search and display. Do not combine these with aggregate channels as a cross-product coverage promise. type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: description: >- True only when the storefront explicitly accepts briefs from every country. type: boolean coverageDeclarations: description: >- Channel and country coverage claims preserved at their source boundaries. A combined filter matches only when one declaration satisfies both dimensions. type: array items: description: >- One source-level coverage claim. Channels and countries are correlated within this declaration; an empty dimension is unknown, not unrestricted. type: object properties: channels: description: Channels accepted by this correlated source declaration. type: array items: type: string countries: description: >- ISO 3166-1 alpha-2 countries accepted by this correlated source declaration. type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: description: >- True only when this correlated source declaration explicitly accepts every country. type: boolean required: - channels - countries - acceptsAllCountries additionalProperties: false advertisingPolicies: nullable: true type: string maxLength: 10000 coverage: type: object properties: channels: type: string enum: - declared - partial - unknown countries: type: string enum: - declared - partial - unknown required: - channels - countries additionalProperties: false provenance: type: object properties: identity: type: object properties: displayName: type: string enum: - operator - registry - upstream_capabilities - unknown logoUrl: type: string enum: - operator - registry - upstream_capabilities - unknown description: type: string enum: - operator - registry - upstream_capabilities - unknown website: type: string enum: - operator - registry - upstream_capabilities - unknown brandColors: type: string enum: - operator - registry - upstream_capabilities - unknown required: - displayName - logoUrl - description - website - brandColors additionalProperties: false coverage: type: object properties: channels: type: string enum: - operator - registry - upstream_capabilities - unknown countries: type: string enum: - operator - registry - upstream_capabilities - unknown required: - channels - countries additionalProperties: false advertisingPolicies: type: string enum: - operator - registry - upstream_capabilities - unknown required: - identity - coverage - advertisingPolicies additionalProperties: false required: - storefrontId - platformId - storefrontKind - displayName - logoUrl - logoBackground - description - website - brandColors - channels - countries - acceptsAllCountries - coverageDeclarations - advertisingPolicies - coverage - provenance additionalProperties: false StorefrontCapabilities: description: >- Which AdCP capabilities the storefront advertises to buyers. Product composition is derived from Source product-path readiness and entitlement. type: object properties: offersCreativeReview: description: >- Surfaces the creative review protocol surface to buyers. `sync_creatives` returns review-status fields; inline creatives in `create_media_buy` / `update_media_buy` flow through the storefront review gate. The operator policy (auto-approve vs manual queue) is separate config — this flag only governs whether the capability is advertised. default: false type: boolean offersCampaignApproval: description: >- Surfaces the campaign approval protocol surface to buyers. `create_media_buy` and material-change `update_media_buy` may return a submitted-task envelope until the operator decides. The operator policy (auto-approve vs manual queue, material-change threshold) is separate config. default: false type: boolean offersProductComposition: deprecated: true description: >- Read-only compatibility projection. True only while the customer has merchandising access and at least one active Source has a ready Storefront-built product path (`WHOLESALE`). default: false type: boolean required: - offersCreativeReview - offersCampaignApproval - offersProductComposition additionalProperties: false StorefrontCompositionPricingOutput: description: >- Storefront composition pricing settings: fallback guidance percentile plus lightly structured seller pricing facts. type: object properties: targetPercentile: default: p75 description: >- Deprecated. Historical auction-clearing percentile, retained for explainability only — it no longer sets the price. Pricing is value-led: the Merchandising Agent prices each brief to its value, bounded by wholesale floors and seller ceilings, never anchored to a clearing percentile. type: string enum: - p50 - p75 - p90 rateCard: description: >- Seller product-pricing facts. Separate from Scope3 contract rate cards. default: facts: [] type: object properties: currency: description: >- Default ISO 4217 currency for pricing facts in this storefront rate card. example: USD type: string minLength: 3 maxLength: 3 facts: default: [] maxItems: 500 type: array items: $ref: '#/components/schemas/StorefrontPricingFactOutput' required: - facts additionalProperties: false required: - targetPercentile - rateCard additionalProperties: false BusinessProfileOutput: description: >- Operator-supplied business profile captured by Murph during storefront setup. type: object properties: summary: description: >- One-paragraph natural-language summary of the business (e.g. "30 properties across web, mobile, and CTV, primarily UK, sports and entertainment focus"). type: string maxLength: 2000 agentName: description: >- Deprecated agent-name field, kept for legacy compatibility only. Prefer the Storefront display name for buyer-facing naming; do not use this to create a separate persona. type: string minLength: 1 maxLength: 80 agentPersonality: description: >- Deprecated. An agent has no personality of its own — voice belongs to the brand, and is read from the brand manifest (`tone`). Nothing consumes this field; pass null to remove an existing legacy value. type: string minLength: 1 maxLength: 1000 propertyCount: description: Approximate number of owned properties / domains. type: integer minimum: 0 maximum: 10000 channels: description: >- Channels the operator sells across (ADCP channel codes — display, olv, ctv, social, audio, dooh). maxItems: 16 type: array items: description: >- Legacy V2 storefront channel code. Values round-trip unchanged; the Discovery Card projection, Marketplace filters, and outbound AdCP capabilities normalize `audio` to canonical `streaming_audio`. type: string enum: - display - olv - ctv - social - audio - dooh regions: description: >- Primary regions the business operates in (ISO 3166-1 alpha-2 country codes or group codes). example: - UK - EMEA maxItems: 64 type: array items: type: string pattern: ^[A-Z0-9_-]{2,32}$ verticals: description: Topic/vertical focus areas, free-text. example: - sports - entertainment maxItems: 32 type: array items: type: string minLength: 1 maxLength: 80 publisherDomains: description: >- Publisher domains/properties the Merchandising Agent should be authorized to sell through this Storefront. Omit when unknown; omission does not mean all domains are authorized. Domains are normalized to lowercase and deduplicated. example: - pitchside.co.uk - football.pitchside.co.uk maxItems: 128 type: array items: type: string maxLength: 253 pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ evidenceUrls: description: >- URLs the operator pointed Murph at (media kits, about pages, etc.) so a future conversation can re-read the source material. New values must use HTTP(S). maxItems: 16 type: array items: type: string maxLength: 2048 format: uri notes: description: >- Free-form Murph-captured notes that did not fit into the structured fields. type: string maxLength: 4000 updatedBy: description: >- Identifier of the agent or user that last wrote this profile (e.g. "murph" or a userId). Audit-only. type: string maxLength: 120 additionalProperties: false StorefrontPricingFactOutput: description: >- Lightly structured seller value-pricing fact. Pricing facts anchor prices and floors; they are not product assembly templates. type: object properties: id: description: >- Stable operator-facing id for this pricing fact. Murph should preserve ids across rewrites when the fact is semantically the same. type: string minLength: 1 maxLength: 120 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ label: description: Short display label for this pricing fact. example: Rich media packages type: string minLength: 1 maxLength: 160 appliesWhen: description: >- Natural-language applicability condition. This is intentionally not a rigid product template; the Merchandising Agent uses it as reasoning context. type: string minLength: 1 maxLength: 2000 hints: description: >- Optional structured hints for deterministic matching. Missing hints are fine. default: {} allOf: - $ref: '#/components/schemas/StorefrontPricingFactHintsOutput' pricing: $ref: '#/components/schemas/StorefrontPricingFactPriceOutput' strength: default: default description: >- `hard_floor` is a must-not-go-below seller constraint. `default` is the preferred value-pricing anchor. `guidance` is advisory context only. type: string enum: - hard_floor - default - guidance provenance: description: >- Where this pricing fact came from, such as "Uploaded 2026 rate card, page 3" or "Operator statement on setup call". type: string maxLength: 500 notes: description: Human-readable rationale or caveats for operators and Murph. type: string maxLength: 2000 required: - id - label - appliesWhen - hints - pricing - strength additionalProperties: false StorefrontPricingFactHintsOutput: description: >- Optional best-effort hints for matching a seller pricing fact. These are not product assembly rules; the Merchandising Agent still reasons over the natural-language appliesWhen field. type: object properties: channels: description: >- AdCP channel codes (e.g. `olv`, `ctv`, `dooh`) this fact applies to. Unlike the free-text hint categories, channels are matched as EXACT codes against the product's seller-declared `channels` plus the broad channel family inferred from its creative format kind — never as substrings of names, ids, or tags. So a fact scoped to `["ctv"]` applies only to products that declare `ctv`; a `video_hosted` format on its own resolves to the broad `video` family, which cannot distinguish `olv` from `ctv`. Within the array any code may match (OR); across hint categories every populated category must match (AND). maxItems: 32 type: array items: type: string minLength: 1 maxLength: 80 creativeTerms: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 publisherDomains: maxItems: 128 type: array items: type: string maxLength: 253 pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ countries: maxItems: 64 type: array items: type: string pattern: ^[A-Z0-9_-]{2,32}$ advertiserVerticals: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 seasonality: maxItems: 32 type: array items: type: string minLength: 1 maxLength: 120 signalTags: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 placementTags: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 120 additionalProperties: false StorefrontPricingFactPriceOutput: description: >- Value-pricing anchor extracted from seller rate cards, media kits, or operator instructions. type: object properties: pricingModel: description: >- AdCP pricing model this pricing fact anchors, sourced from the AdCP SDK vocabulary. A price shape the protocol has no model for — share of voice, a day-part premium — is a product-coverage gap to report, not a value to store. default: cpm type: string enum: - cpm - vcpm - cpc - cpcv - cpv - cpp - cpa - flat_rate - time currency: description: >- ISO 4217 currency for this pricing fact. Falls back to the storefront pricing currency when omitted. example: USD type: string minLength: 3 maxLength: 3 targetPrice: description: >- Preferred value-based buyer-facing price for this fact. This is a value anchor, not a cost-plus markup. type: number minimum: 0 exclusiveMinimum: true floorPrice: description: >- Hard minimum buyer-facing price when this fact applies. Composition also floors at wholesale cost/floor. type: number minimum: 0 ceilingPrice: description: Optional maximum buyer-facing price when this fact applies. type: number minimum: 0 exclusiveMinimum: true required: - pricingModel additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````