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. You can create one by visiting the tokens page in your account settings. There are two types of tokens you can create.
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
- Cannot be used to access your personal resources on Railway
Note that Teams are a Pro feature.
Personal 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. Do not share this token with anyone else.
Project Token
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. 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 } }"}'
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.
The Network Tab
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.
Examples
To help you get started, we have provided some example queries in the guides within this section -
Support
If you run into problems using the API or have any suggestions, feel free to join our Discord server where you can interact with the engineers working on the API directly.
Rate Limits
Rate limits are enforced on the Public API. For details on the limits visit the Public API reference page.
Edit this file on GitHub