Link headers (RFC 8288)

What are Link headers?

The HTTP Link response header (RFC 8288) is a response header that a server uses to annotate a page with links to related machine-readable resources. AI agents use these headers to automatically discover APIs, documentation, and catalogs.

Link: </.well-known/api-catalog>; rel="api-catalog",
      </terms>; rel="terms-of-service",
      </status>; rel="status"

Why does a site need Link headers?

Link headers are a standard service-discovery mechanism that requires no HTML parsing. When an agent makes a request to the homepage, it immediately sees links to all important meta-resources right in the response headers.

This is especially important for API services: a client finds the API catalog, OAuth discovery endpoint, or documentation without prior knowledge of the URLs.

Relevant rel values for agents:

rel	What it points to
api-catalog	API Catalog (RFC 9727)
service-doc	Service documentation
service-desc	Service description (OpenAPI)
status	Status page
terms-of-service	Terms of use

How to configure Link headers?

Nginx:

add_header Link '</.well-known/api-catalog>; rel="api-catalog", </terms>; rel="terms-of-service"';

Next.js middleware:

response.headers.set('Link',
  '</.well-known/api-catalog>; rel="api-catalog", </status>; rel="status"');

Astro middleware (src/middleware.ts):

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware((ctx, next) => {
  const response = await next();
  response.headers.set('Link',
    '</.well-known/api-catalog>; rel="api-catalog"');
  return response;
});

How do we check Link headers?

The scanner performs HEAD / (with a fallback to GET on HTTP 405) and inspects the Link header in the response.

1. Presence of the Link header — if absent, status fail
2. Link parsing — extract all <url>; rel="..." pairs
3. Relevant rel values — look for at least one of: api-catalog, service-doc, service-desc, status, terms-of-service

Status pass (1.0) — at least one relevant rel value found. Status warning (0.5) — Link header is present but has no relevant rel values. Status fail — header is absent.