Skip to main content
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"
  }'

​
Parameters

FieldTypeRequiredNotes
namestringYesDisplay name (1–255 chars)
sourceIdstringNoStorefront-scoped ID (1–255 chars). Defaults to a slugified name
executionTypeenumNoOnly AGENT is accepted here. Default AGENT
typeenumYes (for AGENT)SALES, SIGNAL, CREATIVE, or OUTCOME
endpointUrlstring (uri)Yes (for AGENT)Agent endpoint URL (max 2048)
protocolenumYes (for AGENT)MCP or A2A
authenticationTypeenumYes (for AGENT)API_KEY, JWT, BASIC_AUTH, NO_AUTH, or OAUTH
authobjectConditionalRequired for API_KEY, JWT, and BASIC_AUTH; 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)
descriptionstringNoAgent 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. The agent’s endpointUrl must be registered with AAO or the request is rejected.

​
Errors

  • 400 VALIDATION_ERROR — missing required field, auth supplied for an OAUTH/NO_AUTH agent, auth missing for API_KEY/JWT, or the agent is not registered with AAO.
  • 401 UNAUTHORIZED — missing or invalid API key.
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