Storefront agents

Deprecated. This page documents the v2 storefront API, which is being retired for external callers. Use Organization-owned Agents in V3 instead.

A storefront agent is an agent registered for use with your storefront — a sales/media agent, a signal/data agent, a creative agent, or an outcome measurement agent. Your organization can own the Agent (SELF) or use one from the wider set listed on Apostra (MARKETPLACE). Each Agent also carries capability metadata (type, protocol, authenticationType) and a lifecycle status. List and inspect Agents to decide which ones power your storefront and which need authorization. Agents that use OAuth need an interactive consent flow before the platform can call them. There are two flows: agent-level OAuth stores tokens in the agent configuration for platform-to-agent calls, and per-account OAuth stores tokens against the buyer/operator account the grant represents. All examples use the storefront base URL:

https://api.apostra.com/api/v2/storefront

Authenticate every request with Authorization: Bearer $SCOPE3_API_KEY.

Partner-agent endpoint URLs must be directly reachable public HTTPS endpoints. Private-network, localhost, DNS-rebound, and redirecting URLs are rejected when you create or update an agent. See Public callback URL requirements.

Manage an Agent in Apostra

Agents is its own workspace, and the Agent page belongs to the Developer account. Only a Developer account has the Agent page: a storefront, buyer or organization account never does, and the seller navigation has no Agents row. Switch to your organization’s Developer account with the account switcher, which opens on the Agents page, and the collection appears in the main canvas. If your organization has no Developer account yet, choose Create on the Developer account row of its account list. Select an Agent, then use its workspace navigation to move between:

Overview for identity, ownership, current status, and the next action.
Endpoint & protocol for the shared, non-secret endpoint contract.
Test Agent for the next test action, its result, and the Agent’s live certification results by use case.
Inventory sources for the exact Sales Agent deployments you can access.

Credentials belong to the exact Inventory Source and are never copied into the Agent or its observed revision. Open that source from Inventory sources to set up a supported connection. Other Agent roles show only the sections supported by their authorized connection contract. See Agents for the ownership and navigation model.

Prepare an Agent for testing

The page shows one next action for the Agent’s current state. A new Agent first needs an authorized Source connection with the endpoint and any required authentication. When you choose Test Agent, the platform reads the current observed protocol surface and tells you what still needs to happen before a test can start. The main test card shows the current outcome and the next useful action. The test it runs is a discovery test: it asks the Agent for its products with a no-spend brief. It is not certification. If the page says Testing needs setup, no test has run and no Agent check has failed. The message identifies the next safe action. Completing it does not deploy code or certify the Agent. The page keeps a safe diagnostic reference with a not-started result when the server supplies one. It does not show raw transport or provider error text.

Run a test

Use Run test only when the page says the test can start. The page names the current Source when that Source is the target. If the test environment is still being prepared, it does not present a runnable test button. A test records evidence; it does not deploy code or certify the Agent. The test the page runs for your account is the brief-only test. The page does not offer a transaction test, and a test is not certification. Certification is judged on live traffic, use case by use case. See How certification works. A claimed owner, or Interchange Support viewing an exact current Source, can start a test. Governed administrators can review the target, instructions, results, and certification state, but cannot run the test. If the app or the server refuses a test request before it starts, the page shows Test didn’t start with the reason. Nothing ran and no Agent check failed. Test status needs checking appears only when a request was accepted and its outcome could not be confirmed. Do not start another test until Apostra Support has reconciled it. The current Agent model does not represent separate serving and test targets in the public Agent read. Do not infer that registering an observation promotes new software or that a test is running against a different serving version. Results are bound only to the target the current runner reports. A test result identifies whether it completed, failed a check, or could not start, and reports the safe run reference and cleanup outcome when available. A passed test is evidence for the target it names, not a certificate or an authorization for a client connection.

Certification

