Create inventory source

POST /api/v2/storefront/inventory-sources Creates an inventory source and registers its backing agent. Only external AGENT sources are created here — MANAGED_SALES_AGENT, LINKED_STOREFRONT, and MODULAR_SOURCE rows are created through their own provisioning and linking flows.

Request

curl -X POST https://api.interchange.io/api/v2/storefront/inventory-sources \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "retail-network-agent",
    "name": "Retail Network Agent",
    "executionType": "AGENT",
    "type": "SALES",
    "endpointUrl": "https://agent.retail-network.example.com/mcp",
    "protocol": "MCP",
    "authenticationType": "API_KEY",
    "connectionContract": {
      "id": "external-sales-agent",
      "version": 1,
      "authenticationMethod": "bearer_token"
    },
    "auth": { "type": "bearer", "token": "<SOURCE_API_KEY>" },
    "description": "Primary external sales agent for on-site display and CTV"
  }'

{
  "name": "Retail Network Agent",
  "executionType": "AGENT",
  "type": "SALES",
  "endpointUrl": "https://agent.retail-network.example.com/mcp",
  "protocol": "MCP",
  "authenticationType": "JWT",
  "auth": {
    "type": "jwt",
    "privateKey": "<PRIVATE_KEY>",
    "issuer": "https://retail-network.example.com",
    "subject": "retail-sales",
    "keyId": "key-1",
    "scope": "agent:invoke",
    "tokenEndpointUrl": "https://auth.retail-network.example.com/oauth/token",
    "audienceUrl": "https://agent.retail-network.example.com/mcp"
  }
}

{
  "name": "Retail Network Agent",
  "executionType": "AGENT",
  "type": "SALES",
  "endpointUrl": "https://agent.retail-network.example.com/mcp",
  "protocol": "MCP",
  "authenticationType": "OAUTH",
  "oauthAudience": "https://platform.retail-network.example.com"
}

Parameters

Field	Type	Required	Notes
`name`	string	Yes	Display name (1–255 chars)
`sourceId`	string	No	Storefront-scoped ID (1–255 chars). Defaults to a slugified `name`
`attachToAgentId`	string (UUID)	No	ID of an organization-owned Sales Agent to attach to the new Source. Creation and attachment succeed together or neither is created.
`agentProductMode`	enum	Conditional	Per-Source product-path choice when the Agent named by `attachToAgentId` declares `BOTH`: `WHOLESALE`, `COMPOSING`, or `BOTH`. Omit it for single-mode or undeclared Agents.
`executionType`	enum	No	Only `AGENT` is accepted here. Default `AGENT`
`type`	enum	Yes (for `AGENT`)	`SALES`, `SIGNAL`, `CREATIVE`, or `OUTCOME`
`endpointUrl`	string (uri)	Yes (for `AGENT`)	Executable agent URL from the selected AAO `authorized_agents[].url` entry (max 2048). Do not use a publisher’s `adagents.json` URL or its `authoritative_location`
`protocol`	enum	Yes (for `AGENT`)	`MCP` or `A2A`
`authenticationType`	enum	Yes (for `AGENT`)	`API_KEY`, `JWT`, `BASIC_AUTH`, `NO_AUTH`, or `OAUTH`
`connectionContract`	object	No	Pins a migrated setup definition by `id`, `version`, and typed `authenticationMethod`. The external sales-agent Task sends `external-sales-agent:v1`. Omit for the legacy compatibility path. An explicit unknown version or a method that conflicts with `authenticationType`/`auth` is rejected.
`auth`	object	Conditional	Required only for `JWT`. For `API_KEY` and `BASIC_AUTH` it is optional — supply credentials now, or omit them to create the source `PENDING` and add the secret later (e.g. through the secure credential form). Omit for `OAUTH` and `NO_AUTH`. API-key shape: `{ type: "bearer"\|"apikey"\|"api_key", token }`. Basic shape: `{ type: "basic", username, password }`. JWT shape: `{ type: "jwt", privateKey, issuer, subject, keyId, scope, tokenEndpointUrl, audienceUrl, algorithm?, environment? }` (`algorithm` is `ES256` or `RS256`)
`oauthAudience`	string (public URI)	No	Compatibility override for a newly registered `OAUTH` identity whose gateway validates a resource-specific audience but does not publish it through RFC 9728 protected-resource metadata. Interchange sends the value as both Auth0 `audience` and RFC 8707 `resource`. Omit it when protected-resource discovery supplies the resource. If the endpoint reuses an existing identity, its stored OAuth configuration is reused; update the existing source first to change the audience.
`description`	string	No	Agent description (max 2000)

Treat auth.token and JWT private keys as production secrets. They are encrypted at rest, referenced only by an opaque ref, and never echoed back — responses surface authConfigured: true. Never log or commit raw credentials.

