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.
adddeclares 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 leadingwww.. Declaring a domain you already declared is not an error.removeun-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.domainsdeclares 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 combinedomainswithadd,remove,declareProperties,removePropertiesorrefreshin one call.declarePropertiesclaims a property under a domain you already declared. Give aproperty_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.removePropertiesretracts a claim you made. A property the publisher declares cannot be removed here. It follows the publisher’s file.
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 inrefresh on save_coverage:
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
failuresasNOT_FOUND, and nothing is re-checked for it. - A re-check counts against the same 20-edit limit as
add,remove,declarePropertiesandremoveProperties, 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
failuresasSERVICE_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.jsonchanges. If one of those re-checks starts while yours is running, yours is reported infailuresasCONFLICTand 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. refreshcannot be combined withdomains, which replaces your whole set, and a domain cannot be in bothremoveandrefresh.- A re-check can run in the same call as
add, after it, so you can declare a domain and check it at once.
Related
- Authorizing Apostra in a publisher’s adagents.json gives the entry a publisher adds and what each authorization reason means.
- Seller readiness reads whether publisher authorization is blocking go-live.
- Errors explains the per-item
failuresand their codes.