Agent Link Headers Missing or Broken

TL;DR: If your site exposes machine-readable discovery documents, Link headers are a clean way to advertise them. If you do not expose those resources, an info result here is fine.

Treat "Agent Link Headers Missing or Broken" as a practical fix cycle: isolate the break, patch the smallest safe thing, and confirm quickly. The payoff is more reliable AI crawl and citation signals over time.

This check is about discoverability at the HTTP layer. Instead of forcing a client to download HTML and hunt for links in page markup, a site can advertise important machine-readable resources directly in the response headers.

Scavo treats this as optional because most ordinary marketing sites do not need to publish service-desc, describedby, or api-catalog relations. But if you do publish them, they should be stable, reachable, and mapped to the right resource type.

What Scavo checks (plain English)

Scavo inspects the Link response header on the scanned URL, looks for agent-relevant relations such as service-desc, describedby, and api-catalog, resolves the target URLs, and checks whether those targets are publicly reachable.

A pass means at least one advertised relation resolved cleanly. A warning means a relation was advertised but the target was broken or unreachable. An info result means no relevant Link headers were found.

• Scan key: ai_link_header_discovery
• Category: AI_VISIBILITY

How Scavo scores this check

• Warning: at least one agent-oriented Link relation was present, but its target URL was broken, invalid, or not publicly reachable.
• Pass: at least one recognized relation resolved to a reachable machine-readable target.
• Info: no relevant Link header relations were found on the scanned URL.

Why fixing this matters

Good Link headers shorten the discovery path for agents, API tooling, and automation systems. That matters most when you want integrations to find your docs, API catalog, or server description without custom instructions.

Broken Link headers are worse than no Link headers. They advertise capability, then send the caller into a dead end. That creates unnecessary friction and makes the integration surface look stale or half-finished.

Common reasons this check flags

• The header points to a relative URL that resolves incorrectly from the final production URL.
• The target document moved or was removed, but the header stayed in place.
• The header is only added on one route, while the canonical public route does not advertise it.
• A CDN or reverse proxy strips the Link header in production.

If you are not technical

1. Only treat this as action-worthy if your site actually exposes an API, protocol document, or public machine-readable capability you want others to discover.
2. If you do, ask engineering for a short list of the resources that should be discoverable and which public URL should advertise them.
3. If you do not, an info result is acceptable and you do not need to force adoption just for score-chasing.

Scavo flagged Agent Link Headers (ai_link_header_discovery). Please review the live Link response headers, remove stale relations, and ensure every advertised service-desc, describedby, or api-catalog target resolves publicly on production before re-running the scan.

If you are technical

1. Check the final response with curl -I https://example.com/ and inspect every Link: header value on the canonical URL.
2. Use registered relation types where possible. For example, service-desc is intended for machine-readable service descriptions and api-catalog for a published API catalog.
3. Resolve relative targets against the final URL and confirm redirects do not send the caller somewhere unexpected.
4. Do not advertise documents you are not committed to keeping public and current.
5. If a relation is only relevant for a specific route or API host, advertise it there rather than on every page on the domain.

How to verify

• Fetch the live response headers and confirm the expected Link relations are present.
• Request every advertised target directly and confirm it returns a stable public response.
• Re-run Scavo and verify the check moves to pass or intentional info.

What this scan cannot confirm

• Scavo does not deeply validate the full semantics of the target document beyond basic reachability and machine-readable structure.
• Scavo cannot decide whether your product should publish these relations. It only reports what is advertised and whether it resolves.

Owner checklist

• [ ] Name one owner for this check and note where it is controlled (app, CDN, server, or CMS).
• [ ] Add a release gate for this signal so regressions are caught before production.
• [ ] After deploys that touch this area, run a follow-up scan and confirm the result is still healthy.
• [ ] Re-check AI crawler and citation signals after robots, schema, or author metadata changes.

FAQ

What does Scavo actually validate for Agent Link Headers Missing or Broken?

Scavo checks live production responses using the same logic shown in your dashboard and weekly report.

Will AI visibility changes show immediately after we ship fixes?

Usually not instantly. Crawlers and answer engines refresh on different schedules, so confirm technical signals first, then monitor citations and mentions over time.

What is the fastest way to confirm the fix worked?

Run one on-demand scan after deployment, open this check in the report, and confirm it moved to pass or expected info. Then verify at source (headers, HTML, or network traces) so the fix is reproducible.

How do we keep this from regressing?

Keep one owner, keep config in version control, and watch at least one weekly report cycle. If this regresses, compare the release diff and edge configuration first.

Sources

• RFC 8288: Web Linking
• RFC 8631: Link Relation Types for Web Services
• RFC 9727: api-catalog
• IANA Link Relations Registry

Need stack-specific help? Send support your stack + check key and we will map the fix.