Why well-known paths exist#
Because an agent that knows your domain and nothing else needs somewhere predictable to look. RFC 8615 reserved /.well-known/ for exactly this: a namespace where a client can ask a question of a host without being told the answer in advance.
The agent ecosystem has filled it in quickly and somewhat inconsistently.
The six paths worth knowing#
| Path | Who reads it | What it answers |
|---|---|---|
/.well-known/agent-card.json | Other agents, over A2A | What is this agent, what can it do, how do I call it |
/.well-known/x402 | Buyers and indexers | What is priced here and on what terms |
/.well-known/oauth-protected-resource | OAuth clients | Where is the authorisation server for this resource |
/.well-known/oauth-authorization-server | OAuth clients | The authorisation server's own metadata |
/.well-known/openapi.json | Anything calling your API | What endpoints exist and what they take |
/llms.txt (root, not well-known) | Models reading your site | What this site is, in prose |
Note the agent card's filename. It changed during A2A's development, and documentation written against the earlier version points at a path that no longer resolves. A2A reached v1.0.0 in March 2026; read the current specification rather than a tutorial.
The trap that matters#
The HTTP status decides whether a document exists, not the content type.
Plenty of hosts answer every unserved path with a 404 whose body is JSON and whose content-type is application/json. A crawler that decides "this looks like JSON, so the document is present" records a missing file as a present one, parses an error body as a declaration, and stores nothing useful while reporting success.
Warning
This is a measurement bug with a silent failure mode. A crawl built this way reports high coverage and holds garbage. If you are building the crawling side, branch on the status code first and only then look at the body. If you are publishing, make sure your 404s are 404s.
The second half of the trap: an identity document is not a service declaration. An agent card carries no price and no payee, so storing it as a priced listing creates a catalogue entry for something that cannot be bought. Keep the two apart.
What should you publish?#
Depends what you are, and most domains should publish fewer of these than they could.
You run a priced API. Publish your x402 declaration and an OpenAPI document. Those two answer the only questions a buyer has: what can I call and what does it cost. Making your API discoverable covers the rest of the checklist.
You run an agent other agents should delegate to. Publish an agent card. It is the thing A2A reads before deciding whether to call you.
You run both. Publish both and keep them separate. The card describes you; the x402 declaration prices what you sell.
You run a site people read. llms.txt, and nothing else from this list. What it is actually good for is narrower than most descriptions suggest.
What a crawler should do with what it finds#
Three rules that are not obvious until something has gone wrong.
Three outcomes, not two. A host either served the document, said it has none, or failed. A certificate error, a timeout or a rate limit is not the same as "this host publishes nothing", and collapsing them produces a catalogue that quietly loses hosts it could not reach.
Follow a pointer once, and only to the same host. Documents sometimes point at another catalogue. Following an arbitrary URL out of an untrusted document means making a request on a stranger's behalf, which is a different and worse thing than fetching a well-known path.
Back off rather than drop. A host that refuses today may serve tomorrow. A backoff is not a removal, and treating it as one makes coverage look worse than it is and then stay worse.
Does any of this find you?#
No, and it is worth being blunt about it because the ecosystem's documentation blurs this constantly.
Every path on this page can only be read by something that already has your domain. They answer "what does this host offer", never "which host offers this". Discovery by capability needs a registry, a catalogue or an index, and the well-known files are what those sources read once they know where to look.
So publish them, and do not expect them to generate demand. They convert a known domain into an understood one.
Frequently asked questions#
Do I need all of them?#
No. Publishing a file you do not maintain is worse than not publishing it, because stale terms in a discoverable location get believed and paid against.
What happens if my card and my live endpoint disagree?#
The live response wins and the reader loses. A buyer that trusted a stale declaration pays wrong terms or fails. Treat these files as part of your deploy, not as documentation.
Should these be authenticated?#
No. They are the documents that let something decide whether to engage with you at all, so gating them defeats their purpose. Do not put anything in them you would not publish.
Is there a registry of well-known paths?#
IANA maintains the registry for formally registered ones. Several of the agent-ecosystem paths are conventions that have not gone through that process, which is worth knowing before treating one as stable.
How often are they crawled?#
Varies by crawler, from hours to never. Nothing guarantees anybody fetches yours, which is the main reason catalogue registration is a better first investment.
Where to check this yourself#
/services is assembled partly from host probing of exactly these paths, so you can see whether your domain's documents were found and what was read from them. If your endpoint is missing or the recorded terms are wrong, that is what a buyer sees too.