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",
    "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"
  }
}

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`
`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`)	Agent endpoint URL (max 2048)
`protocol`	enum	Yes (for `AGENT`)	`MCP` or `A2A`
`authenticationType`	enum	Yes (for `AGENT`)	`API_KEY`, `JWT`, `BASIC_AUTH`, `NO_AUTH`, or `OAUTH`
`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`)
`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.

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"
}

The source is created in status: "PENDING" and auto-activates once the agent is reachable with the credential. For OAUTH agents the response includes an oauth.authorizationUrl to redirect the operator to. For NO_AUTH agents the source is ACTIVE immediately. 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.

After connection

Once connected, an external AGENT source can either answer buyer briefs live through passthrough, or provide cached components for merchandising. 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, auth supplied for an OAUTH/NO_AUTH agent, auth missing for a JWT agent, or the agent’s endpoint is not registered with the AAO registry. (Agent registration is distinct from publisher authorization — see the note above.)
401 UNAUTHORIZED — missing or invalid API key.
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

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

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