Skip to main content
v3 is available to every authenticated buyer and seller account. The account selected by your credential determines which tools appear. The v2 buyer API switches off on 1 December 2026; see Move a v2 buyer REST integration to V3.

​
Before you connect

You need:
  • an Apostra account;
  • an OAuth login or API key with the permissions your work needs; and
  • an MCP client that supports remote streamable HTTP servers.
Interactive clients should use OAuth. Headless automation may use a user API key stored in an environment variable or secret manager. See Authentication for credential types and permissions.

​
Add the endpoint

The v3 endpoint is:
For headless automation, use Codex’s bearer-token environment-variable option instead of placing a key in shell history.
The broader Built for Agents guide covers ChatGPT, Cursor, credential handling, and client-specific setup. Use the v3 URL in place of the stable buyer or seller URL.

​
Verify the connection

Ask the client:
Each buyer or seller receives account readiness plus its account-specific catalog. An account that is not classified as either receives only the information needed to orient and to find the accounts you can name.
A successful connection proves authentication, not authorization for every operation. Tool calls still enforce the account each call names, user permissions, and resource-level access. The get_status result is the authority on that account’s readiness.

​
Hosts without a widget surface

For commercial operator domains, advertiser branding and supported human verification, follow Identity and brands. That flow returns current state, previews and proof status in text. Some tools open an interactive page in hosts that support MCP apps. A host that cannot render them, such as Claude Code or a plain MCP client, still receives the tool’s text result. When a buyer account opens the Creative Library with open_creative_library, or the Campaigns Page for an advertiser with open_campaigns_page, that text includes an Open in the browser: link that opens the same Page in Apostra chat for the account your API key belongs to, with the chat input below it. The link addresses the advertiser (and the focused campaign, when there is one), so it stays valid outside the conversation that produced it. The same URL is available as openInBrowserUrl in the structured result. A seller account that opens the Campaigns Page for its own-supply or sponsored-buyer scope gets no link: the buyer hosted chat does not model those scopes. To open a campaign’s Creative composer, call open_creative_library with lens: "composer", campaignId, and optionally sessionId for an editable Creative Session to resume. campaignId is required for this lens. Its browser link uses creativeAction=compose with the same campaign and optional session state, so a host without a widget surface opens the Composer Task in Apostra chat instead of losing the draft. The buyer-only composer lens creates a durable draft when no session is supplied, using the campaign’s configured Creative Engine. If the campaign does not declare exactly one composer-supported format, the draft starts as Snap Story and the Task directs the buyer to change the format in chat.

​
Name the account

Use an accountId returned by get_status, and send it on every call:
A principal who can reach both Buyer and Seller Accounts already receives both tool families at connection time, and the status read confirms which account can authorize each account-specific tool. See Name the account on every call. switch_account is retired on v3. It is in no tool list, and it still runs from cached tool lists for now. A call that omits accountId also still works for now, in the account your connection last switched to or your credential’s home account, and its result tells you to send accountId.

​
Make a first read

Choose a noun that belongs to the account you named:
Then read one returned campaign:
Kinds differ by account. Use the current search and get input schemas from tools/list; do not copy a kind from a different account’s stale catalog.

​
Safe first-write checklist

Before a write:
  1. Read the object and retain its current ID and revision when provided.
  2. Use the typed save_<noun> tool shown in the current catalog.
  3. Send only fields you intend to change.
  4. Supply expectedRevision when the schema offers it.
  5. Reuse an idempotency key only for the same logical attempt.
  6. Read the object again and confirm the reported outcome.
Continue with a buyer workflow, a seller workflow, or the tool catalog.