A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Railway API is how an app or AI agent works with a Railway account: listing projects, creating a service, triggering and rolling back deployments, and reading or setting a service's environment variables. Access is granted through an API token, and the token's type sets its reach, from an account token that sees every workspace to a project token confined to one environment. Railway keeps a single, continuously updated schema rather than dated versions, and it can push deployment events to a project webhook.
How an app or AI agent connects to Railway determines what it can reach. The API is a single GraphQL endpoint, and what each call can touch is set by the type of token behind it.
Railway's public API is a single GraphQL endpoint at https://backboard.railway.com/graphql/v2, the same API that powers the Railway dashboard. Every operation is a POST to that one endpoint, sending a query or mutation, and the schema can be explored live by introspection or in the GraphiQL playground at railway.com/graphiql.
Railway's first-party MCP server lets an agent drive Railway through the Model Context Protocol, calling the same GraphQL API underneath. A remote server at mcp.railway.com needs no local install and authenticates through OAuth in the browser, while a local server runs through the Railway CLI and shares its authentication and project context. It is under active development, with tools for creating projects, deploying templates, managing environments, pulling variables, and redeploying services.
A project can register a webhook URL in its settings, and Railway POSTs a JSON payload when a deployment changes state or a usage alert fires. The payload carries a type such as Deployment.failed, the deployment details, and the workspace, project, environment, and service it belongs to. Railway can format the payload for Discord and Slack automatically.
An account token acts as the user and reaches every resource and workspace that user can. It is sent as a Bearer token in the Authorization header, and is meant for personal scripts and local development rather than shared automation.
A team token, called a workspace token, is scoped to a single workspace and can be shared with teammates. It is sent as a Bearer token in the Authorization header, and suits team CI/CD and shared automation.
A project token is scoped to a single environment in one project, which is the narrowest scope. It is sent in the Project-Access-Token header rather than as a Bearer token, and suits deployment automation that only needs to act on one environment.
OAuth grants user-approved permissions to a third-party app acting on a user's behalf, and is the basis for the remote MCP server's browser sign-in. The resulting token is sent as a Bearer token in the Authorization header.
The Railway API is split into areas an agent can act on, like projects, services, deployments, variables, and environments. Reads fetch the current state of an account, while writes create services, change variables, and start deployments.
Read the authenticated account, list accessible projects, and read the project a project token is scoped to.
Read a single project with its services and environments, and create a new project.
Create a service from a repo, image, or empty, update its build and deploy settings, and delete it.
List and read deployments, trigger and redeploy a service, and stop, restart, or roll back a deployment.
Read the variables for a service or environment, set one or many, and delete one.
List and read environments in a project, create one, and delete one.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Account & workspaceRead the authenticated account, list accessible projects, and read the project a project token is scoped to.3 | ||||||
| POST | query me | Read the authenticated account's profile, such as name and email. | read | Account token | Current | |
Identifies who a call is acting as. An account token reaches every resource and workspace the user can; a project token cannot run this and reads its own scope through projectToken instead. Acts onuser Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query projects | List the projects the token can access, each with id, name, description, and timestamps. | read | Account token | Current | |
Returns the projects in the personal account or workspace behind the token. A project token is scoped to one project and does not list across projects. Acts onproject Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query projectToken | Read the project and environment a project token is scoped to, returning projectId and environmentId. | read | Project token | Current | |
The way a project token discovers its own scope. A project token authenticates through the Project-Access-Token header, not Authorization. Acts onproject Permission (capability) Project tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsRead a single project with its services and environments, and create a new project.2 | ||||||
| POST | query project | Read a single project by id, with its services and environments. | read | Account token | Current | |
A workspace or project token reaches the project only if its scope covers it. Acts onproject Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation projectCreate | Create a new project, optionally assigning it to a workspace and connecting a GitHub repo. | write | Account token | Current | |
Takes a ProjectCreateInput. A project token cannot create projects, since it is scoped to one environment in an existing project. Acts onproject Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ServicesCreate a service from a repo, image, or empty, update its build and deploy settings, and delete it.3 | ||||||
| POST | mutation serviceCreate | Create a service in a project from a GitHub repo, a Docker image, or empty. | write | Account token | Current | |
Takes a ServiceCreateInput with projectId, name, and an optional source of a repo or image. Acts onservice Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation serviceInstanceUpdate | Update a service's settings in an environment, like start command, region, replicas, or healthcheck path. | write | Account token | Current | |
Takes serviceId, environmentId, and a ServiceInstanceUpdateInput. A service instance is the service as configured in one environment. Acts onservice Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation serviceDelete | Delete a service and all of its deployments. | write | Account token | Current | |
Takes the service id. This removes the service and every deployment under it, and cannot be undone. Acts onservice Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DeploymentsList and read deployments, trigger and redeploy a service, and stop, restart, or roll back a deployment.7 | ||||||
| POST | query deployments | List the deployments for a service in an environment, with id, status, and timestamps. | read | Account token | Current | |
Takes a DeploymentListInput. A project token can read deployments in the environment it is scoped to. Acts ondeployment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query deployment | Read a single deployment by id, including its status and URLs. | read | Account token | Current | |
Takes the deployment id. Acts ondeployment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation serviceInstanceDeployV2 | Trigger a new deployment for a service in an environment, optionally pinning a commit, and return the deployment id. | write | Account token | Current | |
Takes serviceId, environmentId, and an optional commitSha. A project token scoped to the environment can run this, which suits deployment automation. Acts ondeployment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook event deployment-statusRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation serviceInstanceRedeploy | Redeploy a service in an environment, reusing the existing commit without checking for new GitHub updates. | write | Account token | Current | |
Takes serviceId and environmentId. Acts ondeployment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook event deployment-statusRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation deploymentRedeploy | Redeploy an existing deployment by id, returning the new deployment's id and status. | write | Account token | Current | |
Takes the deployment id. Acts ondeployment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook event deployment-statusRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation deploymentStop | Stop a running deployment by id. | write | Account token | Current | |
Takes the deployment id. Acts ondeployment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook event deployment-statusRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation deploymentRollback | Roll a service back to a previous deployment by id. | write | Account token | Current | |
Takes the deployment id, and only works on deployments where canRollback is true. Acts ondeployment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook event deployment-statusRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VariablesRead the variables for a service or environment, set one or many, and delete one.4 | ||||||
| POST | query variables | Read the variables for a service in an environment, or the shared environment variables when no service is given. | read | Account token | Current | |
Takes projectId, environmentId, and an optional serviceId. Variables can hold secrets, so this read returns sensitive values. Acts onvariable Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation variableUpsert | Create or update a single variable on a service or environment. | write | Account token | Current | |
Takes a VariableUpsertInput with projectId, environmentId, name, value, and an optional serviceId. By default this triggers a redeploy unless skipDeploys is set. Acts onvariable Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation variableCollectionUpsert | Create or update many variables at once on a service or environment. | write | Account token | Current | |
Takes a VariableCollectionUpsertInput. A replace option clears variables not in the set, and skipDeploys avoids the redeploy. Acts onvariable Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation variableDelete | Delete a single variable from a service or environment. | write | Account token | Current | |
Takes a VariableDeleteInput with projectId, environmentId, name, and an optional serviceId. Acts onvariable Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EnvironmentsList and read environments in a project, create one, and delete one.4 | ||||||
| POST | query environments | List the environments in a project, optionally filtering to ephemeral PR or preview environments. | read | Account token | Current | |
Takes projectId and an optional isEphemeral flag. Acts onenvironment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query environment | Read a single environment by id, with its service instances and their latest deployment. | read | Account token | Current | |
Takes the environment id. Acts onenvironment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation environmentCreate | Create an environment in a project, optionally cloning another environment. | write | Account token | Current | |
Takes an EnvironmentCreateInput with projectId and name, plus optional sourceEnvironmentId and ephemeral fields. Acts onenvironment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation environmentDelete | Delete an environment and all of its deployments. | write | Account token | Current | |
Takes the environment id. This permanently removes the environment and the deployments under it. Acts onenvironment Permission (capability) Account tokenVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Railway can notify an app or AI agent when something happens in a project, instead of the app repeatedly asking. Railway posts a JSON payload to a webhook URL set on the project when a deployment changes state or a usage alert fires.
| Event | What it signals | Triggered by |
|---|---|---|
Deployment status change | Fires when a deployment changes state, such as building, deploying, success, failed, or crashed. The payload carries a type like Deployment.failed, the deployment details, and the project, environment, and service it belongs to. | mutation serviceInstanceDeployV2mutation serviceInstanceRedeploymutation deploymentRedeploymutation deploymentStopmutation deploymentRollback |
Volume or resource usage alert | Fires when a volume approaches its capacity, or when CPU or memory usage crosses a configured threshold. | In-app only |
Railway limits how fast an app or AI agent can call, through an hourly request quota that depends on the account's plan, with the current state reported in response headers.
Railway meters requests per hour, and the ceiling depends on the account's plan rather than on the operation. The Free plan allows 100 requests per hour; Hobby allows 1,000 per hour and about 10 per second; Pro allows 10,000 per hour and about 50 per second; and Enterprise is custom. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to report the current state, and going over returns HTTP 429 with a Retry-After header.
List queries follow the GraphQL connection pattern, returning edges with a node, so a query like projects or environments is read through its edges. List inputs accept a first argument to cap how many records come back.
Requests and responses are JSON over a single GraphQL endpoint. There is no separate documented payload size limit; the practical constraint is the per-plan request rate.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | GraphQL errors array | A GraphQL request returns HTTP 200 even when an operation fails. A failure shows up as an errors array in the JSON body, each entry carrying a message that names what went wrong, like a misspelled field or a wrong type, alongside any data that did resolve. | Read the errors array rather than relying on the HTTP status, fix the field or type it names, and resend. |
| 401 | Unauthorized | The token is missing, invalid, or sent in the wrong header. Account, workspace, and OAuth tokens go in the Authorization header as a Bearer token, while a project token goes in the Project-Access-Token header. | Send a valid token in the header that matches its type. |
| 429 | Too Many Requests | The plan's hourly or per-second request limit was exceeded. The X-RateLimit-Remaining header reaches zero and a Retry-After header gives the wait. | Wait for the window to reset, guided by the Retry-After and X-RateLimit-Reset headers, then retry. |
Railway does not put a dated version on its GraphQL API. There is a single, continuously updated schema, served under the v2 path, and changes are tracked through the public API reference and changelog.
Railway does not put a dated version on its public API. There is a single GraphQL schema served under the v2 path at https://backboard.railway.com/graphql/v2, the same API that powers the dashboard, and it is updated continuously rather than cut into dated releases. The schema is explored live through introspection or the GraphiQL playground, and changes are tracked through the public API reference rather than version strings.
Railway added Infrastructure as Code, which describes projects, services, and environments declaratively, alongside Sandboxes. These run on the same schema the public API exposes, so the same projects, services, and environments are reachable through GraphQL.
Railway shipped a hosted remote MCP server at mcp.railway.com, signed in through OAuth in the browser, plus a Railway Agent in the CLI. Both drive the same GraphQL API underneath through the Model Context Protocol.
Railway introduced its first-party MCP server, letting an agent drive Railway through the Model Context Protocol against the same GraphQL API the dashboard uses.
Railway's public GraphQL API moved from preview to generally available, opening the same API that powers the dashboard for projects, services, deployments, environments, and variables.
The schema can be explored live through introspection and the GraphiQL playground.
Railway API reference ↗Bollard AI sits between a team's AI agents and Railway. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.