Poppy.json Validator & Personal Agent Protocol Guide
Shopify just enabled /.well-known/poppy.json across merchant stores for Personal Agent Protocol (Poppy 1.0). Validate your manifest, spot Shopify 0.4 vs 1.0 compatibility gaps, generate a clean config, and verify AI agent accessibility.
Following the Poppy 1.0 release (Nov 13, 2026), Shopify enabled /.well-known/poppy.json across standard Online Stores in 175+ countries, while personal agents like Meta Muse check this file first.
Poppy (/.well-known/poppy.json) handles agent discovery, session tracking, and OAuth consent. UCP (/.well-known/ucp) handles product search, cart, and checkout actions.
Custom or headless Shopify storefronts often still return 404 for /.well-known/poppy.json and must serve the manifest explicitly over HTTPS with at least one channel.
Validate your /.well-known/poppy.json manifest
curl -sS -i https://www.northwindgoods.com/.well-known/poppy.json
Valid JSON document syntax.
Poppy protocol_version "1.0" meets the v1.0 backward-compatible baseline.
Organization name "Northwind Goods" is present.
Organization domain "www.northwindgoods.com" is a valid hostname.
Interaction channels declared: agent, web.
1 agent protocol endpoint(s) validated with HTTPS and descriptions.
Website browsing channel configured cleanly.
OAuth scope_hints specify valid reversibility and personal_data flags.
Declared extension(s): ucp.
Key fields in /.well-known/poppy.json
Poppy Section 3.1 requires every URL in the manifest to use https:// and at least one interaction channel (agent, apis, or web).
| Field | Requirement | Purpose & compliance details |
|---|---|---|
| protocol_version | Required | String in major.minor format ("1.0"). Note: Shopify's initial rollout serves "0.4". |
| organization | Required | Object with display name, bare domain matching the serving host, and optional HTTPS logo_uri. |
| agent.protocols[] | Channel | Lists conversation endpoints (type such as ucp or poppy, HTTPS endpoint, and description required in 1.0). |
| apis[] | Channel | Programmatic contracts (type: openapi or mcp, HTTPS url, and short description). |
| web | Channel | Empty {} permits signed-out visitor browsing; set disabled: true to steer agents to APIs instead. |
| auth.scopes & scope_hints | Optional | Supplements OAuth metadata with human-readable scopes, changes ("none" | "reversible" | "irreversible"), and personal_data boolean. |
| extensions | Optional | Standard extensions include ucp, operations, disclosures, browser-control, and mediated-sign-in. Custom keys need a domain prefix. |
AI agent accessibility checklist for Shopify & SaaS sites
Publishing a valid manifest is only half the setup. Make sure personal agents and answer engines can actually reach your endpoints and verify your facts.
Serve /.well-known/poppy.json over HTTPS with 200 JSON
Headless Shopify, Hydrogen, Next.js, and Cloudflare Worker sites do not inherit Shopify's hosted Online Store manifest automatically. Return Content-Type: application/json without login walls.
Do not block verified agent fetches at the WAF or robots layer
Allow /.well-known/* discovery endpoints in CDN firewall rules and verify OAuth protected-resource metadata (/.well-known/oauth-protected-resource) matches organization.domain.
Pair agent endpoints with machine-readable pages and FAQPage schema
Discovery protocols let agents interact with your store, but answer engines still cite public product specs, llms.txt, comparison tables, and FAQPage JSON-LD when deciding which brand to recommend.
Plan for the Shopify 0.4 -> Poppy 1.0 schema transition
Early Shopify manifests use protocol_version "0.4" and omit description inside agent.protocols. Custom manifests you publish directly should target "1.0" with explicit descriptions.
Frequently asked questions
What is /.well-known/poppy.json?
It is the discovery manifest for the Personal Agent Protocol (Poppy), an open Apache 2.0 standard led by Sierra and Meta. It tells personal AI agents who owns the domain, how to establish a verified session or OAuth sign-in, and which agent, API (MCP/OpenAPI), UCP commerce, or web channels are supported.
Did Shopify enable poppy.json automatically for merchants?
Yes, for standard Shopify Online Store domains following the Poppy 1.0 rollout in November 2026. However, headless or custom-hosted storefronts often still return 404 and need to host /.well-known/poppy.json themselves.
Why does this validator warn on Shopify's 0.4 manifest?
Live Shopify stores initially serve protocol_version "0.4" and omit the description field inside agent.protocols. Under the finalized Poppy 1.0 specification, description is required on agent.protocols items and 0.4 is pre-1.0.
How does poppy.json relate to llms.txt and AI visibility (GEO)?
They solve complementary layers. llms.txt and structured pages (FAQPage, direct answers, comparisons) help answer engines understand and cite your brand in search answers. poppy.json and UCP tell personal AI agents how to interact, authenticate, and transact with your business.
Does validating poppy.json here send my data to an external server?
No. Both the validator and generator run 100% locally in your browser with zero external API calls.
Protocol files make you agent-ready. CiteRank tests whether AI recommends you.
Run a focused check across ChatGPT, Gemini, Perplexity, Claude, Grok, and DeepSeek to see competitor mentions, cited sources, and the first page gap to fix.