Certification is per use case. Apostra places a small sandbox test buy for each use case the Agent declares, lets it serve through the seller’s real ad server, and judges the result from Apostra’s own tracker and the seller’s reports. The Agent page lists each use case under Live certification as Passed, Failed or Inconclusive, with a reason when it did not pass. One passed use case completes the Successful transaction go-live step for every Source that uses the Agent. Allow certification buys with Allow certification buys on the Developer account’s Agent page, or with certificationRequested: true on save_agent. See Allow certification buys. Registering a production revision is not a prerequisite for certification; it is used for change detection. Joining the Partner Program is a separate commercial action; it does not repair a technical test prerequisite or grant certification. See How certification works for what makes an Agent ready, what each check judges and what every result means, and Sales Agent requirements and best practices for the declarations Apostra reads. When some of a Sales Agent’s products declare no AdCP channels, the Agent page Overview shows a Products missing AdCP channels notice. It gives the count, explains that buyers filtering by channel won’t find those products, and links to how to declare them. Under the certification details, the Catalog Product Quality requirement also shows the full advisory count: how many of the Agent’s products declare AdCP channels, counted the same way as the storefront readiness warning Product channels declared. It covers the active third-party Sources your organization can see for the Agent. The count is guidance only. It never changes a certification result, and it is omitted until a product from one of those Sources has been observed. The count covers up to 50 Sources; when the Agent has more, the page says so under the count. See Declare AdCP channels on every Product.

Provision a text-message line

A storefront Agent can be given its own SMS-capable US phone number. Apostra buys the number from its carrier and binds it to that one Agent, so inbound texts to it are routed to that Agent and messages sent from the line carry its number. Where Apostra has prepared the region for agent calling, it buys a number that can carry calls as well as texts. That narrows what is on offer, so an area code with plenty of texting numbers can still come back empty. On such a number, calls reach the same Agent as texts. The line answers a call, tells the caller they have reached an automated agent, and ends the call; it does not hold a spoken conversation yet. Answering a call is billed by the carrier as an answered call. See Agent voice lines for exactly what a caller hears and what Apostra keeps. If Apostra cannot confirm the number’s calling setup with its carrier, the line still becomes active for texting, and Apostra completes the calling setup separately. This is available only to organizations Apostra has enabled for agent phone lines. Until yours is enabled, a signed-in administrator’s request answers 404.

Who can request a line

Only a signed-in seller administrator can request a line. The request spends money — it buys a telephone number from a carrier — so Apostra refuses an API key, an M2M client, a service token, and any impersonated or simulated session, and answers ACCESS_DENIED. Apostra staff helping you through support access are refused too, even when support gives them administrator rights in your account: only your own administrators buy numbers. The same rule applies to reading a request’s status. Make the call from your authenticated Apostra session, not from a shared automation credential.

Request the line

POST https://api.apostra.com/api/v2/communications/phone-lines

{
  "requestId": "cdb0f08c-b2fc-46bd-bf24-25142fb31f19",
  "storefrontAgentId": "storefront-AGENT_ID",
  "areaCode": "347",
  "maxQuotedUpfrontUsdCents": 500,
  "maxQuotedMonthlyUsdCents": 500
}

requestId is a UUID you choose; it makes the request replayable. areaCode is a US area code. The two price fields are the highest quoted prices you accept for the number.

A price limit is a limit on the carrier’s quote, not a cap the carrier enforces. Apostra reads the carrier’s own price for the exact number immediately before it orders, and orders only while that price is at or below both of your limits and Apostra’s own deployment limit. The carrier offers no maximum-price field on a number order, so a price change inside that last window is billed at the carrier’s price. Apostra reports the price it read at the moment it ordered, so you can reconcile it against the invoice.

The request returns 202 Accepted. It does not mean a number was bought.

Follow the request

GET https://api.apostra.com/api/v2/communications/phone-lines/{requestId}

The status moves through requested, ordering, order_pending, and binding before it reaches one of:

Status	Meaning
`active`	The line is live. The response carries the assigned `phoneNumber` and its `endpointId`.
`failed`	No line was bought, or one could not be bound. `failureCode` says why — for example `no_number_within_quote_limit` when nothing suitable in that area code is offered at or below your limits, or `provider_order_failed` when the carrier declined the order. A request that keeps hitting a temporary problem before anything is ordered — the carrier is unavailable, or the number it offered stops being available — is retried for about ten minutes and then fails with the last `failureCode` it saw. Send a new `requestId` to try again. When a failed request still reports a `phoneNumber` (a number was bought but not bound, or the order never settled, `provider_order_pending_timeout`), an Apostra operator reconciles it before the agent can request another line.
`submission_unknown`	The carrier may hold a purchase Apostra could not confirm — no conclusive answer, or an order Apostra cannot match to this request. It is terminal, an Apostra operator reconciles it by hand, and it never retries — that is what stops a second number from being bought.

