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:

Authorization: Bearer <token>

Team-Access-Token: <token>

Project-Access-Token: <token>

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

1. SKILL.md (this file): Quick reference and common operations
2. 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
3. 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:

1. Always check for

   errors

   field in response
2. Use appropriate token type for operation scope
3. Handle rate limiting (429 responses)
4. Validate input before mutations
5. 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/

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

1. Start: Read

   references/graphql-endpoint.md

   for endpoint details
2. Authentication: Study

   references/authentication.md

   for token setup
3. Queries: Explore

   references/common-queries.md

   for data retrieval
4. Mutations: Review

   references/common-mutations.md

   for operations
5. Automation: Use scripts in

   scripts/

   for workflow examples
6. 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