Railway API 是一份针对 Railway.com GraphQL API v2 自动化的综合参考文档，用于通过 API 自动化管理 Railway 平台上的项目、服务、部署和环境变量。
用途 该技能面向需要以编程方式操作 Railway 平台的场景，包括自动化 Railway 操作、查询项目信息、管理环境变量、触发和监控部署，以及团队与资源管理、用量与账单查询等。
主要能力 文档按渐进式披露结构组织：SKILL.md 为主文件，提供快速参考和常见操作；references/ 目录包含详细文档，包括 graphql-endpoint.md（完整 API 端点文档）、authentication.md（认证指南）、common-queries.md（31 个查询示例及响应）、common-mutations.md（37 个变更示例及模式）、api-limitations.md（已知限制与变通方案）；scripts/ 目录提供自动化工具，如 query-project.py（用于查询 Railway API 的 Python 脚本）和 set-variables.ts（用于变量管理的 TypeScript 脚本）。
支持的操作类型包括：项目与服务管理、环境变量配置、部署触发与监控、团队与资源管理、用量与账单查询。文档给出了用户与账户信息查询、列出项目、获取项目详情与服务、获取环境变量、设置/更新变量、触发部署等示例代码。
使用方式 API 端点为 https://backboard.railway.com/graphql/v2。认证支持三种令牌类型：账户令牌使用 Authorization: Bearer <token> 头，作用于所有用户资源，适用于个人自动化；团队令牌使用 Team-Access-Token 头，作用于团队特定资源，适用于团队工作流；项目令牌使用 Project-Access-Token 头，仅限单个项目，适用于 CI/CD 和项目自动化。获取令牌可通过 railway-auth 技能或 Railway 控制台的账户设置中的 Tokens 页面。文档提供了基于 curl 的基础查询与变更示例，并建议使用 GraphQL 变量处理所有动态值。
错误处理方面，API 以 errors 字段返回错误，常见错误码包括 UNAUTHORIZED（无效或过期的令牌）、FORBIDDEN（对资源权限不足）、NOT_FOUND（资源不存在）、VALIDATION_ERROR（输入数据无效）。最佳实践包括始终检查响应中的 errors 字段、按操作范围选择合适令牌类型、处理速率限制（429 响应）、在变更前验证输入、为参数化查询使用变量。
速率限制为：账户令牌 100 次/分钟，团队令牌 500 次/分钟，项目令牌 1000 次/分钟。
适用场景 文档列出了集成模式，包括 CI/CD 流水线（获取项目令牌、设置部署变量、触发部署、监控部署状态）、基础设施即代码（在代码中定义 Railway 资源、通过 GraphQL 变更应用更改、跟踪状态与变更）、监控与告警（查询部署状态、检查资源使用、失败告警）。生产环境的变更建议使用项目令牌以增强安全性。
限制 文档记录了已知 API 限制：部分 GraphQL 查询即使令牌有效也会返回“Problem processing request”，这是 Railway API 的限制而非令牌问题。受影响查询包括 deployment(id:)、deploymentLogs、buildLogs、me.teams、teams。变通方案是使用 Railway CLI，例如 railway list --json（项目/团队）、railway logs（部署/构建日志）。
其它说明包括：所有时间戳为 ISO 8601 格式（UTC）；ID 为不透明字符串，不应解析或构造；分页使用基于游标的 edges/nodes 模式。学习路径建议从 graphql-endpoint.md 开始了解端点细节，再学习 authentication.md、common-queries.md、common-mutations.md，然后使用 scripts/ 中的脚本进行自动化，最后组合模式实现复杂自动化。相关资源包括 Railway API 文档、GraphQL Explorer 和令牌管理（通过 railway-auth 技能）。