Railway is Agent-Ready to agents.
Discry independently scored how well an AI agent can discover and understand the Railway 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 · 83/100Comprehension
55% of score · 96/100What we found
- Railway is built for agents end-to-end: a dedicated 'Railway for Agents' page, an official local + hosted MCP server, a published agent-skills format (use-railway), and a railwayapp/railway-skills repo carrying AGENTS.md. An agent arriving cold can self-configure with a single `railway setup agent` command — a top-decile discovery story.
- Discoverability is excellent: robots.txt allows all crawlers, a well-structured 38KB llms.txt (with a description-rich link map including the agents page), a 1.3MB llms-full.txt, a sitemap, and any page is retrievable as clean markdown by appending `.md` — so an agent can consume the docs in its native format without HTML parsing.
- Comprehension is near-ideal: GraphQL endpoint guides are task-oriented ('List domains for a service'), examples use realistic values across multiple languages via code tabs, and capability boundaries (rate limits, edge traffic limits, known SSH/monorepo limitations) are spelled out — an agent rarely has to discover limits by failing.
- The one discovery gap is the absence of a conventional machine-readable spec: the API is GraphQL-only with no OpenAPI/Swagger document. A downloadable Postman/GraphQL collection and full introspection partly compensate, but agents expecting an OpenAPI contract won't find one, and there is no /.well-known/mcp.json.
- Error-recovery guidance is the weakest comprehension area: troubleshooting flows (autodeploy, GitHub app) and Retry-After on rate limits give recovery steps, but the GraphQL API's error response format and a systematic error-code-to-fix mapping are not documented, so an agent must infer how to self-correct on API errors.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish the GraphQL error response envelope and a top-10 error scenarios table with explicit recovery steps (which field was invalid, what valid values are, when to retry). This is the single highest-leverage comprehension fix and would push the comprehension score toward 100.
- 02Add a /.well-known/mcp.json manifest pointing at the hosted remote MCP server with tool declarations and auth info, so MCP-aware agents can auto-discover Railway's MCP without reading prose docs.
- 03Because the API is GraphQL, ship the introspected SDL as a versioned, publicly downloadable schema file (e.g., /api/schema.graphql) linked from the API overview — the agent-equivalent of an OpenAPI spec and an easy upgrade of the openApiSpec signal from partial to pass.
- 04Surface idempotency guidance for mutations (whether retries are safe, any idempotency-key or staged-commit pattern) so agents can safely retry write operations after network failures.
- 05Keep doing what already works — the agents page, agent skills, AGENTS.md, and .md content negotiation are exemplary; consider linking the agents page even more prominently from the docs root and llms.txt top section.
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.
Authentication is thoroughly documented (Bearer access tokens, project tokens with a distinct Project-Access-Token header, and OAuth2), as are rate limits — with explicit per-tier RPH/RPS limits and named response headers (X-RateLimit-Limit/Remaining/Reset, Retry-After). Pagination uses documented Relay-style cursors (edges/node, first/after, pageInfo). The GraphQL error response envelope and idempotency keys are not explicitly documented.