HTTP Link Headers for AI Agents and Machine Clients
How to publish typed HTTP links for real machine resources without turning performance hints into false service discovery.
Suppose a readiness scanner marks your site green for machine discovery because every response carries a Link header. Open one and the only relation is preconnect. That is valid Web Linking, and it tells an automated client nothing beyond connection preparation. The useful part of a Link field is the relationship it declares: a response that points to a current security contact gives a client something it can act on.
Review the destination before changing the header. Follow the URL and check whether the relation describes that resource from the requested page's context. A site-wide header can repeat the same incorrect pointer across every page.
Of the mechanisms in the agent-readable web field guide, this is the cheapest to publish, which is also why it is the easiest to publish carelessly. Our application configures two site-wide links: the RSS feed and the RFC 9116 security contact. The examples below describe those publishing relationships and the checks needed after deployment.
The RFC 8288 link model
RFC 8288 defines Web Linking. A link has a context, a relation type, a target, and optional target attributes. In an HTTP response, the context is normally the effective request URI unless an anchor parameter changes it.
The relation type explains how the target relates to the context. Registered short names include alternate, canonical, describedby, and security. An extension relation can be an absolute URI. The target is enclosed in angle brackets, followed by semicolon-delimited parameters:
Link: </feed.xml>; rel="alternate"; type="application/rss+xml"; title="TKOResearch Insights"
Here the requested page is the context, /feed.xml is the target, alternate is the relation, and type plus title are target attributes. The type value is a hint. A client still needs to request the target and inspect its actual response.
The distinction between relation and attribute matters. rel defines the link's semantics. type, hreflang, media, and title provide information about the target or intended use. Adding type="application/json" to an arbitrary URL doesn't make that URL an API, and attaching rel="alternate" doesn't establish that two resources contain equivalent material.
Multiple values and parsing
The Link field uses a comma-separated list of link-values. A server can send one field with several values:
Link: </feed.xml>; rel="alternate"; type="application/rss+xml", </.well-known/security.txt>; rel="security"; type="text/plain"
It can also send separate Link field lines. RFC 8288 treats these forms as equivalent after normal HTTP field combination:
Link: </feed.xml>; rel="alternate"; type="application/rss+xml"
Link: </.well-known/security.txt>; rel="security"; type="text/plain"
Don't split the combined value on every comma. Quoted parameter values and extension relation URIs have syntax that a conforming parser must respect. Use an RFC-aware library when consuming untrusted fields. For publishers, quote parameter values consistently and keep each link-value simple enough to inspect in a raw response.
A single rel parameter may contain several space-separated relation types that share the same context, target, and attributes. That is different from publishing several targets. Repeating a rel parameter within one link-value is invalid; RFC 8288 says parsers use the first occurrence.
Relative targets are allowed. A client resolves them against the applicable base URI. For a site-wide configuration, root-relative paths are easier to audit than page-relative paths because the meaning doesn't depend on directory depth.
Security contact discovery
RFC 9116 defines the security.txt format and the security link relation. The canonical Web location uses /.well-known/security.txt. A publisher may attach this relation to other responses:
Link: </.well-known/security.txt>; rel="security"; type="text/plain"
The target has its own requirements. It needs a Contact field, an Expires field, HTTPS delivery for Web use, and a current expiration date. A header that points at an expired or missing file is not useful discovery. It creates a failed escalation path at the moment a reporter needs it.
The configured target and the Canonical value inside the file should agree. A legacy redirect can remain useful for older clients, but it shouldn't leave new responses advertising a different location. I would also test the contact channel itself through the organization's normal process: a healthy HTTP route says nothing about whether someone receives a report.
Why preconnect doesn't advertise a machine resource
Frameworks and browsers often emit performance links such as:
Link: </>; rel=preconnect; crossorigin=""
This can be a valid link. The preconnect relation tells a user agent that opening a connection to an origin may improve future fetch performance. It says nothing about an API description, a feed, an MCP server, or an agent-oriented representation.
A readiness checker that asks only whether any Link field exists can misclassify this response. The right question is whether the response contains a relevant relation whose target resolves to the claimed resource. preconnect proves the site emits Web Linking syntax, nothing more.
The same caution applies to preload, dns-prefetch, stylesheet, and icon relations. They serve browser loading and presentation. Agents may process them, but they don't substitute for a relation that identifies the intended operational resource. If a client wants a machine-oriented representation of the page itself, that is a content negotiation question, and the response should say so with Vary: Accept and a matching content type rather than with a performance hint.
Publishing links in Next.js
For a stable site-wide relationship, Next.js can attach a response field through headers() in next.config.ts. We use one combined value:
{
key: 'Link',
value: '</feed.xml>; rel="alternate"; type="application/rss+xml"; title="TKOResearch Insights", </.well-known/security.txt>; rel="security"; type="text/plain"',
}
That works because both targets are public and apply across the site. A relation that applies only to one resource belongs on that route instead. Over-broad publication can imply a relationship that isn't true for every response, including error pages or private variants.
Configuration is only one layer. A CDN can combine, replace, or cache fields. Validate the deployed response with GET and HEAD requests:
curl -sSI https://www.tkoresearch.com/
curl -sSI https://www.tkoresearch.com/feed.xml
curl -sSI https://www.tkoresearch.com/.well-known/security.txt
Then request each target body. Confirm status, content type, canonical URL, redirects, and freshness. If the target requires authentication, decide whether advertising it on public responses reveals an unwanted surface.
Review and maintenance checklist
Before adding a link relation, record the following:
- The governing specification or registered relation definition.
- The exact context to which the relation applies.
- The production target and expected media type.
- The team responsible for availability and retirement.
- The client behavior that following the link is expected to trigger.
Test duplicate fields and edge caching as well. Confirm that an upstream proxy doesn't remove quotes, truncate a long value, or append a conflicting target. Monitor the destination, not merely the presence of the source field.
Remove discovery when the resource is retired. A 410 Gone response can be a deliberate transition, but an indefinite header pointing at a dead route is an operational defect.
Make the relationship survive the next release
A header test that only asserts the word Link will pass after the feed moves, the security contact expires, or a proxy strips one of several values. Keep target checks alongside the deployment checks for the source response.
Make the failure actionable: “the advertised security contact expired yesterday” or “the Markdown alternate returned HTML.” Include the target URL and observed response so the owner can reproduce it.
For a new API or agent service, decide whether the relation applies to the current resource, the whole origin, or a separate API catalog with its own well-known location. Publish it where that statement is true, and remove it when the destination is retired.