---
title: "List your APIs in one file · Agent Wranglers"
url: https://agentwranglers.se/playbook/website/standard-addresses/api-catalog
updated: 2026-10-20
licence: "All rights reserved"
---

# List your APIs in one file

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Standard addresses](https://agentwranglers.se/playbook/website/standard-addresses)
- Rule: List your public APIs and machine-readable files at `/.well-known/api-catalog`, as an RFC 9727 linkset (a JSON list of links).
- How: Serve it as `application/linkset+json` with the RFC 9727 profile, anchored at the catalog's own URL. Link each API with `item`, and its description with `service-desc`. Answer a HEAD request with a `Link` header naming the catalog.
- Check: `curl -sI` on the catalog shows `application/linkset+json` and the `api-catalog` link. Every URL listed in it answers 200.

Example:

```http
HTTP/1.1 200 OK
Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"
Link: </.well-known/api-catalog>; rel="api-catalog"
```

```json
{
  "linkset": [
    {
      "anchor": "https://example.com/.well-known/api-catalog",
      "item": [{ "href": "https://example.com/api/v1" }],
      "describedby": [{ "href": "https://example.com/llms.txt", "type": "text/markdown" }]
    },
    {
      "anchor": "https://example.com/api/v1",
      "service-desc": [{ "href": "https://example.com/api/v1/openapi.json", "type": "application/json" }],
      "service-doc": [{ "href": "https://example.com/docs/api", "type": "text/html" }]
    }
  ]
}
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers website playbook: https://agentwranglers.se/playbook/website/standard-addresses/api-catalog`.

- Previous: [Say you honour privacy signals](https://agentwranglers.se/playbook/website/standard-addresses/gpc-json)
- Next: [Answer account lookups](https://agentwranglers.se/playbook/website/standard-addresses/webfinger)
- [Standard addresses](https://agentwranglers.se/playbook/website/standard-addresses)