Check that your store answers agents: five requests you can run yourself Free & Pro

Tools → Site Health does most of this for you. But when a host, a CDN or a security plugin is involved, it helps to see the exact answers an agent gets. These five requests need only a terminal with curl (macOS, Linux and Windows all have it). Replace your-store.com with your domain. None of them changes anything.

1. The discovery document

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

Healthy: JSON starting {"protocol_version":"0.1","organization":{"name":"Your Store","domain":"your-store.com" and going on to list auth, apis and web.

Wrong answers:

• HTML, or a page from your CDN or security service: something answered before WordPress. Exclude /.well-known/ 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. See Site Health checks.
• A redirect to http://: your site address is set to HTTP. Agents follow redirects only to HTTPS.
• A different domain from the one you asked: your Site Address under Settings → General doesn’t match the domain customers use.

2. The OAuth server metadata

curl -s https://your-store.com/.well-known/oauth-authorization-server/agent-adapt

Healthy: JSON whose issuer is https://your-store.com/agent-adapt, with token_endpoint, revocation_endpoint, authorization_endpoint, device_authorization_endpoint, poppy_domains containing your domain, and dpop_signing_alg_values_supported listing ES256 and RS256.

The same document is served at https://your-store.com/agent-adapt/.well-known/oauth-authorization-server. Either address should work.

3. The API description

curl -s https://your-store.com/wp-json/agent-adapt/v1/openapi.json | head -c 600

Healthy: JSON beginning with "openapi" and a version, then "info" naming your store and "paths" including /catalog/search, /cart, /cart/handoff and /orders. This document is generated from the same code that answers the calls, so what it lists is what the store does.

Wrong: a 404 here, when 1 and 2 worked, usually means the REST API is disabled or blocked by a plugin. Agents need /wp-json/agent-adapt/ reachable.

4. A call without a token

curl -si "https://your-store.com/wp-json/agent-adapt/v1/catalog/search?q=test"

Healthy: HTTP/2 401 with a header WWW-Authenticate: DPoP error="invalid_token", algs="ES256 RS256" and a JSON body {"error":"invalid_token", ...}. This is the right answer: you sent no token, and the store told you how to authenticate. An agent with a token gets your products.

Wrong answers:

• 200 with products: the store is not enforcing authentication. This should not happen; email [email protected].
• 401 or 403 with an HTML body, or without the WWW-Authenticate: DPoP header: a server rule or security plugin answered instead of the plugin.
• 401 from the plugin even when a real agent sends a valid token: the Authorization header is being stripped before PHP sees it. Site Health has the one-line .htaccess fix.

5. The token endpoint

curl -si -X POST https://your-store.com/agent-adapt/oauth/token

Healthy: HTTP/2 400 with a JSON body {"error":"invalid_request", ...} and Cache-Control: no-store. You sent an empty request and the store refused it in the standard OAuth form. A GET to the same address gets 405 and Allow: POST.

Wrong: HTML, a 404, or a redirect. The /agent-adapt/ path is being intercepted or isn’t reaching WordPress.

Reading the headers

Add -i to any of the first three requests to see headers. Things worth noticing:

• Cache-Control on the discovery documents allows caching for 300 seconds. On anything carrying a token it says no-store.
• Content-Type: application/json on all of them. A text/html content type means a page got in the way.
• Retry-After appears only on a 429, when you have gone over a rate limit. Running these five by hand will not get you there.

What this does not test

These requests prove the store is reachable and answering in the right shape. They do not prove a full visit works end to end, because that needs an agent with keys to sign requests. Agent Adapt’s own test suite does exactly that on every release, with a test agent over real TLS; see How we test. If the five requests above pass and Site Health is green, a real agent will get through.

Common questions

Do I need to run these if Site Health is green?

No. Site Health fetches the discovery documents from your public address and checks the Authorization header. Run these when Site Health is red and you want to see why, or when a customer’s assistant reports it cannot reach you.

Can I run them from my browser instead?

Requests 1 to 3 work in a browser address bar; you will see the JSON. Requests 4 and 5 are easier with curl because you need the status line and headers.

The output is one long line. How do I read it?

Pipe it through a formatter: curl -s https://your-store.com/.well-known/poppy.json | python3 -m json.tool on a machine with Python, or paste it into any JSON viewer.

Should any of these be blocked from the public?

No. All five are public endpoints by design. The discovery documents are meant to be read by anyone, and the API and token endpoint refuse anything without valid credentials.