Cloud-B

Documentation

Public API v1: authentication, regions, limits and error handling. The endpoint reference is in a separate section.

API v1Updated 12.11.2026Schema: 2026-09-01

Getting started

The API runs over HTTPS and accepts and returns JSON in UTF-8. The base URL is https://cloud-b.myftp.org/api/v1. Everything is also available through the cloudb CLI and the cloudb/cloudb Terraform provider.

An access token is issued when the agreement is signed or when a trial account is created. There are two token types: cb_test_… — an isolated environment without internet access, and cb_live_… — production.

1. Verify the token

export CLOUDB_TOKEN="cb_live_…"

curl -s https://cloud-b.myftp.org/api/v1/whoami \
  -H "Authorization: Bearer $CLOUDB_TOKEN"
{"account":"acc_2b91","plan":"standard",
 "scopes":["compute:read","compute:write","storage:read"],
 "zone_default":"sto-1a"}

2. Create an instance

curl -s -X POST https://cloud-b.myftp.org/api/v1/instances \
  -H "Authorization: Bearer $CLOUDB_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6d0f0e-1d0a-4c66-9d54-2a0b1c9e7f21" \
  -d '{"zone":"sto-1a","plan":"c4.m8","image":"debian-12",
       "ssh_keys":["ssh-ed25519 AAAAC3Nza… ops@laptop"]}'

The response is 202 Accepted with an identifier and the current status. The instance is ready when the status changes to running; this takes 20–60 seconds and progress is visible in GET /v1/instances/{id}.

{"id":"vm_7f3c1a92","status":"provisioning","zone":"sto-1a",
 "plan":"c4.m8","created_at":"2026-11-19T08:41:12Z"}

3. Terraform

terraform {
  required_providers {
    cloudb = { source = "cloudb/cloudb", version = "~> 1.4" }
  }
}

resource "cloudb_instance" "web" {
  zone     = "sto-1a"
  plan     = "c4.m8"
  image    = "debian-12"
  ssh_keys = [file("~/.ssh/id_ed25519.pub")]
}

Authentication

Tokens are passed only in the Authorization: Bearer header. Passing a token in a query parameter is rejected with 400 invalid_request — tokens must not end up in proxy logs or browser history.

  • Scopes are issued per product: compute, storage, db, dns, network, billing:read.
  • Write access requires the matching :write scope; read-only tokens return 403 insufficient_scope.
  • Token rotation is available through support or the API; the old token stays valid for 24 hours after a new one is issued.
  • Every request receives an X-Request-Id; include it when contacting support.

Use a separate token for the test environment: cb_test_…. Test account resources are not billed and are removed 7 days after the last activity.

Regions and zones

A zone is the unit of placement: an instance, a volume and a database cluster live in one zone. Public addresses can move between zones; data moves only through snapshots.

ZoneSiteRTT from StockholmMaintenance window (CET)
sto-1aSTO1, Stockholm0.7 msTuesday, 03:00–06:00
sto-1bSTO1, Stockholm0.9 msWednesday, 03:00–06:00
got-1aGOT1, Gothenburg4.8 msThursday, 03:00–06:00

Zones sto-1a and sto-1b are in different halls of the same data centre: independent power feeds and network paths, but a shared region. For full geographic isolation use the Stockholm–Gothenburg pair.

Limits and quotas

Quotas apply per account and can be raised by a support request. Rate limits apply per token and do not depend on the number of source IPs.

ResourceDefaultNotes
Virtual machines64per account
vCPU in total128across all zones
Object storage20 TBincluding object versions
B-DB clusters16replicas included
DNS zones1005,000 records in total
API requests120/minburst 300, 60-second window

Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time). When the limit is exceeded the API returns 429 rate_limited with a Retry-After header in seconds. Clients must honour Retry-After; exponential backoff starts at 1 second.

Errors

A single format: an error object with a machine-readable type, a human-readable message and a request_id. Error bodies never contain tokens.

{"error":{"type":"quota_exceeded",
  "message":"vCPU quota exceeded in sto-1a",
  "request_id":"req_9c2f4a1e",
  "details":{"limit":128,"used":128}}}
HTTPtypeWhen
400invalid_requestsyntax error, unknown field, wrong type
401missing_token, invalid_tokenno header, or the token was revoked
403insufficient_scopethe token lacks the required scope
404not_foundthe object was deleted or belongs to another account
409conflictthe current state does not allow the operation
422capacity_exhausted, quota_exceededno free capacity in the zone / quota reached
429rate_limitedrequest-rate limit exceeded
500internal_errorinternal error; the request can be retried safely
503unavailablezone under maintenance; see Retry-After

Retry only idempotent requests (GET, PUT, DELETE) and POST requests with an Idempotency-Key. Responses with 4xx other than 429 should not be retried.

Changelog

DateVersionChanges
2026-11-121.14maintenance_policy field for instances; zone field in webhook payloads
2026-09-011.13cursor pagination for /v1/instances and /v1/snapshots
2026-06-031.12cold class in B-Storage; PITR extended to 7 days
2026-03-171.11DNSSEC in B-DNS, batch record changes

Backwards compatibility is preserved: fields are not removed and do not change type. A removal is announced 6 months in advance and repeated in the Deprecation header.