railway

Troubleshooting

If requests fail, run zero doctor check-connector --env-name RAILWAY_TOKEN or zero doctor check-connector --url https://backboard.railway.com/graphql/v2 --method POST.

Authentication

Railway exposes a single GraphQL endpoint. Requests authenticate with an account or workspace token (use this skill) sent as a Bearer header:

Authorization: Bearer $RAILWAY_TOKEN

Account tokens span every workspace the user belongs to. Workspace tokens are scoped to a single workspace but expose the same query/mutation surface. For environment-scoped automation use the separate railway-project skill instead — it sends Project-Access-Token and has different scope rules.

Environment Variables

Variable	Description
RAILWAY_TOKEN	Railway account or workspace token (UUID v4 format)

Base URL

https://backboard.railway.com/graphql/v2 — every operation is a POST to this single endpoint.

Official docs: https://docs.railway.com/reference/public-api

Patterns

• Every request is a POST with a JSON body of the form { "query": "...", "variables": { ... } }.
• Write the body to /tmp/railway_request.json and reference it with -d @/tmp/railway_request.json. Never inline GraphQL strings with shell escaping.
• Railway's connection types use edges { node { ... } } cursor pagination.
• When you do not know the exact field name, run an introspection query first instead of guessing.

Verify Authentication

Write to /tmp/railway_request.json:

{
  "query": "query { me { id name email } }"
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Discover the Schema

Use introspection to look up exact field names, argument types, and enum values before composing a real query.

Write to /tmp/railway_request.json:

{
  "query": "query Introspect($name: String!) { __type(name: $name) { name fields { name description args { name type { name kind ofType { name kind } } } type { name kind ofType { name kind } } } } }",
  "variables": { "name": "Query" }
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Re-run with "name": "Mutation", "name": "Project", "name": "Service", etc. to drill into specific types.

Projects

List Projects

Write to /tmp/railway_request.json:

{
  "query": "query { projects { edges { node { id name description createdAt } } } }"
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Get a Project (with services and environments)

Replace <project-id> with the actual project ID:

Write to /tmp/railway_request.json:

{
  "query": "query GetProject($id: String!) { project(id: $id) { id name description services { edges { node { id name } } } environments { edges { node { id name } } } } }",
  "variables": { "id": "<project-id>" }
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Deployments

List Deployments for a Service

Replace <project-id>, <environment-id>, and <service-id> with the actual IDs returned by the project query above:

Write to /tmp/railway_request.json:

{
  "query": "query Deployments($input: DeploymentListInput!) { deployments(first: 20, input: $input) { edges { node { id status createdAt staticUrl meta } } } }",
  "variables": {
    "input": {
      "projectId": "<project-id>",
      "environmentId": "<environment-id>",
      "serviceId": "<service-id>"
    }
  }
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Redeploy a Deployment

Replace <deployment-id> with the deployment to redeploy:

Write to /tmp/railway_request.json:

{
  "query": "mutation Redeploy($id: String!) { deploymentRedeploy(id: $id) { id status } }",
  "variables": { "id": "<deployment-id>" }
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Trigger a New Deployment from Latest

Replace <service-id> and <environment-id>:

Write to /tmp/railway_request.json:

{
  "query": "mutation Trigger($serviceId: String!, $environmentId: String!) { serviceInstanceDeployV2(serviceId: $serviceId, environmentId: $environmentId) }",
  "variables": {
    "serviceId": "<service-id>",
    "environmentId": "<environment-id>"
  }
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Variables

Read Variables for a Service Environment

Write to /tmp/railway_request.json:

{
  "query": "query Variables($projectId: String!, $environmentId: String!, $serviceId: String!) { variables(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId) }",
  "variables": {
    "projectId": "<project-id>",
    "environmentId": "<environment-id>",
    "serviceId": "<service-id>"
  }
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Upsert a Variable

Write to /tmp/railway_request.json:

{
  "query": "mutation Upsert($input: VariableUpsertInput!) { variableUpsert(input: $input) }",
  "variables": {
    "input": {
      "projectId": "<project-id>",
      "environmentId": "<environment-id>",
      "serviceId": "<service-id>",
      "name": "FEATURE_FLAG",
      "value": "enabled"
    }
  }
}

curl -s -X POST "https://backboard.railway.com/graphql/v2" --header "Authorization: Bearer $RAILWAY_TOKEN" --header "Content-Type: application/json" -d @/tmp/railway_request.json

Guidelines

1. Always do an introspection query for the relevant type before building a new query — the schema evolves and Railway does not version its API.
2. Read mutations and queries return Railway-defined error objects in the top-level errors array; always parse and surface them rather than assuming a 200 status means success.
3. Token leak risk: never echo $RAILWAY_TOKEN into logs, files, or shell output.
4. For tighter blast radius on automation that only touches one project/environment, use the railway-project skill instead — its token is scoped and revokable per project.