Skip to main content
POST
Create inventory source

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json

Request body for creating an inventory source

​
name
string
required

Display name for the inventory source

Required string length: 1 - 255
Example:

"Retail Network Agent"

​
connectionContract
object

Pinned connection contract used to validate this setup. Omit only for integrations that have not migrated to connection contracts yet.

​
sourceId
string

Unique identifier for this source within the storefront. Defaults to a slugified version of the name if not provided.

Required string length: 1 - 255
Example:

"retail-network-agent"

​
attachToAgentId
string<uuid>

Optional organization-owned Sales Agent to attach in the same server-authoritative operation. The request fails before Source creation when the Agent is not an eligible first-party binding target.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
agentProductMode
enum<string>

Required with attachToAgentId only when the selected Sales Agent declares both product paths. Choose WHOLESALE for a Storefront-built catalog, COMPOSING for Agent-supplied products, or BOTH to enable both paths for this Source.

Available options:
WHOLESALE,
COMPOSING,
BOTH
​
executionType
enum<string>
default:AGENT

Only external AGENT inventory sources can be created through this endpoint. MANAGED_SALES_AGENT and MODULAR_SOURCE rows are created by their dedicated provisioning flows; LINKED_STOREFRONT sources cannot be created and are not admitted until linked sellers have canonical Source representation. Storefront-level ADAPTER dispatch is configured on the storefront, not as an inventory source.

Available options:
AGENT
​
type
enum<string>

Agent type — required when executionType is "AGENT"

Available options:
SALES,
SIGNAL,
CREATIVE,
OUTCOME
​
endpointUrl
string<uri>

Executable agent endpoint URL from authorized_agents[].url — required when executionType is "AGENT". Do not use an adagents.json authoritative_location.

Maximum string length: 2048
​
protocol
enum<string>

Agent protocol — required when executionType is "AGENT"

Available options:
MCP,
A2A
​
authenticationType
enum<string>

Auth method for the agent — required when executionType is "AGENT"

Available options:
API_KEY,
NO_AUTH,
JWT,
OAUTH,
BASIC_AUTH
​
auth
object

Optional for most schemes. NO_AUTH sources need no credentials at all, and OAUTH sources are authorized through their own flow — neither carries an auth payload. BASIC_AUTH and API_KEY sources may include credentials here, or be created without them and start PENDING, with the secret collected later through the secure credential form rather than at create time (for BASIC_AUTH use { type: "basic", username, password }). JWT is the exception: its secret must be supplied here at create time, because the secure credential form cannot collect JWT yet.

​
oauthAudience
string<uri>

OAuth audience / resource indicator for a newly registered OAUTH agent identity (the protected-resource URI the agent gateway validates, e.g. "https://platform.example.com"). When set, the OAuth flow requests a token whose aud claim targets this resource (sent as both Auth0 audience and RFC 8707 resource). Leave unset to auto-discover it from the agent's RFC 9728 protected-resource metadata. If the endpoint reuses an existing identity, that identity's OAuth configuration is reused; update the existing source first to change its audience.

Maximum string length: 2048
Example:

"https://platform.example.com"

​
description
string

Agent description

Maximum string length: 2000

Response

Create inventory source

Inventory source response

​
id
string
required

Globally unique surrogate id (BIGINT serialized as string). Use this when acting on rows the caller does not own (e.g. a seller approving an inbound link).

​
sourceId
string
required

Storefront-scoped identifier — unique within the row owner's storefront. Use this for actions on the caller's own rows; use id for cross-customer actions.

​
name
string
required

Display name

​
executionType
enum<string>
required

Execution type

Available options:
AGENT,
MANAGED_SALES_AGENT,
LINKED_STOREFRONT,
MODULAR_SOURCE
​
status
enum<string>
required

Source lifecycle status

Available options:
PENDING,
ACTIVE,
DISABLED
​
agentId
string | null
required

Linked agent ID (when executionType is agent)

​
createdAt
string<date-time>
required

Creation timestamp (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
updatedAt
string<date-time>
required

Last update timestamp (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
connectionType
enum<string>

Public connection family for a preconfigured ad-server source. Omitted for other inventory-source families.

Available options:
AD_SERVER
​
adServerProvider
enum<string>

Ad-server provider for a preconfigured ad-server source. Omitted for other inventory-source families.

Available options:
citrusad
​
type
enum<string> | null

Agent type

Available options:
SALES,
SIGNAL,
CREATIVE,
OUTCOME
​
endpointUrl
string | null

Agent endpoint URL

​
protocol
enum<string> | null

Agent protocol

Available options:
MCP,
A2A
​
description
string | null

Agent description

​
authenticationType
enum<string> | null

Agent authentication type

Available options:
API_KEY,
NO_AUTH,
JWT,
OAUTH,
BASIC_AUTH
​
authConfigured
boolean

Whether the agent has authentication configured

​
oauth
object

OAuth authorization info (for OAUTH agents)

​
managedSa
object | null

Embedded-sales-agent state when executionType is MANAGED_SALES_AGENT. Null/absent for external AGENT-type sources. The current REST surface (/api/v2/storefront/esa/...) remains the way to mutate this state today; subsequent PRs will move those actions under /api/v2/storefront/inventory-sources/:sourceId/....

​
linkedStorefront
object | null

Always null. The version-1 ambient storefront-interchange pool has no canonical Source identity and therefore cannot populate this per-Source projection. Retained for response-shape stability.

​
reportingType
enum<string> | null

How the underlying agent reports delivery (WEBHOOK, BUCKET, POLLING). Mirrors the AdCP-spec values used when connecting the source. Projected from storefront_agent_source; null for non-AGENT sources.

Available options:
WEBHOOK,
BUCKET,
POLLING
​
reportingPollingCadence
enum<string> | null

Polling cadence (DAILY, MONTHLY) — only meaningful when reportingType is POLLING. Projected from storefront_agent_source; null for non-AGENT sources or non-polling reporting.

Available options:
DAILY,
MONTHLY
​
isAdapterSource
boolean

True when this source is routed through an official Scope3-hosted adapter (storefront routing_mode is ADAPTER and the source_id matches the configured adapter). When true, the UI labels this as an official adapter rather than a generic external sales agent.

​
agentCapabilityUid
string<uuid> | null

Explicit reusable SALES Agent capability connected to this Source. Null means the Source requires governed connection reconciliation; endpoint similarity is never used.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
declaredAgentProductMode
enum<string> | null

The backing Agent completeness contract. Managed ESA and initial modular Sources project their fixed WHOLESALE contract.

Available options:
WHOLESALE,
COMPOSING,
BOTH
​
bindingProductMode
enum<string> | null

Source product-path selection only when the Agent declares BOTH; null for single-mode Agents.

Available options:
WHOLESALE,
COMPOSING,
BOTH
​
effectiveProductMode
enum<string> | null

Effective mode for new discovery. Null when the explicit Agent connection or declaration is unresolved.

Available options:
WHOLESALE,
COMPOSING,
BOTH
​
productModeReasons
enum<string>[]

Bounded reconciliation reasons when effective mode cannot be resolved.

Available options:
SOURCE_NOT_ACTIVE,
AGENT_BINDING_MISSING,
AGENT_MODE_UNDECLARED,
BOTH_SELECTION_REQUIRED,
MERCHANDISING_ACCESS_INACTIVE,
WHOLESALE_CATALOG_NOT_READY
​
productPaths
object[]

Readiness for the Agent-supplied and Storefront-built product paths. BOTH exposes both entries; neither path silently replaces the other.