Skip to main content
Your coverage is the set of publisher domains you sell and the properties claimed under them. Each domain carries an authorization verdict that comes from the publisher’s own adagents.json. Apostra re-reads those files on a schedule. When you have just fixed a publisher’s file, or a publisher has just published one, you can ask for a re-read now instead of waiting. The entry a publisher adds to authorize your Storefront is on Authorizing Apostra in a publisher’s adagents.json.

Read your coverage

search({ "kind": "coverage" }) lists your declared domains with each one’s authorization status and reason. get({ "kind": "coverage" }) returns the roster with the properties under each domain.

Add, remove or replace what you declare

save_coverage changes your declared coverage in two ways. Name only what you change, or declare the whole set.
  • add declares the domains you name and leaves every other domain alone. A domain can be a bare domain or a full URL. Apostra stores the bare domain, without the scheme, path, port or leading www.. Declaring a domain you already declared is not an error.
  • remove un-declares the domains you name. A domain Apostra crawled or discovered for you is not yours to remove. It stays, and the call reports a conflict instead of a removal. A domain you remove is also removed from your managed sales agent, so you can no longer build products for it.
  • domains declares the whole set and replaces what you had, up to 5,000 domains. A domain in both your old and new set keeps its properties, collections, formats, your own property claims and its authorization verdict. A domain you leave out is removed only if you declared it, and it is removed from your managed sales agent too. Apostra’s crawled and discovered domains stay. You cannot combine domains with add, remove, declareProperties, removeProperties or refresh in one call.
  • declareProperties claims a property under a domain you already declared. Give a property_id, an identifier or a name. Apostra never invents an identity. If the publisher’s own file already declares the property, the publisher’s entry keeps its identity and Apostra records your claim on it.
  • removeProperties retracts a claim you made. A property the publisher declares cannot be removed here. It follows the publisher’s file.
Apostra refuses a domain that cannot be a publisher’s site and says what to fix. That is a single word such as gundemhaber, a name ending in .example, .test, .invalid or .localhost, which are reserved and never point to a website, or a domain that DNS says does not exist. add checks all three. domains checks the first two but does not look up each domain, so a domain in a replace that does not exist shows up when Apostra checks it, as described below. One exception is for testing. A Developer account, your organization’s test storefront, or an account Apostra staff have flagged as a test account may declare a domain ending in .example, such as pinnacle-news.example. The AdCP test agent’s simulated inventory agents sell properties of fictional publishers on these names. Apostra skips the DNS lookup and never fetches an adagents.json for them, so they stay at pending and authorize nothing. A live storefront that staff have not flagged as a test account still refuses them, and .test, .invalid and .localhost are refused everywhere. When you remove a domain, Apostra takes it off your managed sales agent before it takes it off your coverage. The agent keeps every other domain it holds, including domains you did not declare. If your managed sales agent cannot be updated, the call fails and your coverage is unchanged, so you can try again. A seller with no managed sales agent only has its coverage changed. A property you claimed is yours until you retract it. When the publisher’s file changes, your claim is never dropped: if the publisher stops declaring a property you also claimed, it returns to your coverage as your declaration.

Re-check a publisher now

Name the declared domains in refresh on save_coverage:
For each domain, Apostra reads the publisher’s adagents.json and format catalog again and returns a refreshed list. Each item carries: A domain you added to the roster is recorded on your managed sales agent the first time Apostra checks it, even when the check cannot read the publisher’s file, so you can build products for it straight away. Its authorization stays unchecked until a check reads the file. pushedToManagedAgent says whether this check’s result reached the agent. It is false when the check could not read the file, and Apostra checks again on its own. If it is false after a check that did read the file, the agent did not take the result, and you can re-check the domain again once the cause is fixed. The response also carries the authorization state for every domain you re-checked, so one call answers “is this publisher authorized now” without a second read. When Apostra could not reach a domain, because it timed out, its server failed or it blocked the request, the item says so and adagentsStatus is error. Apostra keeps trying on its own. When DNS says the domain does not exist, authorizationReason is domain_not_found and Apostra stops trying until you fix it: check the spelling, or declare the domain your site is served from. Both states also show on your setup checklist.

Limits

  • Only domains you have declared can be re-checked. A domain you have not declared is reported in failures as NOT_FOUND, and nothing is re-checked for it.
  • A re-check counts against the same 20-edit limit as add, remove, declareProperties and removeProperties, because each one fetches from the publisher.
  • A single call spends at most 45 seconds on re-checks. A domain the call did not reach is reported in failures as SERVICE_UNAVAILABLE. Send it again in a new call.
  • Apostra also reads the copy of the publisher’s file held by the AgenticAdvertising.org registry. When the publisher’s file authorizes you but the registry’s copy predates the fix, the registry’s copy still decides. The re-check then asks the registry to read the file again and waits for its answer, up to about 15 seconds across all the domains in one call. If the registry has not read the file by then, the domain keeps its old reason. Re-check it again in a few minutes.
  • Apostra makes a limited number of these registry requests each hour. When that limit is reached, a re-check does not ask the registry and the domain keeps its old reason until the registry reads the file on its own schedule.
  • Apostra also re-checks publishers on its own when their adagents.json changes. If one of those re-checks starts while yours is running, yours is reported in failures as CONFLICT and the other one’s result replaces it. Read your coverage again a few seconds later, and re-check again only if it still shows the old state.
  • refresh cannot be combined with domains, which replaces your whole set, and a domain cannot be in both remove and refresh.
  • A re-check can run in the same call as add, after it, so you can declare a domain and check it at once.