Ahrefs is Needs Work to agents.

What we found

• —An agent can fully understand Ahrefs' capabilities fast: the introduction page summarizes every product area (Site Explorer, Keywords Explorer, Site Audit, SERP, Rank Tracker, Batch Analysis, Brand Radar) in well under 5,000 tokens, and authentication (Bearer API key) is stated plainly.
• —Capability boundaries are exceptionally well documented — a dedicated limits-consumption page gives the exact unit-cost formula, per-field costs, response headers (x-api-units-cost-total, x-api-cache), the 60 req/min rate limit, and 429 throttling behavior, so an agent can predict cost and limits before calling.
• —An agent trying to auto-discover the API gets little help at the file level: llms.txt, llms-full.txt, and .well-known/mcp.json all 404, and there is no AGENTS.md — though robots.txt blocks /*.txt$, which would prevent an llms.txt from being crawled even if added.
• —Discovery is rescued by ecosystem presence: an official Ahrefs MCP server is listed on Glama and PulseMCP, and Ahrefs publishes a dedicated agent-skills repo and a Python SDK auto-generated from its OpenAPI spec — so agents reach it through registries even without on-site agent files.
• —Endpoint reference pages are agent-friendly (method + path lead, snake_case fields, allowed values, status codes 400/401/403/429/500), but per-endpoint error bodies render as a bare 'error: string' with no recovery steps, so an agent learns which errors exist but not how to fix them.

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

1. 01Publish an llms.txt at docs.ahrefs.com covering the API's core product areas and linking to the introduction, authentication, limits-consumption, and key endpoint references — and remove or scope the robots.txt 'Disallow: /*.txt$' rule so the file is actually crawlable.
2. 02Expose the OpenAPI spec that already powers the reference and the Python SDK as a publicly downloadable file at a discoverable URL (e.g. /openapi.json), so agents can ingest the full machine-readable contract in one fetch.
3. 03Add a dedicated API errors page (separate from the Looker Studio errors page) with actionable recovery guidance for the top error codes — e.g. how to back off on 429, what 401/403 mean for key scope/expiry, and which parameter triggered a 400.
4. 04Add 2-3 end-to-end workflow guides that chain endpoints for real tasks (e.g. 'audit a competitor: domain-rating → backlinks-stats → all-backlinks → keyword overlap'), since current guidance documents endpoints in isolation plus best-practices tips.
5. 05Add an AGENTS.md (or generate one from the existing agent-skills repo) at the primary public repos to give coding agents canonical, on-repo guidance instead of relying on registry listings.