Inventory sources

https://api.apostra.com/api/v2/storefront

​

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. AGENT sources use the generic inventory-source endpoints. A pilot-enabled seller can use the same create endpoint to create a linked storefront source that selects an approved storefront as LINKED_STOREFRONT; the new row remains PENDING, cannot receive requests or bookings, and can only be disabled until its separate terms and activation requirements are met. Managed and modular sources use dedicated provisioning 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 → ACTIVE. 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. A linked storefront source starts PENDING; configure its pass-through terms and activate it when the selected partner storefront still consents. A failed activation keeps the current status: PENDING stays PENDING, and DISABLED stays DISABLED. You can update terms while it is pending, active, or disabled. Updating disabled terms leaves it disabled; activate it separately to use the latest terms version. Archived linked storefront sources cannot be configured. You can disable a linked storefront source with the standard update endpoint. 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.
• Linked storefront source terms. The pilot uses pass-through terms: the buyer price equals the partner price, the platform retains 0%, and supplier settlement is external to the platform. The buyer-payment collector comes from the buyer account’s approved billing setting for the selected seller account on your storefront and is recorded on each booking. This is separate from the partner’s consent for your storefront to buy from it. Changing terms creates a new version; a later activation uses the latest version, while existing bookings keep the terms recorded when they were booked. For flag-enabled pilot storefronts, active linked storefront sources with current partner consent receive briefs and bookings. Pending, disabled, archived, or no-longer-authorized sources do not. The partner sees your storefront as the buyer for these requests; your buyer’s account remains on your own booking and is not sent to the partner.
• Linked partner availability. A linked partner must remain marketplace-listed, opted in, unpaused, and unarchived for new briefs, bookings, budget increases, and new packages. If the partner later delists, existing bookings still support delivery reads and polling, cancellation, budget decreases, creative sync, and approval forwarding for as long as that partner storefront exists. A delisted partner cannot receive new work.
• 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

• 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.

​

Working with an ad-server source in Murph

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.

​

Add another source

​

Submit a certification test-fixture setup request

POST /api/v2/provider/registration/capabilities/{capabilityUid}/certification-fixture-setups
Authorization: Bearer <your direct Account Admin session token>
Content-Type: application/json

{
  "revisionUid": "<uuid>",
  "endpointUid": "<uuid>",
  "inventorySourceId": "<positive bigint>",
  "sourceAccountId": "<positive bigint>",
  "isolationEvidence": {
    "reference": "review://provider/sandbox",
    "digest": "sha256:<64 lowercase hex characters>",
    "expiresAt": "2026-09-30T12:00:00.000Z"
  },
  "spec": { "...": "Provider certification fixture specification" },
  "idempotencyKey": "<8-128 character replay key>"
}

​

Administrative review

POST /api/v2/admin/provider-certification/candidates/{capabilityUid}/fixture-setup-requests/{setupRequestUid}/review
Authorization: Bearer <SuperAdmin user session token>
Content-Type: application/json

{
  "ownerCustomerId": 123,
  "action": "APPROVE"
}

​

Task reference

​

Manage

​

Ad-server connection

​

Lifecycle

​

Modular

​

Related