api
API Overview
Introduction to the Runix REST API, authentication, and response format.
REST API#
The Runix API lets you manage deployments, environment variables, domains, and projects programmatically. Every action available in the dashboard and CLI is also available through the API.
Base URL#
https://api.runix.devAll endpoints are relative to this base URL. For example, listing deployments is a GET request to https://api.runix.dev/deployments.
Authentication#
All API requests (except auth endpoints) require a Bearer token in the Authorization header.
Authenticated request
curl https://api.runix.dev/deployments \
-H "Authorization: Bearer YOUR_TOKEN"Getting your token#
There are two ways to get an API token:
From the CLI (recommended)
Log in with the CLI, then find your token in the credentials file.
runix login
cat ~/.config/runix/credentials.jsonCreate a CLI token via the API
If you already have a session token (from GitHub OAuth or email login), you can create a long-lived CLI token.
curl -X POST https://api.runix.dev/auth/cli-token \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"Response format#
All responses are JSON. Successful responses return the data directly. Error responses have this shape:
Error response
{
"error": "Deployment not found",
"code": "NOT_FOUND"
}| Status code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad request — check your parameters |
| 401 | Unauthorized — missing or invalid token |
| 403 | Forbidden — you don't have access to this resource |
| 404 | Not found |
| 409 | Conflict — resource already exists |
| 429 | Rate limited — slow down |
| 500 | Server error — try again or contact support |
Rate limits#
API requests are rate-limited per account. The default limit is 100 requests per minute. If you exceed this, you will receive a 429 response. The Retry-After header tells you how many seconds to wait.
Deploy-related endpoints have separate, stricter rate limits based on your plan (e.g., 5 deploys/hour on Hobby). Check the Billing page for details.