REST API · v1

API reference

The Avenlith API is organised around REST. It accepts JSON request bodies, returns JSON responses and uses standard HTTP status codes and bearer-token authentication.

Base URLhttps://api.avenlith.com/v1

Servers

List servers

GET/servers

Returns all servers in the project of the token, newest first.

Parameters

regionstringqueryoptional
Filter by region code, e.g. `ist1`.
labelstringqueryoptional
Filter by label, e.g. `role=web`.
per_pageintegerqueryoptional
Items per page, 1–200. Default 50.
cursorstringqueryoptional
Cursor from `meta.next_cursor` of the previous page.

Request

Shell

curl -X GET https://api.avenlith.com/v1/servers \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

Response

JSON

{
  "data": [{
      "id": "srv_8f2k1",
      "name": "web-01",
      "status": "running",
      "plan": "vps-pro",
      "region": "ist1",
      "image": "ubuntu-26.04",
      "ipv4": "203.0.113.24",
      "ipv6": "2a0f:9400:7a00::1",
      "shield": "standard",
      "labels": { "role": "web" },
      "created_at": "2026-09-18T09:12:44Z"
    }],
  "meta": { "per_page": 50, "next_cursor": null }
}

Create a server

POST/servers

Creates a cloud server. The response is returned immediately with status provisioning; the server is usually running within 40 seconds.

Parameters

namestringbodyrequired
Hostname, 1–63 characters.
planstringbodyrequired
Plan slug, e.g. `vps-pro`.
regionstringbodyrequired
Region code.
imagestringbodyrequired
Image slug or snapshot ID.
ssh_keysstring[]bodyoptional
IDs of SSH keys to install.
shieldstringbodyoptional
`standard` (default), `advanced` or `enterprise`.
labelsobjectbodyoptional
Key/value labels for filtering and firewalls.

Request

Shell

curl -X POST https://api.avenlith.com/v1/servers \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web-01", "plan": "vps-pro", "region": "ist1", "image": "ubuntu-26.04", "ssh_keys": ["key_31xa"], "shield": "advanced", "labels": { "role": "web" } }'

Response

JSON

{
  "id": "srv_8f2k1",
  "name": "web-01",
  "status": "provisioning",
  "plan": "vps-pro",
  "region": "ist1",
  "image": "ubuntu-26.04",
  "ipv4": "203.0.113.24",
  "ipv6": "2a0f:9400:7a00::1",
  "shield": "standard",
  "labels": { "role": "web" },
  "created_at": "2026-09-18T09:12:44Z"
}

Retrieve a server

GET/servers/{id}

Returns a single server.

Parameters

idstringpathrequired
Server ID, e.g. `srv_8f2k1`.

Request

Shell

curl -X GET https://api.avenlith.com/v1/servers/{id} \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

Response

JSON

{
  "id": "srv_8f2k1",
  "name": "web-01",
  "status": "running",
  "plan": "vps-pro",
  "region": "ist1",
  "image": "ubuntu-26.04",
  "ipv4": "203.0.113.24",
  "ipv6": "2a0f:9400:7a00::1",
  "shield": "standard",
  "labels": { "role": "web" },
  "created_at": "2026-09-18T09:12:44Z"
}

Reboot a server

POST/servers/{id}/actions/reboot

Sends an ACPI reboot. Use "hard": true to power-cycle a server that does not respond.

Parameters

idstringpathrequired
Server ID, e.g. `srv_8f2k1`.
hardbooleanbodyoptional
Power-cycle instead of a graceful reboot.

Request

Shell

curl -X POST https://api.avenlith.com/v1/servers/{id}/actions/reboot \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "hard": false }'

Response

JSON

{ "action_id": "act_2Lw9", "status": "in_progress" }

Delete a server

DELETE/servers/{id}

Permanently deletes the server and its disks. Snapshots and backups are kept.

Parameters

idstringpathrequired
Server ID, e.g. `srv_8f2k1`.

Request

Shell

curl -X DELETE https://api.avenlith.com/v1/servers/{id} \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

Response

JSON

{ "deleted": true }

Networking

List private networks

GET/networks

Returns private networks and the servers attached to them.

Parameters

