Skip to main content
Every MCP connection to the v3 endpoint (/mcp/v3) is listed the same complete tool catalog, whatever kind of account you are in and whatever role you hold. Apostra’s in-product assistant keeps its account-scoped tool list for now. The account a call names decides whether it can run. Begin every new session by calling get_status with no accountId. When you can reach more than one account it lists them, with each account’s accountId, kind and name, so you can ask the person which one they mean. When you reach one account it returns that account’s status directly. Keep the returned account identity, readiness and blockers for the account you work in. Then name that account on every call with an accountId returned by get_status:
Every tool takes it, reads and writes alike. A call runs in the account it names, for that call only, so one conversation can work across accounts by naming each call’s account, and nothing it does moves another conversation. Naming an account never grants access you do not already have. See Name the account on every call for the errors and for how to work across accounts. switch_account is retired on V3: it is not in any tool list, and it still runs for now from tool lists that hosts cached earlier.

Which account a call runs in when you name none

Send accountId and this section does not apply. Until the removal date announced in Name the account on every call, a call from a cached tool list that names none still runs in the account the server picks, in this order:
  1. The account the connection last switched to, if it has a stored selection and you still reach that account. A stored selection belongs to the connection (the sign-in grant) or, when there is no grant, to the person. Some clients, such as ChatGPT, carry no session, so they read the stored selection on every call. A client that keeps a session, such as Claude, starts a new session on your home account and ignores a selection stored by an earlier one. Naming an account on a call never changes it.
  2. Otherwise your home account. For an Apostra staff member it is their staff account. For everyone else it is the oldest active membership; a legacy Seller membership that is not yet set up is skipped when you have another account.
Two clients signed in as the same person can therefore start in different accounts: one reads a stored selection and the other starts at home. A credential fixed to one account, and a request that carries its account in a header, always run in that account. Such a call’s result carries one line asking you to send accountId on every call. A buyer agent, and an API key with no user behind it, can name only the account it runs in, so get_status lists no other account it can name, even when a hosted buyer agent is answering a person who belongs to other accounts. A buyer agent whose organization granted it advertisers in other accounts sees each of those accounts in reachableAccounts with nameWith: "advertiserId", up to 10 of its advertiserIds, advertiserCount, and access (read when every grant there is read-only, otherwise read_write). A call that names one of those advertisers in advertiserId runs in that account, and naming the account in accountId is refused. When you can reach more than one account and name none, get_status lists them. The structured result carries accounts, and the text lists the same accounts after a paragraph that says the account was chosen by default. nextActions leads with confirm_account, a recommended step that names the account the call ran in and where it came from. You can answer a read-only question in that account. Tell the person which account you used. Confirm the account with them before your first write, then send that accountId on every call. get_status with accountId reads another account. A page lists up to 25 other accounts. An Apostra staff member reaches every customer, so their list is paged: the text says how many accounts are not shown, and nextActions carries a list_more_accounts step with the cursor to send. Send cursor only on a call that has no account named; with an account named, or with one account reachable, there is no list to page and the call is refused. A call that names its account, a caller with one account and a credential fixed to one account see none of this. Every authenticated Buyer, Seller and Organization account can connect, and every connection to /mcp/v3 is listed the same complete catalog: Buyer, Seller, Organization and Agents tools, search and get with all their kinds, filters and includes, and every write tool, even for a read-only login or a directory reviewer’s login. Listing a tool is not permission to run it:
  • A tool runs only in an account of its kind. A call in the wrong kind of account is refused with WRONG_ACCOUNT, naming the kinds the tool needs and the accounts you can reach that can run it. Send one of them as accountId and call again. The same goes for the includes that read a Seller account’s own state: get({ kind: "seller" }) with identity, readiness, operating, entitlements, teaching or prebid is refused with WRONG_ACCOUNT outside a Seller account, naming the include. Asked for with an id, they are refused with VALIDATION_ERROR, because another seller’s own state is never readable.
  • A call needs the role it always needed. Without it, the call is refused with ACCESS_DENIED. A directory reviewer’s login is refused every write with REVIEWER_TOOL_PROHIBITED.