phoneNumber is set only once the carrier has accepted an order for that number. A request that fails before then reports no number and no quote. Once a number is held, quotedUpfrontUsdMicros and quotedMonthlyUsdMicros report the accepted price in USD micros (1,000,000 micros = 1 USD).

Replays and conflicts

Reuse the same requestId with an identical body after a client timeout: the replay returns the original request with duplicate: true and buys nothing. Reusing a requestId with different input returns CONFLICT. So does a second request for an Agent that already has a line, or an unresolved earlier request.

Request a line from Distribution

Your Listing page shows a Text destination under Distribution once your organization is enabled for agent phone lines. It covers your storefront’s own Agent and shows what to do next:

The Text tab shows	What it means	What to do
Add number	The Agent has no line, or its last request ended without buying a number.	Enter a US area code and select Add text number. The tab shows Apostra’s deployment price limits before you submit, and the request is held to them.
Setting up	A request is being ordered and bound (`requested`, `ordering`, `order_pending`, or `binding`).	Nothing. Setup continues after you close the page; check back in a few minutes.
Ready	The line is active. The tab shows its number.	Nothing. Texts to that number reach your storefront Agent.
Needs attention	The carrier may already have sold a number for this Agent: the request is `submission_unknown`, a bought number could not be bound, or an order never settled.	Contact Apostra support. An operator reconciles the order; another request for this Agent is refused until then.

The same rules apply as for the API request: only a signed-in seller administrator can add a number, and Apostra staff using support access cannot. If the page loses its connection while you submit, select Add text number again with the same area code. The page replays the original request instead of buying a second number. An agent can read the same state without opening the page: get({ kind: "distribution" }) returns it as channels.text, which is null until your organization is enabled.

Field	Type	Meaning
`storefrontAgentId`	string or null	The storefront Agent the line belongs to. `null` when the account has no active storefront.
`status`	string or null	The status of the Agent’s line or request, from the table above. `null` when the Agent has no line and no request on record.
`requestId`	string or null	The request that bought or is buying the line.
`phoneNumber`	string or null	The number in E.164 format, once the carrier has accepted an order.
`failureCode`	string or null	Why the last request failed, when it did.
`canRequestLine`	boolean	Whether a new request for this Agent would be accepted.
`maxQuotedUpfrontUsdCents`	number	Apostra’s deployment limit on the upfront quote, in US cents.
`maxQuotedMonthlyUsdCents`	number	Apostra’s deployment limit on the monthly quote, in US cents.
`nextStep`	string	One sentence naming the next action, or that none remains.

Requesting a number stays a page action. The model-visible tools never buy a number.

Task reference

Create an Agent

POST /agents — register a private Agent for your organization

List agents

GET /agents — registered agents, filterable by type, status, and relationship

Run creative conformance

Run AdCP’s no-spend creative storyboards against an Agent’s attested endpoint

Publish connection setup

Define, preview, and publish the immutable non-secret contract publishers use

Start here

Buy media

Sell media

Help and updates

Storefront agents

Manage an Agent in Apostra

Prepare an Agent for testing

Run a test

Certification

Provision a text-message line

Who can request a line

Request the line

Follow the request

Replays and conflicts

Request a line from Distribution

Task reference

Create an Agent

List agents

Run creative conformance

Publish connection setup

​Manage an Agent in Apostra

​Prepare an Agent for testing

​Run a test

​Certification

​Provision a text-message line

​Who can request a line

​Request the line

​Follow the request

​Replays and conflicts

​Request a line from Distribution

​Task reference

Create an Agent

List agents

Run creative conformance

Publish connection setup

Manage an Agent in Apostra

Prepare an Agent for testing

Run a test

Certification

Provision a text-message line

Who can request a line

Request the line

Follow the request

Replays and conflicts

Request a line from Distribution

Task reference