Skip to main content
Commercial identity setup has a text-only workflow. Public brand lookup and advertiser linking cannot create, edit or publish brand.json, or refresh a saved snapshot in place. Buyer AAO OAuth proof has no portable v3 initiation or callback flow; v3 can inspect its evidence or file a support ask. Seller domain review progress is available through get({ kind: "seller", include: ["identity"] }). Organisation names, login domains, members and roles remain outside the commercial identity tools. Identity confirmation is opt-in for operator saves and corrections to an existing advertiser’s brand through identityContract: "confirmed-v1". Earlier payloads retain their existing behaviour; this release does not require those clients to adopt the new confirmation exchange.

​
Availability and compatibility

  • v3 is available to every authenticated Buyer and Seller Account.
  • The v2 buyer API is closed to new API clients and switches off on 1 December 2026, except the conversion endpoint POST /api/v2/buyer/advertisers/{advertiserId}/log-event, which stays open. See Move a v2 buyer REST integration to V3. The v2 admin API remains stable. In production, the v2 storefront (seller) API refuses external callers with GONE and a pointer to v3.
  • v3 is served over MCP and over the v3 HTTP API. The HTTP API exposes the public v3 operation catalogue at POST /api/v3/tools/<operation>; app-only helpers that in-chat Pages use are not part of it. It is not a replacement for the whole v2 REST surface: admin operations outside the catalogue stay on the stable v2 admin REST API. Sellers use v3 only. /api/v3/documents is limited to authenticated exact reads and downloads of approved public immutable agreement revisions. Discovery, comparison, private documents, and governing-agreement selection are not yet REST resources.
  • The unversioned buyer MCP alias resolves to the v2 buyer MCP endpoint, which closes to external callers on 1 December 2026 with the v2 buyer API. The unversioned seller MCP alias redirects to the v2 storefront endpoint, which refuses external callers in production; sellers connect to /mcp/v3.
  • Organisation accounts currently provide navigation and shared tools, not an organisation-specific noun catalog.
  • The account kinds you can reach determine which buyer or seller catalog appears.
get_status remains available in an unclassified account so a session can orient and find the Buyer or Seller Account to name. No domain catalog is implied by a successful connection to an unclassified account.

​
Buyer limitations

The Buyer surface supports advertiser and campaign authoring, creative management, proposal requests, media-buy staging, and explicit campaign launch. The following gaps remain: Launching is supported, but only as a separate, two-call update to an existing campaign: a preview with desiredPhase: "active" and no confirmLaunch returns the campaign revision and what would launch; the confirm call sends confirmLaunch: true with that expectedRevision. Both calls require their own idempotencyKey. See Launch a campaign with explicit confirmation. A failed launch may report a partial write because downstream execution state was attempted. Re-read before retrying.