Two kinds of tool stay out of the list: Apostra staff tools, and tools for a feature your account is not enrolled in, such as notification settings or advertiser grants. Tools that only a Page calls are listed, and their metadata marks them as not for the model. An Organization account’s own tools are navigation, shared settings, and the bounded organization-account task below. get with kind: "advertiser_access" is seller-only by design and shows the seller who may buy for an advertiser; for buyer-side access questions, see organisation delegation.

Manage organization accounts

A direct organization administrator manages the organization’s child accounts with save_account, from the organization account or any child account they administer. Send no id to create a child, id and name to rename one, or id and isArchived to archive (true) or restore (false) it. Each of those is recorded for approval on the website: the tool returns a link, nothing changes until an administrator of that organization approves the exact request, and the agent cannot approve it. Repeat the same call with the same idempotencyKey to see the outcome. Send dryRun: true first to see what the request would do, including the campaigns and media buys that block an archive. A preview runs the same checks and records nothing. See Manage accounts with a V3 agent for the fields each change takes. The in-app Apostra chat also offers save_account to a direct organization administrator using an administered Agents, Buyer, or Seller account. The chat returns the same website approval link, and no account changes until an administrator approves that exact request there. Direct organization administration that takes effect immediately stays available only from a direct session. An Apostra support person with an active staff elevation on the organization (see “When Apostra staff help with your account’s members” below) can list the organization’s accounts and request the same creates, renames, archives and restores from the organization account, under their own name. An elevation on one child account does not reach the organization. While the elevation lasts they can also approve those requests on the website. If the elevation has ended or been revoked by the time an approved change runs, the change is refused and nothing is changed. An organization has no limit on how many Buyer or Seller accounts it holds, so restoring one is never refused for a count, and archiving or restoring an account changes nothing about what else you can add. Restoring or reactivating an account is never refused because of the plan either: an account the organization held keeps its place even if its plan no longer allows that type for a new one. Creating accounts is capped at 25 in any 24 hours per organization. The 26th is refused with 429 RATE_LIMITED, details.reason account_creation_daily_limit and a message to contact support to raise the limit; do not retry it, because the window slides over 24 hours. It counts creations, so an account you created and then archived or deleted still counts, while restoring one does not, and repeating a request with the same idempotencyKey is never refused. A save_account create, including its dryRun preview, is refused with the same error when you ask, so no approval is recorded. See Accounts in an organization. Two other checks remain. The plan must allow the account type you create; otherwise the request is refused with 409 CONFLICT, details.reason plan_does_not_cover_account, the plan that would allow it and the next step. The same check refuses a staff create, moving an account into the organization, and switching an account to Storefront. And an organization holds one Agents account: creating or restoring a second is refused with 409 CONFLICT and details.resource developer_account_limit, so build further agents in the existing one. Repeating a request with the same idempotencyKey returns the first result.

Account types

