Netlify is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Netlify API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.
Discovery
45% of score · 81/100Comprehension
55% of score · 96/100What we found
- An agent landing on docs.netlify.com is handed an explicit on-ramp: a 24KB API-focused llms.txt links straight to the OpenAPI spec, the official @netlify/mcp server, and an installable skills repo — Netlify is actively designing for autonomous agents, even pointing to netlify.ai for agents that 'deploy to the web autonomously.'
- A valid /.well-known/mcp.json declares the official hosted Netlify MCP server with npx and Claude Code install commands — a rare, high-value discovery signal that most APIs fail entirely.
- Comprehension is near-perfect: docs are served as clean .md, examples use realistic IDs/timestamps in multiple languages, naming is consistently snake_case, and dedicated limitations pages plus rate-limit/pagination docs give an agent clear capability boundaries.
- Discovery is held back by a missing /robots.txt (404) and no llms-full.txt — small gaps, but they keep an otherwise excellent surface from an A.
- Error recovery is the weakest comprehension area: status codes and rate-limit headers are documented, but most API errors lack explicit 'do this to fix it' recovery steps, so an agent would still discover some failures by trial.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Add a /robots.txt at docs.netlify.com that explicitly allows AI crawlers (GPTBot, ClaudeBot, Google-Extended, CCBot) — currently it 404s, the single biggest easy discovery win.
- 02Publish an llms-full.txt with the expanded markdown corpus so agents can ingest full API context in one fetch rather than crawling individual .md pages.
- 03Strengthen error-recovery guidance: pair the documented status codes with explicit actions (e.g., 'on 429, wait for X-RateLimit-Reset before retrying'; 'on 422, inspect the validation message and correct the named field').
- 04Document idempotency: specify whether deploy/create operations support idempotency keys so agents can safely retry without duplicating sites or deploys.
- 05Enrich the OpenAPI operation descriptions with one-line task framing ('Create a new deploy from a file digest') so the raw reference is as outcome-oriented as the narrative guides.
Execution coverage · INFORMATIONAL, UNSCORED
Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.
Execution characteristics are documented thoroughly. Auth is OAuth2 plus Bearer personal access tokens with clear token-generation and invalidation guidance. Rate limits are explicit (500 req/min general, 3 deploys/min, 100/day) with X-RateLimit-Limit/Remaining/Reset headers. Pagination uses page/per_page with RFC-style Link headers (next/prev/last). Error responses carry standard HTTP status codes with a default error schema. Idempotency keys are not documented.