Management API
The console is a client of this API. The same routes serve scripts when you send Authorization: Bearer <ORC_API_TOKEN>. See Scripting with the API for examples.
Property names are PascalCase and times are unix milliseconds. Errors map to status codes: 400 for invalid input, 401 only when you are not signed in, 403 for everything else that is refused, 404 for an unknown workspace and 409 for a conflict such as backing up a running workspace.
Authentication
| Method and route | What it does |
|---|---|
POST /api/auth/login |
Body { "User", "Password" }. Signs in the global administrator or a console user and sets the session cookie. 401 for a wrong password, 429 after repeated failures. |
POST /api/auth/logout |
Ends the session. |
GET /api/auth/session |
The current session: IsAuthenticated, User, IsRoot, and for a console user its prefix and quota. |
Everything under /api/admin needs a console session or the API token. Routes marked global are for the global administrator and the token. A console user gets 403.
Public routes
No sign-in.
| Method and route | What it does |
|---|---|
GET /api/public/landing |
The title, subtitle and published workspaces. With ORC_LANDING_SIGN_IN, an empty list and SignInRequired until an account signs in. |
POST /api/public/instances/{slug}/wake |
Wakes a workspace and returns its start status. This is what the starting page calls. |
GET /api/public/instances/{slug}/status |
The start status: each step and whether it is ready. |
POST /api/account/sign-in, POST /api/account/sign-out, GET /api/account/session |
The landing page's sign-in with an account. |
GET /health |
ok. |
Workspaces
| Method and route | What it does |
|---|---|
GET /api/admin/overview |
The host: Docker version, CPU, memory, disk, counts, defaults, settings in effect and, on a central, its nodes. |
GET /api/admin/instances |
Every workspace you may manage. On a central, every workspace of the fleet with NodeId and NodeName. |
GET /api/admin/instances/{slug} |
One workspace. |
GET /api/admin/slug?name=&slug= |
Suggests an address and says whether it is valid and free. |
POST /api/admin/instances |
Creates a workspace. Body fields: Name, Slug, Description, Image, MemoryLimitMB, CpuLimit, ShowOnLanding, SkipSetupWizard, GuestAccess, GuestAutoSignIn, StartNow, Environment, and on a central NodeId and Labels. Returns the workspace and an operation. |
PUT /api/admin/instances/{slug} |
Updates Name, Description, Image, limits, the flags and Environment. Returns an operation. Only the global administrator changes Image. |
DELETE /api/admin/instances/{slug}?deleteData=true |
Deletes the workspace. deleteData=false keeps its volume. |
POST /api/admin/instances/{slug}/start |
Starts it and returns its start status at once. |
POST /api/admin/instances/{slug}/stop |
Stops it and clears keep warm. |
POST /api/admin/instances/{slug}/restart |
Restarts it. Answers 202. |
POST /api/admin/instances/{slug}/update-image |
Pulls the image and re-creates the container. Returns an operation. |
POST /api/admin/instances/{slug}/recreate |
Re-creates the container from its record. Returns an operation. |
POST /api/admin/instances/{slug}/keep-warm |
Body { "Hours": n } or { "AlwaysOnline": true }. { "Hours": 0 } clears it. 409 when always online is turned off. |
GET /api/admin/instances/{slug}/credentials |
The workspace administrator's user, e-mail and password. |
POST /api/admin/instances/{slug}/rotate-password |
Rotates it and re-creates the container. Returns an operation. |
POST /api/admin/instances/{slug}/sign-in |
Returns a token, the storage key and the URL the console uses to open the workspace signed in as administrator. |
GET /api/admin/instances/{slug}/logs?tail=500&since=0 |
Log lines. |
GET /api/admin/instances/{slug}/logs/download |
The full log as a text file. |
GET /api/admin/instances/{slug}/stats |
The workspace's resource history. |
GET /api/admin/instances/{slug}/owners, PUT /api/admin/instances/{slug}/owners |
The console users who own it. |
Backup and restore
| Method and route | What it does |
|---|---|
GET /api/admin/instances/{slug}/backup |
Streams /DATA as a .tar.gz. 409 while the workspace runs. |
POST /api/admin/instances/{slug}/restore |
The raw .tar or .tar.gz as the body, Content-Type: application/octet-stream. 400 when the archive is incomplete or not a backup. Returns an operation. |
POST /api/admin/instances/{slug}/reset |
Starts over with an empty volume. Returns an operation. |
Operations, activity and statistics
| Method and route | What it does |
|---|---|
GET /api/admin/operations?slug= |
The 20 most recent operations. |
GET /api/admin/operations/{id} |
One operation with its log lines. Poll it until it finishes. |
GET /api/admin/events?slug=&max=200 |
Activity entries, newest first, at most 1000. |
GET /api/admin/stats |
Host CPU and memory history. |
Global administrator only
| Method and route | What it does |
|---|---|
GET /api/admin/environment, PUT /api/admin/environment |
The environment passed to every workspace. |
GET /api/admin/accounts, PUT /api/admin/accounts |
The accounts every workspace gets. |
POST /api/admin/accounts/{user}/disable, .../enable, DELETE /api/admin/accounts/{user} |
Disable, enable or delete an account. |
GET /api/admin/users, POST /api/admin/users, PUT /api/admin/users/{user}, DELETE /api/admin/users/{user} |
Console users. |
GET /api/admin/custom-html, PUT /api/admin/custom-html |
The custom CSS and HTML. |
GET /api/admin/images |
The Docker images on the host and which workspaces use them. |
POST /api/admin/check-updates |
Pulls every image in use and refreshes which workspaces are outdated. Returns an operation. |
POST /api/admin/update-all |
Re-creates every outdated workspace, one at a time. Returns an operation. |
GET /api/admin/https |
The certificate list with each name's state and expiry. |
Fleet routes
On a central, GET /api/admin/fleet describes the fleet. Node and join token management is global administrator only.
| Method and route | What it does |
|---|---|
GET /api/admin/nodes, GET /api/admin/nodes/{id} |
Nodes and one node's details. |
POST /api/admin/nodes/probe |
Body { "Address" }. Reads a node's identity. Changes nothing. |
POST /api/admin/nodes |
Enrolls a node by enrollment code, or attaches one by API token. |
PUT /api/admin/nodes/{id} |
Name, address, labels and the running limit. |
POST /api/admin/nodes/{id}/approve, .../reject |
Decide on a pending node. |
POST /api/admin/nodes/{id}/drain, .../undrain |
Stop or resume placing new workspaces. |
POST /api/admin/nodes/{id}/disable, .../enable |
Stop or resume sending the node anything. |
POST /api/admin/nodes/{id}/rotate-secret |
Issue a new node secret. |
POST /api/admin/nodes/{id}/upgrade |
Upgrade an API-token node to a node secret. |
DELETE /api/admin/nodes/{id} |
Remove it. Refused while workspaces are placed there, unless detached. |
GET /api/admin/join-tokens, POST /api/admin/join-tokens, DELETE /api/admin/join-tokens/{id} |
List, create and revoke join tokens. A new token is shown once. |
POST /api/admin/instances/{slug}/adopt |
Adopt an unadopted workspace on a node. |
POST /api/admin/instances/{slug}/move |
Body { "NodeId" }. Moves a workspace. local is the central itself. |
The routes /api/node/* and /api/fleet/* are for the fleet's own traffic, signed with ORC1-HMAC-SHA256. Do not call them from scripts.
Operations
A call that does slow work returns an operation: an id, the workspace, a state and log lines. Poll GET /api/admin/operations/{id} until it ends. On a central, an operation on a node carries the node's id as a prefix.