Skip to main content
GET
List inventory sources

Authorizations

​
Authorization
string
header
required

API key or access token

Response

List inventory sources

​
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,
OAUTH_CLIENT_CREDENTIALS,
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.

​
linkedStorefrontTarget
object | null

Durable selected-target identity and lifecycle diagnostics for a publicly retrievable LINKED_STOREFRONT Source. Null or absent for ambient pool Sources and every other execution type; archived Sources are excluded from public Source reads.

​
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 Apostra-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.