save_account creates an account of one type. Send accountType and, for a seller, sellingMode: The Agents account is the account type where you build and manage agents. Its wire value is still developer. A seller needs sellingMode; a buyer, an Agents account and a Demo Storefront refuse it with VALIDATION_ERROR. operatingMode (LISTING_ONLY or AGENTIC_MEDIA_COMPANY) still works as the older name for the same choice, and sending it with sellingMode is refused. It will be removed once the hosts that list save_account have approved the new definition. Which of these an organization can add depends on its plan. The Listing plan allows Listing accounts and one Agents account; adding a Campaign management or a Storefront is refused, and the next step is to move to the Standard plan. Read the answer for your organization from the organization account’s get_status instead of trying a create. Its organization.addableAccountTypes lists the four types above, each with canAdd. A type you cannot add also has a reason (code and message) and a nextStep (code, message, and canAct, which is false when only another administrator of the organization can take the step). A save_account create or dryRun for a type that canAdd says no to is refused with that same reason, because both come from one plan check. If the read fails, addableAccountTypes is null and gaps says so. The organization account’s get_status shows the child account counts and which account types the organization can add (see Account types); an organization has no limit on how many accounts it holds. It also says whether the organization has an Agents account. If none exists, its next step is to create one with save_account; an organization holds one Agents account, and a second is refused. get with kind: "account" and include: ["lifecycle", "capacity"] adds one child’s archive state and blockers. These reads and the writes check that you are a direct administrator of that organization. Send organizationId to save_account to act for an organization from a child account you administer; without it the call acts in the organization account you are connected to. A Apostra platform operator can name any customer organization, and only an operator can create a Demo Storefront (accountType: "seller" with demoStorefront: true). An organization administrator can make these calls from any of their own signed-in sessions: their home account, a child account they switched to, customer view, Murph or an MCP OAuth connection. The server checks their direct administrator membership of the named organization; access inherited from a parent organization is not enough. An Apostra staff member in a support session gains nothing from support access: they can act on an organization only through their own direct administrator membership of it. An API key, a machine credential, a delegated agent and a session acting as another person are refused with ACCESS_DENIED, even when the person behind them administers the organization. A platform operator who is not a member of the organization must call from their own home account: one working in a customer account is refused, so send your home account’s accountId, then retry. Browsing products under your company’s seller account is open to every member of the company and to the company’s service tokens, not only to administrators; buying still needs an Operator or Admin or a token that is not read-only. See who can browse under a company seller account.

Who decides an account’s approvals

A creative review or a media-buy approval on a Seller account goes to that account’s approval audience. With no saved approval routing, the audience is the account’s own administrators. If the account has none, it is the administrators of the organization the account belongs to. Only the audience is notified about it. An administrator of the organization may also decide any approval that is routed to administrators (the default routing, or saved routing that names the Admin role), even when the account has administrators of its own. They are not notified about it; they decide it from the account’s approvals or with save_work_item. An approval whose saved routing names particular people, and no role, can be decided only by those people.

Spend approval on a buyer account

Each buyer account has a spend approval setting, requireSpendApproval. When it is on, no new money reaches a seller until an administrator of the account approves it on the Apostra site, whoever asks: an agent, an API key, Murph or a person in chat. It is off unless an administrator turns it on. What waits for approval while it is on:
  • Launching a campaign. Confirming a launch that would book media buys with sellers, including a media buy staged on a campaign that is already live. See Confirm launch.
  • Adding a product to a live media buy.
  • Raising what a live media buy spends: a higher total budget, or a higher sum of its line item budgets. See Change a live media buy.
  • Applying optimizer suggestions that raise a live media buy’s spend. Even in automatic mode, the suggestion set waits for a decision and then an administrator’s approval. Sets that only lower budgets or bids apply as usual.
A live media buy is one that has left draft. Nothing else waits: drafts, proposals, staging a media buy, creative work and reads; pausing, resuming, lowering a budget and cancelling; moving budget between one buy’s own line items with its total unchanged; and changing targeting, pacing or dates. Raising a campaign’s budget does not wait either, because it only raises the ceiling the campaign’s media buys must fit under. What your agent receives. A V3 tool returns approval_required with the approval’s id, its link on the Apostra site and when it expires, recorded under the call’s idempotencyKey. Nothing was sent to a seller. Show the person the link, then repeat the same call with the same idempotencyKey to see the outcome (Approving agent requests). A v2 buyer route returns HTTP 409 with code SPEND_APPROVAL_REQUIRED and the same approval in details.approval. Who approves: an administrator of the buyer account, or of the organization it belongs to, signed in to the Apostra site in their own browser. The approval runs the request exactly as it was recorded. If what the campaign or media buy would spend changed after the request, the approval fails and nothing is sent, and the agent asks again. An approval expires after 24 hours.
  • Read it on get_status in a buyer account (account.requireSpendApproval, always present), and on account rows from search and get (kind: "account"), where it is true or false on a buyer account and null on any other account.
  • Turn it on with save_account, sending id (the buyer account) and requireSpendApproval: true. It saves at once and returns saved, or unchanged if it is already on. A reason is optional and is kept in the account’s audit log. dryRun: true checks it first and saves nothing.
  • Turn it off with save_account, sending id, requireSpendApproval: false, a reason and an idempotencyKey, and nothing else. Turning it off is itself recorded for an administrator’s approval on the Apostra site, so an agent cannot remove the check it works behind. It returns approval_required with the link. dryRun: true checks it first. On an account where it is already off, the call returns unchanged and records nothing.
  • Who can change it: an administrator of the buyer account, or of the organization it belongs to. Each account has its own setting; there is no organization-wide switch. Service tokens, impersonated sessions and Apostra support sessions cannot change it. A seller, organization or Agents account has no setting, and naming one returns VALIDATION_ERROR.

