Skip to main content
New to building on Apostra? Start with Build and certify an agent. Every agent you build lives in your organization’s Agents account. An organization holds one Agents account, and it holds any number of agents. Name it with accountId on every call you make to create an agent. If the organization has none, create it from the organization’s Accounts screen or with save_account in the organization account. A second Agents account is refused.

Who can do what with an agent

Your role in the Agents account decides what you can do with its agents. The roles are the ones on the account’s member list: Each of these actions needs a person signed in as themselves. Service tokens, delegated sessions and impersonation cannot take them, whatever role the person behind them holds. On the agent’s Overview page, a button that runs a test or the Allow certification buys switch shows to Operators and Admins, and the other buttons that change something show to Admins only. A member of the organization who has not been added to the Agents account does not reach it; an Admin adds them as a member. An administrator of the organization is an administrator of every account in it, so you do not need to be added to the Agents account as a member. Open it on the web or name it with accountId, and you can create, read and register agents there. See Name the account on every call. An Apostra support person sees the agents read-only unless a staff elevation is active. The Agents account’s Account members page lists everyone with access to the account: the people added to it and the administrators of the organization. An organization administrator has access without being added, so the page tags them Organization admin and offers no Remove or permission control on them. An organization administrator opens Organization members from the page to manage that access. A session that may see the members but not change them, such as a read-only Apostra support session, sees the list without Invite members or the other member controls. A session that may not see them is told so instead of being shown an empty list. An agent reads the same list with search and get for kind: "member", where each member says in accessSource whether it was added to the account or comes from the organization. See Who an account’s member list shows and Inviting members.

Start building

Building a sales agent? What a great sales agent does puts everything it has to do in order, step by step, and the sales agent checklist lists what to declare before you connect it. Any of these opens the same Connect an agent task:
  • My agents. Choose Connect an agent.
  • Ask Apostra. In the Agents account, ask for the agent you want, for example “build a sales agent for my publisher”. Apostra opens the Connect an agent task. Ask Apostra’s starter prompts in an Agents account cover building a sales, creative or buyer agent, testing an agent and getting it certified. In an Agents account Ask Apostra has the same tools as the account’s /mcp/v3 connection, so it can also connect an agent’s URL, read an agent’s findings and open its pages. It works on the agent you name or have open; when the account holds several and it is not clear which you mean, it asks.
  • The Agents screen. Choose Connect an agent.
  • MCP. Call open_create_agent_task on the organization MCP surface. From an Agents account’s /mcp/v3 connection, call open_agents_page, then choose Connect an agent. To connect an agent without the task, call save_agent with the agent’s URL: see Connect an agent from its URL. To register a sales or creative agent that has no URL yet, call save_agent with no agentId, and send kind, displayName and an idempotencyKey. For a sales agent you can also send salesMode. A buyer agent is created with save_buyer_agent.
  • REST. POST /api/v2/agents. See Create an Agent for the request and errors.

What the task asks

The task first asks what you are connecting, then asks for the agent’s URL and shows you what Apostra read. The agent belongs to your organization. Everything it shows, and every field it makes required, comes from the save_agent response, so an assistant calling save_agent sees the same answers.
  1. Choose what you are connecting. The first screen, What are you connecting?, offers three choices. Your choice decides the next steps. It is never sent to Apostra, and it does not change what Apostra reads: Apostra works out what the agent is from what it serves, and tells you when that is not what you chose. Another kind of agent skips the choice for a creative agent, a buyer agent or an agent you have not built yet. Opening the task with a kind already chosen starts on the URL step.
  2. Enter the URL. Paste the agent’s address and choose Read agent. Beside it are two other choices: It’s a buyer agent and I haven’t built it yet. Change what I’m connecting returns to the first screen.
  3. Confirm. The task shows the kind, the sales mode if it is a sales agent, a suggested name, what the agent also declares and what Apostra read. You can change the name. If the agent declares no buying mode, you choose its sales mode. A field the agent did not declare is empty and required. If the agent declares both a sales and a creative role, you choose the kind first. If your Agents account already has an agent of the same kind that you registered with no URL, the task lists it as Connect this URL to [name], with Register a new agent beside it. Nothing is chosen for you. Choosing an existing agent connects the URL to it and keeps its name. A buying mode declared by the agent replaces its saved mode; without a declaration, the saved mode stays. Choosing Register a new agent works as described below.
  4. Connect. Apostra records the agent and its URL, then starts its first test. The task shows Connected while a creative agent’s test runs, and Tested when the test passes. If the test fails, times out or does not run, the agent stays connected, the task says which, and a failed creative test can be run again from the task. A sales agent’s check runs again from its Agent page.
  5. Connect as the other kind. When the agent also declares the other offered kind, the task offers Connect as sales agent too or Connect as creative agent too. Each kind is its own agent and its own confirm, so connecting one never connects the other, and the task reads the agent again for the kind you choose.
If a read fails, the task shows the reason for it in plain words and keeps the address you typed, so you can correct it or try again. The reasons are listed in When a read fails. If the agent needs credentials before it will describe itself, the read does not fail. The task says Apostra could not read this agent, offers it as a sales agent named after its host, and shows Register sales agent in place of Connect. Registering saves its address without a read, and the task ends at Registered, not read yet, with the next step: connect the agent from your Seller account and store its credentials there. See Register an agent that needs credentials. It’s a buyer agent skips the read. A buyer agent calls Apostra with a credential and Apostra never calls it, so it needs no address. You give it a name, which is only a label you’ll recognize it by, such as a person’s or a team’s name. The task creates it and opens the credential step, where you set up the credential it uses to call Apostra. Apostra stores no URL for a buyer agent. I haven’t built it yet registers an agent by kind and name only, so you can connect its URL later from its Agent page. Registering an agent by kind and name records its identity only. It does not publish the agent, connect a source or request credentials. See Agents.

Connect an agent from its URL

You can paste an agent’s URL and let Apostra read what it is, then save it. Apostra calls the agent’s get_adcp_capabilities tool, works out the kind of agent it is, how a sales agent sells and what to call it, and shows you the result for you to confirm or correct. Saving it creates the agent in your Agents account and records its URL, so the agent moves from Built to Connected. To register an agent that has no URL yet, use a kind and a name, as in Start building, and connect it later.

Preview what Apostra reads

Call save_agent with the agent’s URL and dryRun: true. A preview needs no idempotencyKey, saves nothing and creates no agent.
You can send three optional fields to confirm or correct what Apostra read: kind (sales or creative), salesMode (WHOLESALE, COMPOSING or BOTH, for a sales agent only) and displayName. salesMode supplies the answer when the agent declares no buying mode; it cannot replace an explicit declaration. A correction can change the name. It can never add a role the agent does not declare: a kind the agent does not declare is refused with the reason kind_changed.

What Apostra reads

Apostra reads the agent with no credentials. It finds the agent’s MCP endpoint, lists its tools, and calls get_adcp_capabilities. The preview returns what the agent declared, under reading: The preview also returns waitingAgents, outside reading and inferred: your Agents account’s agents of the inferred kind that have no URL, each with its agentId and displayName. It is empty while the kind is not chosen, for a buyer agent, and when nothing is waiting. See Connect an agent you already registered.

What Apostra infers

