> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Inventory sources
> Connect AdCP-compatible agents and ad servers to your storefront so buyers can discover and transact against your inventory
An **inventory source** is a named slot inside your storefront that your Merchandising Agent draws from when it answers buyer briefs. Each source wraps something the agent can call: an external AdCP-compatible sales agent, an operator-owned ad server with Apostra-managed sales-agent plumbing behind it (an **ad-server-backed source**), a linked storefront, or a modular source assembled from individual modules. Buyers never target a source directly — they call your storefront, and discovery fans out to every eligible, compatible Source.
All examples use the storefront base URL:
```
https://api.apostra.com/api/v2/storefront
```
Authenticate every request with `Authorization: Bearer $SCOPE3_API_KEY`. The storefront is resolved from your API key's account context — there is no `customerId` path parameter.
## Key concepts
* **Execution type.** Every source has an `executionType`: `AGENT` (external AdCP sales/signal/creative/outcome agent), `MANAGED_SALES_AGENT` (ad-server-backed source — GAM, FreeWheel, SpringServe, or AdsWizz), `LINKED_STOREFRONT`, or `MODULAR_SOURCE`. Only `AGENT` sources are created and updated through the generic inventory-source endpoints; the other kinds use dedicated provisioning and linking flows.
* **Two identifiers.** `sourceId` is unique within your storefront and is what you use for actions on your own rows. `id` is a globally unique surrogate used for cross-account actions (for example, a seller approving an inbound link).
* **Lifecycle.** A source moves through `PENDING → ACTIVE → DISABLED`. That source status is the single lifecycle authority for an external-agent source; its connection metadata and legacy agent registration do not carry a second status. Existing diagnostics may still return `agentStatus` as a deprecated copy of `sourceStatus`; do not interpret it independently. An ad-server-backed source is enabled unless `deactivatedAt` is set (`null` means enabled). Its `operational.isLive` value is health/readiness presentation, not a discovery-eligibility decision. Recent failures surface as `lastErrorCode`/`lastError`. The operator flow is the same: create the connection, save ad-server config, test it, launch into the admin UI, then deactivate or reactivate as needed.
* **Eligibility is not health.** Apostra sends discovery to every Source
whose Storefront and Source setup are complete, whose Storefront is not
paused, and whose Source and mapped Agent are explicitly eligible. Request
channel, country, and currency compatibility then selects the recipients for
that request. Degraded or erroring health remains visible but does not stop
requests by itself; an explicit ineligibility decision does.
* **Product paths.** A Sales Agent explicitly declares whether it supplies
ingredients for Apostra to merchandise (Storefront-built), complete
buyer-ready products (Agent-supplied), or both. A Source whose Agent supports
both selects one or both paths. This is not a separately priced add-on and is
not controlled by a Storefront-wide toggle.
* **Managed sources are wholesale.** An ad-server-backed source has a fixed
Storefront-built contract because raw ad-server inventory must be converted into
sellable products. Other active Sources retain their own independent paths.
* **Component cache.** When a Storefront-built source supports AdCP 3.1+
wholesale products, Apostra stores those inputs for merchandising and
Storefront-built reads.
Cache success means the source returns stable component ids, pricing, formats,
property/selectors, delivery type, and execution metadata. A cache miss does
not by itself mean live passthrough is broken.
* **Credentials are never echoed.** Agent API keys and JWT private keys are encrypted at rest and referenced by an opaque ref. Responses surface `authConfigured: true` instead of the raw secret.
* **Connection definitions are versioned.** The external sales-agent Task pins
the endpoint, protocol, and authentication definition used during setup.
Built-in and Partner-backed integrations use the same typed definition model,
while older integrations keep their existing setup path until migrated.
* **Modular readiness.** A `MODULAR_SOURCE` is composed of typed modules (inventory feed, booking ledger, trafficking, status sync, reporting import). Its readiness projection reports per-module contracts, lifecycle stages, missing setup fields, and open work-item counts.
## Plans, entitlements, and feature profiles
Inventory Sources is available in the navigation for every seller account. A
new seller chooses **Just list** or **Agentic Media Company**. Both include
listing and can connect inventory through the supported source paths. Just list
uses an agent operated by your company, a partner, or another provider; that
agent can be connected during setup and does not need to exist at signup.
Agentic Media Company adds Apostra's hosted Merchandising Agent, which you train
for your business. Operator ownership is Source configuration, not a separate
plan or feature profile.
Plans are the commercial choice. Each plan declares its default feature
profile. Feature profiles determine the coherent set of product surfaces the
account receives; entitlements are reserved for independently sold additions:
* **Basic / Listing** includes Apostra listing,
sales-agent connection, and operational surfaces for campaigns, media buys,
creatives, approvals, delivery, activity, and reporting. AI Business Rules
are available here. Saving, enabling, and evaluating AI Business Rules is not
an IU-rated activity today; other qualifying activity remains governed by the
organization's accepted IU Rate Card.
* **Listing + Distribution** is the standard paid Seller Account package for unlimited
self-serve advertiser invitations and management, public listing distribution
and an optional customer CNAME, and
customer-branded AdCP and ChatGPT app channels. It does not improve or rank
Apostra listing, replace the connected sales agent, or enable
Merchandising and modular inventory sources. Existing accepted offers continue
to use the advertiser capacity stated in their terms. Until this package is active,
**Listing** shows the Public distribution benefits and an
upgrade link instead of the domain step and destination controls.
* **Premium** uses the Merchandising profile. Merchandising includes publisher
self-service and **Custom modular sources** without separate entitlements.
**Enterprise** describes custom commercial terms such as price, term, credits,
support, and payment arrangements. It uses the same Premium/Merchandising profile
when the product surfaces are the same, so Enterprise also includes publisher
self-service and **Custom modular sources**. A separate Enterprise feature
profile is needed only if the account receives a genuinely different product
experience—not merely a different contract.
Standard managed integrations are included with every seller plan; sellers do
not need to know whether Apostra implements one with modular internals. The
stable internal feature key for customer-specific composition is
`modular-sources`, and customer-facing surfaces call it **Custom modular
sources**. Basic excludes it; Premium and Enterprise include it through the
Merchandising profile. It is not a separately provisioned entitlement.
## Working with an ad-server source in Murph
Ad-server setup is separated by job so first-time connection does not compete
with operational detail:
1. **Connect ad server** is a one-completion task. Choose the provider, enter
the account or credential details it requires, create the source, and the
task closes.
2. **Ad server source** is the return page for an existing source: current
posture, default-advertiser work, configuration, and deactivation.
3. **Sync & diagnostics** is the evidence page for source health, sync streams
and run history, and buyer-discovery cache freshness. It appears when you
ask for diagnostics or follow a source problem; it is not a permanent green
setup step.
If part of the diagnostics payload is temporarily unavailable, Murph names the
missing evidence and keeps the rest visible instead of treating a failed read
as an empty or healthy result.
## Add another source
Open the **Inventory** workspace in the seller navigation and choose **Add
inventory source** whenever you want to connect another source. This opens the
Inventory sources list and expands the provider choices immediately. Choose an
ad server, a modular inventory source, or an external AdCP sales agent to open
its structured setup flow; the button does not turn the action into a new chat
prompt.
Adding a source keeps the storefront settings you already completed: currency,
approval routing, business profile, publisher domains, acceptance policy, and
selling rules. The new source gets its own connection, credentials, catalog,
health, and setup work. Seller Setup lists those facts per source, so a healthy
first source cannot hide a second source that is still waiting for credentials,
sync, products, or repair.
When an exact specialist destination is available, the source card also shows
**Open source**. It opens the existing ad-server detail, modular readiness, or
external-agent diagnostics surface directly. The action is omitted when that
destination cannot be resolved or its capability is not enabled.
Seller Setup keeps the decisions separate: setup complete or setup required;
Agent unmapped, certified, validated, or unvalidated; context-free routing
eligibility; Source health; and Agent implementation health. Use Source Health or TARS to
preview whether a Source is selected for an exact channel/country/currency request.
A sales agent on the Agent-supplied path does not need a warm merchandising cache.
Bad or malformed returned products are a health error and are filtered from the
response, but they do not silently make the Source ineligible.
Sources can't be deleted while their backing agent has non-terminal media buys
(`ACTIVE`, `PAUSED`, `PENDING_APPROVAL`, or `INPUT_REQUIRED`). Cancel or
terminate those first.
## Task reference
### Manage
Every source on the storefront
Register an external AGENT source
Read one source by ID
Check source health and recent AdCP activity
Change fields, rotate auth, transition status
Remove a source and disable its agent
### Ad-server connection
Connection state for a managed source
Operational snapshot of the managed source
Historical sync runs for drill-down
Set GAM, FreeWheel, SpringServe, or AdsWizz config
In-place credential rotation
### Lifecycle
Mint a one-time URL into the managed source
Probe upstream reachability
Force-refresh the status cache
Soft-delete the managed source
Re-enable a deactivated source
### Modular
Modular sources use a staged operator lifecycle: ingest avails, inspect product
projections, reserve capacity, prepare supported execution handoffs, release
capacity when needed, and work any source-side human queue items. See the [modular lifecycle guide](/v2/storefront/inventory-sources/modular-lifecycle)
for the full setup checklist, feed format, sequence, and examples.
Request the complete evidence pack and copy parser-valid avails templates
End-to-end avails, reservation, execution handoff, release, and HITL
workflow
Preview and author property/tag to key-value, ad-unit, or placement mappings
Runtime projection for a modular source
Write non-secret config for one module
## Related
Every operation in one place
End-to-end seller setup
How to inspect source health and recent ADCP calls
How buyers see your storefront
Shared error contract