Self-Describing Link Headers So Agents Can Discover Your Schema From Any Endpoint
Lets an AI agent that lands on any of your JSON endpoints find the full API description without guessing.
What this signal tests
We check whether your API responses include a Link header (per RFC 8288) pointing to your machine-readable API description. The relation type must be describedby, service-desc, or service-doc - the standard relation names for self-describing API responses. The link should resolve to your OpenAPI document, JSON Schema, or equivalent.
Why it matters for your visibility in AI
AI agents do not always discover APIs from the top down. A user might paste a single endpoint URL, or an agent might follow a link from a third-party site and arrive directly at /api/products/12345. In that situation, the agent needs to figure out what kind of API it is talking to without going back to the homepage. The Link header is the standard mechanism for that: every JSON response points the agent at its own description. With Link headers in place, an agent arriving at any endpoint can fetch the OpenAPI document, learn the full schema, and call other endpoints intelligently. Without them, the agent either gives up or makes guesses based on the JSON shape it sees, often wrongly. This is a cheap, RFC-standardised way to make every API response self-orienting; it pairs naturally with the openapi-discoverable signal but adds resilience for agents that arrive mid-flow.
Pass criteria at a glance
| Criterion | Passes when |
|---|---|
| API endpoints expose self-describing Link headers. |
How we test it
Our scanner makes a GET request to one of your API endpoints and parses the Link header in the response per RFC 8288. The signal passes when at least one link relation is describedby, service-desc, or service-doc and resolves to a real machine-readable description document. The Link header format allows multiple relations; we only need one matching relation to pass.
Show technical detection method
GET API endpoint; parse Link header; pass if any rel describedby|service-desc|service-doc.
If your site fails: how to fix it
- Confirm you publish an OpenAPI document or equivalent machine-readable API description; if not, address the openapi-discoverable signal first, because the Link header has nowhere useful to point until that exists.
- Configure your API gateway, reverse proxy, or framework middleware to emit a Link header on every JSON API response, pointing to the OpenAPI document with relation type service-desc.
- Use the exact RFC 8288 syntax: Link: </openapi.json>; rel="service-desc" - agents follow the syntax literally, and small deviations like missing quotes will silently break parsing.
- Verify the header survives every intermediate CDN, proxy, and edge layer; some platforms strip non-standard headers by default and need to be told to preserve Link.
- Test from a real agent client or any HTTP client that follows Link headers (curl -I will show the response) to confirm the header is present and the target resolves to a parseable document.
Quick facts
| Maturity | ESTABLISHED |
|---|---|
| Weight | low |
| Category | Agent Actions |
Primary sources
Related signals
Frequently asked questions
Is this redundant if we already publish OpenAPI?
No, it complements it. OpenAPI at /openapi.json is the top-down discovery path. Link headers are the bottom-up path for agents that arrive at a specific endpoint without first visiting the homepage. Both work together; publishing OpenAPI alone misses agents that arrive mid-flow.
Does this cost anything to implement?
It is a configuration change in your web server, gateway, or framework - usually one line. There are no licensing fees and no performance impact. The cost is purely engineering time to identify the right place to emit the header and verify it survives all intermediate layers.
What if our API does not yet have a published description?
Then this signal is not your highest priority - address the openapi-discoverable signal first. A Link header pointing at a non-existent document is worse than no header. Once your OpenAPI is published, adding the Link header is a quick follow-on task.
Which relation type should we use?
service-desc is the most specific and is the preferred choice for pointing at OpenAPI or similar service descriptions. service-doc is for human-readable docs. describedby is the generic IANA relation. Use service-desc for machine descriptions; the scanner accepts any of the three.
Run your own scan
Run a free scan and see how your site grades across all 155 AI-readiness signals.