What Apostra infers comes only from fields the agent declares. No product, price, traffic or hostname decides anything. The result is under inferred. One role is previewed at a time. An agent that declares both sales and creative can be connected as either, one after the other. If a pasted URL has no AdCP agent behind it, Apostra makes one more public request, for /.well-known/brand.json on the same address. When that file lists the URL as a buying agent, the read reports the kind buyer. Apostra uses it only as a suggestion and never stores the URL. Create the buyer agent with save_buyer_agent.

What needs means

needs lists what you still have to supply before an agent could be saved: kind when the agent declares both kinds, and salesMode when a sales agent declares no buying modes. An empty list means the read decided everything. Send the missing field on the next preview to confirm it. When an agent needs credentials, the preview has not read its declarations: needs is empty, and its sales mode may remain null until the credentialed read.

Save the agent

To save, send the same call without dryRun, with an idempotencyKey (a UUID you generate) and the confirmations you chose.
Apostra reads the URL again when you save. It does not trust an earlier preview, because the agent may have changed in between. A save is refused, and nothing is created, when:
  • needs is not empty. The error names the missing field (kind or salesMode) and carries the reason needs_confirmation. Send the field and save again.
  • the kind you confirm is no longer one the agent declares (kind_changed).
  • the URL reads as a buyer agent. Apostra never stores a buyer agent’s URL, and the error points you to save_buyer_agent (buyer_agent_not_connected_by_url).
  • your account already has an agent of this kind with that name. Choose another name.
One save connects one role. To connect an agent that declares both sales and creative as both, save twice with a different kind and a different idempotencyKey. Each role is its own agent.

What saving creates

A successful save writes everything together, or nothing: The response is the developer_created outcome. It carries agentId, created, stage, reading, inferred, connection, test and endpointControl. connection.state is connected and connection.revision is the revision’s id. endpointControl is unverified or verified, as Prove your agent is yours explains. stage is the agent’s stage as get_status reports it, so the two always agree. test says which test applies to the agent and what happened to it, as the next section explains.

What happens right after connecting

Saving connects the agent first and tests it second. The test runs after the connect has committed, so a test that fails, times out or cannot run never undoes the connect: the agent stays Connected. A sales agent is checked inside the same call. Apostra runs the endpoint check against the URL it just read: one get_products call with a fixed no-spend brief, sent with no credentials. The check may spend up to 10 seconds on get_products, and it must be over within 25 seconds of the start of the save_agent call. Reading the URL counts against those 25 seconds, so a slow read leaves the check less time. The quick reads that build the response afterwards are not counted. test carries profile: "endpoint-brief" and one of these states: For failed, timed_out and not_started, fix anything slow or failing at the agent URL, then re-run the endpoint check from the agent’s Agent page. stuckOn on get_status names the same next step. A creative agent is handed off. Creative conformance can take up to 90 seconds, which no tool call should wait for, so the response returns test: { "profile": "creative-conformance", "state": "not_started" } and names how it starts in test.start. The Connect an agent task starts it with POST /api/v2/agents/{agentId}/creative-conformance, the call the Agent page already makes. An assistant opens the Agent page with open_agent_page, because there is no typed V3 call that starts a test yet. The creative agent stays Connected until a conformance run passes. What Tested means. An agent is Tested when its latest test run passed. A passing sales endpoint check is recorded for 30 days, and a passing creative conformance run for 7 days. Re-run the test before then to keep a current result.

Connected, Tested and not yet verified as yours

An agent is Connected once Apostra holds its URL and has read it. It is Tested when its latest test run passes. Saving runs the first test for a sales agent and hands it off for a creative agent (see What happens right after connecting), and later runs start from the agent’s Overview page. Connected and Tested are statements about the URL: Apostra read it, and it answered as an AdCP agent. They do not say that you run the agent. Apostra cannot tell, from reading a URL, who controls it, so every agent connected from a URL starts not yet verified as yours: endpointControl is unverified. Until you prove you control the URL, the agent:
  • cannot be given Partner standing or listed in the marketplace.
  • cannot be used by another organization.
An unverified agent can still be certified through your own organization’s storefront: Allow certification buys and certification need no proof, because an agent behind its owner’s storefront is reached only through Apostra. Only your own account can see the agent, so a connected URL never appears as another company’s agent.

Prove your agent is yours

Apostra checks that you control an agent’s URL by reading a file on the agent’s own host. It checks right after every connect, and again each time you connect the same agent again with its agentId and agentUrl. There is no separate call and no new input. What to publish, and where. Serve a brand.json at https://<your agent's host>/.well-known/brand.json, on the same host as the agent’s URL and nowhere else. Add an entry to its agents list for the agent:
  • url is the agent’s URL exactly as Apostra stores it, character for character: the same case, the same path, the same presence or absence of a trailing slash. The response of the connect names it as reading.agentUrl, and stuckOn repeats it.
  • type is sales for a sales agent and creative for a creative agent. A proposal agent is listed as sales, because AdCP’s brand.json has no proposal agent type.
  • The file is a valid AdCP brand.json, which also gives each entry an id of lowercase letters, digits and underscores.
The domain rule. The agent’s host must be a domain your organization has already verified, or a subdomain of one. That is the domain registered on your account or organization once Apostra has approved it: an email on the domain, a DNS TXT record, or an Apostra review. See Which domain is which. A host on another domain does not verify, even if its file lists the agent. If your agent runs on a domain you have not verified, verify the domain first. A domain that only resembles yours, such as evilnorthstar.example, does not count as northstar.example. When the agent’s host is not on a verified domain, the endpoint_control.unverified finding and stuckOn name the host’s domain, for example “The agent’s host is on wapo.pub, which is not a domain your organization has verified. If wapo.pub is yours, verify it for your organization. If it belongs to someone else, move the agent to a stable host on a domain your organization has verified, then reconnect it.” An organization verifies one registered domain today, with one approval, so the host must be on that domain or a subdomain of it. If your agent runs on a different domain from the one your organization verified, host it on a subdomain of the verified domain. Apostra cannot yet verify a second domain for an organization. Your brand domain does not widen this: verifying a brand domain that differs from the registered domain proves the brand, not the agent’s host. A shared or temporary host cannot be verified. A host on a domain that many unrelated people publish under, such as a tunnel (trycloudflare.com) or a hosting platform’s subdomain, is not a domain your organization can own, so there is nothing to verify. The finding says so: “a shared or temporary domain that your organization cannot verify. Move the agent to a stable host on a domain your organization has verified, then reconnect it.” A tunnel host can also stop resolving without notice, which makes Apostra unable to reach the agent at all (see When Apostra cannot reach your agent). The same applies to a domain that belongs to a third party, such as another organization’s website: move the agent to a host on your own verified domain. How Apostra reads it. Apostra fetches the file from that exact host. It follows no redirect at all, so a file served from another host, or from a path the host redirects to, does not count. It does not read the file identity.brand_json_url points to. It reads from public addresses only, waits at most 8 seconds, and reads at most 1 MB. How to re-check. Publish the file, then connect the agent again. The finding gives the call: save_agent with the agent’s agentId, its agentUrl and a new idempotencyKey (any value you have not used before). The response shows endpointControl, and the text version says why a check did not pass. A check counts against the same hourly limits as reading the URL, when it fetches the file. What stays true afterwards.
  • Verification belongs to the URL it proved. Connect a different URL and the agent returns to unverified, until the file on the new host lists it.
  • A check that fails because the file is briefly unreachable, missing or wrong leaves a verified agent verified. Only connecting a different URL, or losing the domain approval, ends the verification.
  • Verification lasts only while the agent’s host is on a domain your organization has verified. If the approval is withdrawn, for example the DNS record is removed or the member whose email proved the domain leaves, the agent reads as unverified at once in get, get_status and stuckOn, and Partner standing, listing and use by other organizations are refused again, with no re-check. Certification through your own storefront is not affected. If the approval returns, the agent reads as verified again. If you connect the agent again while the approval is missing, Apostra records it as unverified, and it becomes verified again when you connect it again after the domain is approved.
  • Until the agent is verified, get_status and get show endpointControl: unverified, and the endpoint_control.unverified finding tells you what to publish and where: the file URL, the entry with its url and type, and the domain rule. For a creative agent, which has no certification stage, stuckOn names the same step once the agent has passed its conformance test. An agent that was not connected from a URL carries no endpointControl at all.
