Documentation
Public API v1: authentication, regions, limits and error handling. The endpoint reference is in a separate section.
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
:writescope; read-only tokens return403 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.
| Zone | Site | RTT from Stockholm | Maintenance window (CET) |
|---|---|---|---|
sto-1a | STO1, Stockholm | 0.7 ms | Tuesday, 03:00–06:00 |
sto-1b | STO1, Stockholm | 0.9 ms | Wednesday, 03:00–06:00 |
got-1a | GOT1, Gothenburg | 4.8 ms | Thursday, 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.
| Resource | Default | Notes |
|---|---|---|
| Virtual machines | 64 | per account |
| vCPU in total | 128 | across all zones |
| Object storage | 20 TB | including object versions |
| B-DB clusters | 16 | replicas included |
| DNS zones | 100 | 5,000 records in total |
| API requests | 120/min | burst 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}}}
| HTTP | type | When |
|---|---|---|
| 400 | invalid_request | syntax error, unknown field, wrong type |
| 401 | missing_token, invalid_token | no header, or the token was revoked |
| 403 | insufficient_scope | the token lacks the required scope |
| 404 | not_found | the object was deleted or belongs to another account |
| 409 | conflict | the current state does not allow the operation |
| 422 | capacity_exhausted, quota_exceeded | no free capacity in the zone / quota reached |
| 429 | rate_limited | request-rate limit exceeded |
| 500 | internal_error | internal error; the request can be retried safely |
| 503 | unavailable | zone 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
| Date | Version | Changes |
|---|---|---|
| 2026-11-12 | 1.14 | maintenance_policy field for instances; zone field in webhook payloads |
| 2026-09-01 | 1.13 | cursor pagination for /v1/instances and /v1/snapshots |
| 2026-06-03 | 1.12 | cold class in B-Storage; PITR extended to 7 days |
| 2026-03-17 | 1.11 | DNSSEC 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.