Borealis Docs

Borealis public API

Use the versioned HTTP API to create sandboxes, run commands, and manage your workloads from your own applications.

Base URL and authentication

The production base URL is https://api.borealishq.io/api/v1. Send an OAuth access token issued for the Borealis API in the Authorization: Bearer header.

For an organisation-specific request, supply X-Organization-Id with an organisation you are authorised to access. This selects context; it does not grant membership or permissions.

For example, with a token already supplied securely in your environment:

curl --fail-with-body \
  --header "Authorization: Bearer $BOREALIS_ACCESS_TOKEN" \
  'https://api.borealishq.io/api/v1/sandboxes?page=1&pageSize=50'

Never commit the token or include it in shared logs.

Create a sandbox

Send POST /api/v1/sandboxes with Content-Type: application/json, your authorisation header, and an Idempotency-Key containing a non-empty UUID. Persist that key for the logical creation attempt.

{
  "name": "api-demo",
  "image": "ubuntu:24.04",
  "command": "sleep",
  "args": ["infinity"],
  "resourceProfile": {
    "cpuCores": 1,
    "memoryGb": 2
  },
  "idleTimeoutMinutes": 60,
  "startImmediately": true
}

Keep the returned sandbox ID and read GET /api/v1/sandboxes/{sandboxId} until it is ready for work.

Common operation families

These are common routes, not an exhaustive endpoint reference. Use the CLI for an installed command catalogue, and the task-specific guides for transfer and terminal flows.

Retries and long-running operations

Keep request IDs, sandbox IDs, execution IDs, and idempotency keys distinct. An HTTP timeout can leave the result unknown even when the server accepted the work.

Reuse the original idempotency key when retrying the same keyed request, with the same body. Query the resource or operation before starting another mutation. Honour Retry-After when supplied and use bounded backoff rather than tight polling.

Creation, deletion, snapshots, imports, and executions can outlive their initial response. Observe their reported state. Destructive operations also use server preflight confirmation; the CLI handles that protocol. A raw deletion request is not a replacement for the confirmation flow.

Handle errors

A 401 usually means authentication needs attention; a 403 can indicate missing scope, membership, ownership, or entitlement. A 409 indicates a conflict to resolve before repeating the request. For 429 or temporary service errors, inspect retry guidance and the operation’s existing state.

See troubleshooting for what to collect without exposing credentials.