agentsready
Discoverability Easy

HTTP Link headers for agent discovery

What Link headers (RFC 8288) are, why AI agents use them to discover resources, an example, right vs wrong, mistakes, and how to verify.

Updated:

What it is

The HTTP Link header (RFC 8288) advertises related resources right in the server’s response, with no need to parse HTML. Through rel types you tell an agent where your API catalog, terms of service, privacy policy, and so on live.

Why it matters for AI agents

An agent makes a cheap HEAD/GET and learns from the headers what you have and where — without downloading and parsing the whole HTML. It’s a fast, reliable capability-discovery channel: api-catalog, terms-of-service, service-desc, and more.

Minimal working example

HTTP/1.1 200 OK
Link: <https://example.com/.well-known/api-catalog>; rel="api-catalog",
      <https://example.com/terms>; rel="terms-of-service"

Multiple links are comma-separated; the URL goes in angle brackets, rel after the ;.

Right vs wrong

RightWrong
Standard rels (api-catalog, terms-of-service)Made-up rels an agent won’t understand
Absolute URLs in <...>Relative paths
The header on relevant responsesA Link only on 404, or none at all
Correct RFC 8288 syntaxBroken brackets/commas — the header won’t parse

Common mistakes

  • Home-made rel types instead of registered ones.
  • Relative URLs — the spec allows them, but agents handle absolute URLs more reliably.
  • Syntax errors (a missing > or ,) — the whole header is invalid.
  • Duplicates that conflict with <link> tags in the HTML.

How to verify

A scan checks for valid Link headers. Manually:

curl -sI https://example.com/ | grep -i '^link:'

The response should contain a Link: with clear rel types and absolute URLs.

Sources