Railway API

Comprehensive reference for Railway.com GraphQL API v2 automation including authentication, queries, mutations, and workflow automation.

Overview

The Railway GraphQL API enables programmatic access to all Railway platform features:

Project and service management
Environment variable configuration
Deployment triggering and monitoring
Team and resource management
Usage and billing queries

API Endpoint: https://backboard.railway.com/graphql/v2

Quick Start

1. Authentication Setup

Railway supports three token types with different scopes:

Token Type	Header	Scope	Use Case
Account	`Authorization: Bearer <token>`	All user resources	Personal automation
Team	`Team-Access-Token: <token>`	Team-specific resources	Team workflows
Project	`Project-Access-Token: <token>`	Single project only	CI/CD, project automation

Get tokens: Use the railway-auth skill or Railway dashboard → Account Settings → Tokens

2. Basic Query Example

curl https://backboard.railway.com/graphql/v2 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { me { name email } }"}'

3. Basic Mutation Example

curl https://backboard.railway.com/graphql/v2 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: VariableUpsertInput!) { variableUpsert(input: $input) }",
    "variables": {
      "input": {
        "projectId": "project-id",
        "environmentId": "env-id",
        "name": "API_KEY",
        "value": "secret-value"
      }
    }
  }'

Common Operations

User & Account Information

query {
  me {
    id
    name
    email
    avatar
    isAdmin
  }
}

List Projects

query {
  projects {
    edges {
      node {
        id
        name
        description
        createdAt
        updatedAt
      }
    }
  }
}

Get Project Details with Services

query GetProject($projectId: String!) {
  project(id: $projectId) {
    id
    name
    description
    services {
      edges {
        node {
          id
          name
          serviceInstances {
            edges {
              node {
                id
                environmentId
                serviceId
              }
            }
          }
        }
      }
    }
    environments {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Get Environment Variables

query GetVariables($projectId: String!, $environmentId: String!) {
  variables(projectId: $projectId, environmentId: $environmentId) {
    edges {
      node {
        name
        value
      }
    }
  }
}

Set/Update Variable

mutation SetVariable($input: VariableUpsertInput!) {
  variableUpsert(input: $input)
}

# Variables:
{
  "input": {
    "projectId": "your-project-id",
    "environmentId": "your-env-id",
    "name": "DATABASE_URL",
    "value": "postgresql://..."
  }
}

Trigger Deployment

mutation TriggerDeployment($serviceId: String!, $environmentId: String!) {
  deploymentTrigger(serviceId: $serviceId, environmentId: $environmentId) {
    id
    status
    createdAt
  }
}

Architecture

Progressive Disclosure Structure

SKILL.md (this file): Quick reference and common operations
references/: Detailed documentation
- graphql-endpoint.md - Complete API endpoint documentation
- authentication.md - Comprehensive authentication guide
- common-queries.md - 15+ query examples with responses
- common-mutations.md - 15+ mutation examples with patterns
scripts/: Automation tools
- query-project.py - Python script for querying Railway API
- set-variables.ts - TypeScript script for variable management

Error Handling

Railway API returns errors in this format:

{
  "errors": [
    {
      "message": "Error message",
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

Common errors:

UNAUTHORIZED - Invalid or expired token
FORBIDDEN - Insufficient permissions for resource
NOT_FOUND - Resource doesn't exist
VALIDATION_ERROR - Invalid input data

Best practices:

Always check for errors field in response
Use appropriate token type for operation scope
Handle rate limiting (429 responses)
Validate input before mutations
Use variables for parameterized queries

Integration Patterns

CI/CD Pipeline

# Get project token from railway-auth
# Set deployment variables
# Trigger deployment
# Monitor deployment status

See scripts/ for complete automation examples.

Infrastructure as Code

// Define Railway resources in code
// Apply changes via GraphQL mutations
// Track state and changes

Monitoring & Alerts

# Query deployment status
# Check resource usage
# Alert on failures

Cross-References

railway-auth: Token generation and management
railway-deployment: High-level deployment workflows
railway-troubleshooting: API error debugging

Learning Path

Start: Read references/graphql-endpoint.md for endpoint details
Authentication: Study references/authentication.md for token setup
Queries: Explore references/common-queries.md for data retrieval
Mutations: Review references/common-mutations.md for operations
Automation: Use scripts in scripts/ for workflow examples
Advanced: Combine patterns for complex automation

Quick Reference

Essential Queries

Get user info: query { me { name email } }
List projects: query { projects { edges { node { id name } } } }
Get variables: Use variables query with projectId and environmentId
Deployment status: Query deployments with filters

Essential Mutations

Set variable: variableUpsert mutation
Trigger deploy: deploymentTrigger mutation
Create service: serviceCreate mutation
Delete variable: variableDelete mutation

Rate Limits

Account tokens: 100 requests/minute
Team tokens: 500 requests/minute
Project tokens: 1000 requests/minute

Notes

All timestamps are in ISO 8601 format (UTC)
IDs are opaque strings, don't parse or construct them
Pagination uses cursor-based edges/nodes pattern
Use GraphQL variables for all dynamic values
Production mutations should use Project tokens for security

Known API Limitations

Some GraphQL queries return "Problem processing request" even with valid tokens. This is a Railway API limitation, not a token issue.

Affected queries: deployment(id:), deploymentLogs, buildLogs, me.teams, teams

Workaround: Use Railway CLI for these operations:

railway list --json     # Projects/teams
railway logs            # Deployment/build logs

See api-limitations.md for full details.

References

common-queries.md - 31 query examples
common-mutations.md - 37 mutation examples
api-limitations.md - Known limitations and workarounds
authentication.md - Token types and headers
graphql-endpoint.md - Endpoint details

Resources

Railway API Documentation: https://docs.railway.com/reference/public-api
GraphQL Explorer: https://backboard.railway.com/graphql/v2 (with GraphiQL)
Token Management: Use railway-auth skill

railway-api