Skip to main content
When a buyer asks your storefront for proposals, a brain composes the answer from your Library: your products, prices, playbook and rules. You choose which brain that is: You can also run a second brain in shadow mode. A shadow brain gets the same requests under the same rules, and its proposals are checked and recorded, but never shown to a buyer. Use it to see how another brain would have answered your real briefs before you switch. Shadow brains run at no charge during the beta.
Apostra sends buyers’ request_proposals calls to the brain you choose: Chef, your account’s own Prime, or your own proposal agent. A Chef shadow never runs, because Chef already answers. A buyer’s request_proposals reaches your brain whether the buyer calls your storefront directly over AdCP or asks through Apostra’s V3 API (Murph, the widgets and API clients). A direct get_products brief and a refinement are still answered by Chef.
Choosing a brain is in beta. If get(kind: "seller") returns no proposalAgent, your account is not on the beta.

Who can change it

Only a direct administrator of your organization, signed in as themselves, can choose the brain. A call from any agent, including your own, or from a staff member impersonating someone, is refused: who answers your buyers is your decision. The account must sell as a Storefront. A Listing has no brain to choose, because Apostra does not answer its buyers’ proposal requests (see Change a Seller Account’s type).

Read the setting

get(kind: "seller") returns proposalAgent:

Change it

Send the whole setting with save_seller, on its own, with the updatedAt you read:
  • expectedUpdatedAt is required. Send the updatedAt you read, or null while the setting was never saved. If someone saved a change since you read it, the call is refused with CONFLICT and names the setting now in force, so two administrators never overwrite each other.
  • shadow must differ from answering.
  • ownAgentId is required when answering or shadow is own, and must be null otherwise. It must be a proposal agent your organization connected and verified as its own. See Connect your own proposal agent.
  • Prime and your own proposal agent are not open to sellers yet, as answering or shadow. They open when the choice of brain launches to sellers. Until then prime and own are refused with FEATURE_NOT_ENABLED and reason: "own_proposal_agent_unavailable", and only Apostra’s own accounts can choose either or register a proposal agent.
  • Saving the setting already in force changes nothing.
A change applies to new requests. A negotiation that is already open finishes with the brain that opened it, so a buyer partway through a negotiation never sees the answering brain change under them. Every change is recorded with the administrator who made it.

When your own agent answers

When your setting names your own proposal agent, Apostra sends each new request_proposals call for your storefront to the agent’s endpoint, signed as Apostra (see How your agent knows a request is from Apostra). Apostra calls it only while it is still a verified proposal agent of your organization; otherwise Chef answers. Your agent has about 85 seconds to answer. If it does not answer in time, answers with an error, or answers submitted, Chef answers instead, in the rest of the buyer’s two-minute window. A buyer always gets an answer. Answering submitted and delivering later is not supported yet. Apostra checks the answer before the buyer sees anything. The answer must validate against the AdCP schema and be proposed or rejected, or Chef answers. Then each proposal must pass five checks, and one that fails is withheld: If every proposal is withheld, Chef answers. Your agent plans only for an account the buyer holds. Before your agent is called, Apostra checks that the buyer holds the account its request names, as it does for Chef, and that any brand the request names is that account’s own. A request for an account the buyer does not hold, or for another advertiser’s brand, is refused, and your agent never sees it. Your agent receives the account by its id and the brand the proposal is for. The buyer sees your storefront, not your agent. The products in the answer are your storefront’s own, from its catalog, and each proposal gets a proposal id your storefront assigns. Each purchase is priced at the pricing option it names, as your catalog publishes it. Your agent’s own products, ids, extensions (ext) and messages are left out, so nothing in the answer names or reveals your agent. For now none of your agent’s own words reach the buyer either: each proposal’s name comes from your catalog’s product names, its description and brief_alignment are left out, and a rejected answer reaches the buyer as the storefront’s standard decline, not your agent’s reason and suggestions. Your agent’s text will reach buyers once Apostra screens it. Every call is on your decision record. An answer the buyer got, a brief your agent declined, a proposal withheld (with the check that withheld it, such as grounding_failed or pricing_currency_mismatch) and a call that missed its time (deadline_missed) are each a decision, with your agent as the brain. A shadow brain’s decisions are recorded the same way, marked as shadow. Read them with search(kind: "decision").

When Prime answers

Prime is your account’s own. It runs inside Apostra, so there is no endpoint to connect and nothing to verify: you choose it with prime, as answering or as shadow. Prime reads only your storefront. For each request Prime reads your catalog and prices, your playbook and rate card, and how this buyer has dealt with you before, and nothing about any other seller or buyer. It writes the same kind of answer Chef writes, and that answer is checked the same way Chef’s is: your prices and floors, your currency and the safety checks on what a buyer sees. Prime has about 85 seconds to answer. If it does not answer in time, fails, or gives no answer a buyer may see, Chef answers instead, in the rest of the buyer’s two-minute window. A buyer always gets an answer. Prime answers storefronts that Apostra composes for. A storefront composed in a hosted sales agent is answered by Chef. Every call is on your decision record. Each Prime call, as the answering brain or as a shadow, is a decision with Prime as the brain, and shadow calls are marked as shadow. Read them with search(kind: "decision"). A shadow Prime runs at no charge during the beta.

Refusals