User API (v8.0)¶

Using basic authentication is the easiest way to get started with our API. However, keep in mind that the API credentials that are generated for basic authentication give full access to your entire account, just as if you were logged into the control panel.

If you plan to distribute an application using our API, or allow more than one user access to the tool you’re building, please use OAuth. This is the more secure alternative as it allows you to restrict what your application can do while authenticated to your account.

Invalidating tokens / api keys¶

When you generate a new api key in ComputeStacks, any previously generated tokens will be immediately invalidated.

OAuth2¶

Our OAuth2 endpoint supports the following grant types:

Authorization Code
Password
- Same API credentials used basic auth, not your normal login credentials.
Client Credentials
- Only has access to API methods with the public scope. No user data.
Refresh Token
- Only available via the Authorization Code grant type.

Scopes allow you to restrict what access your OAuth application has access to. When your users authenticate, they will be shown what access you're requesting, so please only request access to the scopes you will actually need.

Endpoint Type     | URL
------------------|-----------------------
Token URL         | `/api/oauth/token`
Authorization URL | `/api/oauth/authorize`

Data Types¶

DateTime will be returned as a String
Decimal when referring to prices will be returned as a String.
Array<ContainerImage> means it returns the same result as the primary REST interface. For example, /api/projects/{project-id}/images would return an array of /api/container_images

Available Scopes¶

public
images_read
images_write
dns_read
dns_write
order_read
order_write
profile_read
profile_update
register
project_read
project_write

Pagination¶

All collection requests will be paginated using the headers Per-Page and Total. To set these values in your request, pass the URL params page= and per_page=.

Versioning¶

You may optionally request a specific API version by modifying the Accept header with: application/json; api_version=80, where 80 is the version of the API.

If you omit this value, then the current version will be used.

Current version: 80

If you pass an unsupported API version, you will receive an HTTP status code of 422 (UNPROCESSABLE ENTITY)

Get API Version¶

# GET /version
* `version`: String
* `api_latest_version`: String
* `api_available_versions`: `Array<Integer>`

Successful Responses¶

The following HTTP codes may be returned to denote a successful response:

200 OK
201 Created
202 Accepted

Error Handling¶

The following error codes may be returned. If any error messages exist, they will be passed to the {errors: []} field.

400 Bad Request
401 Unauthorized Basic auth will return this if your credentials are invalid
403 Forbidden OAuth will return this for invalid tokens
404 Not Found
408 Request Timeout
409 Conflict The request is valid, but the node behind it is in maintenance or offline. See Refused and deferred actions.
422 Unprocessable Entity
500 Internal Server Error

Callbacks¶

Some actions accept an optional callback object (url and authorization). When the action's event finishes, ComputeStacks posts the result to that URL. See API callbacks for the payload.

Node status¶

Containers, container services, bastions, projects, and each availability zone returned by GET /api/locations carry a node_status object. It describes the node (or nodes) running the resource: whether it is online, in maintenance, or offline, and what each kind of action will do in that state. It is read from stored state, so including it does not slow down the request, and one call to GET /api/locations covers every availability zone.

Schema

node_status: Object
- state: String<online,maintenance,offline>
- since: DateTime | When that state began. May be null.
- planned: Boolean | true for maintenance, false for an unplanned outage (or while online).
- message: String | The operator's notice to customers. Always null while online, and may be null otherwise.
- operations: Object | What each action does in this state.
  - power: String<available,deferred,refused> | Start, stop, restart, and rebuild.
  - backup: String<available,refused>
  - restore: String<available,refused>
  - export: String<available,refused> | Backup downloads. Backup deletion follows the same rule.
  - scale: String<available,refused> | Adding containers. Removing them is always allowed.
  - bastion_password_reset: String<available,refused>
  - config_changes: String<available,deferred> | Changes sent to the node, such as firewall rules, SSH keys, and volume settings. When deferred, they are re-sent once the node is back online.

Example

{
    "node_status": {
        "state": "maintenance",
        "since": "2026-10-08T12:00:00Z",
        "planned": true,
        "message": "Kernel upgrade; back within the hour.",
        "operations": {
            "power": "deferred",
            "backup": "refused",
            "restore": "refused",
            "export": "refused",
            "scale": "refused",
            "bastion_password_reset": "refused",
            "config_changes": "available"
        }
    }
}

State¶

maintenance while the node is in maintenance, even if it is also unreachable (as it is during a reboot).
Otherwise offline when the node is disconnected.
Otherwise online. There is no unknown state.

When a resource spans several nodes (a container service, a project, or an availability zone), the worst state wins: offline, then maintenance, then online. since is then the earliest start among the nodes in that state, and message the first notice among them.

A container or bastion reports its own node. A container that hasn't been placed on a node is offline.
A container service reports the nodes running its containers. A service with no containers yet reports its availability zone.
A project reports the nodes running its containers and bastions. With nothing deployed yet, it reports its availability zones.
An availability zone reports the nodes open for new containers, plus any closed node that still hosts containers or bastions. A zone with no such nodes is offline.

Operations¶

Operation	`online`	`maintenance`	`offline`
`power`	available	deferred	refused
`backup`, `restore`, `export`	available	refused	refused
`scale`	available	refused	refused
`bastion_password_reset`	available	refused	refused
`config_changes`	available	available	deferred

Note

message is public: every API user can read it through GET /api/locations. It clears itself once the node is back online.

Refused and deferred actions¶

Deferred: `202 Accepted`¶

A power action (start, stop, restart, or rebuild) on a container whose node is in maintenance is deferred: it is accepted, waits, and runs on the same event once maintenance ends. The response is 202 Accepted with deferred: true, the event_id, code: "node_maintenance", and the container's node_status. The service-level power endpoint reports this per container instead.

The latest request wins. A later power request for the same container cancels the waiting one (its event is canceled as "Superseded"). If the replaced request carried a callback, that callback fires with status: "cancelled" and code: "superseded". The callback of the action that does run fires when it finishes.

Refused: `409 Conflict`¶

An action the node can't take in its current state is refused with 409 Conflict:

Creating, restoring, or deleting a backup, and requesting a backup download, while the volume's node is in maintenance or offline.
Resetting a bastion's SSH password, while its node is in maintenance or offline.
Adding containers to a service, when no node in its availability zone can take them because of maintenance or an outage.
Power actions, while the node is offline.

These previously returned 422 Unprocessable Entity (or 202 Accepted for service power actions and scaling). Retry once node_status.state is online again.