Reference

API

The panel and the CLI both run on Nebla's REST API, so anything you can do in the browser you can script. The API lives under /v1 on your panel and is described by an OpenAPI 3 spec in the repository.

Authentication

Create a token on a project's API tokens page (see Projects and access) and send it as a bearer token:

curl -H "Authorization: Bearer $NEBLA_TOKEN" https://panel.example.com/v1/servers

A token belongs to one project, so requests need no project ID. A Read token can only make GET requests. A token reaches the project's locations, images, server types, SSH keys, servers, volumes, firewalls and actions. Account, project and admin endpoints need a browser session.

Resources

PathWhat it holds
/locations, /images, /server_typesWhat the project can create servers from
/ssh_keysThe project's SSH keys
/serversServers, with power, rebuild, change type, console and metrics under /servers/{id}/…
/volumesVolumes, with attach, detach and resize actions
/firewallsFirewalls, with set rules, apply and remove actions
/actionsEvery action in the project

Objects can be looked up by ID. Lists take filters such as name, status and label_selector.

Create a server

curl -X POST https://panel.example.com/v1/servers \
  -H "Authorization: Bearer $NEBLA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "web1", "server_type": "small-2", "image": "debian-13", "location": "home", "ssh_keys": ["laptop"]}'

server_type, image, location and each SSH key take an ID or a name. The response has the new server, the action that creates it, and next_actions that follow it.

Actions

Anything that changes a server, volume or firewall runs in the background as an action. The call returns the action straight away:

{
  "action": {
    "id": 812,
    "command": "start_server",
    "status": "running",
    "progress": 0,
    "resources": [{ "id": 42, "type": "server" }],
    "error": null,
    "started": "2026-11-21T10:04:12Z",
    "finished": null
  }
}

Poll GET /v1/actions/{id} until status is success or error. The CLI backs off from one second to five between polls. When an action fails, error has a code and a plain message.

Server actions are POST /v1/servers/{id}/actions/{name}, where the name is poweron, poweroff, shutdown, reboot, reset, rebuild or change_type. A second change to a resource while an action runs on it is refused with 409 and the code locked.

Errors

Errors use HTTP status codes and a JSON body:

{ "error": { "code": "not_found", "message": "not found" } }

Pagination

List endpoints take page (from 1) and per_page (default 25, at most 50), and return the total in meta:

{ "servers": [], "meta": { "pagination": { "page": 1, "per_page": 25, "total_entries": 0 } } }

Label selectors

label_selector takes comma-separated terms that must all match: key=value, key!=value, key (the label exists) and !key (it doesn't). For example role=web,env!=prod.

Rate limits

Each token can make 3600 requests an hour, with bursts of up to 100. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Past the limit, the panel answers 429 with the code rate_limit_exceeded and a Retry-After header.

Health

GET /v1/healthz needs no token and answers 200 while the panel is up. Use it for load balancer and uptime checks.