> ## 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. # Create inventory source > Create an inventory source and optionally register an agent for it. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml post /inventory-sources 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: /inventory-sources: post: tags: - Storefront summary: Create inventory source description: Create an inventory source and optionally register an agent for it. operationId: createInventorySource requestBody: required: true content: application/json: schema: type: object properties: connectionContract: description: >- Pinned connection contract used to validate this setup. Omit only for integrations that have not migrated to connection contracts yet. type: object properties: id: type: string minLength: 1 maxLength: 128 pattern: ^[a-z][a-z0-9_-]*$ version: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 authenticationMethod: type: string enum: - none - bearer_token - api_key - credential_exchange - basic_auth - oauth2 - jwt - platform_service_account required: - id - version - authenticationMethod additionalProperties: false sourceId: description: >- Unique identifier for this source within the storefront. Defaults to a slugified version of the name if not provided. example: retail-network-agent type: string minLength: 1 maxLength: 255 attachToAgentId: description: >- Optional organization-owned Sales Agent to attach in the same server-authoritative operation. The request fails before Source creation when the Agent is not an eligible first-party binding target. 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)$ agentProductMode: description: >- Required with attachToAgentId only when the selected Sales Agent declares both product paths. Choose WHOLESALE for a Storefront-built catalog, COMPOSING for Agent-supplied products, or BOTH to enable both paths for this Source. type: string enum: - WHOLESALE - COMPOSING - BOTH name: type: string minLength: 1 maxLength: 255 description: Display name for the inventory source example: Retail Network Agent executionType: default: AGENT description: >- Only external `AGENT` inventory sources can be created through this endpoint. `MANAGED_SALES_AGENT` and `MODULAR_SOURCE` rows are created by their dedicated provisioning flows; `LINKED_STOREFRONT` sources cannot be created and are not admitted until linked sellers have canonical Source representation. Storefront-level `ADAPTER` dispatch is configured on the storefront, not as an inventory source. type: string enum: - AGENT type: description: Agent type — required when executionType is "AGENT" type: string enum: - SALES - SIGNAL - CREATIVE - OUTCOME endpointUrl: description: >- Executable agent endpoint URL from authorized_agents[].url — required when executionType is "AGENT". Do not use an adagents.json authoritative_location. type: string maxLength: 2048 format: uri protocol: description: Agent protocol — required when executionType is "AGENT" type: string enum: - MCP - A2A authenticationType: description: >- Auth method for the agent — required when executionType is "AGENT" type: string enum: - API_KEY - NO_AUTH - JWT - OAUTH - BASIC_AUTH auth: description: >- Optional for most schemes. NO_AUTH sources need no credentials at all, and OAUTH sources are authorized through their own flow — neither carries an `auth` payload. BASIC_AUTH and API_KEY sources may include credentials here, or be created without them and start PENDING, with the secret collected later through the secure credential form rather than at create time (for BASIC_AUTH use { type: "basic", username, password }). JWT is the exception: its secret must be supplied here at create time, because the secure credential form cannot collect JWT yet. anyOf: - type: object properties: type: type: string enum: - jwt privateKey: type: string minLength: 1 issuer: type: string minLength: 1 subject: type: string minLength: 1 keyId: type: string minLength: 1 scope: type: string minLength: 1 tokenEndpointUrl: type: string format: uri audienceUrl: type: string format: uri algorithm: type: string enum: - ES256 - RS256 environment: type: string required: - type - privateKey - issuer - subject - keyId - scope - tokenEndpointUrl - audienceUrl - type: object properties: type: type: string enum: - bearer - apikey - api_key token: type: string minLength: 1 required: - type - token - type: object properties: type: type: string enum: - basic username: type: string minLength: 1 password: type: string required: - type - username - password - type: object properties: {} additionalProperties: false oauthAudience: description: >- OAuth audience / resource indicator for a newly registered OAUTH agent identity (the protected-resource URI the agent gateway validates, e.g. "https://platform.example.com"). When set, the OAuth flow requests a token whose `aud` claim targets this resource (sent as both Auth0 `audience` and RFC 8707 `resource`). Leave unset to auto-discover it from the agent's RFC 9728 protected-resource metadata. If the endpoint reuses an existing identity, that identity's OAuth configuration is reused; update the existing source first to change its audience. example: https://platform.example.com type: string maxLength: 2048 format: uri description: description: Agent description type: string maxLength: 2000 required: - name description: Request body for creating an inventory source allOf: - $ref: '#/components/schemas/CreateInventorySourceBody' responses: '201': description: Create inventory source content: application/json: schema: $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: CreateInventorySourceBody: type: object properties: connectionContract: description: >- Pinned connection contract used to validate this setup. Omit only for integrations that have not migrated to connection contracts yet. type: object properties: id: type: string minLength: 1 maxLength: 128 pattern: ^[a-z][a-z0-9_-]*$ version: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 authenticationMethod: type: string enum: - none - bearer_token - api_key - credential_exchange - basic_auth - oauth2 - jwt - platform_service_account required: - id - version - authenticationMethod additionalProperties: false sourceId: description: >- Unique identifier for this source within the storefront. Defaults to a slugified version of the name if not provided. example: retail-network-agent type: string minLength: 1 maxLength: 255 attachToAgentId: description: >- Optional organization-owned Sales Agent to attach in the same server-authoritative operation. The request fails before Source creation when the Agent is not an eligible first-party binding target. 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)$ agentProductMode: description: >- Required with attachToAgentId only when the selected Sales Agent declares both product paths. Choose WHOLESALE for a Storefront-built catalog, COMPOSING for Agent-supplied products, or BOTH to enable both paths for this Source. type: string enum: - WHOLESALE - COMPOSING - BOTH name: type: string minLength: 1 maxLength: 255 description: Display name for the inventory source example: Retail Network Agent executionType: default: AGENT description: >- Only external `AGENT` inventory sources can be created through this endpoint. `MANAGED_SALES_AGENT` and `MODULAR_SOURCE` rows are created by their dedicated provisioning flows; `LINKED_STOREFRONT` sources cannot be created and are not admitted until linked sellers have canonical Source representation. Storefront-level `ADAPTER` dispatch is configured on the storefront, not as an inventory source. type: string enum: - AGENT type: description: Agent type — required when executionType is "AGENT" type: string enum: - SALES - SIGNAL - CREATIVE - OUTCOME endpointUrl: description: >- Executable agent endpoint URL from authorized_agents[].url — required when executionType is "AGENT". Do not use an adagents.json authoritative_location. type: string maxLength: 2048 format: uri protocol: description: Agent protocol — required when executionType is "AGENT" type: string enum: - MCP - A2A authenticationType: description: Auth method for the agent — required when executionType is "AGENT" type: string enum: - API_KEY - NO_AUTH - JWT - OAUTH - BASIC_AUTH auth: description: >- Optional for most schemes. NO_AUTH sources need no credentials at all, and OAUTH sources are authorized through their own flow — neither carries an `auth` payload. BASIC_AUTH and API_KEY sources may include credentials here, or be created without them and start PENDING, with the secret collected later through the secure credential form rather than at create time (for BASIC_AUTH use { type: "basic", username, password }). JWT is the exception: its secret must be supplied here at create time, because the secure credential form cannot collect JWT yet. anyOf: - type: object properties: type: type: string enum: - jwt privateKey: type: string minLength: 1 issuer: type: string minLength: 1 subject: type: string minLength: 1 keyId: type: string minLength: 1 scope: type: string minLength: 1 tokenEndpointUrl: type: string format: uri audienceUrl: type: string format: uri algorithm: type: string enum: - ES256 - RS256 environment: type: string required: - type - privateKey - issuer - subject - keyId - scope - tokenEndpointUrl - audienceUrl - type: object properties: type: type: string enum: - bearer - apikey - api_key token: type: string minLength: 1 required: - type - token - type: object properties: type: type: string enum: - basic username: type: string minLength: 1 password: type: string required: - type - username - password - type: object properties: {} additionalProperties: false oauthAudience: description: >- OAuth audience / resource indicator for a newly registered OAUTH agent identity (the protected-resource URI the agent gateway validates, e.g. "https://platform.example.com"). When set, the OAuth flow requests a token whose `aud` claim targets this resource (sent as both Auth0 `audience` and RFC 8707 `resource`). Leave unset to auto-discover it from the agent's RFC 9728 protected-resource metadata. If the endpoint reuses an existing identity, that identity's OAuth configuration is reused; update the existing source first to change its audience. example: https://platform.example.com type: string maxLength: 2048 format: uri description: description: Agent description type: string maxLength: 2000 required: - name description: Request body for creating an inventory source InventorySourceResponse: type: object properties: id: type: string 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). sourceId: type: string 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. name: type: string description: Display name executionType: type: string enum: - AGENT - MANAGED_SALES_AGENT - LINKED_STOREFRONT - MODULAR_SOURCE description: Execution type 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: type: string enum: - PENDING - ACTIVE - DISABLED description: Source lifecycle status agentId: nullable: true description: Linked agent ID (when executionType is agent) 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. The version-1 ambient storefront-interchange pool has no canonical Source identity and therefore cannot populate this per-Source projection. 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: 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))$ description: Creation timestamp (ISO 8601) updatedAt: 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))$ description: Last update timestamp (ISO 8601) required: - id - sourceId - name - executionType - status - agentId - createdAt - updatedAt additionalProperties: false description: Inventory source response 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 ManagedSalesAgentSummary: type: object properties: connectionId: type: string 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. tenantId: nullable: true description: >- Upstream tenant id for the managed ad-server source. Null until provisioning succeeds. type: string adServer: nullable: true description: Publisher-supplied ad-server config. Null if not yet collected. allOf: - $ref: '#/components/schemas/AdServerConfigView' lastError: nullable: true description: >- Failure reason from the most recent provisioning or test-connection attempt. type: string lastErrorCode: nullable: true 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. 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 description: >- Read-only managed ad-server source state for inventory sources with `executionType=MANAGED_SALES_AGENT`. LinkedStorefrontSummary: type: object properties: status: type: string enum: - PENDING - ACTIVE - REJECTED - CANCELLED description: >- Retired. Storefront interchange no longer uses per-counterparty links; this enum is retained only for response-shape stability and is never emitted. 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: nullable: true description: Which side stopped the link. Null until status is `CANCELLED`. type: string enum: - BUYER - SELLER required: - status - buyer - seller - requestMessage - responseMessage - requestedAt - respondedAt - cancelledAt - cancelledBy additionalProperties: false description: >- Retired. Never populated. The version-1 ambient compatibility pool has no canonical Source identity and therefore cannot populate this per-Source projection. Retained as a reserved, always-null component for response-shape stability. 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 AdServerConfigView: oneOf: - type: object properties: type: type: string enum: - google_ad_manager networkCode: type: string minLength: 1 maxLength: 32 pattern: ^[0-9]+$ description: Google Ad Manager network code. example: '12345678' 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 description: >- Non-secret view of the connection ad-server config. Returned by GET endpoints; never contains credentials. type: object StorefrontResponse: type: object properties: storefrontId: type: string description: Surrogate id (BIGINT serialized as string) example: '1234' platformId: type: string description: Public-facing slug example: acme-media name: type: string description: Display name example: Acme Media publisherDomain: nullable: true description: Publisher domain for the storefront's business profile example: acme.com type: string operatorDomain: nullable: true description: Canonical brand domain example: scope3.com type: string brandName: nullable: true description: Brand name from AAO registry example: Scope3 type: string logoUrl: nullable: true description: Logo URL from brand.json 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: nullable: true description: AAO membership tier. Null when the operator has not set a value. type: string enum: - AAO_FOUNDING_MEMBER - AAO_MEMBER - NONE regions: type: array items: type: string description: >- Legacy merchandising-region context projected from businessProfile. This does not govern brief acceptance or listing country coverage. acceptedCountries: nullable: true description: >- Operator-confirmed exhaustive country allowlist for brief routing. Null means routing scope has not been confirmed. type: array items: type: string pattern: ^[A-Z]{2}$ acceptsAllCountries: type: boolean description: Whether the operator explicitly accepts briefs from every country. advertisingPolicyDisclosure: type: array items: type: string enum: - brief_acceptance - creative_policy description: >- An AI Business Rules section the seller elects to disclose publicly as Advertising Policies on its listing. description: >- Seller-selected AI Business Rules sections disclosed publicly as Advertising Policies. Empty means no local disclosure. advertisedCountries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- Standard primary countries advertised by backing AdCP sales agents. Authoritative for the listing on a pure pass-through storefront; inventory evidence otherwise. advertisedChannels: type: array items: type: string description: >- Standard primary channels advertised by backing AdCP sales agents. Authoritative for the listing on a pure pass-through storefront; inventory evidence otherwise. description: nullable: true description: Operator-curated description (overrides brand.json). type: string channels: type: array items: type: string description: ADCP channel codes the storefront offers. website: nullable: true description: Operator-curated website URL (overrides brand.json). type: string subtitle: nullable: true description: >- Short operator-authored tagline, projected by every marketplace channel listing. Null when unset. type: string supportUrl: nullable: true description: >- Operator-curated support/contact URL, projected by every marketplace channel listing. Null when unset. type: string privacyUrl: nullable: true description: >- Operator-curated privacy policy URL, projected by every marketplace channel listing. Null when unset. type: string termsUrl: nullable: true description: >- Operator-curated Terms of Service URL, projected by every marketplace channel listing. Null when unset. type: string discoveryCard: description: >- Canonical buyer-visible storefront identity and coverage. This is distinct from the legacy Business Profile merchandising inputs and seller policies. allOf: - $ref: '#/components/schemas/DiscoveryCard' demandContactName: nullable: true description: Demand contact name. Null when the operator has not set one. type: string demandContactEmail: nullable: true description: Demand contact email. Null when the operator has not set one. type: string operatorDomainVerified: type: boolean description: >- Whether the brand domain has been verified (email match or manual KYC) routingMode: type: string enum: - CHEF - ADAPTER description: >- Which backend function the buyer-facing storefront dispatches to: the Merchandising Agent or an expert-run adapter. adapterProviderType: nullable: true description: >- Expert-run adapter provider when routingMode is `ADAPTER`; null otherwise. type: string enum: - amazon - audiostack - elevenlabs - fal - gemini - google - linkedin - meta - openai - openai_ads - pinterest - reddit - snap - spotify - tiktok - veo adapterSourceKind: nullable: true description: Adapter role when routingMode is `ADAPTER`; null otherwise. type: string enum: - sales - creative - signals - measurement - optimization - composite adapterCredentialMode: nullable: true description: >- Adapter credential mode when routingMode is `ADAPTER`; null otherwise. type: string enum: - BYOK plan: type: string enum: - basic description: Legacy v2 Seller Account plan tier transacting: type: boolean description: >- Deprecated compatibility projection of `!isPaused`; not proof that the storefront currently satisfies readiness. isPaused: type: boolean 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. archivedAt: nullable: true description: >- When the storefront was archived (read-only thereafter). Null for non-archived storefronts. 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: type: string enum: - configuring - transacting - archived - neutral - paused description: >- Deprecated stored-control display status. This is never proof that the storefront can transact; use the readiness projection. 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' merchandisingEntitled: type: boolean description: >- Whether the Seller Account commercial plan entitles it to Merchandising. This is a server-derived commercial fact, separate from needing a connected source that is ready to supply products your storefront can sell, such as an ad server. listingDistributionEntitled: type: boolean description: >- Whether the Seller Account commercial plan entitles it to Listing + Distribution. This is independent from Merchandising and from the connected sales agent that fulfills the listing. 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: >- Compatibility record of the reversible signup package choice, or null when none was selected. It is not a behavioral mode: what the storefront exposes is always the derived `capabilities` and its Source treatment. nullable: true type: string enum: - third_party_connect - sell_through_scope3 operatingMode: description: >- Derived display value for the mutable supply operating capabilities. Null means a legacy account has not selected a mode yet. nullable: true type: string enum: - LISTING_ONLY - AGENTIC_MEDIA_COMPANY operatingCapabilities: description: >- Mutable account capabilities for listing and Scope3 merchandising. Listing is always enabled after selection; null means a legacy account has not selected a product yet. nullable: true type: object properties: listingSelected: type: boolean enum: - true scope3MerchandisingSelected: type: boolean required: - listingSelected - scope3MerchandisingSelected additionalProperties: false 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: type: string enum: - auto - manual description: >- Stored operator setting for creative submissions. It applies at Interchange-managed review checkpoints; a connected sales agent or downstream source may enforce additional source-native review. mediaBuyApproval: type: string enum: - auto - manual description: >- Stored operator setting for new media buys. It applies when the storefront exposes an Interchange-managed campaign-approval checkpoint; a connected sales agent or downstream source may enforce additional source-native review. capabilitiesLocked: type: boolean 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. advertiseAsAgent: type: boolean 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. 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: 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))$ description: Creation timestamp (ISO 8601) updatedAt: 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))$ description: Last update timestamp (ISO 8601) businessProfile: nullable: true description: >- Operator-supplied business profile captured during Murph-led setup. Null when the operator has not shared one. allOf: - $ref: '#/components/schemas/BusinessProfileOutput' defaultCurrency: description: >- Seller-confirmed primary settlement currency (ISO-4217). Null until confirmed; required before go-live for Interchange-cleared Seller Accounts. Direct sales adapter Seller Accounts 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 Seller Account 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 - subtitle - supportUrl - privacyUrl - termsUrl - discoveryCard - demandContactName - demandContactEmail - operatorDomainVerified - routingMode - adapterProviderType - adapterSourceKind - adapterCredentialMode - plan - transacting - isPaused - archivedAt - displayStatus - capabilities - merchandisingEntitled - listingDistributionEntitled - configuredCapabilities - compositionPricing - creativeApproval - mediaBuyApproval - capabilitiesLocked - advertiseAsAgent - createdAt - updatedAt - businessProfile additionalProperties: false description: Storefront configuration response DiscoveryCard: 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: type: array items: type: string description: >- Aggregate channel facets for search and display. Do not combine these with aggregate countries as a cross-product coverage promise. countries: type: array items: type: string pattern: ^[A-Z]{2}$ 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. acceptsAllCountries: type: boolean description: >- True only when the storefront explicitly accepts briefs from every country. coverageDeclarations: type: array items: type: object properties: channels: type: array items: type: string description: Channels accepted by this correlated source declaration. countries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- ISO 3166-1 alpha-2 countries accepted by this correlated source declaration. acceptsAllCountries: type: boolean description: >- True only when this correlated source declaration explicitly accepts every country. required: - channels - countries - acceptsAllCountries additionalProperties: false description: >- One source-level coverage claim. Channels and countries are correlated within this declaration; an empty dimension is unknown, not unrestricted. description: >- Channel and country coverage claims preserved at their source boundaries. A combined filter matches only when one declaration satisfies both dimensions. 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 description: >- Canonical buyer-visible storefront identity, coverage declaration, and optional Advertising Policies disclosure. Unknown coverage never means worldwide or all channels. StorefrontCapabilities: type: object properties: offersCreativeReview: default: false 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. type: boolean offersCampaignApproval: default: false 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. type: boolean offersProductComposition: default: false 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`). type: boolean required: - offersCreativeReview - offersCampaignApproval - offersProductComposition additionalProperties: false description: >- Which AdCP capabilities the storefront advertises to buyers. Product composition is derived from Source product-path readiness and entitlement. StorefrontCompositionPricingOutput: type: object properties: targetPercentile: default: p75 type: string enum: - p50 - p75 - p90 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. rateCard: default: facts: [] description: >- Seller product-pricing facts. Separate from Scope3 contract rate cards. type: object properties: currency: description: >- Default ISO 4217 currency for pricing facts in this Seller Account 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 description: >- Storefront composition pricing settings: fallback guidance percentile plus lightly structured seller pricing facts. BusinessProfileOutput: 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 — the full AdCP MediaChannel vocabulary (e.g. display, olv, ctv, social, streaming_audio, dooh, ...), plus the legacy `audio`/`video` aliases. maxItems: 22 type: array items: type: string enum: - display - olv - social - search - ctv - linear_tv - radio - streaming_audio - podcast - dooh - ooh - print - cinema - email - gaming - retail_media - influencer - affiliate - product_placement - sponsored_intelligence - audio - video description: Channel. 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 description: >- Operator-supplied business profile captured by Murph during storefront setup. StorefrontPricingFactOutput: type: object properties: id: type: string minLength: 1 maxLength: 120 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ description: >- Stable operator-facing id for this pricing fact. Murph should preserve ids across rewrites when the fact is semantically the same. label: type: string minLength: 1 maxLength: 160 description: Short display label for this pricing fact. example: Rich media packages appliesWhen: type: string minLength: 1 maxLength: 2000 description: >- Natural-language applicability condition. This is intentionally not a rigid product template; the Merchandising Agent uses it as reasoning context. hints: default: {} description: >- Optional structured hints for deterministic matching. Missing hints are fine. allOf: - $ref: '#/components/schemas/StorefrontPricingFactHintsOutput' pricing: $ref: '#/components/schemas/StorefrontPricingFactPriceOutput' strength: default: default type: string enum: - hard_floor - default - guidance description: >- `hard_floor` is a must-not-go-below seller constraint. `default` is the preferred value-pricing anchor. `guidance` is advisory context only. 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 description: >- Lightly structured seller value-pricing fact. Pricing facts anchor prices and floors; they are not product assembly templates. StorefrontPricingFactHintsOutput: 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 formatDimensions: description: >- Creative dimensions this fact applies to. A fact matches when at least one pair is admitted by a selected canonical format option: an exact width/height pair must equal it, sizes[] must contain it, and min/max bounds must include it. Unselected options on the same inventory bundle do not count. Within the array any pair may match (OR); across hint categories every populated category must match (AND). maxItems: 64 type: array items: type: object properties: width: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 height: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - width - height additionalProperties: false additionalProperties: false 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. StorefrontPricingFactPriceOutput: type: object properties: pricingModel: default: cpm 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. type: string enum: - cpm - vcpm - cpc - cpcv - cpv - cpp - cpa - revenue_share - flat_rate - time currency: description: >- ISO 4217 currency for this pricing fact. Falls back to the Seller Account 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 description: >- Value-pricing anchor extracted from seller rate cards, media kits, or operator instructions. securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````