Requests & Responses

This page describes the request format, the response envelope, and the data conventions shared by every CMP API endpoint.

---

Request format

Methods & paths

Each operation uses a fixed HTTP method and a path relative to the API base URL:

<METHOD> https://portal.your-domain.com/restapi/<resource>/<operation>

• GET — reads (...List, lookups) and several action operations (for example, startInstance, attachVolume, acquireIpAddress). Parameters are supplied as query-string parameters.
• POST — create operations that take a JSON request body.
• PUT — update operations (for example, updateNetwork, startKubernetes).
• DELETE — delete operations. The identifier is supplied either as a path segment (/deleteVolume/{uuid}) or as a query parameter (releaseIpAddress?uuid=…).

note

The HTTP method is not always inferable from the operation name — several read-style paths use GET to perform actions. Always use the method shown on each endpoint page.

Parameter locations

Location	Used for	Example
header	apikey, secretkey (always)	-H "apikey: …"
query	GET/DELETE parameters, and filters	?zoneUuid=…
path	resource UUID in some deletes	/deleteVolume/{uuid}
body (JSON)	POST/PUT request payloads	-d '{ … }'

Content type

POST and PUT requests that carry a JSON body must set:

Content-Type: application/json

Responses are returned as application/json.

---

Identifiers (UUIDs)

Resources are referenced by UUID strings — for example zoneUuid, networkUuid, or the resource's own uuid. Obtain a resource's UUID from the corresponding ...List endpoint, then use it in subsequent action/update/delete calls.

Most ...List endpoints require zoneUuid — you must specify which zone to query. List zones first with the Zone endpoint.

---

Response envelope

Successful responses are list-wrapped: the payload is an array under a named key, plus a count. This holds even for create/update operations, which return the affected resource(s) inside the same wrapper.

List / action response (shape):

{
  "list<Resource>Response": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "example-name",
      "status": "Active"
    }
  ],
  "count": 1
}

Delete response: most deletes return a bare boolean true (some return 204 No Content; a few return a small { "uuid", "status" } object).

note

The wrapper key and item fields vary per resource. Each endpoint page documents its own response schema and shows a representative sample.

---

HTTP status codes

Code	Meaning
200	Successful operation.
202	Accepted — the update is being applied asynchronously (returned by some PUT updates).
204	No content (returned by some deletes).
401	Invalid authentication credentials.
550	Permission denied.

The full list, with the error body shape, is on the Error Codes page.

---

Asynchronous operations & job polling

Some operations (provisioning a volume, VM snapshot, Kubernetes cluster, etc.) run asynchronously. When an operation is queued, the response includes a jobId (and the resource is created in a transitional state such as Allocating, Starting, or Creating).

To track completion, poll the Resource API Status endpoint with the jobId:

curl -X GET \
  "https://portal.your-domain.com/restapi/asyncjob/resourceStatus?jobId=JOB_ID" \
  -H "apikey: YOUR_API_KEY" \
  -H "secretkey: YOUR_SECRET_KEY"

Continue polling until the returned status reaches a terminal value. Alternatively, poll the resource's own ...List endpoint and inspect its status / state field.

tip

A small number of PUT updates return 202 Accepted directly instead of a jobId. Treat both the same way — the change is applied asynchronously.

---

Dates & regions

• Timestamps such as createdTimeStamp and generatedDate are returned as epoch values (int64).
• Zones / regions are referenced by zoneUuid. List available zones with the Zone endpoint.