When a Seller account can’t sign in yet

A Seller account can be used once it has been set up as an Apostra Seller. When an administrator of the account signs in with a work email on the company’s own domain (the domain recorded on the account), sign-in finishes that setup and lets them in, the same way signing up as a new Seller does. You’ll be asked to accept the current Terms of Service if you haven’t yet. Anyone else, for example a member who is not an administrator or who signs in with an email on another domain, can’t sign in until the account is set up. The sign-in page says the Seller account isn’t set up yet, and our team is told which account it is. You don’t need to request access or fill in the Buyer access form. Ask your company’s administrator to sign in, or sign out and sign in again once the account is ready. Sign-in refuses such an account with ALPHA_OPT_IN_REQUIRED and reason: "seller_awaiting_setup". A Buyer account that is not yet in the advertiser beta gets the same error with reason: "buyer_not_enrolled", and can request access. The signed-in account read (/auth/me) reports the same value as accessRefusal, or null when the account is not refused.

What signup creates

Signing up for Buyer or Seller access creates a new organization with your first account inside it, and makes you the organization’s administrator. The account is the one you chose at signup: a Buyer account for Campaign management, or a Seller Account. It keeps its own id. The Terms you accepted and the plan you took sit with the organization, so you can add more accounts with save_account (see Manage organization accounts) without converting anything first. A colleague you invite to the organization joins the organization; a colleague you invite to the account joins only that account. Invite colleagues to the organization when they should reach every account in it. A new Seller Account still starts as a Listing account. Some signups do not create an organization. Joining a company that already has an account, by invitation, by claiming an account nobody administers, or by an access request, adds you to that account (see below). Agents signups already create an organization. Accounts that signed up before this change, and accounts Apostra staff create, can still be standalone; see Turn a standalone account into an organization. If the organization cannot be set up, signup does not finish and says so. Signing up again finishes it.

Requesting access to your company’s account

When you sign up with a work email and your company already has an account, signup offers Request Access instead of making a second account. This includes the Agents experience: if a colleague already created your company’s Agents account, you ask its organization’s administrators for access, and you are told so before you reach the Terms. The account’s administrators are emailed your request, and you get access when one of them approves it. If the account has no administrator, and neither does the organization above it, nobody there can approve the request. It comes to our account team instead. We email you when you have access, or if we need anything from you. If you have questions in the meantime, write to support@apostra.com. An email address on the account’s domain does not by itself make you that account’s first administrator. Verifying your mailbox proves the address is yours, not that the domain is your company’s, and many domains are shared by people from different companies — university alumni addresses, mail forwarders and some internet providers among them. We make you the first administrator without review only when the organization has proved it controls the domain, either by publishing the DNS record we ask for or through a check by our account team. Until then the request goes to the account team, as above. Asking again does not file a second request; your first one stays in place.

Who an account’s member list shows

search with kind: "member" lists the people with access to an account, and get with kind: "member" reads one of them by the id search returned. In an organization account you can name a direct child account: filter.accountId on search, memberAccountId on get. In any other account you read the account you are working in. Reading the list takes the authority to manage the account’s members: an administrator of the account or of its organization. See Name the account on every call. Every member says where their access comes from in accessSource:
  • search returns both kinds, ordered by email. It has no filter on accessSource and its query matches only the id, email and name. To see only the organization’s administrators, read accessSource on the rows, and raise limit when truncated is true.
  • get finds an organization administrator by id on a child account.
  • A person who is both added to the account and an administrator of its organization is listed once, as direct, with the level they hold on the account.
  • An organization account has no organization above it, so every member of it is direct.
  • Apostra staff who reach an account through a support session, a staff elevation or an account switch hold no membership of it and are not listed. A staff member who administers the organization is listed like anyone else.
  • The member read is read-only. To remove an organization member, or change their access, use the organization’s Members page, not the account.
  • Removing a person’s administrator membership of an organization removes their organization access to every account in it, deactivated accounts included. A person who was also added to an account directly keeps that membership until it is removed on the account itself.

