> ## 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.
# Create inventory source
> Register an external AdCP-compatible agent as an 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
```bash curl theme={null}
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": "" },
"description": "Primary external sales agent for on-site display and CTV"
}'
```
```json JWT auth theme={null}
{
"name": "Retail Network Agent",
"executionType": "AGENT",
"type": "SALES",
"endpointUrl": "https://agent.retail-network.example.com/mcp",
"protocol": "MCP",
"authenticationType": "JWT",
"auth": {
"type": "jwt",
"privateKey": "",
"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`:
```json theme={null}
{
"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](/v2/concepts/glossary) 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`](/v2/concepts/glossary) 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](/v2/reference/errors) for the full error contract.
## Related
All operations
Concepts and lifecycle
Change fields or rotate auth
End-to-end seller setup