per_pageintegerqueryoptional
Items per page, 1–200. Default 50.
cursorstringqueryoptional
Cursor from `meta.next_cursor` of the previous page.

Request

Shell

curl -X GET https://api.avenlith.com/v1/networks \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

Response

JSON

{
  "data": [
    { "id": "net_5d1q", "name": "app-net", "region": "ist1", "cidr": "10.20.0.0/24", "servers": ["srv_8f2k1", "srv_9a7c3"] }
  ],
  "meta": { "per_page": 50, "next_cursor": null }
}

Assign a floating IP

POST/floating-ips/{ip}/assign

Moves a floating IP to another server in the same region. Traffic switches in under one second.

Parameters

ipstringpathrequired
The floating IP address.
server_idstringbodyrequired
Target server ID.

Request

Shell

curl -X POST https://api.avenlith.com/v1/floating-ips/{ip}/assign \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "server_id": "srv_9a7c3" }'

Response

JSON

{ "ip": "203.0.113.50", "server_id": "srv_9a7c3", "region": "ist1" }

Shield

List attacks

GET/shield/attacks

Returns mitigated attacks against the project, including vectors and peak values.

Parameters

sincestringqueryoptional
ISO 8601 date or relative value such as `7d`.
targetstringqueryoptional
Filter by attacked IP address.
per_pageintegerqueryoptional
Items per page, 1–200. Default 50.

Request

Shell

curl -X GET https://api.avenlith.com/v1/shield/attacks \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

Response

JSON

{
  "data": [
    {
      "id": "atk_9Qx2",
      "target": "203.0.113.24",
      "vectors": ["udp_amplification", "syn_flood"],
      "peak_bps": 412000000000,
      "peak_pps": 38200000,
      "started_at": "2026-09-18T21:04:11Z",
      "ended_at": "2026-09-18T21:31:40Z"
    }
  ],
  "meta": { "per_page": 50, "next_cursor": null }
}

Create a filtering rule

POST/shield/rules

Applies a filtering profile to a port range of an IP address.

Parameters

targetstringbodyrequired
Protected IP address.
protocolstringbodyrequired
`tcp` or `udp`.
portsstringbodyrequired
Single port or range, e.g. `27015-27030`.
profilestringbodyrequired
Profile slug, see Filtering profiles.

Request

Shell

curl -X POST https://api.avenlith.com/v1/shield/rules \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "target": "203.0.113.24", "protocol": "udp", "ports": "27015-27030", "profile": "game-source" }'

Response

JSON

{ "id": "rule_7Fk2", "target": "203.0.113.24", "protocol": "udp", "ports": "27015-27030", "profile": "game-source", "active": true }

Account & billing

List SSH keys

GET/ssh-keys

Returns the SSH keys available to new servers.

Request

Shell

curl -X GET https://api.avenlith.com/v1/ssh-keys \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

Response

JSON

{
  "data": [
    { "id": "key_31xa", "name": "laptop", "fingerprint": "SHA256:Qm4b…9Zs", "created_at": "2026-05-02T08:00:00Z" }
  ]
}

Add an SSH key

POST/ssh-keys

Uploads a public key. Ed25519 and RSA (3072 bit or more) are accepted.

Parameters

namestringbodyrequired
Display name.
public_keystringbodyrequired
The public key in OpenSSH format.

Request

Shell

curl -X POST https://api.avenlith.com/v1/ssh-keys \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… you@company.com" }'

Response

JSON

{ "id": "key_31xa", "name": "laptop", "fingerprint": "SHA256:Qm4b…9Zs" }

List invoices

GET/invoices

Returns invoices with totals and a link to the PDF.

Parameters

statusstringqueryoptional
`open`, `paid` or `overdue`.
per_pageintegerqueryoptional
Items per page, 1–200. Default 50.
cursorstringqueryoptional
Cursor from `meta.next_cursor` of the previous page.

Request

Shell

curl -X GET https://api.avenlith.com/v1/invoices \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

Response

JSON

{
  "data": [
    { "id": "inv_2026_0913", "status": "paid", "currency": "EUR", "total": 812.40, "issued_at": "2026-09-01", "pdf_url": "https://console.avenlith.com/invoices/inv_2026_0913.pdf" }
  ],
  "meta": { "per_page": 50, "next_cursor": null }
}