API v1 reference
REST, JSON, Bearer tokens. All identifiers are strings with a type prefix; timestamps are ISO 8601 in UTC.
Conventions
- The base URL is
https://cloud-b.myftp.org/api/v1. The version is mandatory in the path. - Request and response bodies are JSON,
Content-Type: application/json, UTF-8 encoded. - Timestamps use RFC 3339 / ISO 8601 with a
Zsuffix. Monetary amounts are integers in öre, and the field name always ends with_ore. - 2xx responses contain the full resource; partial updates return the updated object.
- Unknown fields in a request are rejected with
400 invalid_request. This guards against typos in parameter names.
Endpoints
| Method | Path | Purpose | Scope |
|---|---|---|---|
GET | /instances | list instances, filters zone, status | compute:read |
POST | /instances | create an instance | compute:write |
GET | /instances/{id} | instance details | compute:read |
DELETE | /instances/{id} | delete; the volume is kept | compute:write |
POST | /instances/{id}/actions | start, stop, reboot, rebuild | compute:write |
GET | /volumes | volumes and their attachments | compute:read |
POST | /snapshots | snapshot a volume or a database cluster | compute:write |
GET | /buckets | buckets, size and storage class | storage:read |
POST | /buckets | create a bucket, set versioning | storage:write |
GET | /db/clusters | database clusters and replicas | db:read |
POST | /db/clusters | create a cluster | db:write |
GET | /dns/zones | zones and records | dns:read |
POST | /dns/zones/{zone}/records | batch record changes | dns:write |
GET | /vpc/networks | private networks and subnets | network:read |
GET | /events | account audit log, 30 days | compute:read |
Examples
List instances
curl -s "https://cloud-b.myftp.org/api/v1/instances?zone=sto-1a&limit=2" \
-H "Authorization: Bearer $CLOUDB_TOKEN"
{"data":[
{"id":"vm_7f3c1a92","status":"running","zone":"sto-1a",
"plan":"c4.m8","ipv4":"192.0.2.41","created_at":"2026-11-19T08:41:12Z"},
{"id":"vm_2f90b1c4","status":"stopped","zone":"sto-1a",
"plan":"c2.m4","ipv4":null,"created_at":"2026-10-02T13:07:55Z"}
],
"next_cursor":null}
Stop an instance
curl -s -X POST https://cloud-b.myftp.org/api/v1/instances/vm_7f3c1a92/actions \
-H "Authorization: Bearer $CLOUDB_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"stop","force":false}'
force:false performs a graceful ACPI shutdown with a 30-second timeout. With force:true power is cut immediately; unsaved data on the volume may be lost.
Pagination
Lists are cursor-based: limit ranges from 1 to 100 (default 50), and cursor is the value from next_cursor on the previous response. Offsets (offset) are not supported, so a page does not shift when objects are deleted.
GET /api/v1/instances?limit=50&cursor=eyJpZCI6InZtXzdmM2MxYTkyIn0
next_cursor: null marks the end of the list. A cursor is valid for 15 minutes; after that the API returns 400 invalid_request.
Idempotency
POST requests accept an Idempotency-Key header (UUID v4). Repeating a request with the same key within 24 hours returns the original result without creating a second resource. The key is bound to the method, path and request body; if the body changes the API returns 409 conflict.
The Terraform provider generates keys automatically. For custom scripts, always send a key for create operations — it is cheaper than cleaning up duplicate instances.
Webhooks
Events are delivered as a POST request to your HTTPS endpoint. Any 2xx response within 5 seconds is considered successful; otherwise delivery is retried with backoff: 10 s, 1 min, 5 min, 30 min, 2 h (5 attempts).
| Event | When |
|---|---|
instance.status_changed | instance status changes, including provisioning failures |
snapshot.completed | a snapshot is created and available for restore |
db.failover | primary switched, with the new address |
billing.threshold | usage reached 80% or 100% of a limit |
POST /hooks/cloudb HTTP/1.1
X-CloudB-Signature: t=1763540400,v1=5f0c1c9d3a7e42b8…
Content-Type: application/json
{"id":"evt_01JB7Q2K9S","type":"instance.status_changed",
"created_at":"2026-11-19T08:42:03Z",
"data":{"id":"vm_7f3c1a92","status":"running","zone":"sto-1a"}}
The signature is an HMAC-SHA256 of t + "." + raw_body using the webhook secret. Compare it in constant time and drop events older than 5 minutes to protect against replay.
import hmac, hashlib, time
def verify(secret: bytes, header: str, body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret, parts["t"].encode() + b"." + body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
The webhook secret is issued once when the subscription is created. If it leaks, delete the subscription and create a new one — the old secret stops working immediately.