​
Seller limitations

  • Every Media Company account can use save_advertiser, save_campaign, save_creative, save_creative_collection, request_proposals, and save_media_buy directly from its Seller account. Sandbox Advertisers are available to every Media Company. Live Advertisers and campaigns come with Merchandising and are available only to organizations on a current Merchandising plan. Every operation is pinned server-side to that company’s own Storefront. A missing, foreign, or wider Storefront, Proposal, qualified Product, or existing MediaBuy scope is rejected before dispatch.
  • Integrated search/get can list and read authorized sandbox or live Advertisers, scoped Campaigns, Creative, Creative Collections, Proposals, and buyer-side MediaBuys. get(kind: "seller", id, advertiserId, include: ["products"] ) opens the company’s own wholesale catalog, so callers can pass qualified Products directly to save_media_buy without requesting Proposals. When a Product advertises signal_targeting_options, its eligible Signals can be selected through products[].targetingOverlay.
  • Merchandising changes account access only. Live campaign launch still requires ordinary source currency compatibility, account mapping, publisher authorization, funding, standing, and any seller-side approval. Creative approval does not block launch: a destination that needs an approved creative waits to deliver. No sandbox or publish-validation bypass applies to live traffic.
  • Seller search(kind: "media_buy", filter: { campaignId }) or filter: { advertiserId } selects the integrated Buyer projection. Omitting both selects the Seller inventory/execution projection.
  • Seller Accounts use the left navigation’s three modes: Storefront, Managed campaigns, and Settings. Setup progress appears at the top of Storefront. Managed campaigns lists the account’s sandbox Advertisers, plus live own-supply Advertisers once the account has live managed campaigns; selecting an Advertiser opens its Campaigns, Creatives, and Reporting work. Add advertiser in Managed campaigns or Campaigns opens the shared Advertiser Setup Task. It creates through save_advertiser, refreshes the roster, and can switch directly into the new Advertiser. Sandbox is the only choice unless the account has live managed campaigns (Merchandising). Campaign creation and delivery requests stay in Apostra so the same V3 own-supply guards apply. Buyers, under Your storefront in Storefront, lists external AdCP counterparties separately; selecting one shows media buys, synced creatives, and Delivery on your inventory for that relationship, plus its account admission case when setup needs attention. Managed campaigns uses the shared buyer advertiser picker and work navigation for the accounts the seller operates; protected System accounts are read-only. Agents are managed from the organization’s Developer account, not from the seller navigation. Browse media partners, Connections, Buyer Setup, and unbound production Advertisers are not part of this preview.
  • Shared Page hydration permits only three Seller-key Buyer REST reads: the Advertiser roster (sandbox by default; live only with Merchandising), Campaign listing for an explicitly bound Advertiser in either environment with wider-supply rows removed, and that Advertiser’s promoted Creative list in read-only mode. Buyer REST detail, mutations, and reporting remain unavailable to Seller keys. The Advertiser Setup Task writes through the public V3 save_advertiser contract instead.
  • Portable callers can use get_delivery({ report: "campaign_delivery" }) with explicit metrics, dimensions, a date range of at most 90 inclusive days or range: { lifetime: true }, and optional advertiser, campaign, or media-buy filters. A packageId filter requires a bounded date range (not lifetime), because the reporting operation fetches all campaign data before filtering by package. Integrated Media Companies must name an own-supply advertiser, campaign, or media buy.
  • Portable callers can use the additive get_delivery({ report: "live_campaign_delivery" }) mode with one exact campaignId and a bounded date range or range: { lifetime: true }. It reads the connected provider and does not accept metrics, dimensions, other filters, or a cursor.
  • Some credential, payout, approval, retry, and reassignment work intentionally remains in Pages rather than model-authored tools.
  • save_media_kit remains for compatibility but is deprecated; new clients should author Listing identity through save_seller’s listing field. get/save_media_kit’s deprecated kind/field is now canonically spelled listing, with media_kit/mediaKit accepted as deprecated aliases for the same handler.
  • Seller delivery is seller-reported. It is not Buyer measurement and does not establish billing eligibility by itself.

​
Catalog and host differences

The runtime catalog may be narrower than the tables in these docs because of account kind, permissions, feature rollout, and MCP App visibility. A principal that can reach both Buyer and Seller Accounts instead receives their deduplicated union at connection time, so hosts that cache tools/list retain both workflows whichever account a call names. Tools remain authorized only for the account a call names. Always use tools/list and get_status, and send accountId on every call. A stale tool call fails with typed wrong-account guidance that names the reachable accounts that can run it, rather than crossing the account boundary. switch_account is retired and still runs only from cached tool lists.

​
Payload, connection, and timing limits

  • Structured responses over 200 KB are truncated as a safety backstop.
  • One MCP connection is held open for at most 30 minutes; reconnect with the existing session when the client uses sessionful MCP.
  • A single tool call is also limited to 30 minutes.
  • Deploys can close connections and eventually interrupt long in-flight calls.
  • request_proposals durably schedules the full eligible cohort. Each background seller attempt has a 45-second bound; terminal result pages carry at most 50 seller outcomes and at most five bounded product projections. Product-heavy sellers continue on the returned cursor. Diagnostic pages carry at most 100 sanitized outcomes.
  • A productQueryId returned by request_proposals or a wholesale_product search books into one campaign. Booking the same products into another campaign needs a new request_proposals round or search.
  • A returned productQueryId stays stageable while the buyer deliberates. The discovery-analytics sweep marks a product query inactive after 60 minutes without activity (DISCOVERY_SESSION_INACTIVITY_MS, an infrastructure setting), but save_media_buy reopens such a query on first use, so a long deliberation does not lose the offer. A query that was already executed or replaced is refused with PRODUCT_QUERY_EXPIRED; call request_proposals or search again. A quoted proposal expires at the seller’s own validUntil or after 90 days, whichever comes first; PROPOSAL_EXPIRED names which window lapsed.
  • Seller delivery ranges are inclusive and limited to 90 days.
Long-running work should use an asynchronous workflow where one is available instead of holding a single MCP call open.

​
Direct-client model usage

Apostra can observe API calls, server-side model calls, and Apostra-hosted turns. It cannot observe the input/output token usage or model cost incurred by an external MCP client’s own model. Integrators remain responsible for that client-side budget and telemetry.

​
Choosing v2 or v3

Buyer integrations move to v3. The v2 buyer API is closed to new API clients and switches off on 1 December 2026; see Move a v2 buyer REST integration to V3. The conversion endpoint POST /api/v2/buyer/advertisers/{advertiserId}/log-event stays open. If your integration depends on a workflow listed as incomplete above, contact Apostra support before the switch-off. Sellers use v3 only. Admin operations outside the v3 catalogue stay on the v2 admin REST API.