What verification unlocks. A verified agent can be given Partner standing and listed, and can be used by another organization. Certification through your own organization’s storefront, and Allow certification buys, never need it. Publisher authorization (adagents.json) still decides whose inventory a storefront may sell.

Register an agent that needs credentials

Some agents refuse every call without a credential, including the call that describes them. Apostra never takes credentials on the Agents account and never in chat, so it cannot read such an agent when you save its URL. A save that reaches an agent like this does not create the agent unless you send kind: "sales". An agent does not have to answer get_adcp_capabilities without credentials to be connected. If it does, Apostra can show what it declares before you save it. In the Connect an agent task, choose Read agent and then Register sales agent. Then, in your Seller account, connect the agent as a source and enter its credentials in the secure credential form, as the steps below describe. Send the same save_agent call with kind: "sales", and optionally displayName and salesMode. Only a sales agent can be registered this way, because only a sales agent is read by connecting it in a Seller account; a creative agent that needs credentials is refused. Without displayName Apostra names the agent after its host, and without salesMode its mode is null (not decided). The first credentialed refresh sets the mode from the agent’s declared buying modes; if it declares none, choose a mode. Apostra records the URL as the agent’s address and returns the agent with notReadYet: { "reason": "authentication_required" }. An agent that has not been read has had no check run, and a check from the Agents account can never pass for it, because Apostra holds no credential there. So the agent’s validationSkill lists the endpoint-brief profile as UNAVAILABLE, its day_one_test.sales_validation finding says Apostra has not read it, and no Run the test again action is offered. Connect it from your Seller account (save_inventory_source with accountId and the agent’s agentId), where its credentials are stored. Apostra reads it then, and refresh_inventory_source_health runs the credentialed check on the connected source. A preview (dryRun: true) of an agent like this is not refused. It returns the preview outcome with notReadYet: { "reason": "authentication_required" } and saves nothing. Its reading holds only the URL, because nothing was read, and inferred offers a sales agent named after the host. It lists waitingAgents as for any preview: if one of your sales agents was registered with no URL, send that agent’s agentId with the agentUrl and an idempotencyKey to connect the URL to it, which records it as not read yet. Without a waiting agent, send kind: "sales" to register a new one. Nothing about the agent was read, so its declared protocols, AdCP releases and sales mode are not recorded, and no endpoint check runs. Apostra still checks whether your organization controls the URL, which needs no credential, so the agent is unverified until you prove it. Only an authentication refusal (an HTTP 401 or 403, an OAuth challenge, or the AdCP authentication error) takes this path. A URL that cannot be reached, a timeout, a TLS failure and an answer that is not an AdCP agent fail as they do for any save, and create nothing. The agent is read when your Seller account connects it:
  1. In the Seller account, call save_inventory_source with the accountId and the agent’s agentId. The address is the one you registered.
  2. Store the agent’s credentials on the source in the secure credential form. Credentials stay on the source.
  3. Apostra reads the agent with those credentials and records what it read on the agent: its capabilities, name and AdCP release. notReadYet becomes null, and the agent’s stage and test results follow from what was read.
Apostra reads the agent through the source when the credentials are stored, and again on an hourly check, including while the source is pending and waiting for certification. A read that was missed, for example because the agent was connected again after the source was, is recorded within about two hours. A source’s read is recorded on the agent only when the source calls the agent’s registered URL; a read of another URL is a read of another endpoint. A source keeps the address it was connected at, so if you connect the agent again at a new URL, the source still calls the old one and the agent stays not read yet. Point the source at the new URL from the Seller account (save_inventory_source with the source’s id and the new endpointUrl, then store the credentials that URL takes in the source’s settings), or connect the agent at the source’s URL again. While the agent is not read yet, its next step in get_status and in its day_one_test.sales_validation finding follows from the source of your organization that connects it: If the read with credentials fails, the source reports the failure as for any agent, and the agent stays not read yet. Saving the same URL again for an agent that has already been read changes nothing: a refused read never replaces what an earlier read recorded.

Retries and parallel saves

A save needs an idempotencyKey. Send the same key with the same request again and Apostra returns the first agent with created: false, without reading the URL again. Because nothing is read, reading and inferred are null in that response, and no test runs again: test is the result already recorded for the agent (not_started when none is recorded, for example after a timed_out). Send the same key with a different request and the call is refused with a conflict. A key only protects a retry. If you save the same URL as the same kind twice with different keys, even at the same moment, Apostra makes one agent and returns it with created: false the second time.

Connect an agent you already registered

To connect an agent you registered with a kind and a name, send its agentId with the agentUrl and an idempotencyKey. A dryRun is not accepted here: preview by omitting agentId. Without an agentId, save_agent makes a new agent unless one of your agents already has that URL, so a URL saved alone never lands on the agent you registered earlier. To avoid a duplicate, preview the URL first. The preview’s waitingAgents lists the agents of the same kind in your account that have no URL yet. If the URL belongs to one of them, send that agent’s agentId with the agentUrl and an idempotencyKey; to make a new agent, send the call with no agentId. The Connect an agent task asks you the same question: Connect this URL to [name] for each waiting agent, or Register a new agent.
  • An agent with no endpoint yet gets its revision, endpoint and deployment.
  • An agent that is already connected records a new revision when what Apostra reads from it changed. If nothing changed it keeps the revision it has. If the URL changed, the new URL becomes the agent’s endpoint, for example after you restart a tunnel, and the agent returns to not yet verified as yours until the new URL is proved.
  • The kind Apostra reads must be the agent’s kind, and you must own the agent. The agent keeps its name. Its declared buying mode replaces the saved mode; without a declaration, the saved mode stays. A call that sends displayName or salesMode with an agentId is refused. Rename an agent with displayName and no agentUrl.

Which URLs Apostra accepts

  • An https address, up to 2048 characters, with no username, password, query string or fragment, on the default port (443). A bare host such as agent.example.com is read as https://agent.example.com.
  • A name, not an IP address.
  • An address on the public internet. Apostra refuses localhost, private and internal addresses and any name that resolves to one.
  • No redirect to another address. Apostra follows redirects that stay on the address you pasted.
