By · Founder, Stacktree · Last updated
Personal Agent Protocol · discovery

poppy.json, field by field.

One JSON file on your domain is how a personal AI agent learns that your company exists, what it may do there and how its person signs in. This is every field in Version 1.0, read against the file Stacktree serves in production, with the checks an agent runs before it trusts yours.

The Poppy Simulator tests any domain. Free, no sign-up.

What is poppy.json?

poppy.json is the discovery file of the Personal Agent Protocol (Poppy). A company publishes it at /.well-known/poppy.json on its own domain, over HTTPS. It tells a person's AI agent which protocol version the company speaks, who the company is, how sign-in works, and which APIs, website access or support agent it offers. Version 1.0 requires three things in it: a version, the organization, and at least one channel.

A real file

This is what stacktr.ee/.well-known/poppy.json served on 14 November 2026, the day Version 1.0 was published. The four descriptions are shortened here. Everything else is as served.

{
  "protocol_version": "1.0",
  "supported_versions": {
    "0.4": "https://stacktr.ee/.well-known/poppy/0.4.json",
    "0.3": "https://stacktr.ee/.well-known/poppy/0.3.json"
  },
  "organization": {
    "name": "Stacktree",
    "domain": "stacktr.ee",
    "logo_uri": "https://stacktr.ee/favicon.svg"
  },
  "auth": {
    "issuer": "https://api.stacktr.ee",
    "scopes": {
      "sites:read": "See the pages in their Stacktree account ... Not needed to publish.",
      "sites:write": "Publish pages into their Stacktree account ... Not needed for a one-off page."
    },
    "scope_hints": {
      "sites:read": { "changes": "none", "personal_data": true },
      "sites:write": { "changes": "irreversible", "personal_data": true }
    }
  },
  "apis": [
    { "type": "mcp", "url": "https://api.stacktr.ee/mcp", "description": "Publish a page to a private link ..." },
    { "type": "openapi", "url": "https://api.stacktr.ee/openapi.json", "description": "The same over REST ..." }
  ],
  "tasks": {
    "endpoint": "https://api.stacktr.ee/poppy/tasks"
  }
}

Read top to bottom, it says: we follow 1.0 and still serve two drafts. We are Stacktree at stacktr.ee. A person can sign in through one OAuth server, and there are two things they can approve. You can reach us through an MCP server or a REST API. And there is an address to ask what we chose not to offer.

The smallest valid file

A company that only wants agents to use one API signed out needs this much:

{
  "protocol_version": "1.0",
  "organization": { "name": "Example Company", "domain": "example.com" },
  "apis": [
    { "type": "openapi", "url": "https://api.example.com/openapi.json", "description": "Track an order" }
  ]
}

No OAuth, no scopes, no agent of your own. That is a complete Version 1.0 document.

Every field

From section 3.1 of the 1.0 spec. Required fields first.

  • protocol_version (required). The version this file follows, as major.minor. An agent uses the file only if it implements a compatible version. From 1.0, a newer minor version does not break older agents, which ignore fields they do not know.
  • organization (required). A display name, the domain, and an optional logo_uri. The domain must be the host that serves the file, after any redirects. The name is only a label: the domain is the identity.
  • One of apis, web or agent (required). The three channels. A file with none of them offers an agent nothing to do.
  • apis. A list. Each entry has a type such as openapi or mcp, a url, and a short description that helps the agent pick the right one. Write the description for a model choosing between entries, not for a person browsing docs.
  • web. Your website. An optional browser_session_endpoint is where the agent's browser joins its Session, so it can browse signed in. web.disabled: true asks agents not to use a browser on your site at all. web.unscoped: true warns that the website does not apply your other scopes.
  • agent. Your own Company Agent, if you have one. protocols lists each conversation endpoint with a type, an endpoint and, required since 1.0, a description of what the agent there can help with.
  • supported_versions. The other versions you serve, each mapped to the address of that version's own document. This is how a company moves to a new version without cutting off agents on the old one.
  • auth. Sign-in details. Leave it out entirely if agents only use you signed out.
  • auth.issuer. Your OAuth issuer. Required only when your domain's protected resource metadata lists more than one authorization server. With one server you may leave it out.
  • auth.disabled. true if you have an issuer but offer personal agents no sign-in.
  • auth.scopes. A description for each scope, keyed by scope name. You choose the names. Say what the scope allows, when an agent should ask for it, and whether the task can be done without it. Agents show this to the person, and use it to avoid asking for sign-in they do not need.
  • auth.scope_hints. Two hints per scope: changes (none, reversible or irreversible) and personal_data. An agent can use them to decide how carefully to confirm with its person first.
  • tasks. One endpoint. For a given Session it returns the tasks you chose not to offer, any skills you publish, and where to send feedback.
  • extensions. The extensions you support, by name and version, such as the UCP extension for checkout.

What an agent checks before trusting it