When Apostra staff help with your account’s members

An Apostra support person who opens your account sees it read-only. To change anything they need a staff elevation for your account, which is approved inside Apostra, lasts a limited time and is recorded. While it lasts, they can list the account’s members, invite someone, resend or cancel an invitation, change a member’s role and remove a member, the same as an administrator of the account. An elevation on an organization covers the members of the accounts under it. Every change is recorded under the staff member’s own name. Once the elevation ends or is revoked, these actions are refused again.

When your account has been deactivated

An account can be deactivated, for example when it is closed or merged into another account. No one who belongs to it can use it until it is restored. If every account you belong to has been deactivated, signing in does not stop at an error. You are shown any invitation you have to another account first; if there is none, you are taken to signup to set up a new account, and you administer the account you create there. The deactivated account is left as it is: if it is restored later, you can use it again. If you belong to more than one account, deactivation only matters when none of them is active; an active account still signs you in. If you would rather get the deactivated account back, ask its administrator to restore it, or email support@apostra.com. When signup is not offered, sign-in answers a deactivated account with 403, error: "NO_ACTIVE_HOME_CUSTOMER" and reason: "ACCOUNT_DEACTIVATED", with a plain-language message that agents and API clients can show as it is. That happens on token refresh, and on password sign-in when the email address has not been verified. Browser sign-in with OAuth, SSO or a verified password sends the person to signup instead. A sign-in that asks for one particular account, such as a link into a specific seller’s advertiser, is answered about that account: when it is deactivated the sign-in is refused, and the person is not sent to signup, because they asked for that account and not for a new one.

Before your organization accepts the Terms of Service

Until a direct administrator of your organization accepts the current Terms of Service, the Apostra site asks for that before anything else. Only that administrator can accept them; Apostra staff never accept them for you. Managing the account’s members is not blocked. If you are an administrator of the account or its organization, the Terms window offers Manage members, so you can invite or remind the person who should accept. An Apostra support person with an active staff elevation on your account gets the same choice. The member list, invitations and role changes work as usual; most other work waits for the Terms. Conversion events keep flowing. log_event and the conversion endpoint POST /api/v2/buyer/advertisers/{advertiserId}/log-event accept events whether or not the current Terms are accepted, so an integration that sends your conversions never loses data while you sort out the Terms.

Sandbox advertisers and live spend