Apostra limits a read to 8 seconds for each call, 20 seconds in all, and 1 MB for any reply. It limits you to 20 reads an hour for the Agents account and 5 an hour for the same URL. A preview counts as a read. Only a directly authenticated Admin of the Agents account can read a URL, because the read makes requests in Apostra’s name and can change where Apostra sends the agent’s calls. An Operator re-runs the endpoint check from the agent’s Manual test runs instead. Service tokens, delegated sessions and impersonation cannot.

Test an agent running on your own machine

Apostra can only read agents reachable on the public internet, and there is no override. To connect an agent that runs locally, expose it through a public tunnel: a tunnelling service, or a reverse tunnel to a host you control. Paste the tunnel’s https address. When you restart the tunnel its address changes, so paste the new address.

When a read fails

A failed read creates nothing. A read that fails when you save creates nothing either. In the Connect an agent task, the message for the reason appears under the address field or in an alert on the confirm step, and the address you typed stays in the field, so you can correct it or try again. A reason Apostra returns that the task has no message for shows the server’s own message. The error carries a closed details.reason, the AdCP recovery (correctable, transient or terminal) and, where it applies, retry_after in seconds.

Find your agent’s places

In the web app, an Agents account lands on My agents when it owns no agents or several, and on the Overview of its agent, with the left rail already switched into it, when it owns exactly one. My agents stays in the rail. The chat box is under the page, as everywhere else. My agents lists your agents, one row each, with the agent’s kind, its certification stage (Not started, Testing, Waiting on you, Waiting on Apostra, Waiting on the seller or Certified), its next step and who acts on it. A buyer agent has no certification, so its status is its credential (Needs a credential, Credential not used yet or Connected; see Buyer agents). Choosing a row opens that agent. It lists every agent the account owns, including any Signal or Outcome agent it already holds, 25 at a time, and Show more agents adds the next 25. An agent Apostra mapped to your account that nobody has claimed is marked Apostra mapped · unclaimed, and an account administrator can choose Review and claim in its row. Under the agents are, in this order:
  • Connect an agent is for an agent you already run, whether it is a sales, creative or buyer agent. It opens the Connect an agent task. With no agents it is the main card. Once you have agents it is a button at the top right of the page instead, above the list. It shows only to an Admin of the account, who can connect agents; with no agents, anyone else sees the reason in the card.
  • Set up an agent on Apostra is for an agent Apostra hosts for you, starting with a buyer agent that plans and buys media for your advertisers. The card is hidden until hosted agents are offered to your account, and appears on its own when they are.
  • Work from Claude Code or Codex has the MCP address, the commands that install the Apostra skill in Claude Code and in Codex, and the sentence to say: “Connect my agent” with no agents, “Get my agent certified” after. Once you have agents it shows only its title, and Show setup opens the same commands in place.
The last rows are the guides (Build an agent, Connect an agent and Agent requirements) and links to the docs, AdCP, the AAO and GitHub. Whether an agent is verified as yours is not a status. An unverified agent’s proof is an attention finding (“Publish brand.json at your agent’s domain to prove you own this agent”) that says what it still holds back: listing, Partner standing and use by another organization. It does not stop certification through your own storefront. To work on one agent, choose it from the picker at the top of the left rail. The picker works like the advertiser picker: each agent has a kind label, the agents you chose most recently come first, you can search, and My agents returns you to My agents. Under the picker are only that agent’s places:
  • Overview: what needs your attention, the agent’s states, the checklist with the evidence behind it (live certification results, manual test runs, AdCP 4.0 readiness, capability declarations and, for a creative agent, conformance), the Allow certification buys switch and the agent’s endpoint and protocol details.
  • Activity: the calls Apostra made to the agent, grouped into certification runs. See Read the calls Apostra made to your agent.
  • Inventory sources: the sources connected to the agent.
  • Webhooks: the recent inbound webhook outcomes, each refusal with its reason.
API calls stays under Account in both views. Each place is its own page. Overview links to the agent’s Activity, Inventory sources (Connections for an agent that has no sources) and Webhooks pages, and each of those links back to Overview. The changes you can make from a page are the Allow certification buys switch and the one button each finding on Overview can carry (see Open the Overview page); the other pages only read. Claude, ChatGPT and other MCP hosts open the same page for the same place, so the web app and your assistant show you the same thing. To change anything else about an agent, ask your assistant or call save_agent. get_status in an Agents account also returns, for each agent, findingsHeadline (the finding the server chose to lead with, with its severity and a summary), findingCount (how many findings have not passed yet, whether they failed or Apostra has not checked them yet) and findingCounts (the same findings by outcome). If the findings cannot be read, all three are left out and the agent is still listed.

See which sources an agent is attached to

get with kind: "agent" returns relationships: count is every source attached to the agent, items lists the sources in your own organization by name, and hiddenCount is the attached sources the read does not list, which belong to other organizations’ accounts and stay private to them. A source that is still waiting for certification is listed like any other. Each item carries its state (ACTIVE, PENDING or DISABLED) and, when the source is not active, a reason, for example pending: waiting for certification. The same state reads the same on the source itself: get with kind: "inventory_source" returns selling.blockers with the same reason for a source that is not active, poweredByAgent.agent.currentSource.state is the source’s own state, and refresh_inventory_source_health returns the blocking reason in readiness.reason.

Read the calls Apostra made to your agent

Apostra records the calls it makes to your agent, and you can read each one that went through a source bound to your agent when the call was made. A call recorded with no source, or through a source that was not bound to your agent at that time, is not shown. The Activity page shows them for one agent, in two parts.
  • Certification runs. Each live certification run is one session, newest first. Its steps run from the first read of your products to the evaluation, in the order they happened. Each step shows when it happened, whether its calls succeeded, failed or are still pending, and a View call action for each call. The step that reads your products has no call to view, because Apostra reads them from its stored copy of your catalogue instead of calling your agent.
  • Other calls. The calls that belong to no certification step, newest first, such as get_adcp_capabilities and get_products. Each has a View call action.
View call opens one call in place with a way back to the list. It shows what Apostra sent, what your agent returned, the HTTP status, the status your agent reported, how long the call took and the error. Apostra removes its own credentials and the values under keys that look like credentials, such as token, secret or password, and shows them as [REDACTED]. Each body is capped at 32,768 characters and marked as cut short when it is longer. Apostra keeps request and response bodies for 90 days. After that a call still shows its timing and status, with no body. You see every call Apostra made to your agent, whichever seller’s storefront it came from. Beside the calls, a certification run shows the facts listed under Read a run and the calls Apostra made to your agent. You never see another seller’s prices, buyers or settings, or anything else that was never sent to your agent. The history starts when your organization took the agent. Moving the agent between accounts of one organization keeps it. A call made before your organization took the agent, because Apostra staff assigned it to you or it moved from another organization, is not shown. The seller whose storefront the agent serves does not read this page. On the Overview page, a certification finding that comes from a run has a View session in Activity action. It opens the Activity page at that run. To open the page, ask your assistant to open your agent’s activity, or call open_agent_activity_page with the agent’s agentId. Only the account that owns the agent can open it, and only while the agent is not archived. It changes nothing. Archiving an agent does not remove its certification sessions: you can still find and read them with search and get. To read the same runs and calls without the page, use search and get with kind: "session", as Read a run and the calls Apostra made to your agent describes.

Kinds of agent

