​
Overview

The API is consistent about method semantics and error shape. It is not consistent about list envelopes, because several endpoints pass the underlying compute platform’s response through rather than reshaping it. Knowing which is which saves a lot of guessing.

​
Pagination

Two query parameters, on every list endpoint that pages:
Page numbers start at 1, not 0. Sending page=0 is treated as page 1 rather than rejected, so an off-by-one bug shows up as a silently duplicated first page rather than an error.
Maximum page size is clamped server-side — generally 200, lower on some endpoints. Ask for more and you get the ceiling, not an error. Some endpoints use limit instead, for “most recent N” style reads: GET /api/v1/jobs/recent?limit=10.

​
Response envelopes

Three shapes. The operation’s response schema in the reference tells you which, but the pattern is predictable.

​
The paged envelope

Endpoints the API composes itself, such as GET /api/v1/audit:

​
The pass-through envelope

Endpoints backed directly by the compute platform keep its collection key — so instances arrive under virtualmachines, not content:
count, totalElements, page and currentPage are all present, and page and currentPage carry the same value. Read totalElements and page; the duplicates exist for compatibility and are not worth branching on.

​
A bare array

A few catalogue reads return a JSON array with no wrapper at all — GET /api/v1/offerings/compute is one. These do not page.
Write your client to look for the array wherever it is: check for content, then the resource-named key, then treat the body itself as the list. One helper handles all three and saves special-casing per endpoint.

​
Filtering and sorting

Filters are per-endpoint query parameters rather than a general query language. Common ones:
There is no global sort parameter. Most lists return the platform’s own ordering, which is stable in practice but not guaranteed and not documented. If order matters to you, sort client-side.

​
Identifiers

Resource identifiers are UUID strings. Two things to watch:
Path variable names are not fully consistent — the same resource may appear as {id} on one route and {vpcId} on another within the same area. The value is the same; only the label differs. The reference shows the real name per operation.
An identifier is only valid in the region the resource lives in. See Regions.

​
Request bodies

POST /api/v1/volumes is the example worth remembering: it takes name, zoneId, diskOfferingId and the rest as query parameters, not JSON. Sending a JSON body there produces a 400 complaining about a missing parameter, which reads confusingly when you can see the field in your payload. The reference marks parameter location per operation — trust it over the pattern you assume.

​
Unknown fields are ignored, not rejected

About half the JSON endpoints read the body key by key rather than binding it to a fixed class. Two consequences worth knowing:
  • A misspelt field name fails silently. Sending zoneID where the endpoint reads zoneId produces no error — the value is simply never applied, and you get a 2xx for a request that did not do what you meant. Check the field names in the reference rather than guessing at capitalisation.
  • Extra fields are harmless. You can send a superset of what an endpoint reads without triggering a 400.
Where an endpoint’s body is documented as a set of fields rather than a named schema, those are the keys the handler actually reads, recovered from the implementation. A field that isn’t listed isn’t rejected — it just has no effect.

​
HTTP methods

Action endpoints are POST with a verb in the path rather than a state field on a PUT. So stopping an instance is POST /api/v1/compute/instances/{id}/stop, not a PUT with {"state":"Stopped"}.

​
What this API does not have

Worth stating plainly, so you don’t design around features that aren’t there:

​
Dates

Timestamps are ISO 8601. Values produced by the API’s own layer — including the timestamp on every error — are local server time with no offset, e.g. 2026-09-03T14:52:10.482.
Because there is no offset or Z, a naive parser will interpret those as your local time. Treat them as UTC unless you have confirmed otherwise, and don’t use them for precise sequencing across sources.

Asynchronous work

Following a mutation to completion.

Errors

The single error shape.

Regions

Routing, and identifier scope.

Duplicates and aliases

Which of two equivalent paths to use.