What poppy.json is, and what yours says Free & Pro

poppy.json is the discovery document of the Personal Agent Protocol. A business publishes it at https://its-domain/.well-known/poppy.json, and a personal agent fetches it before doing anything else. It tells the agent who the business is, how to sign a customer in, which APIs exist and where an agent’s browser may join a visit. Agent Adapt publishes one for your store the moment it is active. There is nothing to write by hand.

Where it lives, and why

The address is fixed by the protocol: the .well-known folder at the root of the domain, over HTTPS. An agent given "your-store.com" by a customer has nowhere else to look. That is why Agent Adapt’s Site Health checks insist that WordPress answers at the root of your domain and over HTTPS. If your WordPress lives at your-store.com/shop/, the agent’s request never reaches it unless your server forwards that one path. See Site Health checks.

The file is public and cacheable. Agent Adapt tells agents and proxies they may cache it for five minutes.

What yours contains

With the free plugin, your store’s document looks like this, with your own name and domain:

{
  "protocol_version": "0.1",
  "organization": { "name": "Your Store", "domain": "your-store.com" },
  "auth": {
    "issuer": "https://your-store.com/agent-adapt",
    "direct": { "scopes": ["poppy:read", "poppy:write"] },
    "device": { "scopes": ["poppy:read", "poppy:write"] }
  },
  "apis": [
    {
      "type": "openapi",
      "url": "https://your-store.com/wp-json/agent-adapt/v1/openapi.json",
      "description": "Product search and details, store policies, and the shopping cart."
    }
  ],
  "web": { "browser_session_endpoint": "https://your-store.com/agent-adapt/browser-session" },
  "extensions": { "getagentadapt.com/checkout-handoff": { "version": 1 } }
}

Field by field:

Field	What it tells an agent
protocol_version	Which draft the store speaks. An agent that only knows a different major version must not use the document.
organization	Your store’s name, from Settings → General, and its domain. The domain must match the one the agent fetched from, ignoring a leading www..
auth.issuer	The address of your store’s OAuth server. Everything to do with identity, tokens and sign-in hangs off it.
auth.direct, auth.device	The two ways a customer can connect an agent, by link or by code, and the scopes each can grant. A sign-in type is listed only if the store serves it.
apis	Your agent API, described by an OpenAPI document generated from the same code that answers the calls.
web.browser_session_endpoint	Where an agent’s own browser presents its credentials to join a visit on your website.
extensions	Named additions. The checkout link is one, named with our domain as the protocol requires for anything it doesn’t define itself.

With Pro, three things are added: an operations extension (version 1), an mcp entry under apis pointing at https://your-store.com/agent-adapt/mcp, and auth.custom_scopes describing the addresses scope the consent page can offer.

The second document

poppy.json points at the issuer; the issuer publishes its own metadata, in the standard OAuth form (RFC 8414), at https://your-store.com/.well-known/oauth-authorization-server/agent-adapt. That document lists the token endpoint, the revocation endpoint, the authorization and device endpoints, the signing algorithms accepted (ES256 and RS256) and poppy_domains, the domains whose poppy.json names this issuer. Agent Adapt also serves the same document at https://your-store.com/agent-adapt/.well-known/oauth-authorization-server, because some clients look there.

Check yours

Open https://your-store.com/.well-known/poppy.json in a private browser window. You should see JSON naming your store, not an HTML page, a redirect to your home page or a challenge from a security service. Then open the OAuth metadata address above and check it names the same issuer.

Tools → Site Health does both checks for you, from your store’s public address, and says what is in the way when one fails. For a fuller walk-through with the exact requests an agent makes, see Check that your store answers agents.

When it is wrong

• An HTML page instead of JSON. A page cache, CDN or security plugin answered before WordPress did. Exclude /.well-known/ and /agent-adapt/ from caching and bot rules. See Caches, CDNs and security plugins.
• 404. Pretty permalinks are off, or WordPress is not at the root of the domain.
• A different domain in organization.domain. Your store’s address under Settings → General does not match the domain customers use. If a proxy hides your real address from WordPress, the agentadapt_public_origin filter sets it.
• Stale contents after a change. The file may be cached for up to five minutes. Wait, or purge your cache.

Common questions

Do I have to edit poppy.json?

No. Agent Adapt generates it from your store’s settings and from what the plugin actually serves. If a feature is switched off or not installed, it is left out, so the file never promises something the store cannot do.

Can I add my own fields?

Developers can, with the agentadapt_poppy_document filter. Anything added must actually work: an agent that follows the protocol will try it.

Does it expose anything private?

No. It contains your store’s public name and domain, public addresses and the names of public features. The same information is visible to anyone who shops with you.

Why is it called poppy.json?

The protocol’s authors chose the name. It is fixed by the specification and cannot be changed by a store.