Getting Started

Belune has an API behind every screen in the dashboard. A personal access token authenticates as you, scoped to whatever you chose when you created it, for CI, monitoring, and anything else that isn't a person clicking around.

Authenticating

Send the token as a bearer credential, in the header only:

curl -H "Authorization: Bearer belune_pat_..." \
  https://belune.example.com/api/projects

Scopes

Every token gets one scope, chosen at creation. The four form a ladder, and each one includes everything narrower than it, so a token only ever needs the rung that matches what it's for, not a combination:

A token's reach also follows its owner: it can see and do whatever the owner's role and project access already allow, narrowed further by scope. A Member's read token only reaches the projects that Member can reach — shared or owned.

Project-Pinning

By default a token reaches every project its owner can. Pinning it to one or more projects at creation narrows that further: every project outside the pin returns 403, including ones the owner could otherwise reach.

Create a pinned token from Account → Personal Access Tokens → Create token, choosing one or more projects from the picker instead of leaving it on "All projects." The picker only ever offers projects you can already reach — a Member sees their own and any shared with them — because pinning can only narrow a token below what its owner already has. It can never grant reach the owner doesn't independently have; that boundary is enforced at every request, not just at creation.

Pinning has no representation in the OpenAPI spec — see The Endpoint Reference below — so this section is the only place it's documented; every affected operation's own description just notes that it rejects a project outside a pinned token's pin set.

What a Token Can Never Do

Six things stay behind a live dashboard session no matter what scope a token carries. This is deliberate, as a leaked token should be a bad day, not a catastrophe.

• Delete or restore resources. Every project, application, database, domain, volume, and backup delete or restore, plus orphaned-backup cleanup — rejects a token outright.
• Read a stored secret. Database connection credentials, deploy-hook tokens, webhook secrets, environment variable values, and file mount contents are all decrypted on demand and returned as plaintext — never to a token, even at write scope.
• Manage tokens or users. Minting or revoking a personal access token, and creating, inviting, deleting, changing the role of, or resetting the password or two-factor authentication of any user, all require a session.
• Manage your own account, or enumerate your tokens. Changing your password or profile, logging out, and enrolling, disabling, or checking the status of two-factor authentication and regenerating recovery codes all require a session — a token manages infrastructure, not the account it belongs to. Listing your own tokens joins them: read-only, but the list includes every token's scopes and last-used time, which is a credential inventory a leaked token could use to find the one that holds write.
• Open a terminal. Both starting a container exec session and the WebSocket tunnel it uses reject a token.
• Read or change platform configuration. Listing or updating instance settings, the SMTP configuration, restarting a service, and opening a host shell all require a session. A token should never be able to reach that switch, even though actually opening a shell from there still needs the password, and a second factor if one is enrolled.

Each of these returns 403 with {"error": "this action requires a session, not a personal access token"} — a different message from a plain scope mismatch, so a script can tell "wrong scope, mint a wider token" apart from "no token reaches this, ever."

Limits and Errors

• 100 requests a minute per token, not per user. A token minted for one integration has its own budget, separate from your login session and from any other token on the account. Going over returns 429 as plain text, with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so a client can back off before hitting it rather than after.
• Every other error is {"error": "<message>"}, with a status code that means what it says: 401 for a missing, invalid, or expired token, 403 for a scope or session boundary (see above), 404 for something that doesn't exist or isn't yours to see. Refer more on HTTP Response Codes.

The Endpoint Reference

Every token-callable endpoint is in the sidebar, grouped by resource. Routes that always require a live dashboard session aren't listed there, see What a Token Can Never Do for that boundary.

Two things are deliberately absent rather than guessed at.

• required is omitted from every request schema: field optionality here is enforced imperatively, not encoded in the types, and inferring it from validation code would be far fuzzier than the static resolution the rest of the spec rests on.
• Project-pinning — a project outside a pinned token's pin set being rejected — has no OpenAPI representation at all, so it is called out in the description of each affected operation instead.

Common Tasks

Every example below assumes BELUNE_TOKEN is a token with at least read scope (deploy for the one that triggers a deploy), and real ids in place of $PROJECT_ID/$APP_ID.

List Projects and Applications

curl -H "Authorization: Bearer $BELUNE_TOKEN" \
  https://belune.example.com/api/projects | jq '.[] | {id, name, slug}'

curl -H "Authorization: Bearer $BELUNE_TOKEN" \
  https://belune.example.com/api/projects/$PROJECT_ID/applications \
  | jq '.[] | {id, name, status}'

Check Application and Deployment Status

curl -H "Authorization: Bearer $BELUNE_TOKEN" \
  https://belune.example.com/api/projects/$PROJECT_ID/applications/$APP_ID \
  | jq '{status}'

curl -H "Authorization: Bearer $BELUNE_TOKEN" \
  https://belune.example.com/api/projects/$PROJECT_ID/applications/$APP_ID/deployments \
  | jq '.[0] | {id, status, started_at, finished_at}'

A deployment moves through pending → building → deploying → success (or failed at any step) — see Deployments for what each stage means.

Trigger a Deploy

curl -X POST -H "Authorization: Bearer $BELUNE_TOKEN" \
  https://belune.example.com/api/projects/$PROJECT_ID/applications/$APP_ID/deploy

Needs deploy scope or wider. Returns 202 with the new deployment record immediately — the build and rollout happen after the response, so poll the deployments endpoint above, or tail logs below, to see it through.

Tail Logs

curl -N -H "Authorization: Bearer $BELUNE_TOKEN" \
  https://belune.example.com/api/projects/$PROJECT_ID/applications/$APP_ID/logs

Streams as Server-Sent Events; -N turns off curl's output buffering so lines print as they arrive. For a bounded page of history instead of a live tail, use .../logs/history.

List Backups

curl -H "Authorization: Bearer $BELUNE_TOKEN" \
  https://belune.example.com/api/projects/$PROJECT_ID/backups \
  | jq '.[] | {id, status, started_at, size_bytes}'

Covers every database in the project. read scope reaches this; starting a new backup needs write. Restoring one needs a live session — no scope lets a token do it, per above.

Regenerating API Docs

After add or modify API entrypoints, run this command to generate the docs:

task generate:api-docs

It runs against a disposable database, and nothing it does touches a real install.