A sandbox advertiser is an advertiser created with AdCP’s own sandbox flag set to true. You set it once, in save_advertiser when the advertiser is created, and it is carried on the AdCP account identity {brand, operator, sandbox}. It cannot be changed afterwards: save_advertiser on an existing advertiser that names sandbox returns IMMUTABLE_FIELD. To move to live work, create a new advertiser without the flag. A sandbox advertiser only sees products from sellers with a usable sandbox setup for that advertiser. For an Apostra-managed Google Ad Manager seller, that means a bound advertiser or the seller’s ready sandbox advertiser. If the seller has neither, use a live advertiser to see its products. Every brief a sandbox advertiser sends carries the same flag on its account, and a seller on Apostra is not charged for answering it. Sandbox briefs are also left out of the seller’s analytics (its run counts, win rate, buyer asks and top products), and out of what the seller’s Storefront Agent learns from past briefs, so a buyer’s tests do not look like demand to the seller. What the seller teaches the agent on a sandbox brief, such as a lesson, still applies to live briefs. An Apostra Storefront still answers a sandbox brief in full, so you test the answer a live brief would get. A seller’s own sales agent may answer sandbox requests differently. Because a sandbox brief is never charged, the seller needs no plan and no payment method to answer one. It does need active Brief Acceptance rules on the Storefront that handles the brief, so the seller’s own rules decide what it answers, test briefs included. Brief Acceptance the seller has turned off still meets this: turning rules off is a decision, not missing setup (see Turn a policy off). Where Apostra requires a seller to finish setting up before it answers briefs, a sandbox brief is refused only for missing Brief Acceptance rules (details.reason seller_prerequisites_missing, with details.missing naming brief_acceptance_rules). It is never refused where a live brief to the same seller would be answered. A live advertiser’s brief is also free to the seller while its buyer account cannot book media yet, for example because the account has not finished setup. These briefs come from a real advertiser, so unlike sandbox briefs they stay in the seller’s analytics and in what its Storefront Agent learns. Once the account can book, its live briefs are charged as usual. A brief sent to a seller’s agent with no Apostra buyer account behind it is always charged, and if Apostra cannot check the account’s setup in time, the brief is charged as an ordinary live brief. Each buyer account has 20 sandbox briefs a day that reach an Apostra Storefront, counted in UTC. While the account cannot book media yet, its free live briefs count toward the same 20. One brief sent to many sellers in a single request_proposals call counts once; a direct get_products call to an Apostra Storefront with a sandbox account counts as one brief, and so does a refine pass on one. A catalog read (get_products with buying_mode: "wholesale") is not a brief and never counts. A brief Apostra answers from its recent results, such as the same brief sent again shortly after, does not reach the Storefront and does not count. A brief that reaches the Storefront counts even if the Storefront then cannot answer it. Live briefs from an account that can book have no such limit. Sandbox briefs to Apostra’s synthetic sellers, the Apostra synthetic seller and every Demo Storefront, never count, so you can build and test an agent against them as often as you need. A request_proposals round from a sandbox advertiser whose sellers are all synthetic is never refused for the limit. A round that also names a real seller, or one sent to every eligible seller, still is. Past the limit, the limit is Apostra’s, not a seller’s, and the answer says so. A request_proposals call from a sandbox advertiser that has used its 20 briefs is refused once, before any seller is contacted, with RATE_LIMITED. This applies to every new round from that advertiser until the reset, including a round whose sellers are not Apostra Storefronts, except a round sent only to synthetic sellers. The message names the limit and says it resets at midnight UTC, and retry_after is the number of seconds until then. A direct get_products brief or refine call to an Apostra Storefront gets the same RATE_LIMITED and retry_after; a catalog read is still answered. If another round uses the last brief while yours is running, an Apostra Storefront that refuses it reports the same Apostra limit as that seller’s outcome, not as a seller error. If Apostra cannot read today’s count, request_proposals is refused with SERVICE_UNAVAILABLE and a short retry_after, and no brief is sent. An account that cannot book media yet reaches the same limit with its live briefs. The up-front request_proposals refusal, and the refusal a direct get_products call gets, have details.reason not_transacting_brief_daily_limit and list what the account still needs in details.blockers, such as operator_identity. A seller outcome inside a running round says only that the Apostra limit was reached. The limit lifts as soon as the account can book, as well as at midnight UTC. If Apostra cannot read today’s count for such a brief, the brief is sent and charged as an ordinary live brief rather than refused. A buyer account has no sandbox mode and no live mode. The account is the same in both cases; what changes is which checks an operation has to pass. Setting up a sandbox advertiser (creating, updating or archiving it, and configuring its tracking) does not wait for the verified operator identity, so you can prepare one before claiming it. Creating its campaigns and media buys does. An operation that fails a check is refused with an access-denied error that names the first requirement still missing. See Sandbox mode for the full list of requirements and the buyer REST behavior. Your application should retain the account identity with every workflow checkpoint, send it as accountId on every call, and verify it when resuming. A connection, a seller relationship, or a registered agent does not implicitly grant access to every advertiser.

Full account-access reference

Review customer relationships, role and permission behavior, and stable v2 account switching in the canonical account-access guide. That guide’s customer_switch is v2 only.