Public API Reference
The Railway public API is built with GraphQL and is the same API that powers the Railway dashboard.
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
Endpoint
The Railway API supports introspection meaning you can use popular tools like Postman or Insomnia to query the schema.
GraphiQL Playground
Alternatively, you can use our GraphiQL playground to view the schema and test your queries.
Authentication
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
If you select a Team
in the dropdown in the image above, the token will be tied to that team and will have access to all the team's resources. This token cannot be used to access your personal resources on Railway so feel free to share it with your teammates.
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.
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:
Rate Limits
In order to protect the Railway API from spam and misusage, we have established some basic rate limits. The current limit is 1000 requests per hour to the API. To help you keep track of your usage, Railway sends a few headers with the response on each request.
Header | Description |
---|---|
X-RateLimit-Limit | The maximum number of API requests allowed per day. |
X-RateLimit-Remaining | The number of API requests your token can make in the current window. |
X-RateLimit-Reset | The time at which the current window ends and your remaining requests reset. |
Retry-After | The amount of time after which you can make another request. This header is only sent once you've used up all your requests in the current window. |
Examples
To help you get started, here are a few examples for reference.
Projects
Fetch all your projects
The query below will fetch all your personal projects along with all the services, plugins and environment for them.
Delete a project
The mutation below will delete the project with the specified id
.
Plugins
Add a plugin to a project
The mutation below will add the redis
plugin to the specified project. The response will contain all the fields from the newly created plugin.
Services
Create a new service with a GitHub repo
The mutation below will create a new service with the specified GitHub repo attached. The response will contain the newly created service.
Deployments
Fetch latest active deployment
The query below will fetch the latest active deployment for a service for a specific environment.
Restarting a deployment
The query below will restart the deployment with the specified id
.
Variables
Fetch variables for a service
The query below will fetch all the variables for a service for a specific environment. The response will contain all the variables in a key/value object.
Upsert variable for a service
The mutation below will upsert a new variable for the specified service within the specified environment. You can use this to both create and update variables.
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.
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.
Edit this file on GitHub