When the agent is connected, the task reads it back for its sales role (salesRole on the agent read: storefront, inventory or proposal) and compares it with what you chose:
  • It matches. The task shows the role Apostra read. A sales agent that serves buying without proposals reads as an inventory agent and counts as a match, because an inventory agent is a sales agent.
  • It differs. The task shows a note, not an error: “You chose an inventory agent, but this agent serves something else”, with what Apostra reads it as. Apostra connects the agent as what it serves. A proposal agent that also books reads as a sales agent: the note appears before you connect, and it connects as a sales agent.
  • No role. When the agent has not been read, or serves neither proposals nor buying, the task shows no role and no note.
The Connect an agent task registers sales, creative and buyer agents. A buyer agent also needs a credential before it can call Apostra: follow Manage buyer agents.

Sales modes

A sales agent declares how it sells. The mode follows the AdCP buying modes the agent supports. When Apostra refreshes a connected sales agent’s capabilities, the agent’s own declaration keeps the mode current. An organization administrator can confirm or override the mode with save_agent, recording a reason.

The role an agent plays

An agent’s kind says what you registered it as. Its sales role says which half of the sales job it actually does. get for an agent returns it as salesRole. Apostra works the role out each time you read the agent, from the capabilities and tool list it last returned, so it follows the agent when the agent changes. You never set it, and it is not a certification: it says what the agent serves, not that the agent is certified in that role. salesRole is null when:
  • Apostra has not read the agent yet, for example because it needs credentials for every call;
  • the agent serves neither proposals nor buying;
  • the agent is attached to several sources and their stored capabilities give different roles; or
  • Apostra only has a snapshot of the agent’s tools, which carries no buying modes, and the agent buys without proposals. Such an agent could be an inventory agent or a storefront that takes briefs, and the snapshot cannot say which.
role is a different field: it still holds the kind, such as SALES.

Test and certify your agent

A sales agent reaches buyers, testing and certification through a storefront. The agent stays in your Agents account, and a storefront uses it as an inventory source. Apostra’s certification buyer buys through each source that uses your agent that is active, or pending in your own organization with healthy or degraded health, so an agent with no such source cannot be certified. A source you connect starts pending, and you do not have to activate it first: turn on Allow certification buys and Apostra certifies through your pending source. When the agent passes, the source goes live. You do not need a storefront of your own to do this. From your Agents account you connect the agent to your organization’s test storefront, which Apostra creates for you:
  • It is free and is never listed on Apostra. Nothing on it is offered to anyone outside your organization.
  • It holds only your organization’s own agents. It cannot take an ad server, a partner’s agent or a linked storefront.
  • It needs no plan change and no approval from an organization admin, and it has none of the go-live checks for listing on Apostra (brand domain, billing, currency, accepted countries).
  • Your organization has one. Apostra creates it the first time an Admin of the Agents account connects an agent.
Follow these steps in order. Steps 1 to 3 take an agent from registered to certified. Step 4 is optional, and step 5 is a quick check you can run at any point.
  1. Register the agent. In your Agents account, create a sales agent as described in Start building. See Sales modes for the choice it asks you to make.
  2. Connect the agent to your test storefront. Stay in your Agents account. Choose Connect this Agent on the agent’s page, or call save_inventory_source with only the agent’s agentId. It opens the connection form with the agent’s registered address already filled in, and you enter its credentials there. Credentials never pass through chat. Submitting the form creates the source, pending, on your organization’s test storefront.
    • Who can do it. An Operator or Admin of the Agents account that holds the agent, signed in as themselves. The role that counts is your role on the Agents account: you need no role on the test storefront. The first connection, which creates the test storefront, needs an Admin. Until then an Operator is told that an Admin of the Agents account creates it the first time they connect an agent.
    • Which agents. Only agents your Agents account holds. From an Agents account, save_inventory_source takes agentId and nothing else.
    • Credentials. The form takes an API key, a bearer token, a username and password, or no authentication. Connecting without authentication is allowed here, as in an Agents account, because the test storefront is for testing.
    • OAuth. An agent that signs in with OAuth cannot be connected from the Agents account yet. An organization admin can connect it from the organization’s test storefront account: name that account with its accountId (see Name the account on every call) and call save_inventory_source with the agent’s agentId there. If you would rather certify through a storefront your organization sells through, connect the agent there instead: in that Seller account, call save_inventory_source with the agent’s agentId. You need to be an Operator or Admin of that account. To create a Seller account, an organization administrator calls save_account with accountType: "seller" and approves the request on the website; the organization’s plan must allow the type of account you choose. See Manage organization accounts. Connecting your own agent to your own storefront does not by itself change your organization’s plan. Your organization counts as offering agents to other organizations only once its Partner standing is active.
  3. Allow certification buys. You do not need to prove control of the agent’s URL first: an agent behind your own storefront is reached only through Apostra. Turn on Allow certification buys, or send certificationRequested: true with save_agent. See Allow certification buys. Apostra then starts certification on its own, through its certification buyer, on each active source that uses the agent and on each pending source of your own organization whose health is not failing. When the agent passes, the pending source goes live. Setting the source to ACTIVE yourself is refused until then. See When Apostra starts a run, Test buy size and What is certification?.
  4. Optional: test as a buyer. To see your agent the way a buyer does, create a buyer account in the same organization with save_account and accountType: "buyer". Create a sandbox advertiser in it, which spends nothing. Your organization’s storefronts, the test storefront included, are available to its own advertisers whether they are listed or not, but the storefront still has to be ready to take a buy. Name your storefront with sellerAccountIds when the buyer calls request_proposals. The test storefront is never listed, so the buyer reaches it only by naming it this way. A request that names no sellers does not contact it, and a buyer in another organization cannot reach it. See Sandbox advertisers and live spend and Storefronts. This test is not a certification run, and it does not replace step 3.
  5. Check that the endpoint is alive. On the agent’s Overview page, open Manual test runs in the checklist and choose the endpoint check. It calls the agent’s endpoint with get_adcp_capabilities and get_products and a fixed discovery brief, and it creates no buy and spends nothing. It is offered while the agent has no source, and Apostra limits it to 10 runs an hour for each agent. Once the agent has a source, use Test product discovery in that source’s diagnostics instead. A pass shows that the endpoint answers. It is not a certification result. When the check cannot run, the agent read’s validationSkill lists the endpoint-brief profile as UNAVAILABLE, and its reason says why and what to do: a source uses the agent, no endpoint is registered for its production version (connect it from its URL), Apostra has not read it yet (connect it from your Seller account), or the agent is not claimed yet.
While an agent has no active source and no pending source of your own organization with healthy or degraded health, the agent read says so with the finding certification.no_source. If the agent is attached to no source, its action is step 2 above: connect the agent to your test storefront. If it is already attached to a source in your own organization that cannot be certified through yet, because the source is DISABLED or is PENDING with health that is not healthy or degraded, the finding names that source and its state and says the agent is already attached, so there is nothing to attach again. Bring a pending source’s health up with refresh_inventory_source_health, then turn on Allow certification buys; Apostra certifies through your pending source, then the source goes live. A disabled source has to be turned back on with save_inventory_source. When the agent also has an implementation.not_reachable or implementation.agent_error finding, fix that first: a pending source whose health is failing because your agent does not answer, or answers with an error, does not turn healthy until the agent answers the call. In an Agents account the agent read lists the endpoint check (endpoint-brief) first, and shows the brief and transaction tests (brief-only, transaction) as unavailable, with the reason “Run this from a buyer account that can buy through a storefront this agent is in.” Those tests buy through a storefront.
An agent that another organization owns is a partner’s agent, and a different route connects it: the partner publishes how publishers connect, and the agent must be certified first. The test storefront holds only your own organization’s agents, and a storefront in another organization cannot use your agent this way. Register the agent in an Agents account in the storefront’s organization, or ask Apostra support.

