Kvindo™ Cloud Docs
A few ideas explain how the API behaves and why the examples are shaped the way they are.
Every resource type — VM, VPC, S3 bucket, load balancer, … — exposes exactly the same five endpoints under /api/v1/<type>. Learn them once and you know the whole API. Each has its own page in the tree on the left:
PUT / — create or update a resource (idempotent).GET /{id} — read one resource by id.GET /request/{requestId} — check the status of an async change.GET /get-by-labels — list / filter resources.DELETE /{id} — delete a resource by id.A PUT or DELETE doesn't apply immediately — it records a change request (the desired state) and returns a requestId. Background reconcilers then drive the real resource toward that desired state. So a successful PUT means "the request was accepted", not "the resource is ready"; poll GET /request/{requestId} (or watch status.state) before depending on it.
Unlike the kc CLI, the API and SDK do no name resolution. Every reference field (folderId, vpcId, floatingIpId, …) must be a real ULID. The examples create resources in dependency order and pass each returned resourceId to the resources that depend on it.
You may set metadata.id yourself (any valid ULID) instead of letting the server generate one. That id is the idempotency key: re-sending a PUT with the same id updates the existing resource rather than creating a duplicate, so retries after a dropped connection are safe. It also lets you wire references before a resource exists, since you already know the id you assigned. (The SDK generates a ULID automatically when you omit one.)
Related resources can be grouped into a transaction so they are created, billed and torn down as one unit, with quota checked up front for the whole set. The console and CLI build transactions for you; over the raw API you can create resources individually (as these examples do) or submit a transaction. See Concepts for the full model.
Responses carry a machine-readable errorCode and human errorMessage alongside the HTTP status. Common cases:
200 OK — accepted (for PUT/DELETE, the change request was queued).401 Unauthorized — missing or invalid token.403 Forbidden — the token's user lacks permission for this resource/folder.422 Unprocessable Entity — validation failed, or the resource doesn't exist (errorCode: "NotFound" instead of a 404).423 Locked — the resource is already being modified; retry after the in-flight change settles.The SDK surfaces these on every response object as errorCode / errorMessage (and read_request reports succeeded plus the failure message for async operations).
Resource docs
More in this section
Reference