Only the third is inventory. A brand domain is never a product’s coverage. See
Publisher coverage for publisher domains and
Identity documents for
adagents.json and brand.json.
Choose a domain for Public distribution
Your public listing domain is the address where Apostra hosts your public listing. Use a subdomain that does not serve anything today, such asads.example.com.
Do not use the domain where your website runs, such as example.com or
www.example.com: pointing it at Apostra would send website visitors to your
public listing instead. Most DNS providers also do not allow the required CNAME
on a bare domain such as example.com.
- In Public distribution, enter the address only, such as
ads.example.com, withouthttps://or a path. - At your DNS provider, add the CNAME and TXT ownership records Apostra shows you. The CNAME must point to Apostra’s displayed target.
- After the DNS records have updated, select Check my domain. The check passes once Apostra can read the TXT record and follow the CNAME to its target.
www.example.com, use ads.example.com. Your
listing will be served at https://ads.example.com/, with its JSON at
https://ads.example.com/card.json and its embed at
https://ads.example.com/embed.
With the API
An account administrator can do the same steps withsave_seller, one
distribution change per call. Each call answers with the updated Distribution
read, which you can also read with get({ "kind": "distribution" }).
- Send
{ "distribution": { "hostname": "ads.example.com" } }. The answer shows the CNAME and TXT records to add. - After the DNS records have updated, send
{ "distribution": { "activateHostname": true } }. A check that finds a problem answers with the status it observed. It is not an error, so read the answer, fix the record and send it again.
hostname with "preview": true first.
The preview writes nothing and returns a confirmationToken. Replacing the
domain takes your public listing offline until the new one verifies, so show the
change to the person, then send the same hostname with that
confirmationToken.
To take your listing off Apostra and the public web, send
{ "distribution": { "visibility": "unlisted" } }. That takes effect at once.
To list it on Apostra, send { "distribution": { "visibility": "interchange" } }.
To list it on the public web, send { "distribution": { "visibility": "public" } },
which needs a verified public listing domain. Listing puts your listing in front
of buyers or the open web under your brand, so neither takes effect when you
send it. save_seller records the request and answers approval_required with
a link. An administrator of the account approves it on our site, and the listing
changes only then. While the approval waits, repeating the same call returns the
same link. Once it is approved, the same call answers with the updated
Distribution read. If the approval is rejected, expires or fails, nothing is kept
of it, so a repeated call starts a new approval; read get with
kind: "distribution" to see the current visibility first.
What the ChatGPT reviewer sandbox is
OpenAI’s reviewers need a login to try your storefront before the ChatGPT app is approved. The reviewer sandbox is that login. It gives a reviewer a view of your storefront as a buyer sees it, and nothing more:- It cannot spend money. Requesting the sandbox creates one System advertiser inside your account, marked as a sandbox advertiser. A sandbox advertiser is permanently no-spend: it has no real billing, so nothing a reviewer does can buy media or charge your account.
- It is read-only. The login carries read permission only, for that one advertiser. A reviewer can read what the buyer tools show, but cannot create or change a campaign, a media buy, a creative or any of your settings, and cannot see your other advertisers or any of their data.
- It does not change your listing. Revoking or expiring the sandbox removes the login and deactivates the System advertiser. It never touches your storefront, your listing or your brand.
- It is short-lived and yours to revoke. A sandbox is granted for 90 days at
a time, and you can revoke it now with
save_seller. Reviewers sign in with a generated email and password that only an administrator of your account can open, on our site. No tool returns that login.
Give your storefront agent a text number
The Distribution read shows the storefront agent’s text line when the account has the text channel. Buying the line costs money: Apostra buys one US local SMS number in the area code you choose, and the carrier charges an upfront fee and a monthly fee. Sosave_seller does not buy it on the call. Send
{ "distribution": { "requestTextLine": { "areaCode": "347", "requestId": "<a new UUID>" } } }
and it records the request and answers approval_required with a link. An
administrator of the account approves it on our site, and the number is requested
only then. The approval page shows the area code and the most the carrier may
charge upfront and each month. The order is refused if the carrier’s quote is
above those limits.
While the approval waits, sending the same requestId returns the same approval.
Once the line shows that request, the same call answers with the updated
Distribution read and there is nothing left to approve. If the approval is
rejected, expires or fails, nothing is bought, so send the same requestId again
to start a new approval. The call is refused up front when the account has no
text channel, has no storefront yet, or its agent already has a line or a request
in progress, so an administrator is never asked to approve something that cannot
go ahead.
Read your ChatGPT app setup and download links
The Listing page and your agent read your ChatGPT app and its files with the same call. A seller account administrator can ask for either part ofget({ "kind": "distribution" }) with include:
include: ["chatgpt"]returnsobject.chatgpt: your listing as the ChatGPT app will show it (name, subtitle, description, URLs and category), the icon mode, whether you have approved this exact listing, the readiness of the submission package, the status of the reviewer sandbox, andreviewerLoginUrl, a link to the web page that shows the reviewer login. It never returns the login itself. Your name, subtitle and description are text you wrote, so a reply a model reads wraps them as untrusted. Your first read creates the empty ChatGPT registration for the account.include: ["files"]returnsobject.files: adownloadUrlfor the OpenAI submission package and one for the printable listing card PDF. Each link is signed when you ask, works for two minutes and opens only that file, so read again for a fresh one. A file with no link says why: the package needs a live address, reviewer access, proof of domain ownership and your approval of the current listing, and the card needs a published listing.
chatgpt part, submissionReadiness says whether the package can be
downloaded: ready, the missing prerequisites in the order you meet them
(public_live, reviewer_access, domain_proof, package), and
blockedReason, one plain line naming the first one still outstanding.
bundleAvailable only says the package can be built, and the download itself
refuses with the same reason until it is ready. reviewerSandboxAvailable is
true only while Public distribution and the full entitlement bundle permit a
new reviewer request. reviewerSandboxGrantStatus is loaded when both the
eligibility and the grant lookup succeeded, and unavailable when either one
fails, so a caller retries instead of treating an outage as a missing
entitlement. An existing grant stays visible and revocable if a later change
makes a new request ineligible.
See the reviewer login
The reviewer login is the email and password that OpenAI’s reviewers use to sign in to your reviewer sandbox. It is a secret, so no tool returns it and the Listing page never shows it. Instead,object.chatgpt.reviewerLoginUrl is a link to a
page in the web app while the reviewer sandbox is active, and null otherwise.
The Listing page’s Open reviewer login button opens the same link.
Open the link in your own browser, signed in to the web app as an administrator of
the seller account itself, and choose Show the login. The page shows the email,
the password and when reviewer access ends, with a button to copy them. It reads
nothing until you choose to show it, and it never keeps the login: leaving the
page drops it.
Only a person can see it. An agent, an API key, a service token and an
administrator who reaches the account through a parent organization are all
refused, and so is a member who is not an administrator. The page also refuses
when there is no active reviewer access: request it first with the Listing page’s
Request access button. Every time the login is shown, the audit log records
who saw it. The login stops working when reviewer access ends or is revoked. The
login can only read your sandbox advertiser and cannot spend.
The default read, get({ "kind": "distribution" }), stays a short summary. The
printable card is built from your published listing when the link is opened, so a
listing the card cannot print, for example one with overlong text, shows its
error in the browser.
An organization also claims the domain it operates as, and its buyer accounts take
that claim as their operator domain. Open the organization’s Domains page with
open_domains_page; Your organization’s domain
has the steps.
Every domain is held at the organization, so a buyer or agents account in an
organization does not type a registered domain of its own. It picks one of the
organization’s verified domains, or none, in Settings → Account configuration,
and takes the organization’s proof with it. A domain an account already holds
stays until it is cleared or replaced. A seller account keeps its own brand domain
until the organization’s claims take it over in a later step.
A worked example
Raptive runs a network and sells CafeMedia’s sites.- Registered domain
raptive.com: the account was created by someone with a@raptive.comemail. - Brand domain
raptive.com: Raptive is who the buyer deals with. - Publisher domains
cafemedia.com,wholesomeyum.comand others: the sites whose inventory is for sale, each with its ownadagents.json.
Why the brand domain must be verified
The brand domain is the seller’s buyer-facing identity. Apostra reads the logo and company description from it, and it is what a buyer sees they are dealing with, so Apostra does not take it on assertion. An unverified brand domain blocks go-live. It shows as theoperator_domain check in the seller’s
setup checklist and stays a blocker until it resolves.
Verification depends on whether the brand domain matches the account’s registered
domain.
The brand domain matches the registered domain
The registered domain must be approved. An account administrator, or an administrator of the organization that manages the account, can get there three ways, for buyer, seller and organization accounts alike:- An email on the domain. An active member of the account has an email address at the registered domain. This needs nothing beyond signing in with that address.
- A DNS TXT record. In your account’s domain settings in the Apostra web app, choose Verify with a DNS record. Apostra shows a record name and value. Add that TXT record at your DNS provider, then choose Check now. Apostra reads the record straight from DNS, with no third party and no sign-in.
- A manual review. Choose Request manual review and say why the first two do not fit, for example because you are an agency working for a client. An Apostra administrator reviews it and, if it holds up, attests the domain.
The DNS record
The record sits at a dedicated host under your registered domain, so it does not add to the TXT records at the domain’s apex:
The token is random and belongs to one account and one registered domain. If you
change the account’s registered domain, Apostra issues a new token for the new
domain, and the old record does not verify it. Some DNS providers add the domain
for you, so enter the name as
_apostra-domain-verification if yours does.
DNS changes can take a few minutes to appear. Until Apostra sees the exact value,
the check stays pending, whether the record is missing, wrong, or the lookup did
not finish. A check never approves a domain on a failed lookup. One account can run
a check about once every five seconds; a check made sooner is refused with
RATE_LIMITED. If the domain is already approved, for example by an email on the
domain, there is nothing to verify.
Verify via AAO is no longer offered. Its routes answer
410 Gone and point to the
DNS record and manual review. An approval made earlier through it stays valid.The brand domain differs from the registered domain
This is the case that generates support requests. A seller registers asspanglishmovies.com and sells as latinxctv.com. A company owns both loopme.ai
and loopme.com. Both are legitimate, and neither verifies on assertion. Two
conditions must hold, in order:
- The registered account domain is approved, as above. Alias evidence is never a way around this. An unapproved account cannot verify any brand domain.
- Published evidence links the two domains. Apostra reads each domain’s
brand.jsonthrough the AgenticAdvertising.org (AAO) registry and looks for one domain naming the other. It counts when either domain’sbrand.jsonlists the other inauthorized_operators, names it as itsauthoritative_locationorhouse, or lists it as one of its website properties.
brand.json at both domains. That is yours to do, because Apostra reads what you
publish. If you have published it and the check is still pending, it is waiting on
Apostra, and you can file that with save_ask rather than waiting.
Change a brand domain
Saving a new brand domain withsave_seller runs verification against it from
scratch, so expect the operator_domain check to go back to pending until the new
domain resolves. Identity and brands
shows the preview and confirmation that a change needs.
- Saving the same brand domain again re-runs nothing. A brand domain that is already verified, including one an Apostra administrator attested, keeps its verification when you update other parts of the profile.
- A lookup that fails counts as “not verified”. If the registry or
brand.jsonlookup times out, the result is never “verified”. A pending check after a change may only mean the lookup has not completed. The check runs again each time the storefront is read, so read it again to retry. - Withdrawing approval withdraws the verification. If the account domain stops being approved, a brand domain that was verified through that approval goes back to pending. A verification an Apostra administrator attested directly stays.
When it stays pending
Work down this list. Each step has a different owner.- Is the account’s registered domain approved? Nothing else can succeed first. It needs a member email on the domain, a DNS TXT record Apostra has checked, or Apostra’s attestation. The checklist says which can work for you. If no active member of the organization has an email address on the registered domain, email cannot work, so use the DNS TXT record or Request manual review. This is common when a company’s people email from one domain and its brand lives on another.
- Does the brand domain match the registered domain? If it does and it is still pending, the blocker is step 1.
- If it differs, is the linking evidence published? Check that one domain’s
brand.jsonnames the other. Redirects do not count. - Evidence published and still pending? It is with Apostra for review. File a
request with
save_ask.
Related
- Identity documents explains
adagents.json,brand.jsonand the AAO registry. - Identity and brands covers setting and proving a domain in chat.
- Publisher coverage covers publisher domains and properties.