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:

Entry point

All endpoints sit under a single base URL:

https://api.fortrabbit.com/v1
text

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"
shell

Create a token

The token is created in the dashboard in three steps:

  1. A name to recognize it later
  2. The permissions it gets
  3. 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:

PermissionAllowed methods
ReadGET
Read and writeGET, POST, PUT, PATCH
Read, write and deleteGET, 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

ResourcePath
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 list
  • Link: 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"
shell
  • 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."
}
json
  • The fields follow RFC 9457. type is always about:blank, title is the HTTP status phrase, detail says what went wrong.
  • error repeats detail, for older clients and scripts.
StatusMeaning
400The body is not valid JSON.
403The resource is visible to you, but the token permissions or your team role do not allow the request.
404The ID is unknown, or the resource is outside your access. Both answer the same, so IDs of others stay hidden.
422The input is invalid. violations lists each propertyPath with its message, errors keeps the older field map.
429The 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"
shell

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.

Written by humans and AI in collaboration.

AI use & editorial processEdit on GitHub ↗