Skip to main content
Three facts about an inventory source are readable from V3 without a second tool: whether the source is Apostra’s hosted adapter, which Agent powers it, and how its latest tests went. The first is on every source. The other two are opt-in, so a get that names neither returns exactly what it returned before.

Is the source an adapter

Every source carries isAdapterSource, a boolean. It is on each row of search({ "kind": "inventory_source" }) and on the object of get({ "kind": "inventory_source", "id": "SOURCE_ID" }). isAdapterSource is true when the seller account is routed through an official Apostra-hosted adapter and this source is that adapter’s source. It is false for every other source, including an external sales agent you connected yourself. A caller that wants to tell an Apostra-hosted source from an external one reads this field instead of working it out from the source’s name or endpoint. Whether Apostra operates a source can also depend on how it executes. A source with executionType: "MANAGED_SALES_AGENT" is operated through an Apostra-managed ad-server connection, and an adapter source is operated through a hosted adapter, so a caller that means “Apostra runs this source” treats either as true. isAdapterSource answers only the adapter half. The app names each source by how it executes: “Sales agent” does not say who runs the agent: it can be one you run or one a partner runs for you. On a Listing account that agent is how buyers reach you. On a Storefront account it is one of the sources Apostra’s agent sells from. An executionType the app does not know is shown as unrecognized rather than as a sales agent. The field is isAdapterSource and not a single managed flag for two reasons. The server already computes this exact boolean, so the field reports an existing answer rather than a new rule. And managed already means something else on a source: connection.state: "managed" says the source is provisioned through its own flow and has no credentials of yours to enter.

Listing every source

search({ "kind": "inventory_source" }) returns up to limit sources (at most 200) and, when more match, a nextCursor. Pass it as cursor with the same filters to read the next page, and stop when a page comes back without one. A cursor that is not a whole number is refused with INVALID_CURSOR. total is the number of sources that match the filter, so it stays the same on every page. Pages read the list as it stands when each call is made, so a source added or removed between pages can shift the next page by one.

Which Agent powers the source

Call get with kind: "inventory_source", the source’s id and include: ["poweredByAgent"]. The result carries poweredByAgent, which is one of three things:
There is no other state. “Nothing is mapped” is null, not a state of its own. canOpenAgent is true only when the Agent lives in a Developer account and you are Apostra staff or hold a role in that account. Belonging to the same organization is not enough: a person in a Seller account can have no role in the organization’s Developer account. Show or follow an “Open agent” link only when canOpenAgent is true.

What an active mapping shows about the Agent

agent is the limited view a seller gets of an Agent it uses, whether or not it owns the Agent. It is the same overview the older Powered by read returned, and it is built for a reader who is not the Agent’s operator, so it leaves out what only the operator may know. The view never includes the operator’s internal identifier or whether the operator has claimed the Agent, even for an Agent you own. It carries nothing about the Agent’s other customers: no other seller’s identity, counts, traffic, sources or evidence. To read an Agent you own in full, with its diagnostics, call get({ "kind": "agent", "id": "AGENT_ID" }).

The latest source tests

Call get with kind: "inventory_source", the source’s id and include: ["testRuns"]. The result carries testRuns, the five most recent tests recorded for this source, newest first. A source that has never been tested returns an empty list.
get reads recorded tests. It does not run one, and it does not probe the source. A test belongs to a source when it was recorded for that source’s id or key, so a test recorded without either does not appear.

Where to ask for them

Both includes belong to kind: "inventory_source". They are refused on any other kind, including kind: "seller", and a Buyer Account cannot request them.

When a read fails

There is no “unknown” value. If Apostra cannot work out poweredByAgent or testRuns, for example because a lookup timed out, the call fails with SERVICE_UNAVAILABLE and returns neither include, so you never act on a guess. Retry the same call.