API: Operations

Overview

Many resource operations (create, delete, scale) are asynchronous. When you initiate an async operation, the API returns HTTP 202 with an operation ID. Use the operations endpoint to poll for completion.

Endpoint

Method	Path	Description
GET	`/v1/operations/{id}`	Get operation status

## Get Operation Status

GET /v1/operations/op-abc123

Response (200)

{
  "id": "op-abc123",
  "resource_id": "inst-xyz789",
  "type": "create",
  "status": "running",
  "result": null,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": null
}

Operation Object

Field	Type	Description
`id`	string	Unique operation ID
`resource_id`	string	ID of the affected resource
`type`	string	Operation type: `create`, `delete`, `update`, `scale`
`status`	string	`pending`, `running`, `completed`, or `failed`
`result`	object	Result data on completion (null while in progress)
`created_at`	string	ISO 8601 timestamp of creation
`completed_at`	string	ISO 8601 timestamp of completion (null while in progress)

## Status Transitions

pending → running → completed
                  → failed

Polling Example

# Create an instance (returns operation ID)
OP_ID=$(curl -s -X POST $API/v1/instances -H "$AUTH" -H "$CT" \
  -d '{"metadata":{"name":"web"},"spec":{"type":"cx31","image":"ubuntu-22.04"}}' \
  | jq -r '.operation_id')
Poll until completion
while true; do
  STATUS=$(curl -s -H "$AUTH" $API/v1/operations/$OP_ID | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 5
done

Failed Operations

When an operation fails, the result field contains error details:

{
  "id": "op-abc123",
  "status": "failed",
  "result": {
    "error": "insufficient capacity in region fsn1",
    "code": "CAPACITY_EXHAUSTED"
  },
  "completed_at": "2025-01-15T10:31:00Z"
}