Standard responses

Every qibdo Cloud service returns responses in the same canonical shapes. Because the API is gRPC transcoded to HTTP/JSON, response bodies follow the Protobuf contract: JSON field names are snake_case, and timestamps are RFC 3339 (for example 2026-06-04T12:30:00Z).

This page covers the response bodies. For the request and response headers (such as Content-Type and how the gateway maps the gRPC status onto the HTTP status), see Headers.

Success responses

There are three success shapes, depending on the kind of call.

Reading a resource

Get returns the resource directly, with no envelope. Server-managed fields (id, parent references, created, updated) are output-only:

{
  "id": "6f1c8e2a-…",
  "organisation_id": "0b3d…",
  "name": "prod-ws",
  "created": "2026-06-01T10:00:00Z",
  "updated": "2026-06-04T12:30:00Z"
}

Mutating a resource: the operation acknowledgement

Every mutation (Create, Update, Delete, and custom lifecycle verbs like :start or :stop) returns an operation, not the resource. The operation is your durable handle for tracking the work, following Google’s long-running operations pattern (AIP-151):

{
  "id": "a1b2c3d4-…",
  "resource_id": "9f8e7d…",
  "resource_type": "VirtualMachine",
  "operation_type": "COMPUTE_OPERATION_TYPE_CREATE",
  "status": "COMPUTE_OPERATION_STATUS_RUNNING",
  "insert_time": "2026-06-04T12:00:00Z",
  "start_time": "2026-06-04T12:00:01Z",
  "errors": [],
  "warnings": [],
  "progress": 40
}

Field	Meaning
id	Unique operation id; poll it to track progress.
resource_id	The affected resource (may be empty until an async create materializes it).
resource_type	The kind of resource, e.g. "VirtualMachine".
operation_type	…_CREATE, …_UPDATE, …_DELETE, …_START, …_STOP, etc.
status	…_PENDING, …_RUNNING, …_DONE, or …_ERROR.
insert_time / start_time / end_time	When the operation was created, started, and finished.
errors / warnings	Each carries a numeric code and a human-readable description.
progress	Completion percentage, 0 to 100.

Operations are themselves queryable. Each service exposes a read-only operations collection:

GET /<service>/v1/operations/{id}     # poll a single operation
GET /<service>/v1/operations          # list operations

Poll the operation (GET /<service>/v1/operations/{id}) until status reaches …_DONE (success) or …_ERROR (check errors).

Listing resources

List returns a collection envelope: the page of items plus a cursor for the next page (see Pagination).

Errors

Failures are reported in a separate canonical envelope, not the success shapes above. The full error model, the gRPC to HTTP status mapping, and the structure of qibdo error codes are documented on the Errors page.

Pagination

List responses return the page of items plus an opaque next_page_token. An empty token means you’ve reached the last page:

{
  "vms": [ { "id": "…", "name": "web-1" } ],
  "next_page_token": "Cg0K…opaque…"
}

• Request more with page_size (default 20, capped at 100) and page_token.
• The token is an opaque cursor: treat it as a black box; don’t parse or construct it.
• There is no total_size. Cursor pagination doesn’t compute a total count; page until the token is empty.

See API standards for the full set of list parameters and Filtering for narrowing results.