Use the Public API

The Railway public API is built with GraphQL and is the same API that powers the Railway dashboard.

Use the Public API to integrate Railway into your CI/CD pipelines and other workflows.

Understanding GraphQL

If you haven't used GraphQL before, here are a few resources to get started:

The official Introduction to GraphQL
The GraphQL Basics course by Hasura
GraphQL is the better REST to understand how it is different from a REST API

Connecting to the Public API

To connect to and query the Public API, you will need the endpoint URL and a token for authentication.

Endpoint

The public API is accessible at the following endpoint:

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

Creating a Token

To use the API, you will need an API token. There are three types of tokens you can create.

Team Tokens and Account Tokens

You can create an API token from the tokens page in your account settings.

Team token - Select a team in the Team dropdown to create a token tied to a team. A team token has access to all the team's resources, and cannot be used to access your personal resources on Railway. Feel free to share this token with your teammates.
Account token - If you do not select a team, the token will be tied to your Railway account and will have access to all your resources including the teams you are a part of. Do not share this token with anyone else.

Note that Teams are a Pro feature.

Project Token

You can create a project token from the tokens page in your project settings.

Project tokens are scoped to a specific environment within a project and can only be used to authenticate requests to that environment.

Execute a Test Query

Once you have your token, you can pass it within the Authorization header of your request.

Using an Account Token

You can try the query below in the terminal of your choice. It should return your name and email on Railway:

curl --request POST \
  --url https://backboard.railway.com/graphql/v2 \
  --header 'Authorization: Bearer <API_TOKEN_GOES_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { me { name email } }"}'

Note: This query cannot be used with a team or project token because the data returned is scoped to your personal account.

Using a Team Token

If you have a team token, you can use it to authenticate requests to a specific team. The query below should return the team name and ID:

curl --request POST \
  --url https://backboard.railway.com/graphql/v2 \
  --header 'Team-Access-Token: <TEAM_TOKEN_GOES_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { team(id: \"<TEAM_ID_GOES_HERE>\") { name id } }"}'

Note: This query can also be used with an account token as long as you are a member of the team.

Using a Project Token

If you have a project token, you can use it to authenticate requests to a specific environment within a project. The query below should return the project and environment IDs:

curl --request POST \
  --url https://backboard.railway.com/graphql/v2 \
  --header 'Project-Access-Token: <PROJECT_TOKEN_GOES_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { projectToken { projectId environmentId } }"}'

Viewing the Schema

Use popular tools like Postman or Insomnia to connect to the API and query the schema. Simply set up your connection with the endpoint and Authorization token, and fetch the schema.

API Collection File

We also provide a collection file which can be imported into your preferred API client. Click here to download it.

Once imported, you should only need to add your API token to get connected and start executing queries in the collection.

GraphiQL Playground

Alternatively, you can use our GraphiQL playground to view the schema and test your queries.

Make sure to set an Authorization header with an auth token. Click the "Headers" tab at the bottom of the GraphiQL page and enter this json, using your own token:

{"Authorization": "Bearer <API_TOKEN_GOES_HERE>"}

Tips and Tricks

Resource IDs

While building your queries, if you quickly need to copy resource IDs, you can hit Cmd/Ctrl + K within your project and copy the project/service/environment ID.

If you're unsure about what query/mutation to use for what you are trying to achieve, you can always do the action in the dashboard and look for the request in the network tab. As we use the same API internally, you can simply grab the name and then look for specific query in the introspected schema.

External Resources

The awesome-graphql repository is a great resource for all things GraphQL with implementations available across a variety of languages.
The GraphQL Discord is the official Discord channel for graphql.org with a lot of active members and specific help channels.

Manage Projects

Edit this file on GitHub

Overview

Guides

Tutorials

Reference

Maturity

Migration

Community