A file that parses is not yet a file an agent will use. Section 3 has the agent verify:

  1. The address. The final URL, after redirects, has the path /.well-known/poppy.json exactly, with no query, and every hop was HTTPS.
  2. The domain. organization.domain equals the host that served the file. A copy of your file on someone else's domain fails here.
  3. The issuer, if there is one. The agent finds your OAuth server from /.well-known/oauth-protected-resource on your domain, then confirms that server's own metadata lists https://yourdomain under protected_resources. Both sides have to point at each other.
  4. The version. It reads protocol_version and supported_versions and takes the newest one it implements.
  5. Every URL is HTTPS, and none points at a private or loopback address.

Mistakes that break it

The first three are our own. The rest follow from the checks above.

  • Metadata that names the wrong resource. Until 6 November, the protected resource document at the root of our API host gave our MCP server's address as its resource, because that is where the MCP server sent clients. Under RFC 9728 the document at a host's root has to name that host. An agent that asks about one resource and is told about another should refuse the answer, and nothing in your own logs says why it left.
  • Stopping at a version you do not know. This one is for agent builders. Our simulator read "protocol_version": "1.0", did not recognize it, and gave up before reading supported_versions, where a version it did speak was listed. Read the links first.
  • Scope descriptions that only say what a scope is. "Read access" tells an agent nothing about whether to ask for it. Ours now say when the scope is needed and when it is not, because our main action, publishing a page, needs no sign-in at all.
  • An issuer that does not point back. Your domain names your OAuth server, but the server's metadata does not list your domain under protected_resources. A careful agent stops there.
  • Serving the file from the API host only. The file speaks for the host that serves it. If your product lives at example.com and the file is only on api.example.com, agents looking for example.com find nothing.
  • Vague API descriptions. With two APIs listed, the description is all an agent has to choose between them. Name the tasks.
  • Leaving an old document unreachable. If you list a version under supported_versions, its document has to answer. Agents on that version read it directly.

Fields from the drafts that are gone

Many examples online were written against the October drafts. If you copied one, check for these:

  • poppy_domains. Gone. The domain and its sign-in server now prove their link through OAuth metadata, as above.
  • Sign-in types in poppy.json. Since 0.3, whether you offer Direct or Device Sign-In is read from your OAuth server's metadata.
  • poppy:read and poppy:write. Since 0.3, scopes are your own names, described under auth.scopes.
  • feedback.endpoint. Moved in 0.4. An agent reads the feedback address from the document at tasks.endpoint.

Test yours

Start with one request:

curl -sL https://yourdomain/.well-known/poppy.json

Then let an agent read it. Open the Poppy Simulator, choose Test a company and enter your domain. It runs the checks above, starts a signed-out Session, tries the first API you list, and sends the requests a company must refuse. Each result names the spec section it tested. The build log explains what it does and what it found in ours.

For the rest of the protocol, from Sessions to sign-in, see the Personal Agent Protocol, explained.

FAQ

Frequent questions

What is poppy.json? +
poppy.json is the discovery file of the Personal Agent Protocol. A company publishes it at /.well-known/poppy.json on its own domain, over HTTPS. It tells a person's AI agent which protocol version the company speaks, who the company is, how sign-in works, and which APIs, website access or support agent it offers.
Where does poppy.json go? +
At https://yourdomain/.well-known/poppy.json, exactly. The address may redirect, for example from www to the bare domain, but the final address must end in that same path with no query string. An agent ignores a file served from any other path, so an upload folder cannot speak for your domain.
Which fields are required in poppy.json? +
In Version 1.0, protocol_version and organization (with a name and a domain) are required, plus at least one of three channels: apis, web or agent. Everything else is optional, including auth. A company that serves agents signed out needs no sign-in details at all.
How do I check that my poppy.json is valid? +
Fetch it with curl and confirm it returns JSON over HTTPS with your own domain in organization.domain. Then point a real agent at it: the Poppy Simulator reads the file, runs the checks the spec asks of an agent, starts a signed-out Session and shows each request with the rule it tested.
Does poppy.json need an OAuth server? +
No. The auth section is optional. Without it, agents use the company signed out. When a company does offer sign-in, the agent finds the OAuth server from the domain's protected resource metadata, and auth.issuer is only required when that metadata lists more than one server.
What happened to poppy_domains and feedback.endpoint? +
Both were fields in the October drafts and are gone. The link between a domain and its sign-in server is now proven with standard OAuth metadata instead of poppy_domains. The feedback address moved in 0.4: an agent reads it from the document at tasks.endpoint, per Session.
Can one poppy.json serve several protocol versions? +
Yes. protocol_version names the version the file follows, and supported_versions maps each other version you serve to the address of that version's own document. An agent picks the newest version it implements. From 1.0, any 1.x agent can use a 1.0 document.
Keep reading

Related guides

References

Sources and further reading

The file is the easy part.

Stacktree is a company agents can use today: an agent publishes a private page for its person with no account, over the Personal Agent Protocol, MCP or one HTTP request. Free to start, no card.

Sign up free →