API reference
Everything the panel does is available through the API. Every path below starts with https://your-panel:8443/api/v1.
Authentication
Create a token in the panel under API tokens and send it with each request.
curl -H "Authorization: Bearer klyrnvm_..." https://panel.example.com:8443/api/v1/vmsRequests and answers are JSON. A list takes page, page_size, sort and q, and answers with items, total, page, page_size and pages. A page holds 50 items unless you ask for more, up to 200.
Errors
An error answers with a code, a message and sometimes a hint.
{"error": {"code": "capacity", "message": "No host has 8 GB of memory free."}}| Code | Status | Meaning |
|---|---|---|
invalid | 400 | The request is wrong. The message says which field |
unauthenticated | 401 | The token is missing or no longer valid |
forbidden | 403 | The token may not do this |
not_found | 404 | Nothing has that id |
conflict | 409 | The request clashes with something that exists |
not_ready | 409 | The target is busy or not set up yet |
capacity | 409 | No host has room. The message says what is short |
rate_limited | 429 | Too many requests. Wait and try again |
unavailable | 503 | The host is offline |
internal | 500 | A fault on our side |
Machines
A customer's token reaches only that customer's machines. Actions that take time answer with a task.
| Method | Path | What it does |
|---|---|---|
| GET | /vms | List machines. Filter with status, node, project or q |
| POST | /vms | Create a machine |
| GET | /vms/{id} | Read one machine |
| PATCH | /vms/{id} | Change a machine's name or hostname |
| DELETE | /vms/{id} | Delete a machine. Send its name as confirm |
| POST | /vms/{id}/start | Start |
| POST | /vms/{id}/shutdown | Shut down cleanly |
| POST | /vms/{id}/reboot | Restart |
| POST | /vms/{id}/force-stop | Cut the power. Needs confirm |
| POST | /vms/{id}/reset | Hard reset. Needs confirm |
| POST | /vms/{id}/reset-password | Set a new password. Leave password out to get a generated one, shown once |
| POST | /vms/{id}/console | Open a console session. kind is vnc or serial |
| GET | /vms/{id}/metrics | Processor, memory, disk and network over time. Takes res and hours |
| GET | /vms/{id}/tasks | Tasks for this machine |
| GET | /vms/{id}/activity | Who did what to this machine |
| GET | /vms/{id}/migration-targets | Hosts this machine can move to. Administrators only |
| POST | /vms/{id}/migrate | Move the machine to another host. Administrators only |
A chosen password needs 12 to 128 characters with three of lowercase, uppercase, digits and symbols. KLYRN VM never stores it.
Tasks
| Method | Path | What it does |
|---|---|---|
| GET | /tasks | List tasks. Filter with status, op, node or resource_kind |
| GET | /tasks/{id} | Read one task |
| GET | /tasks/{id}/events | The steps of a task so far |
| POST | /tasks/{id}/cancel | Cancel a running task |
| GET | /events | A live stream of changes, as server-sent events |
Hosts
Administrators only.
| Method | Path | What it does |
|---|---|---|
| GET | /nodes | List hosts. Filter with state, mode or location |
| POST | /nodes/bootstrap | Make the command that adds a new host. The token is shown once |
| GET | /nodes/{id} | Read one host with its capacity and health |
| PATCH | /nodes/{id} | Rename a host, or set maintenance and overcommit |
| DELETE | /nodes/{id} | Remove a host. Refused while machines run on it |
| POST | /nodes/{id}/preflight | Check the host again |
| GET | /nodes/{id}/samples | Capacity by the hour. Takes hours |
Images
| Method | Path | What it does |
|---|---|---|
| GET | /images | List the systems a machine can be built from |
| POST | /images | Add your own image. Administrators only |
| PATCH | /images/{id} | Switch an image on or off. Administrators only |
| POST | /images/{id}/pull | Download an image to a host ahead of time. Administrators only |
Networks and addresses
Administrators only, apart from the calls on a customer's own machine.
| Method | Path | What it does |
|---|---|---|
| GET | /networks | List networks with their pools |
| POST | /networks | Add a network |
| DELETE | /networks/{id} | Remove a network. Refused while addresses are in use |
| POST | /networks/{id}/pools | Add an address pool to a network |
| GET | /pools | List pools with how full each one is |
| PATCH | /pools/{id} | Change a pool. Its range of addresses cannot change |
| GET | /pools/{id}/allocations | Every address in a pool and who holds it |
| POST | /pools/{id}/reservations | Set addresses aside. A note is required |
| POST | /pools/{id}/block | Take one address out of service |
| GET | /vms/{id}/networking | A machine's addresses, firewall groups and traffic this month |
| POST | /vms/{id}/ips | Give a machine another address, up to its plan's limit |
| POST | /vms/{id}/ips/detach | Take an address away. The first address stays |
Firewall
| Method | Path | What it does |
|---|---|---|
| GET | /security-groups | List your firewall groups |
| POST | /security-groups | Create a group. By default it blocks incoming and allows outgoing |
| POST | /security-groups/{id}/rules | Add a rule. Every machine in the group gets it at once |
| DELETE | /security-groups/{id}/rules/{rid} | Remove a rule |
| PUT | /vms/{id}/security-groups | Set which groups a machine uses |
Traffic and backups
| Method | Path | What it does |
|---|---|---|
| GET | /traffic | Traffic for every machine you can see. Takes period as YYYY-MM |
| GET | /vms/{id}/traffic | One machine's traffic for twelve months |
| PUT | /plans/{id}/traffic | Set a plan's allowance and what happens at the limit. Administrators only |
| GET | /backups/schedule | Each scheduled machine, its last backup and its next one |
| PUT | /plans/{id}/backups | Set a plan's backup schedule. Administrators only |
A lower allowance starts next month, so no machine is put over a limit it did not have. Saving a backup schedule deletes nothing by itself.
Plans, people and tokens
| Method | Path | What it does |
|---|---|---|
| GET, POST | /plans | List or add plans |
| GET, POST | /projects | List or add projects |
| GET, POST | /ssh-keys | List or add your SSH keys |
| GET, POST | /tokens | List or create API tokens. A new token is shown once |
| GET | /admin/users | List people. Administrators only |
| PATCH | /admin/users/{id} | Change a person's name, email or role |
| POST | /admin/users/{id}/suspend | Suspend a person. They see the reason you give |
| POST | /admin/users/{id}/restore | Lift a suspension |
| GET | /activity | The audit log. Customers see their own entries |
Billing API
A billing system uses these calls to sell machines. The token needs the provision scope. Every path starts with /provision.
| Method | Path | What it does |
|---|---|---|
| GET | /provision/catalogue | Plans, images and locations in one call |
| POST | /provision/services | Create a service and its machine |
| GET | /provision/services/{id} | Read one service |
| GET | /provision/by-ref/{ref} | Find a service by your billing system's own id |
| POST | /provision/services/{id}/suspend | Suspend. No disk is touched |
| POST | /provision/services/{id}/unsuspend | Lift the suspension |
| POST | /provision/services/{id}/change-plan | Resize the same machine to another plan |
| POST | /provision/services/{id}/reinstall | New system, same machine, same address |
| POST | /provision/services/{id}/terminate | Delete. Needs confirm |
| POST | /provision/services/{id}/retry | Try again after a failed build |
| POST | /provision/services/{id}/sso | A sign-in link for the customer. It works once, for 90 seconds |
| GET | /provision/services/{id}/usage | Traffic for a month |
Send an idempotency_key with every create. If your billing system sends the same order twice, you get one machine and the same answer both times.
A service is provisioning, active, suspended, terminated or provisioning_failed. A failed build holds no address and no storage, and retry builds it again under the same id.