Allow certification buys

Allow certification buys is the control that decides whether Apostra sends certification buys to a Sales agent. On means Apostra sends them. Off means it sends no new ones; a certification buy already running finishes. Set it on the agent’s page, or with one field, certificationRequested, on save_agent. Both save the same setting: you save the value you want, and saving the value the agent already has changes nothing. With it off, Apostra sends no certification buys, so only your real traffic can show your agent working. See The certification deadline for when buys start to depend on a pass. On the agent’s Overview page, under Certification buys, Allow certification buys is a switch you can turn on or off. The page shows the switch only to someone who can save it, and shows Apostra’s own message if a save is refused. Anyone else sees whether it is on. The Overview page that an MCP host opens (see “Open the Overview page” below) shows the same switch. You can also ask your assistant, or call save_agent; to turn it off, send certificationRequested: false.
search and get for kind: "agent" return certificationRequested for every agent in the account, false until you set it.
  • Who can set it. An Operator or Admin of the Agents account that owns the agent, signed in as themselves. An Operator is enough because a certification buy spends nothing (see Which Source certification buys through). A Member sees whether it is on. Service tokens, delegated sessions and impersonation cannot set it, and another account’s agent answers as not found.
  • Which agents. Sales agents. Certification runs on live traffic for Sales agents only, so true on a Creative agent is refused. Saving false is always accepted.
  • What it does. Apostra starts certification runs on its own for each active Source that uses the agent, with no one at Apostra acting. If no run starts within a day, ask Apostra support. See When Apostra starts a run.
  • With a rename. displayName and certificationRequested can be sent in one call. Each is saved on its own, so if a call fails partway, repeat it with the same values. Renaming needs an Admin: an Operator who sends both is refused with a message that names displayName, and neither is saved. Send certificationRequested on its own instead.

See whether Apostra exempted an agent from certification

Apostra staff can exempt a Sales agent from certification until a date. The exemption belongs to the agent, not to any one inventory source, and until that date it counts wherever a certification pass counts: an inventory source can go live on the agent, including a publisher in another organization connecting to it for the first time, as if the agent had passed, and the agent takes new buys for every use case. Its other checks still apply. When the exemption ends, the agent takes new buys only for the use cases it has passed. See What a pass unlocks and The certification deadline. Only Apostra staff set, extend or clear an exemption. You cannot set it, and save_agent does not accept it. get for kind: "agent" returns certificationExemption beside certificationRequested: The field is read-only. Apostra does not show the reason for an exemption or who set it. To ask for one, contact Apostra support.

Archive one agent

Archive an agent you no longer want Apostra to use. An archived agent receives nothing: Apostra sends it no buys, certification runs or requests, and it no longer shows in search or get for kind: "agent". Archiving one agent leaves the others alone, including the agents that share its operator. To archive an operator and all its agents at once, ask Apostra support. Call save_agent with the agent’s agentId and isArchived: true:
Send isArchived on its own. If you send it with displayName or certificationRequested, Apostra refuses the call and saves nothing. Archiving an agent that is already archived changes nothing and succeeds.
  • Who can archive. An Admin of the Agents account that owns the agent, signed in as themselves, and Apostra staff acting in your account under a support elevation, for example when you ask support to do it. An Operator, a Member, a service token or a delegated session cannot. Another account’s agent answers as not found.
  • When Apostra refuses. Apostra does not archive an agent while it is still in use. The refusal says what holds it and how many, and changes nothing: a Source, active or pending, that still uses it; a live buy that has not ended and reports through a Source the agent serves; or a binding that only Apostra staff can close. Disconnect the Sources and let or make the buys end, then archive again.
  • Restore it. Call save_agent with the same agentId and isArchived: false. The agent comes back as it was, with its name and settings. Apostra does not reconnect its Sources: connect them again. If another agent in the account has taken the name since, rename that agent and restore again. If Apostra staff retired the agent’s whole operator, ask Apostra to restore it.
  • The record. Every archive and restore is written to the account’s audit log.
A sales agent you run for other publishers has a published connection setup: the non-secret definition a publisher follows to connect. The setup can carry an optional signupUrl, a public https page where a publisher who has no credentials from you signs up with you.
  • What it is for. A publisher either already has credentials from you or follows signupUrl to get them. You do not approve each publisher, and credentials are never sent through the assistant: the publisher enters them in the secure credential form.
  • What is accepted. A public https URL with no credentials in it, no query string or fragment, and no private or loopback host. Anything else is refused when you save the setup.
  • Where it shows. Your own read of the setup and the connection form a publisher sees when it connects to your agent.
  • Leave it out if you hand out credentials another way.

See where each agent stands

Call get_status in an Agents account to see every agent’s states and its headline finding. A state is a fact Apostra holds about the agent. The states are independent: an agent can be certified without an owner test run, and in one storefront as private and another as listed. They are not steps on a ladder, and no state implies another. A state that does not apply to an agent’s kind is null. Apostra never reports a state it has no record of: an agent with no test run has latestTest: null, not a made-up value. The headline finding says what to do next. Each agent carries findingsHeadline, the one finding to act on first, and get for the agent returns every finding with its fix. get_status offers it as agent_next_step for the agent whose headline is most urgent: a blocking finding first, then one Apostra has not been able to check yet that names who acts, then the attention finding with the nearest date, and only then a check that has not run and that nobody has to act on yet. See Findings: what needs your attention for what blocking, attention and advisory mean. Count problems apart from checks that have not run. findingCount counts every finding that has not passed, so it includes findings Apostra has not checked yet, and an agent with findingCount: 26 may have failed only four of them. findingCounts splits the same findings by outcome: A finding that passed is counted in none of the four. The first three are the problems; unchecked is work Apostra still owes the agent.
stage, nextStage, finalStage and stuckOn are deprecated. They still come back with the values they had, and Apostra removes them no earlier than 3 December 2026. Read states for what is true of an agent and the headline finding for what to do next. While an agent has no headline finding, stuckOn still names its next step, so no step is lost before the removal. While one does, the text of get, search and get_status, and the Overview page, show only the headline: they leave out stuckOn, the agent’s nextAction and certificationNextStep. The fields themselves keep coming back in the structured result until they are removed.
The status also lists build calls for each kind of agent and links to the developer resources: Build and certify an agent, these guides, the AdCP specification, the Apostra GitHub repository and the apostra-developer plugin for Claude Code and Codex. An agent connected from a URL also carries endpointControl, unverified or verified. While such an agent is not yet verified, the endpoint_control.unverified finding, and a creative agent’s stuckOn once it has passed its conformance test, name the file and entry to publish, as Prove your agent is yours explains. The same states come back whenever you read an agent in an Agents account: get with kind: agent and each result of search with kind: agent carry them, with the same values get_status reports, beside the deprecated stage, nextStage, finalStage and stuckOn. The text version of each read says the states in a sentence. My agents and the Agent page show each agent’s certification stage, or a buyer agent’s credential, and its next step; the Agent page still shows the deprecated stage and what is stuck until those fields are removed, and the web app’s Agent page adds a button for the next step. In any other kind of account an agent read carries no states.

