# API catalogs and Link headers: how agents find your APIs > How RFC 8288 Link headers and the RFC 9727 api-catalog let agents discover your APIs, what service-desc and service-doc mean, and a working example. Canonical page: https://aispeedforce.com/blog/api-catalog-and-link-headers/ Last updated: 2026-09-23 Two small standards tell agents where your APIs are: an HTTP Link header on the homepage, and a well-known api-catalog file that lists each API and its description. [Agent readiness](https://aispeedforce.com/blog/category/agent-readiness/) Published 23 September 2026 5 min read By AI SpeedForce 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](https://www.rfc-editor.org/rfc/rfc8288) 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: ; rel="api-catalog", ; 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. How an agent finds an API ## The api-catalog (RFC 9727) [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) 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](https://www.rfc-editor.org/rfc/rfc9264), 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 | Link relations you will use - **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](https://aispeedforce.com/.well-known/api-catalog). It lists two small public APIs: the project inquiry form and the [agent-readiness scan](https://aispeedforce.com/agent-ready/). 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 `operationId` and 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](https://aispeedforce.com/blog/llms-txt-explained/) describes your site for language models and can link your API descriptions. - [Agent skills and the ai-catalog](https://aispeedforce.com/blog/agent-skills-and-ai-catalog/) package instructions for how an agent should use your site, and list them for registries. - [An MCP server](https://aispeedforce.com/blog/mcp-servers-for-business/) is the next step when you want agents to use your systems through a standard tool interface. Minimum working setup ## 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](https://aispeedforce.com/agent-ready/), which checks both, including the content type. If you would rather have the API layer designed for agents from the start, see [agent engineering](https://aispeedforce.com/services/agent-engineering/). ## Questions about this topic ### Do I need an API catalog if I have no public API? No. The catalog lists APIs you actually offer. If you have none, there is nothing to list, and a checker that flags it can be ignored. ### Can I use HTML link tags instead of the HTTP header? You can add both. The HTTP Link header is visible without parsing HTML, which is why checkers look for it on the homepage response. A link tag in the head helps clients that only read the page. ### What format should service-desc point to? Usually an OpenAPI document in JSON or YAML. It gives an agent the operations, parameters and responses it needs to call the API correctly. ## Related posts - [MCP servers for business: when you need one and how to keep it safe](https://aispeedforce.com/blog/mcp-servers-for-business/): Agent readiness 23 September 2026. An MCP server exposes your systems to AI agents through one standard interface. It is worth building when agents need to act inside your business, not just read about it. - [Markdown for agents: serving Markdown with content negotiation](https://aispeedforce.com/blog/markdown-for-agents-content-negotiation/): Agent readiness 23 September 2026. Agents read Markdown far more cheaply than HTML. Serve a Markdown copy when a request asks for text/markdown, keep HTML the default, and link the copy from every page. - [Agent skills and the ai-catalog: telling agents how to use your site](https://aispeedforce.com/blog/agent-skills-and-ai-catalog/): Agent readiness 23 September 2026. Agent skills are short instruction files that teach an agent to do one job with your site. A discovery index lists them, and the draft ai-catalog lets registries find them. - [All posts](https://aispeedforce.com/blog/) - [More on Agent readiness](https://aispeedforce.com/blog/category/agent-readiness/) - [Agent-readiness scan](https://aispeedforce.com/agent-ready/) ## See how your own site scores The free agent-readiness scan checks the files, headers and endpoints this blog writes about, and tells you what to fix first.