Public API
Published
Updated
🔌
Talk to the platform directly.
The fortrabbit public API is a REST interface to manage apps, environments, deployments and domains. It authenticates with a personal API token and is the foundation for the CLI.
Use cases
- Building an integration, a bot, or a custom dashboard
- A capability is missing from the CLI and the MCP server
- A credential is needed that does not expire or require a browser
API reference docs
The full endpoint reference is generated from the API itself and lives at:
- api.fortrabbit.com/v1/docs
- OpenAPI description, for code generators and agents: api.fortrabbit.com/v1/docs.jsonopenapi
Entry point
All endpoints sit under a single base URL:
https://api.fortrabbit.com/v1
Send Accept: application/json on every request. Without it the API answers in JSON-LD, which carries extra @-prefixed metadata most clients do not expect.
Authentication
The API authenticates with a personal API token. A token acts as the person who created it and sees what that person sees in the dashboard. Tokens are managed in the dashboard, under API tokens in the account menu. The CLI authenticates with an OAuth token instead, issued by frbit auth login. Both go in the same header. Pass the token as a bearer token on every request:
curl https://api.fortrabbit.com/v1/apps \
-H "Authorization: Bearer frbit-at-YOUR-TOKEN" \
-H "Accept: application/json"
Create a token
The token is created in the dashboard in three steps:
- A name to recognize it later
- The permissions it gets
- The token itself you should copy
The full token is shown once, on the final step of that flow, and cannot be retrieved later. Copy it before leaving the page. A lost token cannot be recovered — delete it and create a new one.
Token permissions
Permissions limit which HTTP methods a token may send. Choose the smallest set that covers the job:
| Permission | Allowed methods |
|---|---|
| Read | GET |
| Read and write | GET, POST, PUT, PATCH |
| Read, write and delete | GET, POST, PUT, PATCH, DELETE |
Read is preselected. Permissions cannot be changed later — create a new token and delete the old one instead. A request with a method the token does not cover answers 403, with a message naming the method. Restoring a backup is a POST, but it overwrites data, so it needs Read, write and delete. The same goes for switching a component off.
Which apps and environments a token reaches still follows the access of the person who created it. Tokens created before permissions were introduced kept full access.
frbit CLI tokens
A token from frbit auth login can read and write. It can delete only when Allow deletes was ticked when approving the connection. That covers every DELETE, restoring a backup and switching a component off. Without it, these requests answer 403 and ask to run frbit auth login again. The connection ends one year after approval, or after 30 days without use, whichever comes first. See CLI authentication.
List and delete tokens
Tokens for the account are listed in the dashboard, with name, permissions, a preview of the last characters and the date it was created.
Tokens do not expire. Delete the ones that are no longer in use — Delete next to a token in that listing, then confirm. Deleting takes effect immediately: requests carrying that token are rejected from then on, while every other token of the account keeps working.
API coverage
| Resource | Path |
|---|---|
| Own account | /v1/you |
| Apps | /v1/apps, /v1/apps/{id}/git-repository |
| Environments | /v1/environments, /v1/environments/{id}/restart |
| Components | /v1/environments/{id}/components |
| Variables | /v1/environments/{id}/environment-variables |
| Settings | /v1/environments/{id}/php-settings, /v1/environments/{id}/mysql, /v1/environments/{id}/basic-auth |
| Firewall rules | /v1/environments/{id}/firewall-rules, /v1/firewall-rules |
| Jobs | /v1/environments/{id}/jobs, /v1/jobs, /v1/jobs/check-cron |
| Backups | /v1/environments/{id}/backups, /v1/backups/{id}/restore, /v1/backups/{id}/download/{type} |
| Deployments | /v1/deployments, /v1/deployments/{id}/logs, /v1/environments/{id}/deployments |
| Logs and metrics | /v1/environments/{id}/logs, /v1/environments/{id}/metrics, /v1/environments/{id}/metrics/{metric} |
| Domains | /v1/domains, /v1/domains/{id}/dns, /v1/environments/{id}/main-domain |
| Teams | /v1/teams |
| People | /v1/people |
| Payment methods | /v1/payment-methods |
| Catalog, no token | /v1/catalog/* |
Objects are addressed by their public ID — the same short ap-, en-, do- identifiers the dashboard shows. Collections accept a repeated publicId[] parameter to fetch several known objects in one call.
Requests and responses
Pagination
Lists of apps, environments, domains, deployments, teams and payment methods come in pages of 30, selected with ?page=. Every page carries two headers:
X-Total-Count: the number of items in the whole listLink: the URLs of the first, previous, next and last page
Unknown fields
A write with a field the endpoint does not know answers 422 and names the field. A typo in a field name fails instead of being ignored.
Retries
Every POST accepts an Idempotency-Key header with a unique value of up to 255 characters. A retry with the same key and the same request returns the first response again, marked with Idempotent-Replayed: true, and does not run twice:
curl -X POST https://api.fortrabbit.com/v1/environments/en-abc123/restart \
-H "Authorization: Bearer frbit-at-YOUR-TOKEN" \
-H "Accept: application/json" \
-H "Idempotency-Key: 7f3c9a1e-restart-1"
- The same key with a different request answers
422. - The same key while the first request still runs answers
409. - Responses are kept for 24 hours.
Errors
Errors answer with Content-Type: application/problem+json:
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "This API token has no scope permitting DELETE requests.",
"error": "This API token has no scope permitting DELETE requests."
}
- The fields follow RFC 9457.
typeis alwaysabout:blank,titleis the HTTP status phrase,detailsays what went wrong. errorrepeatsdetail, for older clients and scripts.
| Status | Meaning |
|---|---|
400 | The body is not valid JSON. |
403 | The resource is visible to you, but the token permissions or your team role do not allow the request. |
404 | The ID is unknown, or the resource is outside your access. Both answer the same, so IDs of others stay hidden. |
422 | The input is invalid. violations lists each propertyPath with its message, errors keeps the older field map. |
429 | The rate limit is used up. |
Prices before creating
POST /v1/apps and POST /v1/environments return the monthly price of the new environment, in cents, with the currency. With "dryRun": true in the body they run every check and return only the price, without creating anything.
Catalog
The catalog lists what the create endpoints choose from: regions, component plans with prices, software presets, PHP and Node.js versions, PHP extensions and PHP settings. It lives under /v1/catalog/ and needs no token:
curl https://api.fortrabbit.com/v1/catalog/component-plans?currency=USD \
-H "Accept: application/json"
Catalog responses may be cached for an hour.
Rate limits
Requests are counted per token in a sliding window of one minute. A frbit CLI connection counts as one token: its tokens renew while it runs, and they share one budget. Every response carries the limit in X-RateLimit-Limit, with X-RateLimit-Remaining and X-RateLimit-Reset; a rejected request answers 429 and adds Retry-After with the seconds to wait. The catalog without a token has its own limit, per IP address. Failed authentications are counted separately, per IP address. Retrying a rejected credential in a loop locks the address out rather than the token.
Stability
The API is in BETA like the whole platform. Breaking changes are possible while that lasts, though not planned. The /v1 prefix marks the version of the API.