What is poppy.json? Personal Agent Protocol discovery explained

The Personal Agent Protocol (also called Poppy) is an open protocol, led by Meta and Sierra, for how a person's AI agent works with a company on their behalf. Draft 0.1 was published on 9 October 2026. Everything a personal agent does with a company starts by reading this one file, so it is the first thing to get right. This guide follows section 3 of the specification.

Where it lives

At https://{your-domain}/.well-known/poppy.json, over HTTPS. The URL may redirect, for example to a provider that hosts it, but every redirect must be to an HTTPS URL, and the document still speaks for the domain the agent asked for.

An example

{
  "protocol_version": "0.1",
  "organization": { "name": "Example Company", "domain": "example.com" },
  "auth": {
    "issuer": "https://auth.example.com",
    "direct": { "scopes": ["poppy:read", "poppy:write", "addresses"] },
    "device": { "scopes": ["poppy:read", "poppy:write"] },
    "custom_scopes": { "addresses": "Manage saved shipping addresses" }
  },
  "agent": {
    "protocols": [{ "type": "poppy", "endpoint": "https://api.example.com/poppy/conversations" }]
  },
  "web": { "browser_session_endpoint": "https://example.com/poppy/browser-session" },
  "apis": [
    { "type": "openapi", "url": "https://api.example.com/openapi.json", "description": "Orders, returns, and exchanges" },
    { "type": "mcp", "url": "https://mcp.example.com/mcp", "description": "Product search and sizing" }
  ]
}

Shortened from the specification's own example.

The fields

Field	Required	What it says
`protocol_version`	Yes	The version the document follows, as `major.minor`. This draft is `0.1`. Agents must not use a document whose major version they don't support.
`organization`	Yes	Display `name` and `domain`. The domain must match the host the agent requested, ignoring a leading `www.`.
`auth`	If `agent`, `apis` or a browser session endpoint is listed	The OAuth `issuer`, and the sign-in types the company supports: `direct`, `device` and `mediated`, each with the `scopes` it can grant. `custom_scopes` describes scopes beyond `poppy:read` and `poppy:write`.
`agent`	One of agent, apis or web	The company's own agent: its conversation `protocols`, each with a `type` and HTTPS `endpoint`.
`apis`	One of agent, apis or web	A list of APIs, each with a `type` (`openapi` or `mcp`), a `url` and a short `description`.
`web`	One of agent, apis or web	The website. The optional `browser_session_endpoint` lets the agent's browser join its session, so pages apply the user's sign-in.
`extensions`	No	Extensions the company supports, keyed by name, each with a `version`. `operations` is defined with the protocol; anyone else's start with a domain, such as `example.com/gift-wrap`.

The check agents make on your sign-in server

Before using poppy.json, a personal agent fetches the OAuth server metadata of auth.issuer (RFC 8414, at /.well-known/oauth-authorization-server). Its issuer must match auth.issuer exactly, and a new field, poppy_domains, must list your domain. Otherwise any site could claim your issuer and receive its tokens. The metadata must also publish a token_endpoint and revocation_endpoint, plus authorization_endpoint for direct sign-in and device_authorization_endpoint for device sign-in.

Mistakes to avoid

organization.domain set to a parent brand or a different country domain. Several domains can share one issuer; each still names itself, and each must be in poppy_domains.
Scopes that start with poppy: other than poppy:read and poppy:write. That prefix is reserved for the protocol.
An MCP server whose resource metadata doesn't name your issuer in authorization_servers, so MCP clients can't sign in.
A storefront that answers every path with its HTML page. Agents need JSON at the well-known URL, not a soft 404.

Check yours

Run PAP Checker on your domain. It reads the same public documents a personal agent reads, cites the section each rule comes from, and never signs in or calls your APIs.