Agents find your APIs through two small standards. An HTTP Link header on your homepage points to an API catalog. The catalog, served at /.well-known/api-catalog, lists each API with links to its machine-readable description and its documentation. Neither needs new infrastructure; both are a few lines of configuration and one JSON file.
Without them, an agent that wants to use your service has to guess. It might find an OpenAPI file by luck, or scrape your developer docs, or give up and fill in your web forms instead. With them, discovery is one request away.
Link headers (RFC 8288)
RFC 8288 defines Web Linking: a way to express typed links between resources, including in the HTTP Link response header. A link has a target and a relation type that says what the target is:
Link: </.well-known/api-catalog>; rel="api-catalog",
</llms.txt>; rel="describedby"; type="text/plain"Because the header is part of the HTTP response, a client sees it before parsing any HTML. That is why agent-readiness checkers look for it on the homepage: it is the cheapest possible pointer to everything else.
The api-catalog (RFC 9727)
RFC 9727 defines the api-catalog well-known URI and link relation. A publisher serves a catalog at /.well-known/api-catalog, and the default format is a linkset, as defined in RFC 9264, served with the media type application/linkset+json.
A linkset is a list of entries. Each entry has an anchor, which is the API itself, and a set of relations pointing to things about it:
| Relation | Points to |
|---|---|
| api-catalog | The catalog of your APIs |
| service-desc | A machine-readable description, such as OpenAPI |
| service-doc | Human-readable documentation |
| status | A health or status endpoint |
| describedby | A document describing the resource |
- service-desc: a machine-readable description, most often an OpenAPI document.
- service-doc: documentation for people.
- status: optionally, an endpoint that reports whether the API is up.
A working example
This site publishes a catalog you can read at /.well-known/api-catalog. It lists two small public APIs: the project inquiry form and the agent-readiness scan. Trimmed, the scan entry looks like this:
{"linkset": [
{"anchor": "https://aispeedforce.com/agent-ready/scan.php",
"service-desc": [{"href": "https://aispeedforce.com/agent-ready/openapi.json",
"type": "application/vnd.oai.openapi+json"}],
"service-doc": [{"href": "https://aispeedforce.com/agent-ready/",
"type": "text/html"}]}
]}The homepage response carries a Link header with rel="api-catalog" pointing to that file, plus service-desc, service-doc and describedby links. An agent that loads the homepage can reach the OpenAPI description in two requests.
One practical detail: on some hosts you cannot set response headers or custom content types from configuration. We serve the catalog and the homepage headers through a small script for that reason. Check that your catalog really comes back as application/linkset+json; a plain application/json response is a common slip.
Make the description worth finding
The catalog only helps if what it points to is useful. For an agent, a good OpenAPI description:
- names each operation plainly, with an
operationIdand a one-line summary; - describes every parameter, including limits, formats and allowed values;
- documents error responses, and says which error messages are safe to show a person;
- states the rules of use in the description: rate limits, and actions that should only happen when a user asks.
That last point matters for any API that does something on a person's behalf, like sending a message. Our inquiry API description tells agents to call it only when the user has asked, with the user's own details.
How it fits with the other files
The catalog is for APIs. Other files do other jobs, and they point at each other:
- llms.txt describes your site for language models and can link your API descriptions.
- Agent skills and the ai-catalog package instructions for how an agent should use your site, and list them for registries.
- An MCP server is the next step when you want agents to use your systems through a standard tool interface.
Several APIs, versions and private endpoints
A catalog can list as many APIs as you publish. Give each its own linkset entry with its own anchor, and let each entry point to its own description and documentation. If you run two versions of an API side by side, list both, and say in each description which one is current and when the old one retires. An agent that picks the wrong version from an ambiguous catalog will produce errors your support team then has to explain.
Only list what outsiders can actually use. Internal endpoints, admin routes and anything that needs credentials you do not hand out do not belong in a public catalog. If an API needs authentication, say so in its description and document how to get access, so an agent can tell its user what is required instead of failing silently.
Common mistakes
- Wrong content type. The catalog is served as plain JSON instead of
application/linkset+json. - A catalog with no Link header. The file exists, but nothing points to it, so only clients that already know the well-known path find it.
- Descriptions that 404. The catalog points to an OpenAPI file that moved. Check the links whenever you deploy.
- Relative URLs inside the linkset. Use absolute URLs so each entry stands on its own.
Worth it for small sites too
You do not need a large developer platform to benefit. A single public form endpoint, a quote calculator or a stock lookup is an API. Describing it in a catalog takes an afternoon, and it means an agent helping one of your customers can use it correctly instead of guessing at your web form.
Next step
If you offer any API, even a small one, publish a catalog and a homepage Link header pointing to it. Then run the free agent-readiness scan, which checks both, including the content type. If you would rather have the API layer designed for agents from the start, see agent engineering.