apis.guru is Needs Work to agents.

What we found

• —An agent can discover and consume this API almost entirely from machine-readable artifacts: a publicly downloadable OpenAPI 3.0 spec (api.apis.guru/v2/openapi.yaml) plus a permissive robots.txt that blocks no AI crawlers — the strongest signals in the scan.
• —The API is itself a directory of 2,500+ OpenAPI specs, and it is well-represented where agents look for tools: an official APIs.guru MCP server is listed on both PulseMCP and Glama, so an agent hunting for an API-catalog tool would find it.
• —There is no llms.txt, no llms-full.txt, and no .well-known/mcp.json, so an agent relying on the emerging agent-discovery conventions gets nothing and must fall back to scraping the Redoc docs page or the raw spec.
• —Endpoint descriptions are genuinely task-oriented ('List all APIs in the directory. Returns links to the OpenAPI definitions for each API...') and the whole surface fits in well under 5,000 tokens — an agent can understand the entire API in one read.
• —An agent that hits a failure is on its own: only 200 responses are documented, with no error codes, recovery guidance, rate limits, or capability boundaries anywhere in the docs.

What to change

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

1. 01Add an llms.txt at apis.guru/llms.txt with a short description and direct links to the OpenAPI spec (api.apis.guru/v2/openapi.yaml), the api-doc page, and the list.json/metrics.json endpoints — the single highest-leverage discovery fix.
2. 02Document error responses in the OpenAPI spec: define 404 (unknown provider/API), 4xx/5xx shapes, and a brief recovery note per endpoint so an agent can self-correct instead of only seeing 200s.
3. 03Add a short 'capability boundaries' note to the docs — no auth required, no rate limits (or the actual limit), data freshness/update cadence — so agents know what the API can and cannot do without probing by failure.
4. 04Add an AGENTS.md to the primary openapi-directory repo (one already exists in the peripheral APIs-guru/dotviz repo) so coding agents working against the catalog get project-specific context in the place they'd actually look.
5. 05Publish request examples (a simple curl per endpoint) alongside the response samples, and replace 'string'/'property1' placeholders with realistic values to make the copy-pasteable examples fully concrete.