The API

Everything you do in the console, a script can do through the API: servers and their parts, the other products of your account and a read-only view of your money. It speaks JSON over HTTPS and follows the same rules as the console: your level, your credit and the systems and locations that can be built.

Make a token

1. Open Access & security in the console and choose API tokens.
2. Choose Add, give the token a name, choose its access (Read and write, or Read only for a script that only looks) and, if you like, the addresses it may be used from (one address or range per line). Leave that empty to allow every address. Choose Generate token.
3. Copy the token. It is shown once; we keep only a hash of it.

A token acts as you. Disable it when you want a pause, and revoke it when it should never work again. Both are in the same list, and take effect at once.

Call the API

The API lives at https://api.stavane.com/v1, the first server of the OpenAPI description. The same API also answers at /api/v1 on the console, for example https://console.stavane.com/api/v1, with the same tokens and rules; scripts that already use that address keep working. Send the token as a Bearer token:

curl -H "Authorization: Bearer stv_..." https://api.stavane.com/v1/servers

A token can make 120 requests per minute. Beyond that the API answers 429 with a Retry-After header.

What you can do

Build a server

A request that builds needs an Idempotency-Key header: a string of your own, 8 to 100 characters. Sending the same request with the same key again gives back the same server instead of a second one, so a retry after a timeout is safe. Use a new key for every new request: the same key with other fields answers 422 with the error under Idempotency-Key, and nothing is built. A key belongs to one path, and a request we refused (an answer from 400 to 499) leaves the key free, so you can fix the fields and send it again under the same key.

curl -X POST https://api.stavane.com/v1/servers \
  -H "Authorization: Bearer stv_..." \
  -H "Idempotency-Key: build-web-1-2026-09-23" \
  -H "Content-Type: application/json" \
  -d '{"plan":"S-2","region":"ams","image":"ubuntu:24.04","name":"web-1","ssh_keys":["<id from GET /ssh-keys>"]}'

The fields are plan, region, image (as GET /images gives it) and name, and optionally ssh_keys (ids from GET /ssh-keys), root_password_mail (the root password by e-mail, as in the console; on unless you send false, and then at least one key is needed), cloud_init (a cloud-config document) or user_script (the id of a saved script), timezone (Europe/Amsterdam, America/New_York or UTC; without it the time zone of the location), project (the id of a project) and protected (protection against removing and rebuilding; on unless you send false).

The answer is 202 with the server. It is built in the background: read it again with GET /servers/{id} until its status is running.

Calls that wipe data

Rebuilding a server removes what is on the disk now. Send the name of the server as confirm, exactly as you would type it in the console, so a wrong id in a script cannot wipe the wrong machine.

A new server is protected against removing and rebuilding, as in the console. DELETE /servers/{id} and a rebuild of a protected server answer 422; send PATCH /servers/{id}/settings with {"protected": false} first.

Extra addresses

An extra address is billed by the hour from the moment it exists, exactly as in the console. The same Idempotency-Key twice gives the same address, so a retry never adds a second one. The guides of other parts of a server list their own calls under "Through the API".

The other products

Each product below is part of the API while it is part of your account. A call that makes something billed needs an Idempotency-Key, as building a server does. Removing something asks for its name as confirm, exactly as you would type it in the console. Each product has an options call with what can be made and its price per month in your currency.

Every call of every product is in the OpenAPI description at /openapi.json, which only lists what your account can use.

Your balance, usage and invoices

A token of an owner reads your money; a token of a member gets 403 here, and the billing role makes no tokens. A token can never change your money: topping up, cards, automatic top-ups and refunds stay in the console. Amounts are whole cents in the currency of your account.

These lists come a page at a time, see "Lists" below.

Support tickets

Ask us something from a script, and read our answer, as in Support in the console. Tickets are plain text; files cannot be attached. A ticket goes by its reference, such as T-123456. Opening a ticket and replying need an Idempotency-Key, so a retry never sends your message twice.

What stays in the console

The screen of a server needs a browser, so it is only in the console. See The console of your server.

Lists

A list that can grow without end comes a page at a time: your transactions, invoices, tickets and service contracts. A page has 25 rows unless you ask for up to 100 with limit. While there are more, the answer has a next_cursor: send it as cursor to read the next page; it is null on the last page. Every other list holds everything of your account, in the same order on every call, except the activity of a server, which gives the latest rows only (limit, at most 100). What we read from the systems that run your servers (firewall rules, reverse names and the like) comes in the order those systems give.

Answers and errors

Every answer is JSON with the result under data. When something is refused:

• 400: a call that needs an Idempotency-Key came without one.
• 401: no token, or a token that is unknown, disabled or revoked.
• 403: the token may not be used from this address, it is a read-only token and the call changes something, or your role in the organisation does not allow the call (for example billing).
• 404: there is no such thing of yours, or it belongs to a product that is not part of your account.
• 422: a field is missing or refused, for example a plan your level does not open yet or credit that does not cover the first hours. The answer says which field and why, under errors, with the name of the field you sent (size_gb, or targets.0.port for a field inside a list). A refusal that is about the thing itself and not a field you sent is under the name of its path parameter, such as server. A field the call does not take is refused too, by its name, before anything happens: a typo such as "port" where the call takes "from" never passes unnoticed. The same Idempotency-Key with other fields than its first request answers 422 under Idempotency-Key.
• 429: too many requests.