What is the .well-known directory of a website?

If a specification for agentic commerce tells you to publish a file at /.well-known/, or a vendor asks you to upload a verification file there, it is not asking for just any folder: it is a path reserved by an internet standard for information that describes the whole site. The dot at the start matters: on some operating systems, folders whose names start with a dot are hidden, and the standard itself warns that an administrator may not know they exist.⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)} It matters to you because the protocols an AI agent uses to discover what a store can do start looking right there.

How it works

Some applications need to know something about a site before asking it for anything: what permissions it grants, what services it offers, whom to notify about a flaw. The obvious solution is to fix an address known in advance. The problem, says RFC 8615, is twofold: two protocols may pick the same address, or step on a URL the site already uses, and fixing one also takes away the site owner's control over their own URLs. The standard solves it by reserving a single prefix, /.well-known/, in http, https, ws and wss URLs, and asking that each use be registered.⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)}

RFC 8615 is from May 2019 and replaces RFC 5785, the first version. Its rules fit in a few lines:⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)}

• Only the root counts. /.well-known/example is a reserved address; /store/.well-known/example is not.
• One name per application, no slashes and precise. The standard discourages settling for generic words: for the metadata of an application called Example, example-metadata is better than metadata.
• Each name's specification rules. It is the one that defines the format and the content type. The RFC defines nothing for the /.well-known/ path itself, and warns that clients should not expect anything to exist at it: a bare /.well-known/ returning a 404 error is normal.

Names are registered in IANA's Well-Known URIs registry. To get in you need a published specification and an expert's review, and each entry gives its name, who controls it, which document defines it and its status: permanent for open standards and for what the experts see in use, provisional for the rest, which may be withdrawn if it falls out of use.⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)} The registry had 105 entries on October 6, 2026, and its last update was September 16, 2026.⁠^{[2]IANA. Well-Known URIs}

What lives on that path speaks for the whole site, and the standard draws its main security advice from there: control who can write to /.well-known/, especially if several people or services share the same domain. Whoever manages to write there can change what the site declares about itself without anyone noticing.⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)}

In a store

This is what a store may find on that path. The first three are in IANA's registry; the fourth is not:

Fictional example. This is the minimal security.txt of an invented store, example-store.com, served at https://example-store.com/.well-known/security.txt:

Contact: mailto:security@example-store.com
Expires: 2027-10-06T00:00:00.000Z

The Expires date says when the file stops being valid, and the standard asks for it to be served as text/plain; charset=utf-8.⁠^{[3]IETF (RFC Editor). RFC 9116: A File Format to Aid in Security Vulnerability Disclosure} For the UCP profile the conditions are stricter, and worth reviewing if a platform or a CDN sits in the middle: it is served over HTTPS, with no redirects, and with a public Cache-Control header of at least 60 seconds, never private, no-store or no-cache.⁠^{[6]Universal Commerce Protocol. UCP Specification Overview (version 2026-08-25)} A redirect from http to https or from the bare domain to the www one is common in a store, and on this path it is enough to break the specification if the agent arrives by the address that redirects.

How to check it

1. Request the paths from your own store. Open https://your-domain/.well-known/security.txt and, if you sell through agents, https://your-domain/.well-known/ucp. A 404 on the first is not a site error, but it tells you that you do not have one.
2. Look at the headers with curl -I. The response code, whether there is a redirect and the Content-Type. For the UCP profile, also that it does not redirect and that the Cache-Control is public.⁠^{[6]Universal Commerce Protocol. UCP Specification Overview (version 2026-08-25)}
3. If you have a security.txt, check the date. The Expires field says until when what it declares is valid.⁠^{[3]IETF (RFC Editor). RFC 9116: A File Format to Aid in Security Vulnerability Disclosure}
4. Look up in IANA's registry the name you are asked to publish. If it is there, it links to the specification that defines it; if it is not, it is the convention of whoever is asking, not a registered standard.⁠^{[2]IANA. Well-Known URIs}
5. Review who can write to that path, on the server, on the CDN and in the installed applications. The standard asks that you not grant that permission without realizing it.⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)}

Related concept: robots.txt

robots.txt and /.well-known/ get confused because both are fixed addresses that a machine requests before anything else. But robots.txt is a file with a single job: telling crawlers what they may request, and always at the root.⁠^{[7]IETF (RFC Editor). RFC 9309: Robots Exclusion Protocol} /.well-known/ is a namespace for many files, each with its own protocol and its own specification.⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)} RFC 8615 cites the robots exclusion protocol as an example of the problem it came to tidy up, and makes clear it does not touch it.⁠^{[1]IETF (RFC Editor). RFC 8615: Well-Known Uniform Resource Identifiers (URIs)}

To keep going, the reading path for this topic orders the rest of the terms, and the UCP entry explains what an agent does with the profile it finds at /.well-known/ucp.