Buyer agents

Every buyer agent in an Agents account has an agent record of the buying kind, the name AdCP gives a buyer agent in brand.json. save_buyer_agent creates the principal and the record together (save_agent registers sales and creative agents only), and get_status lists the buyer agent beside your sales and creative agents. The record is a handle for tracking the agent. The principal stays the credential, and what the agent may do stays as advertiser grants on your Buyer account. Creating the record grants nothing and changes no credential. A buyer agent’s state is its credential: states.credential says whether a credential is bound to it (issued) and whether that credential has made an authenticated call to Apostra (authenticated). Until then the credential.issued and credential.authenticated findings, and stuckOn until it is removed, ask for the credential (save_buyer_agent with credentialHandoff: true) or for the first call. My agents shows the same state as the buyer agent’s status: Apostra does not record a test run for buyer agents yet, so latestTest stays null. Certification for buyer agents is not available yet, so certified is null too; How certification works explains what it will take. Retiring a buyer agent removes its record from the list; renaming it renames the record. An organization with a buyer agent that was registered before the record existed gets the record from Apostra when the organization has exactly one Agents account. With several, save the agent from the account that should hold it (rename it, or request its credential handoff) and the record is created there.

Findings: what needs your attention

Read an agent with get (kind: "agent") to see its findings. A finding is one thing Apostra checked about the agent, in the order of the setup checklist: declarations, behaviour, tests, certification, then the AdCP 4.0 capabilities. Each has an outcome of passed, failing, or null when there is no decisive result: Apostra has not checked yet, or the check ran and was inconclusive. The summary says which. A behaviour finding Apostra has not checked yet says why in whatWeSaw: no matching calls in the last seven days, no evaluation yet, or no Source whose calls we judge (Behaviour findings). An inconclusive certification use case says when it ran, carries the reason the run recorded in whatWeSaw, and says what you can do next in howToFix. search with kind: "agent" returns each agent’s headline finding (findingsHeadline) and findingCount, the number of findings that have not passed. Your organization and Apostra staff, including support acting for your organization, can read findings. A partner that only connects to your agent cannot. Every finding also names an owner, the role that has to act on it: The two are often one company, but not always: a seller can use a partner’s agent. owner is a different question from stops.by, which says who enforces a block. A declaration finding (declaration.*) judges what the agent declared in its last read. Apostra reads those declarations from the agent’s Sources as soon as a Source has read the agent, including a Source that is still PENDING because the agent is not yet certified, so a connected agent shows each declaration as passed or failing right after the read, with whatWeSaw and howToFix naming the field to declare. The creative_kind declaration waits for the Source’s first products, and shows null until they arrive. While an agent has not been read (notReadYet is set), each declaration finding says not read yet and gives the same howToFix: connect the agent from your Seller account with its credentials. The stuckOn of an agent that a Source read with credentials says that no endpoint check has run, and that you start it from the Agent page, because the read does not run it. A failing finding has a severity that says what is at stake: A finding’s summary is one sentence of 120 characters or less, in Apostra’s own words, so a list or a page can show it on one line. Names and values your agent or a seller wrote, lists such as the untested formats, and the longer explanation of what the finding means are in whatWeSaw, and the change to make is in howToFix. A summary says “cannot” only when its severity is blocking, and only about what stops names. One finding is the headline, marked headline: true, and its action is the agent’s nextAction. It is the missing endpoint while neither the agent’s production version nor any source that uses it has a URL, because nothing else can happen first. Otherwise it is the first failing blocking finding. If none blocks, it is the first finding with no decisive result yet: not checked, or inconclusive. If every check has a decisive result, it is the attention finding with the nearest dueAt, then any attention finding with no date. An advisory finding never becomes the headline. Every failing finding carries whatWeSaw, howToFix and docsUrl. howToFix names the change to make, and where the change is in your agent rather than in Apostra, the finding’s action is NONE. The code below says where each finding is explained, and the next section says who has to act on each. Delivery-window calendar alignment is reported as behaviour.reporting_window_matches_breakdown_date; see Reporting window matches breakdown date finding. The behaviour and declaration codes are explained in Agent requirements: declarations and behaviour, certification in How certification works.

Who has to act on each code

A failed certification use case’s howToFix names the change for the check that failed, as What each check judges describes it.

When Apostra cannot reach your agent

The implementation.not_reachable finding is blocking, for certification, and the owner reads it on the agent’s Overview page, in get and in get_status. It appears when Apostra has never read the agent, or when the last call it recorded to the agent failed because the endpoint did not answer: the name did not resolve, the connection was refused, or the call timed out. whatWeSaw quotes that error and the date of the call. When no call was recorded, it says Apostra has never received an answer from the URL. An agent that needs credentials is not reported here: it has not been read, and that is a different state (see Register an agent that needs credentials). To fix it, make sure the agent is running and reachable from the public internet at its URL, then connect it again with save_agent, giving the agent’s agentId, its agentUrl and a new idempotencyKey. An agent that Apostra reaches only through its source, with no endpoint on its production version, is not connected again: fix it, then refresh its source’s health with refresh_inventory_source_health so Apostra calls it again. If the host is a tunnel or another shared or temporary domain, move the agent to a stable host on a domain your organization has verified first. See Prove your agent is yours.

When your agent returns an error

The implementation.agent_error finding quotes what your agent said. It is the error your agent returned to the newest failing call Apostra made to your agent’s own endpoint, or to the URL its source uses when its production version has none, in whatWeSaw, with the date and what Apostra was asking for (its capabilities, products or creatives). This includes an HTTP error your agent returns when Apostra first opens an MCP session at its URL, for example HTTP 503 Service Unavailable with your agent’s error body: your URL reaches your agent, so do not change it; fix the error your agent returns. Apostra reads only calls made from storefront sources in your own organization that use this agent, in the last 7 days. A source in another organization, a source for a different endpoint, and any reading that is not a call to your agent are never quoted, and no source name appears. The seller whose storefront uses the agent does not read the quote. AdCP’s correctable refusal of package assignments on sync_creatives (the code UNSUPPORTED_FEATURE, the field assignments and the recovery correctable) is not an error either: Apostra sends the creatives again without them, so it is never quoted here. See Answer package assignments on a creative sync. The finding clears once a later call succeeds. A network error that did not answer clears when any later call to your agent succeeds. Any other error clears when a later call of the same kind succeeds. The error is your agent’s, not Apostra’s, so the fix is in your agent: find it in your agent’s logs, change the agent so the call succeeds, then connect it again with save_agent or run the endpoint check from the Agent page. For an agent Apostra reaches only through its source, refresh that source’s health with refresh_inventory_source_health instead. The day_one_test.sales_validation finding quotes the same error when the latest test run failed. Your agent’s endpoint host is replaced with [agent host] in anything quoted.

When an inventory source is unhealthy

