The `/.well-known/` path prefix is the IETF's standard place to put machine-readable metadata about a host. Registered under RFC 8615, it is how a client finds an OpenID Connect discovery document, a `security.txt`, a change password endpoint, or an agent catalogue — without a human reading documentation first.
/.well-known
/.well-known (RFC 8615) — The /.well-known/ path prefix is the IETF’s standard place to put machine-readable metadata about a host. Registered under RFC 8615, it is how a client finds an OpenID Connect discovery document, a security.txt, a change password endpoint, or an agent catalogue — without a human reading documentation first.
- A registry, not a format - Each suffix —
openid-configuration,security.txt,change-password— is registered separately with IANA and defines its own payload. - The only widely-deployed discovery convention on the web - It is the one place software can look on any host and expect to find machine-readable metadata.
- Cheap to publish - A static file at a known path. No infrastructure, no negotiation, no registry to join.
- Underused by API providers - Coverage across the markets scored in this research runs 22–47%, and it is named as a blueprint item in every one of them.
For an agent, /.well-known/ is the difference between discovery and guesswork. It is the first place a machine can look on an unfamiliar host, and it is the cheapest agent-readiness improvement available to an API provider — a text file at a fixed path. That is precisely why its absence keeps appearing in these reports: it costs almost nothing and roughly three-quarters of providers still do not publish one.
Referenced in API Evangelist papers
This standard shows up in my published research. These reports read the machine-readable evidence provider by provider — and put this standard in the context of a real sector.
The Model Context Protocol Standard
MCP discovery is unfinished: a young registry, thin `.well-known` coverage, and 10 conformant Agent Cards worldwide.
The State of Developer Tools APIs
22.0% of the developer-tools upper band publishes a `.well-known` catalog — the cheapest discovery affordance that exists.
The ARD Standard
The well-known path is not ARD's leading discovery mechanism; it is effectively its only one. Of four mechanisms the specification defines, the other three have one publisher between them.
