Serving poppy.json with a Cloudflare Worker, step by step Free & Pro

On 16 October 2026 the Personal Agent Protocol’s draft changed what a redirect of /.well-known/poppy.json means. The document now speaks for the host that serves it after any redirects, and its organization.domain must name that host. A redirect from your domain to a provider’s host therefore no longer makes a valid document for your domain, and the Cloudflare Redirect Rule this page used to describe no longer does the job. If you set one up, delete it and replace it with the Worker below, which fetches the provider’s document and serves it on your own domain. A redirect that stays on your own host, the apex to www for example, is still allowed, as long as the document names the host that finally answers.

If your domain’s DNS is on Cloudflare with the proxy switched on, Cloudflare answers every request before your platform does. That makes it the one place /.well-known/poppy.json can be served on platforms that otherwise refuse the path: Shopify, Squarespace, Wix, Webflow and BigCommerce among them. This page is the procedure, written for someone who has never opened the Workers section. The free plan is enough. Cloudflare renames menus from time to time; if yours differ, look for "Workers & Pages" in the account menu and "Workers Routes" under the domain.

You need the HTTPS address of the hosted document. That is given to you by whoever runs your hosted Company, the provider that will answer agents for your domain; with Agent Adapt’s hosted Company it has the form https://agents.getagentadapt.com/c/<site>/poppy.json, where <site> is the identifier the service gives your site. If your store runs WooCommerce with Agent Adapt, you do not need this page: the plugin serves the file itself, and the only Cloudflare work is excluding three paths from caching and bot rules, described in Caches, CDNs and security plugins.

Before you start

• Your domain’s nameservers are Cloudflare’s, and the DNS record for your site (www, or the apex, or both) shows the orange proxy cloud. A grey cloud means Cloudflare only does DNS and Workers do not run.
• You know the hosted document’s address, and it starts https://.
• You know which hostname customers end up on. If the apex redirects to www, agents follow that redirect, which the protocol allows because it stays on HTTPS, and the document they then receive must say www.your-domain.com in organization.domain: since 16 October 2026 www. is no longer ignored when domains are compared. Put the route on the hostname that finally answers, and tell your provider which hostname that is.

The Worker

1. In the Cloudflare dashboard, open Workers & Pages and create a Worker. Give it a name you will recognise later, such as agent-adapt-discovery (the name the Agent Adapt dashboard uses too).
2. Replace its code with the following, with your hosted document’s address in place of the example:

export default {
  async fetch() {
    return fetch("https://agents.getagentadapt.com/c/<site>/poppy.json");
  },
};

3. Deploy it.
4. Open your domain, then Workers Routes, and add a route with the pattern your-domain.com/.well-known/poppy.json pointing at the Worker. If customers reach you on both www.your-domain.com and the apex, add a second route for the other hostname.

The route matches one exact path. It must not be your-domain.com/.well-known/*: other well-known paths on your domain (security.txt, Apple Pay verification, Shopify’s own UCP document) must keep working.

The Worker’s fetch handler ignores the incoming request on purpose. It sends a fresh request of its own to the provider and returns the answer, so nothing an agent sends to your domain is passed on.

Check it

From any computer:

curl -sI https://your-domain.com/.well-known/poppy.json

A healthy answer starts with HTTP/2 200, has content-type: application/json, and has no location: header: the document is served on your domain, not redirected away from it. Then read it:

curl -s https://your-domain.com/.well-known/poppy.json

You should see JSON whose organization.domain is exactly the hostname you fetched from, not the provider’s, and whose auth.issuer is an HTTPS address. If your provider has a verification button, press it now; it fetches the same URL from outside and tells you what an agent will see.

When it does not work

Symptom	Likely cause
The platform’s own 404 page, no JSON	The record is grey-clouded, or the route is on a different hostname from the one you tested
A redirect to the provider’s address	An old Redirect Rule for this path is still deployed, including the one this page used to describe. Delete it
A redirect to your home page	A platform or Cloudflare rule with broader matching runs first. Narrow it, or move it so the Worker answers
A Cloudflare challenge page	A bot-fighting or WAF rule challenges the path. Add a skip rule for /.well-known/poppy.json, or for the user agents your provider names
JSON with the wrong domain	The hosted address belongs to another site’s configuration at the provider, or the provider was told the apex when customers use www (or the other way round)
An error page from Cloudflare	The address in the Worker is wrong or the provider is not answering. Open the hosted address directly in a browser
It worked yesterday and not today	A cache rule is holding an old answer. Purge the single URL

What the Worker must not do

• It must not pass the incoming request through. The code above sends its own request with none of the agent’s headers; do not hand request to fetch.
• It must not return a redirect to the provider’s host. That was the earlier approach, and since 16 October 2026 the protocol does not accept it.
• It must not match more than the one path.
• It must not be the only thing you set up. The document names an issuer and APIs; those have to answer too. The Worker only gets agents to the door.

Shopify specifically

Shopify answers every /.well-known/ address on a Shopify-hosted storefront itself, and neither themes nor URL redirects nor apps can serve or proxy a file there. Putting Cloudflare in front of a Shopify store, with the proxy on, is supported by Shopify (both sides use Cloudflare, so it is sometimes called an orange-to-orange setup), and then this same Worker works because Cloudflare answers before Shopify does. That is the only route to discovery on a Shopify-hosted storefront today, short of a headless storefront or Shopify adopting the protocol. See Shopify.

Common questions

Will a Worker slow my site down?

No. The route matches one exact path; every other request to your site never touches the Worker. The free plan’s allowance is more than discovery traffic needs.

Can I use a Redirect Rule or a Page Rule instead?

Not any more. Both answer the path with a redirect to the provider’s host, and since 16 October 2026 the protocol says the document speaks for the host that serves it after any redirects, so the agent would end up with a document for the provider’s domain, not yours. Only something that serves the document on your domain counts, and on Cloudflare that is a Worker.

Does the Worker cost anything?

No. Workers are included in Cloudflare’s free plan, and this one handles only requests for one path.

Does the Worker expose anything?

No. The document it serves is public by design, and it contains only your business name, your domain and public addresses. The Worker sends nothing from the agent’s request to the provider.