The source.health finding shows each inventory source that uses your agent and reads unhealthy, one finding for each, with subject set to the source. Apostra reads a source’s health as its row on the Inventory sources page reads it: from the checks Apostra made through the source in the last seven days. A source reads unhealthy when Apostra’s calls through it fail, for example because your agent answers get_products with an error, or because the source’s credentials no longer work. The finding names the source and its storefront, the date it went unhealthy, and links to the source, whose own diagnostics say what failed. It lists only sources in your own organization: an active or pending source whose seller account is in the organization that owns the agent. A source in another organization stays private, as on the agent read, so it never appears here. A turned-off source is not judged. While every source with a recent check is healthy or needs attention, the finding reads passed, and an agent with no recent check on any source has no source.health finding. Who acts follows the cause, in the finding’s owner:
  • agent_developer: your agent answered Apostra’s call with an error, or with a response Apostra could not use. whatWeSaw quotes your agent’s own words, with your agent’s endpoint host replaced by [agent host]. Change your agent so the call succeeds.
  • seller: the call got no answer, never left Apostra because the source’s credential could not be used, or your agent refused the credential the seller stored (AUTH_INVALID, AUTH_MISSING or AUTH_REQUIRED). whatWeSaw gives the code Apostra recorded, never the raw error. The seller reconnects the source or updates its credentials.
  • apostra: the failure is on Apostra’s side, and there is nothing for you to change.
It is attention, never blocking. Buyers’ requests still go to an unhealthy source and fail there until it recovers, and your agent’s other sources keep selling. After a fix, refresh the source’s health with refresh_inventory_source_health so Apostra checks it again; the finding clears once the source no longer reads unhealthy.

Open the Overview page

In an MCP host such as Claude or ChatGPT, ask to open your agent, or call open_agent_page with the agent’s agentId. It opens the agent’s Overview page, which shows:
  • The headline finding first. Its severity names it: Blocking, Needs attention, or Not ready yet when a check has not run. The page says what the finding stops, the date it becomes blocking when it has one, how to fix it, and links to the explanation. A page never reads as passed while any check has not run.
  • One button for each fix. A finding that has not passed carries one button for its fix. A check that has not run and that nobody has to act on yet has no button: it is waiting for evidence, and the checklist counts it apart from the findings that need you. Where the fix is a change to your agent’s own code, the button opens the finding’s explanation. Where you can do it on Apostra, the button does it: Review and claim opens the claim review for an agent Apostra mapped to your organization, Check the proof of control and Run the test again have Apostra read the agent at its URL again (the second also re-runs the endpoint check), Start the conformance test and Run the conformance test again run the creative conformance test, Set up a credential asks for a buyer agent’s credential and then shows a link to finish setting it up, and Open the inventory sources opens that page. Start the conformance test and Run the conformance test again show to an Operator or Admin of the account that owns the agent. Every other button that changes something shows only to an Admin of that account who is signed in as themselves. Anyone else sees the explanation links and the buttons that only open a page. After a change, the page reads the agent again and shows what Apostra now sees.
  • States. One line for each fact Apostra read about the agent: whether an endpoint is registered, how many storefronts use the agent and how many of them are publicly listed, whether it is certified, whether other organizations can find it, the latest manual test, and for a buyer agent its credential. A fact that does not apply to the kind of agent has no line.
  • The checklist. Every finding in the order above. Failing findings and findings Apostra has not checked yet are listed first, each with what we saw, how to fix it, when it was last checked and a link to the explanation. Findings that passed are collapsed under their own heading. Five findings show at a time.
  • Evidence. Under the checklist, one item for each thing Apostra checks. Each opens to its full evidence: Live certification (the latest result for each use case, named and marked as counting toward certification or not, with its channel, when it was judged, each check’s result and, when it did not pass, the reason Apostra recorded; Apostra derives the use cases from the agent’s products and capability declarations); Manual test runs (for a sales agent, the test plan with each test mode, whether it is available and why not, and the recent manual test runs with the outcome, the failed stage, who is accountable and the next step; live certification runs separately, so an agent can have no manual test runs and still show live certification results); AdCP 4.0 readiness and Capability declarations (the same checks as Getting ready for AdCP 4.0 and the declarations the agent makes, shown as declared or eligible for testing and never as passed, with what Apostra saw and how to fix each); and, for a creative agent, Creative conformance.
  • Certification buys. Whether the owner has allowed certification buys. For someone who can change the setting, this is a switch: turn it on or off and the page saves it with save_agent, then reads itself again, so what it shows is what Apostra saved. Anyone else sees only whether it is on. When Apostra has exempted the agent from certification until a date, one line gives that date. See See whether Apostra exempted an agent from certification.
  • Actions on two findings. For an agent Apostra mapped to your organization and you have not claimed, an organization admin sees Review and claim, which opens the claim review. For a claimed agent that has passed certification, an organization admin sees Open Partner operations, which opens the Partner page. No other finding has a button.
  • The agent and its endpoint. Its name, kind, states, the organization it is Built by, the AdCP versions it declares, when Apostra last read its capabilities, its production revision and when it was deployed, and whether the implementation Apostra observes still matches.
The page shows what get returns for the agent, to the same people who can read it, and opening it changes nothing. It leaves out internal fields, such as source identifiers and the links to a run’s diagnostics. Its two buttons open other pages; its one write is the certification switch. It is available in Agents accounts. The text Apostra writes for a finding (its summary, what we saw and how to fix it) is in English whatever language the host uses.

Open the Inventory sources page

In an MCP host such as Claude or ChatGPT, ask to open your agent’s inventory sources, or call open_agent_sources_page with the agent’s agentId. It opens a page that shows how many inventory sources the agent powers (connections, for an agent that is not a sales agent), and for each one its name, the storefront it belongs to, its lane (wholesale or composing) and its latest health: healthy, needs attention or unhealthy, with when Apostra last observed it, or that there is no recent evidence. Each source also shows its own reporting state: no report due yet, on time, late and recovering, needs action, or complete, or that none is available. The page shows each state as Apostra reads it and never adds them up; Source reporting health says what each state means. When the agent also serves other organizations, the page says how many more sources stay private to their organizations; it never names them. The page shows exactly what get returns for the agent, to the same people who can read it. It changes nothing. Credentials, reachability, mappings and failures are not on this page: each source’s own diagnostics carries them, and they do not change the agent’s certification. The tool is available in Agents accounts.

Claim an agent Apostra mapped to your organization

Apostra can map an existing agent to your organization before you register it yourself. That agent shows as unclaimed: it has an id, connections and history, but your organization has not taken ownership. Until an organization admin claims it, the agent takes no owner changes, cannot be certified and has no Partner authority. A legacy connection that was already serving may keep serving, and that is not a claim. The claim.review finding says so, to organization admins only. Its action, Review and claim, opens the claim review: you check what Apostra mapped and claim the agent. Claiming keeps the agent’s id, revisions, connections and history. A member who is not an organization admin, a service credential and Apostra support staff reading for you do not see the finding and cannot claim the agent.

Creative conformance findings

A creative agent’s conformance test runs a fixed set of steps against its endpoint. Each step is a creative_conformance.step finding with the step as its subject: passed, failing with the agent’s own error in whatWeSaw, or null when the step was skipped. A failed step is attention, because nothing stops a creative agent from working while a step fails.

After you create an agent

Test it in the sandbox. A sales agent then goes on to certification. A creative agent stops at tested, and a buyer agent has no certification path yet. What is certification? explains what makes a sales agent ready, what each check judges and what every result means. The Agents page describes the certification state each agent shows.