Create inventory source

POST /api/v2/storefront/inventory-sources Creates an inventory source and registers its backing agent. External AGENT sources are created here. A pilot-enabled seller can also create a linked storefront source with LINKED_STOREFRONT that selects an approved storefront. That linked storefront source is always created PENDING; it cannot receive requests, book media, or be activated through this endpoint. MANAGED_SALES_AGENT and MODULAR_SOURCE rows use dedicated provisioning flows.

Request

curl -X POST https://api.apostra.com/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_CLIENT_CREDENTIALS",
  "auth": {
    "type": "oauth_client_credentials",
    "token_endpoint": "https://auth.retail-network.example.com/oauth/token",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>"
  }
}

{
  "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	Required for `AGENT`	Display name (1–255 chars). A linked storefront source receives its server-owned name.
`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	`AGENT` (default) or `LINKED_STOREFRONT` for the enabled linked storefront source pilot
`targetStorefrontId`	positive integer	Required for `LINKED_STOREFRONT`	Approved storefront to select. The owner comes from the authenticated storefront context, not this request. The linked storefront source remains `PENDING` and non-executable. Omit for `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`, `OAUTH`, or `OAUTH_CLIENT_CREDENTIALS`. Use `OAUTH` when a person signs in to approve access; use `OAUTH_CLIENT_CREDENTIALS` when the agent operator issued you a client ID and secret for its token endpoint. `NO_AUTH` is for testing and is accepted only from a Developer account; a new `NO_AUTH` connection from any other account is rejected. A new source that reuses an agent you already connected keeps that agent’s authentication
`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 for `JWT`. For `API_KEY`, `BASIC_AUTH` and `OAUTH_CLIENT_CREDENTIALS` it is optional — supply credentials now, or omit them to create the source `PENDING` and add them 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`). Client-credentials shape: see OAuth client credentials
`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. Apostra 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)

OAuth client credentials

Some agents accept only short-lived OAuth access tokens, which a client gets from the agent operator’s token endpoint with the OAuth 2.0 client-credentials grant (RFC 6749 §4.4). For these agents, set authenticationType to OAUTH_CLIENT_CREDENTIALS and send the client ID and secret the operator issued. Apostra requests an access token before it calls the agent and reuses it for up to five minutes, requesting a new one sooner if the token is about to expire. If the operator revokes a token early, calls can fail for up to five minutes until the next one is issued. No person needs to sign in, and there is no refresh token to manage. The auth object takes these fields:

type (required): oauth_client_credentials.
token_endpoint (required): the operator’s token endpoint. Must be a public HTTPS URL.
client_id (required): client ID issued by the agent operator.
client_secret (required): client secret issued by the agent operator. Stored encrypted and never returned.
scope (optional): space-separated scopes, when the operator requires them.
resource (optional): the protected resource the token is for (RFC 8707), as one URI or a list, when the operator’s authorization server requires it.
audience (optional): audience to request, when the operator’s authorization server requires one.
auth_method (optional): how the client ID and secret reach the token endpoint, either basic (HTTP Basic header, the default) or body (form fields). Use body only if the operator says its server does not accept basic.

You can also create the source without auth and enter the credentials in the secure credential form in chat. It asks for the token endpoint, client ID, client secret and client-authentication method, plus an optional scope and audience; resource can only be set through the API. To change any of these settings later, send the complete auth object again with update inventory source, or save them again in the credential form. Either way the new settings replace the stored ones, so saving from the form clears a resource that was set through the API.

Treat auth.token, client secrets, 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. 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. For an enabled LINKED_STOREFRONT pilot, send only its execution type and approved partner target:

{
  "executionType": "LINKED_STOREFRONT",
  "targetStorefrontId": 200
}

The response returns one durable pending relationship when the same target is submitted again. Missing, self, cross-account, or no-longer-approved targets fail without revealing the target’s state. A linked Source can be disabled with the normal update endpoint, but this release does not expose activation, selection, request forwarding, or booking. When attachToAgentId is supplied, Apostra 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 Merchandising plan (or the custom modular sources add-on) 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. Apostra 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 new NO_AUTH agent from an account that is not a Developer account, 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. A linked target that is absent, unauthorised, or otherwise unavailable also returns this generic result.
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

OAuth client credentials

Response

After connection

Errors

Inventory source tasks

Inventory sources overview

Update inventory source

Storefront onboarding

​Request

​Parameters

​OAuth client credentials

​Response

​After connection

​Errors

​Related

Inventory source tasks

Inventory sources overview

Update inventory source

Storefront onboarding

Request

Parameters

OAuth client credentials

Response

After connection

Errors

Related