# link-headers

## 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:**
```nginx
add_header Link '</.well-known/api-catalog>; rel="api-catalog", </terms>; rel="terms-of-service"';
```

**Next.js middleware:**
```typescript
response.headers.set('Link',
  '</.well-known/api-catalog>; rel="api-catalog", </status>; rel="status"');
```

**Astro middleware (`src/middleware.ts`):**
```typescript
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.

[← All glossary terms](/en/glossary)