For external-sales-agent:v1, use bearer_token with auth.type: "bearer", basic_auth with auth.type: "basic", or none without auth. The shared contract schema also has typed API-key, OAuth 2.0, JWT, and platform-service-account methods for integrations that register those methods. Authentication is a closed platform-owned set; requests cannot install executable header or request templates.

Response

201 Created with the new InventorySourceResponse:

{
  "id": "900123456789",
  "sourceId": "retail-network-agent",
  "name": "Retail Network Agent",
  "executionType": "AGENT",
  "status": "PENDING",
  "agentId": "agent_01HX...",
  "type": "SALES",
  "endpointUrl": "https://agent.retail-network.example.com/mcp",
  "protocol": "MCP",
  "authenticationType": "API_KEY",
  "authConfigured": true,
  "isAdapterSource": false,
  "createdAt": "2026-04-25T12:05:00Z",
  "updatedAt": "2026-04-25T12:05:00Z"
}

Every external AGENT source is created in status: "PENDING", including a NO_AUTH source, and proceeds through the normal registration and readiness workflow before activation. Reachability is reported independently by source health and connectivity checks. For a newly registered OAUTH identity, the response includes oauth.authorizationUrl when authorization discovery and flow storage succeed; redirect the operator there to complete consent. If the source is created without that block, start consent with Start agent OAuth. Complete authorization even when oauthAudience was supplied—the override selects the token resource; it is not a credential. If the endpoint reuses an existing identity, create reuses its OAuth configuration and does not reinitialize consent; update an existing source first when the audience or authorization must change. When attachToAgentId is supplied, Interchange creates the Source and attaches it to that exact organization-owned Sales Agent as one operation. The response returns the attached Agent in agentCapabilityUid. If the request response is interrupted, return to that Agent’s Inventory sources section and refresh before sending another create request: a committed Source appears there already. Do not blindly resubmit an ambiguous request. If the Agent declares both product paths, agentProductMode records how this Source participates: Storefront-built catalog (WHOLESALE), Agent-supplied products (COMPOSING), or both (BOTH). The Agent declaration is re-read by the server; the launch payload is only presentation guidance. Connecting checks that the agent’s endpointUrl is registered with the AAO registry. If the agent is not registered, the request is rejected with 400 VALIDATION_ERROR. If the registry cannot be reached to perform the check, the request returns 503 SERVICE_UNAVAILABLE — a transient connectivity problem, not a rejection of the agent, so retrying usually succeeds.

An adagents.json file identifies which agents a publisher authorizes; it is not an agent endpoint. When starting from a publisher domain, resolve its file through AAO and copy the selected agent’s authorized_agents[].url. Do not copy the publisher well-known URL, AAO hosting.resolved_url, or the document’s authoritative_location into endpointUrl.

After connection

Once connected, an external AGENT source can either answer buyer briefs live on the Agent-supplied path — available on any account, including an account with Listing + Distribution that keeps routing briefs through its own agent — or provide cached components for the Storefront-built path, which requires a separate Merchandising entitlement and a source that supports component caching. To support component caching, the agent’s product response must expose stable raw products: ids, names/descriptions, pricing options, formats, publisher properties or other inventory selectors, delivery type, and enough execution metadata to route a selected product later. Murph reports component-cache problems separately from live source-call failures.

Registering the agent is not the same as authorizing it to sell a publisher’s inventory. This connect-time check only confirms the agent is registered in the AAO registry. Whether a publisher’s adagents.json authorizes that agent to sell their inventory is a separate question, surfaced later as an advisory setup/product signal today — not at connect time. A registered agent can be connected and still be unauthorized for a given publisher’s inventory.

Errors

400 VALIDATION_ERROR — missing required field, a non-public endpoint or oauthAudience, auth supplied for an OAUTH/NO_AUTH agent, auth missing for a JWT agent, a malformed attachToAgentId, or the agent’s endpoint is not registered with the AAO registry. An adagents.json or authoritative_location document is also rejected as endpointUrl. (Agent registration is distinct from publisher authorization — see the note above.)
401 UNAUTHORIZED — missing or invalid API key.
403 ACCESS_DENIED — attachToAgentId identifies an Agent owned by another organization or one the caller cannot administer.
404 NOT_FOUND — attachToAgentId is unavailable in this organization, or the Agent workspace is not enabled for the account.
503 SERVICE_UNAVAILABLE — the AAO registry could not be reached to verify the agent’s registration. This is transient; retry the request.

See Errors for the full error contract.

Inventory source tasks

All operations

Inventory sources overview

Concepts and lifecycle

Update inventory source

Change fields or rotate auth

Storefront onboarding

End-to-end seller setup

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Create inventory source

Request

Parameters

Response

After connection

Errors

Inventory source tasks

Inventory sources overview

Update inventory source

Storefront onboarding

​Request

​Parameters

​Response

​After connection

​Errors

​Related

Inventory source tasks

Inventory sources overview

Update inventory source

Storefront onboarding

Request

Parameters

Response

After connection

Errors

Related