Cloud-B

API v1 reference

REST, JSON, Bearer tokens. All identifiers are strings with a type prefix; timestamps are ISO 8601 in UTC.

API v1Updated 12.11.2026Schema: 2026-09-01

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 Z suffix. 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

MethodPathPurposeScope
GET/instanceslist instances, filters zone, statuscompute:read
POST/instancescreate an instancecompute:write
GET/instances/{id}instance detailscompute:read
DELETE/instances/{id}delete; the volume is keptcompute:write
POST/instances/{id}/actionsstart, stop, reboot, rebuildcompute:write
GET/volumesvolumes and their attachmentscompute:read
POST/snapshotssnapshot a volume or a database clustercompute:write
GET/bucketsbuckets, size and storage classstorage:read
POST/bucketscreate a bucket, set versioningstorage:write
GET/db/clustersdatabase clusters and replicasdb:read
POST/db/clusterscreate a clusterdb:write
GET/dns/zoneszones and recordsdns:read
POST/dns/zones/{zone}/recordsbatch record changesdns:write
GET/vpc/networksprivate networks and subnetsnetwork:read
GET/eventsaccount audit log, 30 dayscompute: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).

EventWhen
instance.status_changedinstance status changes, including provisioning failures
snapshot.completeda snapshot is created and available for restore
db.failoverprimary switched, with the new address
billing.thresholdusage 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.