REST API

Everything the CLI does goes through a documented REST API that you can call yourself. It follows the same rules as the dashboard: a token can never do more than the person who created it, and it works inside one team only.

The reference on your dashboardCopy Anchor Link

Your launchroom serves the full interactive reference at /docs/api on your dashboard (for example https://launchroom.example.com/docs/api) once you're signed in: every operation with its ability, parameters, request and response schemas, and a copyable curl. The raw OpenAPI 3.1 document is public at /api/v1/openapi.json. This page covers what you need to get started.

TokensCopy Anchor Link

Create a token under Settings → API tokens (in the You group) with Create token. Creating a token asks for your password.

• One team. A token acts as you inside the team that was current when you created it. Everything in your other teams answers 404, as if it didn't exist.
• Abilities narrow what the token can do. The effective rights are your role in the team and the token's abilities, whichever is less.
• Expiry is mandatory: 7 days, 30 days, 90 days or 1 year.
• Shown once. Copy the token when it's shown. launchroom only keeps a hash. Tokens look like <id>|lr_pat_….
• The token list shows when and from which IP each token was last used, and warns when one expires within 7 days. Revoke ends a token at once.
• Removing someone from the team deletes their tokens for that team.

AbilitiesCopy Anchor Link

deploy, env:read and env:write are ticked by default. secrets:read and data:transfer are opt-in and only work for owners and admins. No token can manage servers, members, the team, backup settings or Console and Data sessions.

Actions taken with a token appear in the audit log like the same action in the dashboard, marked as done through that token.

BasicsCopy Anchor Link

Check your token and see what it can do:

curl -s https://launchroom.example.com/api/v1/me \
  -H "Authorization: Bearer $LAUNCHROOM_TOKEN"

ErrorsCopy Anchor Link

Every error has the same shape:

{
  "error": {
    "code": "missing_ability",
    "message": "…",
    "ability": "deploy"
  }
}

Validation errors add fields with messages per field.

Rate limitsCopy Anchor Link

Responses carry X-RateLimit-* headers.

IdempotencyCopy Anchor Link

Creating requests (deployments, deploys of staged changes, variables, domains, rollbacks, redeploys) accept an Idempotency-Key header: 1 to 255 characters of letters, digits and _ . : -. Use it in CI so that a retried request never deploys twice:

• The same key with the same request within 24 hours returns the stored response, with Idempotent-Replayed: true.
• The same key with a different request is refused with 422 idempotency_key_reused.
• A retry while the first request still runs gets 409 idempotency_key_in_progress.
• Server errors (5xx) are not stored, so retrying them is safe.

Deploy a service at a specific commit:

curl -s -X POST https://launchroom.example.com/api/v1/environments/$ENV_ID/deployments \
  -H "Authorization: Bearer $LAUNCHROOM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-$GITHUB_RUN_ID" \
  -d '{"service": "'"$SERVICE_ID"'", "sha": "'"$GITHUB_SHA"'"}'

The body takes service and one of sha (a full 40-character commit), ref (a branch, main or refs/heads/main) or redeploy: true. Without any of them, the head of the service's tracked branch is deployed. The deployment uses the environment's last applied configuration, the same as a push. Staged changes stay staged. The answer is 202 with the deployment, including its status and dashboardUrl. Poll GET /deployments/{deployment} until finished is true, or follow its logs.

To apply an environment's staged changes instead, POST /environments/{environment}/deploy with an optional message.

Follow logsCopy Anchor Link

Logs stream as server-sent events. A deployment's stream runs until the deployment finishes:

curl -sN https://launchroom.example.com/api/v1/deployments/$DEPLOYMENT_ID/logs/stream \
  -H "Authorization: Bearer $LAUNCHROOM_TOKEN"

A : ping comment arrives every 15 seconds. GET /environments/{environment}/logs/stream follows the runtime logs of a whole environment the same way, like Live in the Logs explorer, and GET /environments/{environment}/logs runs a search with range (15m, 1h, 24h, 7d, 30d), source (all, runtime, build), service and q.

What the API coversCopy Anchor Link

Secret values never appear in lists. They come back as null. Reading one needs secrets:read and is audited.